Pipelines Environment Variables

Standard Environment Variables

These environment variables are available to all executing pipelines.

Reserved Environment Variables

These environment variables have predefined values and cannot be overridden. 

 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

'This string 'uses single quotes''

Double Quotes

"This string uses \ttab"

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 (>)

Literal Style (|)

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

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 configuration sections.

pipelines:
  - name: my_pipeline
    configuration:
      environmentVariables:
        readOnly:
          env1: value1
          env2:
            default: value1
            description: env2 description
            values:
              - value1
              - value2
              - value3
    steps:
      - name: my_step
        type: Bash
        configuration:
          environmentVariables:
            step_env1:
              default: value1
              description: step env1 description
              values:
                - value1
                - value2
                - value3
              allowCustom: true
            step_env2: value2
        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 allowCustom is 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 for step_env2, in addition to the values that are already defined. Note that the custom value is available for a specific run only. 

Integrations

A step that uses an integration can access an integration's properties through environment variables. The form of the environment variable is:

int_<integration name>_<tag>

For example, you can access the URL property of an Artifactory Integration named myArtifactory through an environment variable:

$ printenv int_myArtifactory_url
https://mycompany.com/artifactory/

You can also access the properties of an integration through a resource that uses it. The form of the environment variable is:

res_<resource_name>_<integration tag name>_<tag>

For example, an Image resource specifies an Artifactory integration in its registry tag.  You can access the URL of the Artifactory integration used by an Image resource called myImage as follows:

$ printenv res_myImage_registry_url	
https://mycompany.com/artifactory/

For more information, see Pipelines Integrations.

Resources

A step that specifies a resource in inputresources can access the properties of that resource through environment variables. The form of the environment variable is:

res_<resource name>_<tag>

For example, you can access the imageName property of an Image resource myImage through an environment variable:

$ printenv res_myImage_imageName
jfrog.local:5000/alpine37

Some resources maintain additional properties that may be accessed as environment variables. These resource types include:

• GitRepo

For further information see Pipelines Resources.

Resource-based State

Additionally, you can add your own properties to a resource that is specified in outputresources using the write_output utility function. This can be used to create stateful pipelines.

The newly attached properties can be accessed as environment variables of the form res_{Resource Name}_{Key Name}.  For example, the following creates three properties in the resource myImage.

write_output myImage sport="baseball" equipment="bat" field="diamond"

When the resource is specified in a step's inputsources, these properties can be accessed as the following environment variables:

$ printenv res_myImage_baseball
baseball
$ printenv res_myImage_equipment
bat
$ printenv res_myImage_field
diamond

For more information on run state, see Creating Stateful Pipelines.

Run State

Your pipeline can define its own environment variables and add them to the pipeline's run state. These will be available to all steps in the run of the pipeline.

Use the utility functions for run state management to add new environment variables to the current run state. For example, the following line in the execution block of a step:

add_run_variables hero="Superman" villain="Lex Luthor"

will create two environment variables available to the current and all future steps of the pipeline's run:

$ printenv hero
Superman
$ printenv villain
Lex Luthor

For more information on run state, see Creating Stateful Pipelines.

Pipeline State

Your pipeline can define its own environment variables and add them to the pipeline state. These will be available to all runs of that pipeline.

Use the utility functions for pipeline state management to add new environment variables to the current run state. For example, the following line in the execution block of a step:

add_pipeline_variables animal="dog" vegetable="carrot"

will create two environment variables available to all run of the pipeline where they were defined:

$ printenv animal
dog
$ printenv vegetable
carrot

For more information on pipeline state, see Creating Stateful Pipelines.