Environment variables

Built-in variables

Alibaba Cloud DevOps pipelines provide built-in variables related to basic information and code sources. You can use these variables to customize your workflow.

To access information for a specific code or artifact source when multiple exist, append a numeric suffix to the variable name.

For example, a pipeline can have a Git code source (source 1), an artifact source (source 2), and an SVN code source (source 3). After the pipeline runs, you can view the actual values of all variables in the run details. Numeric suffixes distinguish variables for multiple sources, such as CI_COMMIT_REF_NAME_1 and CI_COMMIT_REF_NAME_2.

The value of the CI_COMMIT_REF_NAME variable depends on the specific branch or tag you select when you trigger the pipeline. If you manually trigger the pipeline and select the master branch, the value of CI_COMMIT_REF_NAME is master. If you select the V1.0 tag, its value is V1.0. This runtime selection lets you run the pipeline on different branches or tags, and the variable's value changes accordingly.

When you trigger a pipeline run, you can select a specific branch or tag in the run dialog box. The selected value becomes the runtime value of the CI_COMMIT_REF_NAME variable.

Custom variables

In addition to built-in variables, Alibaba Cloud DevOps Flow supports custom variables. Each custom variable is scoped to the pipeline where it is defined. To create a custom variable, select a pipeline, click Edit, and then go to the Variables and Cache tab. Alibaba Cloud DevOps Flow supports string and enumeration variable types.

This tab contains configuration areas for string variables and runtime-selected variables.

Common variable groups

A common variable group is a collection of environment variables that your organization manages centrally. You can associate a pipeline with a group to use its variables.

1. On the Variables and Cache tab, in the Common Variable Group section, click Associate Variable Group. Select a variable group from the drop-down list and click OK to link it to the pipeline.

2. In this section, you can view details of the associated variable groups or unlink them. After saving the pipeline, you can use the variables as described in Use environment variables.

Default environment

Pass variables within a job

In this scenario, you share environment variables within a single job. For example, Step 1 generates the variable USER_abc=123, and Step 2 references it by using ${USER_abc}.

In a preceding step, you can inject the environment variable by running echo 'USER_abc=123' > .env to write the variable to the .env file. Note: Environment variables in the .env file must have names that start with USER_.

# Step 1: Inject the environment variable
echo 'USER_abc=123' > .env

# Step 2: Reference the environment variable
echo $USER_abc
123

# Step 1: Write the environment variable to .env
echo 'USER_abc=123' > .env

# Step 2: Read the environment variable
echo $USER_abc
123

Pass variables between jobs

In this scenario, you share environment variables between multiple jobs in a pipeline. For example, Job 1 generates the variable USER_abc=123, and Job 2 references it by using ${USER_abc}.

• In a step in Job 1, inject the environment variable by writing it to the .env file. Note: The variable name must start with USER_.

• In Job 1, add another step by choosing to promote the environment variable to the pipeline level.

• In Job 2, you can then use ${USER_abc} to reference the variable.

After Job 1 injects and promotes the variable, Job 2 can reference it by using ${USER_abc}.

# Execution log of Job 2
echo $USER_abc
123
# [Success]

Usage notes for the default environment

• Use append mode to prevent overwriting — When you write variables to the .env file, use the append operator (>>). Do not use the overwrite operator (>), because it replaces all previously written variables.

  # Correct: append mode preserves existing variables
  echo 'USER_abc=123' >> .env
  echo 'USER_xyz=456' >> .env
  
  # Incorrect: overwrite mode — USER_abc is lost
  echo 'USER_abc=123' > .env
  echo 'USER_xyz=456' > .env

• Same-step read limitation — After you write a variable to the .env file by using echo, you cannot immediately read the variable in the same step by referencing $KEY. Variables are loaded into the runtime context only after the current step finishes. To verify a variable value, read it in a subsequent step.

• Kubernetes deployment workaround — If a variable defined in a shell script step is unavailable or returns a default value in a Kubernetes deployment step, add a Set Variables step (navigate to Add Step > Utilities > Set Variables) after the shell step. In this step, explicitly assign the variable to a new variable name that the Kubernetes step can reference.

• Extract a version number dynamically — To extract a version number from a build artifact such as pom.xml and pass it to downstream steps:

  # Extract the version from pom.xml
  VERSION=$(grep -m1 '<version>' pom.xml | sed 's/.*<version>\(.*\)<\/version>.*/\1/')
  echo "USER_VERSION=$VERSION" >> .env

Container or VM environment

Pass variables within a job

In this scenario, you share environment variables within a single job. For example, Step 1 generates the variable yaojia_Test=myParam, and Step 2 references it by using ${yaojia_Test}.

In a preceding step, you can inject the environment variable by running echo "yaojia_Test=myParam" >> "$FLOW_ENV" to append the variable to the $FLOW_ENV file.

# Execution log of Step 2
echo $yaojia_Test
myParam
# [Success]

# Execution log of Job 2
echo $yaojia_Test
myParam
# [Success]

Usage notes for the container or VM environment

• Use append mode to prevent overwriting — When you write variables to $FLOW_ENV, use the append operator (>>). Do not use the overwrite operator (>), because it replaces all previously written variables.

  # Correct: append mode preserves existing variables
  echo "VAR_A=value1" >> "$FLOW_ENV"
  echo "VAR_B=value2" >> "$FLOW_ENV"
  
  # Incorrect: overwrite mode — VAR_A is lost
  echo "VAR_A=value1" > "$FLOW_ENV"
  echo "VAR_B=value2" > "$FLOW_ENV"

• Same-step read limitation — After you write a variable to $FLOW_ENV by using echo, you cannot immediately read the variable in the same step by referencing $KEY. Variables are loaded into the runtime context only after the current step finishes. To verify a variable value, read it in a subsequent step.

• Kubernetes deployment workaround — If a variable defined in a shell script step is unavailable or returns a default value in a Kubernetes deployment step, add a Set Variables step (navigate to Add Step > Utilities > Set Variables) after the shell step. In this step, explicitly assign the variable to a new variable name that the Kubernetes step can reference.

• Extract a version number dynamically — To extract a version number from a build artifact such as pom.xml and pass it to downstream Docker image build steps:

  # Extract the version from pom.xml
  VERSION=$(grep -m1 '<version>' pom.xml | sed 's/.*<version>\(.*\)<\/version>.*/\1/')
  echo "IMAGE_VERSION=$VERSION" >> "$FLOW_ENV"

• Troubleshoot variable setting issues — If variables do not take effect or cause errors in a container environment, verify the following:

  • You have added a Set Variables step to promote the variable to the pipeline level.

  • The syntax matches the target environment. Use echo "KEY=VALUE" >> "$FLOW_ENV" for the container or VM environment. Do not use echo 'USER_KEY=VALUE' > .env, which applies only to the default environment.