Page History

bump_semver

Description

Increments the provided 

Usage

bump_semver <semver string> <action>

• semver string is the semver version to be incremented
• action is the type of increment to be applied

The valid actions are:

• major: Increment the major version. The minor and patch versions are reset to 0.
• minor: Increment the minor version. The patch version is reset to 0.
• patch: Increment the patch version.
• alpha: Increment or add an alpha pre-release tag. For example, v1.1.1 becomes v1.1.1-alpha and v1.1.1-alpha becomes v1.1.1-alpha.1. Any other pre-release tags will be removed.
• beta: Increment or add a beta pre-release tag. For example, v1.1.1 becomes v1.1.1-beta and v1.1.1-beta becomes v1.1.1-beta.1. Any other pre-release tags will be removed.
• rc: Increment or add an rc pre-release tag. For example, v1.1.1 becomes v1.1.1-rc and v1.1.1-rcbecomes v1.1.1-rc.1. Any other pre-release tags will be removed.
• final: Remove any pre-release tags, leaving major.minor.patch.

replace_envs

Description

Replaces variables in a file with values based on your current shell env. This is useful to create config files from templates, for example.

If the file contains placeholders that are not defined in the environment, they will become empty strings (“”).  The original file is overwritten with the modified file.

Usage

replace_envs <filename1> <filename2> <filenameN>

where your files have placeholders in the format $ENVIRONMENT_VARIABLE_NAME or ${ENVIRONMENT_VARIABLE_NAME}.

retry_command

Description

Execute any command up to three times if it returns a non-zero error code. This is useful when you need to execute a command that can be flaky as a result of network hiccups, for example.

Usage

retry_command <shell command> 

• shell command is the command to be retried

get_uuid

Description

Puts a uuid to stdout. Uses /proc/sys/kernel/random/uuid if available and falls back to uuidgen if not. The function calls exit 1 if 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. Either file, buildInfo, or releaseBundle.
• file path: This is 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. Either file or buildinfo.
• file path: This is the path to the metadata file to be validated.

configure_jfrog_cli

Description

Configures the JFrog CLI (v1) with the provided credentials, handling the different 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.

Usage

• artifactory-url: Required. The Artifactory URL.
• 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 to default. Can be specified to configure the CLI with that name.

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 using configure_jfrog_cli.

Usage

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

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 is the file system path to a git repository.
• resource is the name of the gitRepo resource.
• commit-range option specifies the range of commits to look for changes (Example: HEAD~1..HEAD). 
• directories-only option lists only the directories containing changes.
• depth option returns file/folder at certain depth. Root directory has depth value 1.

Anchor
update-commit-status update-commit-status

update_commit_status

Description

Updates the

Usage

update_commit_status <gitRepo resource name> --status <status> --message <message> --context <context>

• gitRepo resource name is the name of the gitRepo resource.
• status is the status to be set on the source provider: processing, success, or failure.
  If no status is specified:
  • processing will be assumed in onStart and onExecute
  • success will be assumed in onSuccess
  • failure will be assumed in onFailure
• message is the message (description) string to send with the status.
  If no message is specified, the default message will be "Step <status> in pipeline $pipeline_name"
• context is the context (key) for the status. 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

Anchor
save_tests save_tests

save_tests

Description

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

Usage

save_tests <file or directory>

• file or directory specifies 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 <path> <source string>

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

decrypt_string

Description

Uses the provided private key to decrypt the specified string.

This is typically used to decrypt information that was encrypted using encrypt_string with the corresponding public key. It helps you avoid building your own encrypt-decrypt system.

Usage

decrypt_string -key <path> <encrypted string>

• key is the fully qualified path of the private key file
• encrypted string is 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 <path> [--output <filename>] <source filename>

encrypt_file -key <path> [-output <filename>] <source filename>

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

decrypt_file

Description

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

This is typically used to decrypt information that was encrypted using encrypt_file with the corresponding public key. It helps you avoid building your own encrypt-decrypt system.

Usage

decrypt_file -key <path> [-output <filename>] <source filename>

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

Notifications

Anchor
send_notification send_notification

send_notification

Description

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

Usage

send_notification <integration> [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.

Command line options

AirBrake

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

Jira

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

NewRelic

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

PagerDuty Events

Sends an event through a PagerDuty Events Integration.

Slack

Sends a message on Slack through a Slack Integration.

smtpCreds (email)

Sends an email through an SMTP 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

Anchor
set_payload set_payload

set_payload

Description

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

Usage

set_payload <resource> <payload> [-file] 

• resource is the name of an OutgoingWebhook resource.
• payload is 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.
• file option specifies that the payload parameter is a file. If not specified, payload will be processed as a string.

Anchor
read-json read-json

read_json

Description

Extracts the json property value from the specified file.

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

Usage

read_json <path to file> <field name>

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

Anchor
resources resources

Resources

replicate_resource

Description

This 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 <from_resource> <to_resource> [-options]

• from_resource is the name of the inputResources  resource that you're copying from. 
• to_resource is the name of the outputResources  resource that will receive the replicated data from the from_resource. Any pre-existing files or key-value pairs in the to_resource will be replaced.
• match-settings option should be set when you want the replication to adhere to any branch/tag settings in the to_resource. For example, If your from_resource gitRepo can trigger on both commits and pull requests, but you only want to update your to_resource on commits, you can replicate with --match-settings, and the to_resource will only be updated when the from_resource had a commit.

Anchor
write-output write-output

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 <resource> <key value pair>...

• resource is the resource to update
• key value pair is 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 form res_{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"

Anchor
caching caching

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 can reduce 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> <name>

• file or directory is a file or directory to store in the cache
• name is 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 <name> in the cache.

Usage

restore_cache_files <name> <path>

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

Anchor
run-state run-state

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: If set as true, the local JFrog CLI on the host or in the image (depending on runtime configuration) 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>...

• key value pair is 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

Sources the file containing the run variables.  This 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> <name>

file or directory is a file or directory to store in the run state

name is 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 <name> in the run state.

Usage

restore_run_files <name> <path>

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

Anchor
pipeline-state pipeline-state

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: If set as true, the local JFrog CLI on the host or in the image (depending on runtime configuration) 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>...

• key value pair is 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> <name>

• file or directory is a file or directory to store in the pipeline state.
• name is a 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 <name> in the run state.

Usage

restore_pipeline_files <name> <path>

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

Anchor
step-properties step-properties

Step Properties

find_resource_variable

Description

Retrieves the value of the named property of a resource. 

Usage

find_resource_variable <resourceName> <propertyName>

• resourceName is the name of the resource.
• propertyName is 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 <integration type>

• integration type  is the name of an Pipelines Integration type

get_resource_name

Description

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

Usage

get_resource_name --type <resource type> --operation <IN | OUT> --syntax-version <semver>

• resource type  is the name of a Pipelines Resource type
• IN | OUT  selects whether the resource is named in inputResources or outputResources 
• semver is the semantic version number of the resource's syntax version

get_resource_names

Description

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

Usage

get_resource_names --type <resource type> --operation <IN | OUT> --syntax-version <semver>

• resource type  is the name of a Pipelines Resource type
• IN | OUT  selects whether the resource is named in inputResources or outputResources 
• semver is 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.

find_step_configuration_value

Description

Retrieves the value of the configuration  property 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>

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