Pipelines Environment Variables

This page describes the availability and usage of environment variables in pipelines.

You can customize your workflow by using environment variables (also called runtime variables) that are available at runtime during step execution. For example, your step can construct a filename or build ID from the pipeline name and current run number. Or your step can execute different commands depending on the state of a resource.

JFrog Pipelines provides access to useful internal information from pipelines and resources through environment variables. Pipelines also provides several easy ways to inject your own environment variables into your runtime during the execution of your pipeline.

Standard Environment Variables

These environment variables are available to all executing pipelines.

Environment Variable	Description
architecture	Node architecture, e.g. x86_64
builder_api_token	Token used to call pipelines API during step execution. Used internally but is accessible to user.
current_script_section	onStart/onExecute/onComplete etc
JFROG_CLI_BUILD_NAME	If not set as a variable in the YML or added as a pipeline, run, or step variable, it will be set to `$pipeline_name`. This is used when accumulating build info.
JFROG_CLI_BUILD_NUMBER	If not set as a variable in the YML or added as a pipeline, run, or step variable, it will be set to `$run_number`. This is used when accumulating build info.
JFROG_CLI_BUILD_PROJECT	If not set as a variable in the YML or added as a pipeline, run, or step variable, it will be set to `$project_key`. This is used when accumulating or publishing build info.
JFROG_PIPELINES_RUN_STATE_DEBUG	To download run state from the UI for debugging purposes, set the environment variable `JFROG_PIPELINES_RUN_STATE_DEBUG=true` in your step's or pipeline's configuration section. For storage efficiency, we recommend removing this configuration option after you are done debugging.
operating_system	OS where step is running, e.g. Ubuntu_20.04
PATH	The value of PATH in the currently executing runtime environment.
pipeline_name	The name string of the pipeline currently executing.
pipelines_api_url	API URL
project_id	ID of the project in JFrog Pipelines
project_key	Project key. If the project is the default project, this will be empty.
project_name	Name of the project
run_id	Internal unique ID for the run.
run_number	The number of the run currently executing.
running_in_container	True if step is running in a container. False if running on host.
shared_workspace	The path of a directory available to all steps in an affinity group that may be used to share files between steps.
step_<inputStepName>_statusName	This environment variable is automatically made available at runtime and can be used in any step. inputStepName is the name of your input step. This environment variable is useful for fetching the status of any input step. For an example, see using `step_<inputStepName>_statusName` in the Conditional Workflows page.
step_affinity_group	Affinity group step belongs to. Default is same as step name.
step_id	Internal unique ID for the step currently executing.
step_image_name	Name of the Docker image used to run the step (e.g. `pipelines-docker.jfrog.io/jfrog/pipelines-u20node`).
step_image_tag	Tag of Docker image used to run the step.
step_name	The name of the step as specified in YAML.
step_node_id	Internal unique ID for node
step_node_name	Name of the node used to run step (user-configured when adding node)
step_node_pool_name	Name of the node pool used to run the step (user configured when creating pool)
step_platform	Same as operating system.
step_runtime	Set to "image" or "host"
step_triggered_by_identity_name	If triggered by a user, name of user. Else empty
step_triggered_by_resource_name	If triggered by a resource, the name of the resource. Otherwise, this environment variable is empty.
step_triggered_by_step_name	If triggered by another step, name of step. Else empty
step_type	The type of step as specified in the field in YAML (e.g., "Bash," "DockerBuild," etc.)
step_url	Direct link to step

Reserved Environment Variables

These environment variables have predefined values and cannot be overridden.

Environment Variable	Description
custom_certs_dir	Location of the custom certificates.
custom_certs_enabled	Indication to use the custom certificates.
no_verify_ssl	Indication for the step to not verify SSL.
run_created_at	Time when the run was created.
step_build_plane_version	The build plane version.
step_dependency_state_dir	Location where input/output dependency information is stored.
step_docker_container_name	Name of the container where the step is running.
step_json_path	Path to the JSON object containing information about the step.
step_namespace	Pipelines extensions namespace. Default is `jfrog`.
step_timeout_seconds	The total number of seconds that the step can run before it times out.
step_tmp_dir	Temporary directory used when the step is executing.
steplet_id	Internal unique ID for the steplet currently executing.
steplet_number	Unique steplet number in the context of the run. Useful for Matrix steps with multiple steplets. Example onExecute: - add_run_variables steplet_${steplet_number}_variable=${env1}

User-defined Environment Variables

User-defined environment variables are custom variables that can be defined in the configuration section of your pipelines YAML file.

Pipelines

In a pipeline, environment variables can be declared within the configuration section. The environment variables declared here are available to all steps in the pipeline.

pipelines:
  - name:       my_pipeline
    configuration:
      environmentVariables:
        readOnly:
          env1:     value1
          env2:     value2

Steps

In a step, environment variables can be declared within the configuration section of the step within a pipeline. The environment variables from this source are available only to the step where they are declared.

    steps:
      - name:       step_1
        type:       Bash
        configuration:
          environmentVariables:
            env1:     value1
            env2:     value2

YAML Schema Reference

When declaring environment variables, it is important to follow YAML syntax conventions and properly quote and escape values to ensure that Pipelines can parse them correctly.

In general, YAML strings are Unicode and can be left unquoted. However, certain rules apply when using special characters. Quotes are required for strings that:

Start with a special character, such as: :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, )
Start or end with whitespace characters
Look like a number or boolean (123, 1.23, true, false, null)

Examples

Single Quotes

Example	Result	Comments
'This string 'uses single quotes''	`This string 'uses single quotes'`	Single quotes let you include almost any character in your string. Single quotes will not parse escape codes. For example: "\n" is returned as the string \n. Use two single quotes (`''`) to include a single quote inside the single-quoted string.
`'This string "uses double quotes"'`	`This string "uses double quotes"`
'& this string starts with a special character, needs quotes'	'& this starts with a special character, needs quotes'

Double Quotes

Example	Result	Comments
`"This string \nis on the next line"`	`This string` `is on the next line`	Double quotes support any character string and escape sequences. For example: `\n`, `\\`, and `\"`)
"This string uses \ttab"	`This string uses tab`

Example

Result

Comments

"This string \nis on the next line"

This string

is on the next line

Double quotes support any character string and escape sequences.

For example: \n, \\, and \")

"This string uses \ttab"

This string uses tab

Multi-line Strings

Multi-line strings can be written using:

Folded Style: Represented by a greater than symbol (>), where each line break is converted to a space.
Literal Style: Represented by a pipe (|), to preserve line breaks.

Folded Style (>)

Example	Result	Comments
`foo: >` `This is a string.` `Another string.` `One more.`	`This is a string. Another one. One more.`	Folded style removes end of line characters and replaces double end of lines with single lines. This is useful for descriptions. Use `>-` if you do not want a line-break appended at the end. Use `>+` if you want a line-break appended at the end.
`execution:` `onExecute:` `- >` `echo "hello"` `echo "world"`	`hello world`

Example

Result

Comments

foo: >

This is a string.

Another string.

One more.

This is a string. Another one. One more.

Folded style removes end of line characters and replaces double end of lines with single lines. This is useful for descriptions.

Use >- if you do not want a line-break appended at the end.
Use >+ if you want a line-break appended at the end.

execution:

onExecute:

- >

echo "hello"

echo "world"

hello world

Literal Style (|)

Example	Result	Comments
`foo: \|` `This is the first line.` `This is the second line.` `This is the third line.`	`This is the first line.` `This is the second line.` `This is the third line.`	Literal style preserves end of line characters. This is useful when defining script actions. Use `\|` `-` if you do not want a line-break appended at the end. Use `\|` `+` if you want a line-break appended at the end.
`execution:` `onExecute:` `- \|` `echo "hello"` `echo "world"`	`hello` `world`

Example

Result

Comments

foo: |

This is the first line.

This is the second line.

This is the third line.

This is the first line.

This is the second line.

This is the third line.

Literal style preserves end of line characters. This is useful when defining script actions.

Use | - if you do not want a line-break appended at the end.
Use | + if you want a line-break appended at the end.

execution:

onExecute:

- |

echo "hello"

echo "world"

hello

world

Escape Sequences

YAML uses escape sequences as follows:

\n is used to represent a new line
\t is used to represent a tab
\\ is used to represent a slash
Bash style "\ " is used to escape additional spaces that are part of the content and should not be folded
The trailing \ is used to represent a continuation marker. This is useful for breaking a long string into multiple lines without introducing unwanted whitespace

Example	Result	Comments
`'price: \$10'`	`price: $10`	Special characters must be escaped with backslash.
'This string has internal \`back ticks\`'	This string has internal `back ticks`	Backticks must be escaped as they are treated specially by the shell.
`'This string has a backslash \\ character'`	`This string has a backslash \ character`
`"This string has \$ several ' special \" characters \\ that are\nescaped as necessary"`	`This string has $ several ' special " characters \ that are` `escaped as necessary"`	In this example: The double quotes enclose the full string. This is done to take advantage of YAML expanding the `\n` into a newline character. Except for the single quote character, everything else is escaped using backslash. Single quote is treated as a character and does not need escaping.

Environment Variables Configuration

Besides the key-value syntax, the following properties can also be used under an environment variable definition to enhance its configuration. The following properties are available for environment variables declared in both pipelines and steps configurationsections.

Important

Environment variable names set at pipeline-level must be unique. A step cannot include the same environment variable name as the one set at the pipeline-level.

Property

Description

Required/Optional

default

Default value for the environment variable.

Required

description

Describes the environment variable usage. This description is displayed in the custom run configuration panel.

Optional

values

List of values that can be assigned to environment variables when custom run configuration is used in the UI.

Optional

allowCustom

Determines if users are allowed to use a custom value that is not part of the list of values. Default value is false.

Optional

secure

Secure environment variables are encrypted variables that can be used in your pipelines without exposing their value. These environment variables are ideal for private information, such as passwords.

When set as true, the value provided is masked in the Pipelines UI. In your pipeline, if you echo, or print a secret environment variable, it is substituted with XXXXX. Default value is false.

As shown in the example below, the secure property requires a default value.

Example
steps: - name: dependency_version_check type: Bash configuration: environmentVariables: mySecureEnv: allowCustom: true secure: true default: "someValue"

Optional

Example

pipelines:
  - name: my_pipeline
    configuration:
      environmentVariables:
        readOnly:
          env1: pipe_value1
          env2:
            default: pipe_value2
            description: This is env2 description
            values:
              - pipe_value2
              - pipe_value3
              - pipe_value4
    steps:
      - name: my_step
        type: Bash
        configuration:
          environmentVariables:
            step_env1:
              default: step_value1
              description: This is step_env1 description
              values:
                - step_value1
                - step_value2
                - step_value3
              allowCustom: true
            step_env2: step_value5
            step_env3:
              allowCustom: true
              secure: true
              default: "someValue"
        execution:
          onExecute:
            - echo "test"

When you trigger a run with custom configuration, the UI uses the configurations in the YAML file to control user input in the Run With Custom Configuration panel:

In the YAML, if allowCustomis set as true, you can enter any value for that field to define your own value for the run. In the example above, you can enter a custom value forstep_env2, in addition to the values that are already defined. Note that the custom value is available for a specific run only.