Environment variables are a common method for customizing pipeline processes and can be used at any stage of a pipeline. This topic describes pipeline environment variables, including built-in variables, custom variables, and common variable groups, and how to use variables in pipelines.
Sources of environment variables
Built-in variables
Alibaba Cloud DevOps provides built-in variables related to basic pipeline information and code sources to help customize processes. You can use these variables as needed.
Module | Environment variable name | Description | Example |
Basic information | PIPELINE_ID | Pipeline ID | None |
BUILD_NUMBER | Pipeline run number, starting from 1 and incrementing by natural numbers | None | |
PIPELINE_NAME | Pipeline name | Frontend Project Release | |
BUILD_REMARK | Remarks about the pipeline run | None | |
BUILD_EXECUTOR | User who triggerred the pipeline | Zhang San | |
BUILD_MESSAGE | Trigger information about the pipeline | Zhang San·manually triggers the pipeline | |
PROJECT_DIR | Working directory for running commands | /root/workspace/1084-abc_docker-08191_b0wE | |
DATETIME | Current time | 2017-06-22-23-26-33 | |
TIMESTAMP | Current timestamp | 1581581273232 | |
Code source (single) | CI_SOURCE_NAME | Name of the code source | None |
CI_COMMIT_REF_NAME | Branch name or tag name of the code source (selected at run time) | master or V1.0 | |
CI_COMMIT_TITLE | Commit message of the last commit | None | |
CI_COMMIT_SHA | Commit ID of the last code version commit | 2bfb63d779e3648c91950f82d374a25784cdabaf | |
CI_COMMIT_ID |
| None | |
Code source (multiple) | CI_SOURCE_NAME_n | Name of the nth code source | None |
CI_COMMIT_REF_NAME_n | Branch name or tag name of the nth code source (selected at run time) | master or V1.0 | |
CI_COMMIT_TITLE_n | Commit message of the last commit for the nth code source | None | |
CI_COMMIT_SHA_n | Commit ID of the last code version commit for the nth code source | 2bfb63d779e3648c91950f82d374a25784cdabaf | |
CI_COMMIT_ID_n | 8-digit commit ID of the last code version commit for the nth code source | None | |
Artifact source | CI_SOURCE_NAME | Name of the artifact source | None |
CI_SOURCE_URL | URL of the artifact source | https://packages.aliyun.com/generic/flow_generic_repo/artifacts?artifactName=Artifacts_2778530&version=2024-01-05-16-28-23 | |
CI_VERSION_NAME | Version number of the artifact source (selected at run time) | 2024-01-05-16-28-23 |
When a pipeline is configured with multiple code sources or artifact sources, you can distinguish different sources based on the variable names and numeric suffixes (the nth code source). The following figure shows the environment variables for three sources:
1: environment variables for a Git-type code source
2: environment variables for an artifact source
3: environment variables for an SVN-type code source
When a user triggers a pipeline, the user can select branches or tags. The variable values change according to the selection. The value of the CI_COMMIT_REF_NAME variable depends on the specific branch or tag selected by the user when triggering the pipeline. If the user manually triggerred the pipeline and selected a specific branch (such as master), the value of CI_COMMIT_REF_NAME is master. If the user selected a tag (such as V1.0), the value of CI_COMMIT_REF_NAME is V1.0.
Custom variables
In addition to built-in pipeline variables, Alibaba Cloud DevOps Flow supports custom pipeline variables to meet more customization scenarios. Custom variables defined within a pipeline are effective only within the pipeline. Select a pipeline, click Edit, and click Variables and Cache. Alibaba Cloud DevOps Flow supports two types of variables: string and enumeration.
String variables
In the String Variables section on the Variables and Cache page of a pipeline, click Create Variable to open the Create Variable dialog box.
Enter the Variable Name and Default Value. Turn on Private Mode and Runtime Settings based on your needs.
Variable Name: Note that environment variable names cannot contain hyphens (-).
Private Mode: Controls whether the variable is publicly visible. If you turn on Private Mode for a variable, the value of the variable cannot be viewed and is not displayed in the corresponding execution logs. You can turn on Private Mode if you need to specify usernames, passwords, and other sensitive information in variable values.
Runtime Settings: Controls whether the variable value needs to be set when the pipeline runs. If you turn on Runtime Settings for a variable, the value of the variable needs to be set when the pipeline runs. You can turn on Runtime Settings if you need to dynamically configure parameter values for a pipeline.
You can add more variables or delete variables.
After clicking Add, you need to save the pipeline to save the variables to the pipeline. After you save the settings, you can use environment variables according to your scenario.
Runtime-selected variables
In the Runtime-Selected Variables section on the Variables and Cache page of a pipeline, click Create Variable to open the Create Variable dialog box.
Enter the Variable Name and Options.
Click Add Option to add multiple options for the variable value.
Turn on Default Value to use the option as the default value of the variable.
After clicking Add, you need to save the pipeline to save the variables to the pipeline. After you save the settings, you can use environment variables according to your scenario.
When you run the pipeline, you need to select the variable value.
Common variable groups
Common variable groups are universal environment variables managed by the organization. You can associate a pipeline with common variable groups to use them.
In the Common Variable Group section on the Variables and Cache page of a pipeline, click Associated Variable Group, select a variable group from the drop-down list, and click OK to associate the variable group with the pipeline.
In the Configure Common Variable Group section, you can view the common variable groups associated with the pipeline, view variable group details, and disassociate variable groups. After you save the settings, you can use environment variables according to your scenario.
Use environment variables
After the variables are defined, you can reference them using the ${XXX} format anywhere in the pipeline where environment variables are needed. Variables take effect according to the following logic:
Variable priority: Step output variables > Pipeline runtime input variables > Pipeline variables > Common variable groups.
When a pipeline is associated with multiple common variable groups and duplicate variable names exist across groups, the value from the most recently associated variable group takes precedence.
The following sections describe several typical scenarios for using environment variables, such as command execution, host deployment, image build parameters, configuration file parameters, and environment variable passing.
Use variables in command execution
Change the parameter value of the key in the a.conf configuration file from 123 to the value of an environment variable named abc.
Use variables in host deployment
You can directly reference environment variables using the ${XXX} format in deployment scripts to control host deployment logic. After running the pipeline, check the logs in the host deployment step.
Use variables as image build parameters
To use pipeline environment variables as build parameters when building images, perform the following operations:
In the image build step, use a specified container environment, add custom parameters in the build parameters, and assign environment variables to build parameters using the
${XXX}format. Build parameters are passed to the build command as--build-argparameters.
In the Dockerfile, reference variables using
ARG argName.
Use variables in configuration file parameters
If you need to modify a parameter in your configuration file using an environment variable, for example, you need to replace the username parameter in the a.conf configuration file of your code repository with an environment variable, perform the following operations:
Set the
usernameparameter in thea.confconfiguration file to${abc}.Configure
abcas an environment variable of the pipeline and set the default value tomy_name_is_hanmeimei.Add a job in the pipeline, find and add the Replace EnvVar in File step in the Utilities section, and enter the Source File Path of the configuration file. The Target File Path is optional. If you enter the Target File Path, a new configuration file is generated. If you do not enter the Target File Path, the original file is modified.
Expected result:
usernameina.confis changed tomy_name_is_hanmeimeiinb.conf.NoteEach Flow pipeline job shares a workspace. Therefore, you must place the step to modify configuration file variables in the same job as the subsequent steps that use the configuration file.
Environment variable passing
Environment variables defined on the pipeline configuration page are preset environment variables with fixed values. During the actual pipeline execution, environment variables may need to be defined as outputs during pipeline runtime and need to be passed to subsequent steps or jobs. The following scenarios are involved:
Passing environment variables within a job: Step 1 generates a custom environment variable -> Step 2 uses it.
Passing environment variables between jobs: Job 1 generates an environment variable -> Job 2 uses it.
Different syntax is required when you use different build environments.
Specified container environment or default VM environment
Passing environment variables within a job
This scenario mainly involves sharing environment variables within a single job node. For example, Step 1 generates the variable yaojia_Test=myParam, and Step 2 references it using ${yaojia_Test}.
You can inject environment variables by outputting them to $FLOW_ENV in the preceding step using echo "yaojia_Test=myParam" >> "$FLOW_ENV".
Passing environment variables between jobs
This scenario mainly involves sharing environment variables between multiple job nodes within a pipeline. For example, Job 1 generates the variable yaojia_Test=myParam, and Job 2 references it using ${yaojia_Test}.
You can inject environment variables by outputting them to
$FLOW_ENVin a step of Job 1.In Job 1, choose , and set the environment variable as a pipeline-level environment variable.
In Job 2, reference the environment variable using
${yaojia_Test}.
