Pipelines Utility Functions

get_uuid

Description

Puts a uuid to stdout. Uses/proc/sys/kernel/random/uuid我f available and falls back touuidgen我f not. The function callsexit 1我f neither of these are available.

Usage

save_artifact_info

Description

Saves metadata about an artifact. When saved, this metadata is used to enable signed pipelines for the artifacts.

Usage

• artifact type: This is the type of artifact. Eitherfile,buildInfo, orreleaseBundle.
• file path: This我s the path to the metadata file to be saved.

validate_artifact

Description

Validates the signature of an artifact. Requires signed pipelines to be enabled.

Usage

• artifact type: This is the type of artifact. Supportsbuildinfo.
• file path: This我s the path to the metadata file to be validated.

configure_jfrog_cli

Description

Configures the JFrog CLI (version 1 or 2 specified asjfrogCliVersion我n thepipeline configurationdiff)提供凭证,处理erent formats for different minor versions. Artifactory integrations listed in the integrations section of the step will be automatically configured, but this may be useful for resources or if the credentials are provided to the step in another way. When using v2, a non-default Xray URL may also be specified using the environment variable JFROG_XRAY_URL.

Usage

• artifactory-url: Required. The Artifactory URL.
• xray-url: Optional. The Xray URL. Only used with CLI v2.
• user: The user. Required when an API key is provided.
• apikey: An API key. Requires --user and may not be used with --access-token.
• access-token: An Access token. May not be used with --access-token or --user.
• server-name: Defaults todefault. Can be specified to configure the CLI with that name.

check_xray_available

Description

With JFrog CLI v2 (version 2 specified asjfrogCliVersion我n thepipeline configuration), checks that Xray is available for the specified CLI configuration, or the default configuration if none is specified.

Usage

• server-name: Optional. Specifies a JFrog CLI configuration to check.

cleanup_jfrog_cli

Description

Removes configuration for the JFrog CLI (v1), handling the different formats for different minor versions. Artifactory integrations listed in the integrations section of the step will be automatically removed at the end of the step, but this may be useful to remove the credentials earlier or when usingconfigure_jfrog_cli.

Usage

• server-name: Defaults todefault. Can be specified to remove that configuration.

set_trigger_payload

Description

添加一个或多个键=值对作为定制的步pipeline variables to a JSON payload that can be used to call the pipelines trigger API.

Multiple key=value pairs can be given in a single command or can be split across multiple commands.

If a key is added twice, the original value will be replaced.

Usage

• stepVariables: These key value pairs will be present in the environment of the triggered step
• pipelineVariables: These key value pairs will be present in the environment of every step in the run that is triggered.

get_trigger_payload

Description

Prints on stdout a payload that can be used with the pipelines trigger API.

Useset_trigger_payloadto add additional values to the payload.

Usage

end_step

Description

Stops execution of the onStart or onExecute section and immediately continues to the onSuccess, onFailure, or onComplete section setting the specified status. If "success" is provided, the onSuccess and onComplete sections will be executed. For "failure," the onFailure and onComplete sections will be executed. And for "skipped," only the onComplete section. The end_step utility function may only be called in the onStart and onExecute sections and the only statuses supported are success, failure, and skipped.

Usage

update_run_description

Description

Provide dynamic description for a run, which will be shown in the UI. This is useful for providing more context about a run. The run description can be updated at any time.

Usage

name: UpdateRunDescription steps: - name: update_l type: Bash execution: onStart: - msg="Run description updated from step $step_id" - update_run_description "$msg" - name: update_2 type: Bash configuration: inputSteps: - name: update_l execution: onStart: - msg="Run description updated from step $step_id" - update_run_description "$msg"

Source Control

compare_git

Lists the files/directories containing changes within a commit range. This function is useful when building a monorepo (monolithic repository) to determine which services have changes.

compare_git[-path | -resource] [options]

• path我s the file system path to a git repository.
• resource我s the name of thegitRepo resource.
• commit-rangeoptionspecifies the range of commits to look for changes (Example:HEAD~1..HEAD).
• directories-onlyoptionlists only the directories containing changes.
• depthoptionreturns file/folder at certain depth. Root directory has depth value 1.

update_commit_status

Description

Updates thestatusof the commit on the source provider. Status options areprocessing,success, andfailure.

Usage

update_commit_status --status --message --context

• gitRepo resource name我sthe name of thegitReporesource.
• status我s the status to be set on the source provider:processing,success, orfailure.
  If no status is specified:
  • processingwill be assumed inonStartandonExecute
  • successwill be assumed我nonSuccess
  • failurewill be assumed我nonFailure
• message我s the message (description) string to send with the status.
  If no message is specified, the default message will be "Step in pipeline $pipeline_name"
• context我sthe context (key) for thestatus. The source provider will retain only the latest status received for that context.
  If no context is specified, the default is "$pipeline_name_$step_name"
  

Test Reports

save_tests

Description

Copies test reports given as input to later be parsed and uploaded (if file storage is available).

Usage

save_tests

• fileordirectoryspecifies either a filename for the test report file, or a directory name for a directory of test report files

Encryption

encrypt_string

Description

Uses the provided public key to encrypt the specified string.

Usage

encrypt_string --key  

• key我s the fully qualified path of the public key file
• source string我s the string to be encrypted

decrypt_string

Description

Uses the provided private key to decrypt the specified string.

这s is typically used to decrypt information that was encrypted usingencrypt_stringwith the corresponding public key.It helps you avoid building your own encrypt-decrypt system.

Usage

decrypt_string -key  

• key我s the fully qualified path of the private key file
• encrypted string我s the string to be decrypted

encrypt_file

Description

Uses the provided public key to encrypt the specified file to a new file.

Usage

encrypt_file --key  [--output ] 

encrypt_file -key  [-output ] 

• key我s the fully qualified path of the public key file
• output我s the name of the resulting encrypted file. Defaults to “encrypted”
• source filename我s the file to be decrypted

decrypt_file

Description

Uses the provided private key to decrypt the specified file to a new file.

这s is typically used to decrypt information that was encrypted usingencrypt_filewith the corresponding public key.It helps you avoid building your own encrypt-decrypt system.

Usage

decrypt_file -key  [-output ] 

• key我s the fully qualified path of the private key file
• output我s the name of the resulting decrypted file. Defaults to “decrypted”
• source filename我s the file to be decrypted

Notifications

send_notification

Description

Utilizes notification integration to send custom messages at any time during the build to any recipient.

For more information, seeSending Notifications from Pipelines.

Usage

send_notification  [options]

The options can be specified as part of the command, or defined as environment variables before the command is issued.

The command line arguments take priority over the environment variables.

AirBrake

Creates an AirBrake deployment through anAirbrake Integration.Not supported in PowerShell.

Jira

Creates a Jira issue (also known as a ticket).

NewRelic

Creates a NewRelic deployment through aNewRelic Integration.Not supported in PowerShell.

PagerDuty Events

Sends an event through aPagerDuty Events Integration.

Slack

Sends a message on Slack through aSlack Integration.

smtpCreds (email)

Sends an email through anSMTP Credentials Integration.

Environment Options

All of the above options can also be included as environment variables instead of arguments. The command line argument will have priority over the environment. Here is the full list of ENVs:

• NOTIFY_USERNAME(--username/-username)
• NOTIFY_PASSWORD(--password/-password)
• NOTIFY_RECIPIENT(--recipient/-recipient)
• NOTIFY_PRETEXT(--pretext/-pretext)
• NOTIFY_TEXT(--text/-text)
• NOTIFY_COLOR(--color/-color)
• NOTIFY_ICON_URL(--icon-url/-icon-url)
• NOTIFY_PAYLOAD(--payload/-payload)
• NOTIFY_TYPE(--type/-type)
• NOTIFY_PROJECT_ID(--project-id/-project-id)
• NOTIFY_ENVIRONMENT(--environment/-environment)
• NOTIFY_REVISION(–revision/-revision)
• NOTIFY_SUMMARY(--summary/-summary)
• NOTIFY_ATTACH_FILE(--attach-file/-attach-file)
• NOTIFY_REPOSITORY(--repository/-repository)
• NOTIFY_EMAIL(–email--email/-email)
• NOTIFY_STATUS(--status/-status)
• NOTIFY_VERSION(--version/-version)
• NOTIFY_CHANGELOG(--changelog/-changelog)
• NOTIFY_DESCRIPTION(–description--description/-description)
• NOTIFY_ATTACHMENTS(–attachments--attachments/-attachments)
• NOTIFY_ATTACH_LOGS(--attach-logs/-attach-logs)
• NOTIFY_SHOW_FAILING_COMMANDS(--show-failing-commands/-show-failing-commands)
• NOTIFY_SUBJECT(--subject/-subject)
• NOTIFY_BODY(–body)

JSON

set_payload

Description

Sets an optional JSON payload (string or file) for anOutgoingWebhookresource. When the OutgoingWebhook is specified in a step'soutputresourcesthe payload is sent when the step is complete.

Usage

set_payload   [-file]

• resource我s the name of anOutgoingWebhookresource.
• payload我s a JSON string or file to attach to the resource that will be sent as part of the outgoing webhook.A file can be specified as a path relative to the current directory, absolute path, or path relative to the step workspace directory.
• fileoption specifies that thepayloadparameter is a file. If not specified,payloadwill be processed as a string.

read_json

Description

Extracts the json property value from the specified file.

这s simplifies handling of a JSON file to read specific property values that are required for your workflow.

Usage

read_json  

• path to file我s the fully qualified path of theJSON file
• field name is the field for which you want to read the value. Use dot notation and [n] for arrays.

2022世界杯阿根廷预选赛赛程

replicate_resource

Description

这s command takes an input resource and creates an exact copy. This helps you to transfer metadata from one step to the next.

Usage

replicate_resource   [-options]

• from_resource我s the name of the我nputResourcesresource that you're copying from.
• to_resource我s the name of theoutputResourcesresource that will receive the replicated data from thefrom_resource.Any pre-existing files or key-value pairs in theto_resourcewill be replaced.
• match-settingsoptionshould be set when you want the replication to adhere to any branch/tag settings in theto_resource.For example, If yourfrom_resourcegitRepo can trigger on both commits and pull requests, but you only want to update yourto_resourceon commits, you can replicate with --match-settings, and theto_resourcewill only be updated when thefrom_resourcehad a commit.

write_output

Description

Adds data to an output resource in the form of key/value pairs that will become properties of the resource.

Usage

write_output  ...[--overwrite]

• resource我s the resource to update
• key value pair我s a single string with a key and a value, separated by an “=”. Multiple of these strings can be supplied as input.A value with spaces should be surrounded by quotes.

The newly attached properties can be accessed as environment variables of the formres_{Resource Name}_{Key Name}.

For example, the above created properties can be accessed as these environment variables:

$ printenv res_myImage_master master $ printenv res_myImage_sha d6cd1e2bd19e03a81132a23b2025920577f84e37 $ printenv res_myImage_description "hello world"

Caching

Caching helps you speed up execution of your steps by preserving and restoring packages and dependencies between runs of a step. In this way, you canreduce build times by avoiding repeating the installation or loading of large dependencies.

add_cache_files

Description

Copies files given as input to later be uploaded if file storage is available.

Usage

add_cache_files

• file or directory我s a file or directory to store in the cache
• name我s a name to give the stored file or directory (without spaces)

restore_cache_files

Description

Copies stored cache (if file storage is available) to the specified location. No error will occur if nothing is available for in the cache.

Usage

restore_cache_files

• name我s the name the file or driectory to be restored was given when cached.
• path我s a path at which to place the file or directory.

Run State Management

add_run_variables

Description

Allows you to add environment variables that will be available in the following steps of the run.

If the following variables are set, they will be used:

• JFROG_CLI_BUILD_NAME: If set, the pipeline uses this value instead of the default pipeline name for the build info collected.
• JFROG_CLI_BUILD_NUMBER: If set, the pipeline uses this value instead of the default run number for the build info collected.
• USE_LOCAL_JFROG_CLI: Ifset astrue, the local JFrog CLI on the host or in the image (depending onruntimeconfiguration) is used instead of the version packaged with JFrog Pipelines. This is not recommended and native steps may not be able to run with the local JFrog CLI version.

Usage

add_run_variables ...

• key value pair我s a single string with a key and a value, separated by an “=”. Multiple of these strings can be supplied as input. Each value will be exported as an environment variable at the time this command is used and automatically in any later steps within the run.

export_run_variables

Description

源文件包含运行变量。这s will be done automatically, but may also be used to “reset” the environment variables in the current step.

Usage

export_run_variables

add_run_files

Description

Copies files given as input into the run state for use in later steps in the run, if file storage is available.

Usage

add_run_files

file or directory我sa file or directory to store in the run state

name我s a name to give the stored file or directory (without spaces). This cannot be run.env.

restore_run_files

Description

Copies files stored in the run state (if file storage is available) to the specified location. No error will occur if nothing is available for in the run state.

Usage

restore_run_files

• name我sthe name the files to be restored were given when added to the run state.
• path我s a path at which to place the file or files.

Affinity Group State Management

add_affinity_group_files

Description

Copies files or directories given as input into the affinity group workspace for use in later steps in the affinity group. Files or directories may be specified using wildcards (*) or as multiple input parameters preceding the name under which the files will be stored.

Usage

add_affinity_group_files

file or directory我sa file or directory to store in the run state.

name我s a name to give the stored file or directory (without spaces).

restore_affinity_group_files

Description

Copies files stored in the affinity group workspace byadd_affinity_group_filesto the specified location. The restore behavior differs from the other state restore functions to better handle wildcard patterns with a variable number of matching files or directories. Withrestore_affinity_group_files, the relative path specified in theadd_affinity_group_filesfunction will be preserved (excluding any traversal to parent directories) and the path specified should be the base for that relative path. The following examples are to symmetrically restore the files saved in the examples above foradd_affinity_group_files.No error will occur if no files were saved for .

Usage

restore_affinity_group_files

• name我sthe name the files to be restored were given when storing the files withadd_affinity_group_files.
• path我s a path at which to place the file or files.

Pipeline State Management

add_pipeline_variables

Description

Allows you to add environment variables that will be available in the following steps of the run and in future runs. These variables may be overridden by another variable with the same key added to the current run.

If the following variables are set, they will be used:

• JFROG_CLI_BUILD_NAME: If set, the pipeline uses this value instead of the default pipeline name for the build info collected.
• JFROG_CLI_BUILD_NUMBER: If set, the pipeline uses this value instead of the default run number for the build info collected.
• USE_LOCAL_JFROG_CLI: Ifset astrue, the local JFrog CLI on the host or in the image (depending onruntimeconfiguration) is used instead of the version packaged with JFrog Pipelines. This is not recommended and native steps may not be able to run with the local JFrog CLI version.

Usage

add_pipeline_variables ...

• key value pair我s a single string with a key and a value, separated by an “=”. Multiple of these strings can be supplied as input. Each value will be exported as an environment variable at the time this command is used and automatically in any steps that start after this run is complete.

export_pipeline_variables

Description

Sources the file containing the pipeline variables. This will be done automatically, but may also be used to “reset” the environment variables in the current step.

Usage

export_pipeline_variables

add_pipeline_files

Description

Copies files given as input into the pipeline state for use in later steps in the run and future runs, if file storage is available.

Usage

add_pipeline_files

• file or directory我sa file or directory to store in the pipeline state.
• name我sa name to give the stored file or directory (without spaces). This cannot be pipeline.env.

restore_pipeline_files

Description

Copies files stored in the pipeline state (if file storage is available) to the specified location. No error will occur if nothing is available for in the run state.

Usage

restore_pipeline_files

• name我sthe name the file to be restored was given when added to the pipeline state.
• path我s a path at which to place the file or files.

Step Properties

find_resource_variable

Description

Retrieves the value of the named property of a resource.

Usage

find_resource_variable

• resourceName我s the name of the resource.
• propertyName我s the name of the resource property whose value to retrieve.

get_integration_name

Description

Retrieves the name of the first integration found of the type specified. Available to extension steps to get the name of the first input integration of a particular type.

Usage

get_integration_name --type

• 我ntegration type我s the name of anPipelines Integration type

get_resource_name

Description

Retrieves the name of the first resource found of the type specified in我nputResourcesoroutputResources. Available to extension steps to get the name of the first input or output resource of a particular type.

Usage

get_resource_name --type --operation --syntax-version

• resource type我s the name of aPipelines Resource type
• IN | OUTselects whether the resource is named in我nputResourcesoroutputResources
• semver我s the semantic version number of the resource's syntax version

get_resource_names

Description

Retrieves an array of names of the type specified in我nputResourcesoroutputResources. Available to extension steps to get the names of input or output resource of a particular type.

Usage

get_resource_names --type --operation --syntax-version

• resource type我s the name of aPipelines Resource type
• IN | OUTselects whether the resource is named in我nputResourcesoroutputResources
• semver我s the semantic version number of the resource's syntax version
• In PowerShell, a native PowerShell array is returned. In Bash, a JSON array is returned that can be handled with jq.

get_affinity_group_step_names

Description

Retrieves a JSON array of names of steps of the type specified in the current affinity group.

Usage

get_affinity_group_step_names [--type ] [--syntax-version ] [--namespace ]

• --type我s used to specify the type of the steps to be found. If not specified, steps of all types will be returned.
• --syntax-version我s used with extension steps to specify the syntax version of the steps to be found.
• --namespace我s used with extension steps to specify the namespace of the steps to be found.

find_step_configuration_value

Description

Retrieves the value of theconfigurationproperty for the currently executing step. If the property is a collection, the first value will be returned. Available to extension steps to get the value of a configuration.

Usage

find_step_configuration_value

• propertyName我s the name of the step's configuration property whose value to retrieve