GitLab CI/CD environment variables

GitLab CI/CD environment variables

环境变量是一个动态命名的值，它可以影响正在运行的进程在操作系统上的行为方式.

环境变量是进程在其中运行的环境的一部分. 例如，正在运行的进程可以查询TEMP环境变量的值以发现合适的位置来存储临时文件，或者为可以在不同脚本中重用的数据库定义URL .

变量对于在 GitLab CI / CD 中自定义作业很有用. 使用变量时，不必对值进行硬编码.

有关高级使用 GitLab CI / CD 的更多信息：

  • 由 GitLab 工程师共享的这可以更快地提高生产力.
  • 了解 Cloud Native Computing Foundation（CNCF）如何通过 GitLab CI / CD 消除许多云提供商之间管理项目 .

GitLab CI / CD 具有一组默认的预定义变量 ，您可以使用它们而无需任何其他说明. 您可以呼叫问题编号，用户名，分支名称，管道和提交 ID 等.

GitLab 为 Runner 的本地环境提供了预定义的环境变量.

GitLab 读取.gitlab-ci.yml文件，并将信息发送到 Runner，在此处公开变量. 然后，运行程序运行脚本命令.

您可以选择现有的预定义变量之一，以由 Runner 输出.

本示例说明如何使用预定义变量CI_JOB_STAGE输出作业的阶段.

在您的.gitlab-ci.yml文件中，从脚本中调用变量. 确保使用正确的 .

在这种情况下，跑步者输出工作test_variable的stage ，即test ：

再举一个例子，假设您使用自己的 GitLab 实例，并且想知道 GitLab 页面在哪个域下提供服务. 您可以通过在脚本中使用预定义变量$CI_PAGES_DOMAIN来调用它：

  1. pages:
  2.   script:
  3.     - ...
  4.     - echo $CI_PAGES_DOMAIN

对于 GitLab.com 用户，输出将为gitlab.io . 对于您的私有实例，输出将是您的系统管理员定义的任何内容.

Custom environment variables

当需要特定的自定义环境变量时，可以在 UI中中或直接在.gitlab-ci.yml文件中进行设置 .

每当管道运行时，Runner 就会使用这些变量. 您还 .

变量有两种类型： Variable和File . 您无法在.gitlab-ci.yml文件中设置类型，但可以在 UI 和 API 中进行设置.

Create a custom variable in .gitlab-ci.yml

要创建自定义env_var在可变文件中，定义下的变量/值对variables ：

  1. variables:
  2.   TEST: "HELLO  WORLD"

然后，您可以在脚本中调用其值：

  1.  script:
  2.     - echo "$TEST"

有关更多详细信息，请参见.gitlab-ci.yml定义的变量 .

Create a custom variable in the UI

在用户界面中，您可以添加或更新自定义环境变量：

  1. 转到项目的“设置”>” CI / CD”，然后展开” 变量”部分.

  2. 单击添加变量按钮. 在” 添加变量模式”中，填写详细信息：

    • 密钥 ：必须是一行，没有空格，只能使用字母，数字或_ .
    • 价值 ：无限制.
    • Type: File or Variable.
    • 环境范围 ： All或特定环境.
    • 保护变量 （可选）：如果选中，则该变量将仅在在受保护的分支或标签上运行的管道中可用.
    • 屏蔽变量 （可选）：如果选中，则变量的值将在作业日志中被屏蔽. 如果该值不满足屏蔽要求，则变量将无法保存.

创建变量后，您可以通过点击 编辑按钮.

设置变量后，请从.gitlab-ci.yml文件中调用它：

  1. test_variable:
  2.   stage: test
  3.   script:
  4.     - echo $CI_JOB_STAGE # calls a predefined variable
  5.     - echo $TEST # calls a custom variable of type `env_var`
  6.     - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file
  7.     - cat $GREETING # the temp file itself contains the variable value

输出将是：

Custom environment variables of type Variable

在 GitLab 11.11 中 .

对于类型为Variable 的变量 ，Runner 会创建一个环境变量，该环境变量将键用作名称，并将值用作值.

有一些这种类型的 ，可以进一步验证. 它们在您在 UI 中添加或更新变量时出现.

Custom environment variables of type File

在 GitLab 11.11 中 .

对于File类型的变量，Runner 创建一个环境变量，该环境变量使用键作为名称. 对于该值，Runner 将变量值写入临时文件并使用此路径.

您可以使用诸如AWS CLI和类的工具通过使用File type 变量来自定义配置.

过去，常见的模式是读取 CI 变量的值，将其保存在文件中，然后在脚本中使用新创建的文件：

  1. # Read certificate stored in $KUBE_CA_PEM variable and save it in a new file
  2. echo "$KUBE_CA_PEM" > "$(pwd)/kube.ca.pem"
  3. kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$(pwd)/kube.ca.pem"

代替此，您可以使用文件类型变量. 例如，如果您具有以下变量：

  • 类型为Variable ： KUBE_URL 变量 ，其值为https://example.com .
  • 类型为File ： KUBE_CA_PEM变量，其值为证书.

您可以从.gitlab-ci.yml调用它们，如下所示：

  1. kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"

Mask a custom variable

在 GitLab 11.10 中引入

可以屏蔽变量，以便将变量的值隐藏在作业日志中.

要屏蔽变量：

  1. 转到设置> CI / CD .
  2. 展开变量部分.
  3. 在您要保护的变量旁边，点击编辑 .
  4. 选择掩码变量复选框.
  5. Click 更新变量.

Masked variable requirements

变量的值必须：

  • 在一行中.
  • 至少要包含 8 个字符.
  • 不是预定义或自定义环境变量.
  • 仅由 Base64 字母（RFC4648）中的字符组成. 在 GitLab 12.2和更高版本中， @和:也是有效值.

您不能屏蔽不满足这些要求的变量.

在 GitLab 9.3 中引入.

变量可以被保护. 受保护的变量将安全地传递到仅在或受保护的标签上运行的管道. 其他管道不获取受保护的变量.

要保护变量：

  1. 转到设置> CI / CD .
  2. 展开变量部分.
  3. 在您要保护的变量旁边，点击编辑 .
  4. 选择保护变量复选框.
  5. Click 更新变量.

该变量可用于所有后续管道. 受保护的变量只能由拥有项目成员更新或查看.

Custom variables validated by GitLab

UI 中列出了一些变量，因此您可以更快地选择它们. GitLab 会验证这些变量的值，以确保它们的格式正确.

注意：存储凭据时，会涉及安全性. 例如，如果您使用的是 AWS 密钥，请遵循其 .

Syntax of environment variables in job scripts

所有变量都在构建环境中设置为环境变量，并且可以使用用于访问此类变量的常规方法来访问它们. 在大多数情况下， bash或sh用于执行作业脚本.

Shell Usage
bash/sh $variable
PowerShell $env:variable （主$env:variable ）或$variable
Windows 批处理 %variable%

Bash

要在bash 中访问环境变量，请在变量名前加上（ $ ）：

  1. job_name:
  2.   script:
  3.     - echo $CI_JOB_ID

PowerShell

要访问Windows PowerShell环境中的环境变量，请在变量名前加上（ $env: . 对于由 GitLab CI 设置的环境变量，包括由参数设置的环境variables ，还可以通过在 ，通过在变量名称前加上（ $ ）来访问它们. 但是，必须使用（ $env:访问系统设置的环境变量.

在某些情况下，环境变量可能需要用引号引起来才能正确扩展：

  1. job_name:
  2.   script:
  3.     - D:\\qislsf\\apache-ant-1.10.5\\bin\\ant.bat "-DsosposDailyUsr=$env:SOSPOS_DAILY_USR" portal_test

Windows Batch

要访问Windows Batch 中的环境变量，请用（ % ）包围变量：

  1. job_name:
  2.   script:
  3.     - echo %CI_JOB_ID%

List all environment variables

您还可以使用 Bash 中的export命令或 PowerShell 中的dir env:命令列出所有环境变量. 请注意，这还将在作业日志中公开您设置的所有变量的值：

  1. job_name:
  2.   script:
  3.     - export
  4.     # - 'dir env:' # use this for PowerShell

值示例：

  1. export CI_JOB_ID="50"
  2. export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
  3. export CI_COMMIT_SHORT_SHA="1ecfd275"
  4. export CI_COMMIT_REF_NAME="master"
  5. export CI_REPOSITORY_URL="https://gitlab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-foss.git"
  6. export CI_COMMIT_TAG="1.0.0"
  7. export CI_JOB_NAME="spec:other"
  9. export CI_JOB_MANUAL="true"
  10. export CI_JOB_TRIGGERED="true"
  11. export CI_JOB_TOKEN="abcde-1234ABCD5678ef"
  12. export CI_PIPELINE_ID="1000"
  13. export CI_PIPELINE_IID="10"
  14. export CI_PAGES_DOMAIN="gitlab.io"
  15. export CI_PAGES_URL="https://gitlab-org.gitlab.io/gitlab-foss"
  16. export CI_PROJECT_ID="34"
  17. export CI_PROJECT_DIR="/builds/gitlab-org/gitlab-foss"
  18. export CI_PROJECT_NAME="gitlab-foss"
  19. export CI_PROJECT_TITLE="GitLab FOSS"
  20. export CI_PROJECT_NAMESPACE="gitlab-org"
  21. export CI_PROJECT_ROOT_NAMESPACE="gitlab-org"
  22. export CI_PROJECT_PATH="gitlab-org/gitlab-foss"
  23. export CI_PROJECT_URL="https://example.com/gitlab-org/gitlab-foss"
  24. export CI_REGISTRY="registry.example.com"
  25. export CI_REGISTRY_IMAGE="registry.example.com/gitlab-org/gitlab-foss"
  26. export CI_REGISTRY_USER="gitlab-ci-token"
  27. export CI_REGISTRY_PASSWORD="longalfanumstring"
  28. export CI_RUNNER_ID="10"
  29. export CI_RUNNER_DESCRIPTION="my runner"
  30. export CI_RUNNER_TAGS="docker, linux"
  31. export CI_SERVER="yes"
  32. export CI_SERVER_URL="https://example.com"
  33. export CI_SERVER_HOST="example.com"
  34. export CI_SERVER_PORT="443"
  35. export CI_SERVER_PROTOCOL="https"
  36. export CI_SERVER_NAME="GitLab"
  37. export CI_SERVER_REVISION="70606bf"
  38. export CI_SERVER_VERSION="8.9.0"
  39. export CI_SERVER_VERSION_MAJOR="8"
  40. export CI_SERVER_VERSION_MINOR="9"
  41. export CI_SERVER_VERSION_PATCH="0"
  42. export GITLAB_USER_EMAIL="user@example.com"
  43. export GITLAB_USER_ID="42"

.gitlab-ci.yml defined variables

注意：此功能需要 GitLab Runner 0.5.0 或更高版本以及 GitLab 7.14 或更高版本.

您可以将在构建环境中设置的变量添加到.gitlab-ci.yml . 这些变量保存在存储库中，它们旨在存储非敏感项目配置，例如RAILS_ENV或DATABASE_URL .

例如，如果将变量全局设置为下方（而不是在作业内部），它将在所有已执行的命令和脚本中使用：

  1. variables:
  2.   DATABASE_URL: "postgres://postgres@postgres/my_database"

还将 YAML 定义的变量设置为所有创建的服务容器 ，以便您可以对其进行微调.

变量可以在全局级别定义，也可以在作业级别定义. 要在作业中关闭全局定义的变量，请定义一个空哈希：

  1. job_name:
  2.   variables: {}

您可以在变量定义内使用其他变量（或使用$$对其进行转义）：

  1. variables:
  2.   LS_CMD: 'ls  $FLAGS  $$TMP_DIR'
  3.   FLAGS: '-al'
  4. script:
  5.   - 'eval  $LS_CMD'  # will execute 'ls -al $TMP_DIR'

Introduced in GitLab 9.4.

您可以定义在管道环境中设置的每个项目或每个组的变量. 组级变量存储在存储库之外（不在.gitlab-ci.yml ），并安全地传递到 GitLab Runner，这使它们在管道运行期间可用. 对于不使用外部密钥存储或使用 GitLab 高级用户，我们建议使用组环境变量来存储密码，SSH 密钥和凭据之类的机密.

组级变量可以通过以下方式添加：

  1. 导航到组的“设置”>” CI / CD”页面.
  2. 在” 变量”部分中输入变量类型，键和值. 子组的任何变量将被递归继承.

设置它们后，它们将可用于所有后续管道. 可以通过以下方式在项目中查看任何组级用户定义的变量：

  1. 导航到项目的“设置”>” CI / CD”页面.
  2. 展开变量部分.

Instance-level CI/CD environment variables

在 GitLab 13.0 中 .

实例变量非常有用，因为不再需要为所有项目重复手动输入相同的凭据. 实例级变量可用于实例上的所有项目和组.

注意：实例级变量的最大数量计划为 25 .

您可以通过 UI 或定义实例级变量.

要添加实例级变量：

  1. 导航到管理区域的“设置”>” CI / CD”，然后展开” 变量”部分.

  2. 单击添加变量按钮，然后填写详细信息：

    • 密钥 ：必须为一行，只能使用字母，数字或_ （下划线），且不能有空格.
    • 值 ：允许 700 个字符.
    • Type: File or Variable.
    • 保护变量 （可选）：如果选中，则该变量将仅在在受保护的分支或标签上运行的管道中可用.
    • 屏蔽变量 （可选）：如果选中，则变量的值将不会显示在作业日志中. 如果该值不满足屏蔽要求，则不会保存该变量.

创建变量后，您可以通过点击 编辑按钮.

实例级 CI / CD 变量的 UI 界面正在开发中，但可用于生产环境. 它部署在默认情况下启用的功能标志的后面. 可以选择为您的实例禁用它.

禁用它：

要启用它：

  1. Feature.enable(:instance_variables_ui)

Inherit environment variables

版本历史

  • 在 GitLab 13.0 后面的禁用功能标志 ： ci_dependency_variables .

您可以从相关作业中继承环境变量.

该功能利用了报告功能.

带有dependencies关键字的示例.

  1. build:
  2.   stage: build
  3.   script:
  4.     - echo "BUILD_VERSION=hello" >> build.env
  5.   artifacts:
  6.     reports:
  7.       dotenv: build.env
  9. deploy:
  10.   stage: deploy
  11.   script:
  12.     - echo $BUILD_VERSION # => hello
  13.   dependencies:
  14.     - build

带关键字的示例：

  1. build:
  2.   stage: build
  3.   script:
  4.     - echo "BUILD_VERSION=hello" >> build.env
  5.   artifacts:
  6.     reports:
  7.       dotenv: build.env
  9. deploy:
  10.   stage: deploy
  11.   script:
  12.     - echo $BUILD_VERSION # => hello
  13.   needs:
  14.     - job: build
  15.       artifacts: true

Priority of environment variables

不同类型的变量可以优先于其他变量，具体取决于它们的定义位置.

变量的优先顺序为（从最高到最低）：

  1. ， 计划的管道变量和 .
  2. Project-level variables or .
  3. Group-level variables or .
  4. Inherited environment variables.
  5. YAML-defined .
  6. YAML-defined global variables.
  7. .
  8. Predefined environment variables.

例如，如果您定义：

  • API_TOKEN=secure作为项目变量.
  • 您的.gitlab-ci.yml API_TOKEN=yaml .

API_TOKEN将采用值，因为项目变量优先于.gitlab-ci.yml定义.gitlab-ci.yml .

Variable names are limited by the underlying shell used to execute scripts (see . Each shell has its own unique set of reserved variable names. You will also want to keep in mind the scope of environment variables to ensure a variable is defined in the scope in which you wish to use it.

Where variables can be used

单击此处以获得描述在何处以及如何使用不同类型的变量的部分.

Advanced use

Limit the environment scopes of environment variables

您可以通过变量可用于的环境来限制变量的环境范围.

要了解有关范围界定环境的更多信息，请参阅使用规范范围界定环境 .

Deployment environment variables

在 GitLab 8.15 中引入.

负责部署配置的集成可以定义在构建环境中设置的自己的变量. 这些变量仅为定义. 请查阅所用集成的文档，以了解它们定义了哪些变量.

定义部署变量的示例集成是Kubernetes 集成 .

Auto DevOps environment variables

在 GitLab 11.7 中引入 .

您可以配置以将 CI 变量传递给正在运行的应用程序，方法是在变量的键之前添加K8S_SECRET_ .

然后，这些前缀变量将在运行的应用程序容器上用作环境变量.

警告：由于当前 Auto DevOps 脚本环境的限制，当前不支持具有多行值的变量.

Override a variable by manually running a pipeline

您可以通过手动运行管道来覆盖当前变量的值.

例如，假设您添加了一个名为$TEST的自定义变量，并且想在手动管道中覆盖它.

导航到项目的CI / CD>管道 ，然后单击运行管道 . 选择要为其运行管道的分支，然后在 UI 中添加变量及其值：

运行器将覆盖先前设置的值，并将自定义值用于此特定管道.

Environment variables expressions

版本历史

使用变量表达式来限制将更改推送到 GitLab 之后在管道中创建的作业.

在.gitlab-ci.yml ，变量表达式可同时用于以下两种情况：

  • rules ，这是推荐的方法，以及
  • ，它们是不推荐使用的候选对象.

与变量和触发的管道变量结合使用时，这特别有用.

  1. deploy:
  2.   script: cap staging deploy
  3.   environment: staging
  4.   only:
  5.     variables:
  6.       - $RELEASE == "staging"
  7.       - $STAGING

在创建管道之前，将对提供的每个表达式进行求值.

如果only使用时variables任何条件评估为 true，则会创建一个新作业. 如果在使用except任何表达式的结果为 true，则不会创建作业.

这遵循only / except策略的常规规则.

Syntax of environment variable expressions

您可以在下面找到受支持的语法参考：

  1. 使用字符串进行相等匹配

    Examples:

    • $VARIABLE == "some value"
    • $VARIABLE != "some value" （在 GitLab 11.11 中引入）

    您可以使用等于运算符==或!=将变量内容与字符串进行比较. 我们支持双引号和单引号来定义字符串值，因此同时支持$VARIABLE == "some value"和$VARIABLE == 'some value' . "some value" == $VARIABLE也正确.

  2. 检查未定义的值

    Examples:

    • $VARIABLE == null
    • $VARIABLE != null （在 GitLab 11.11 中引入）

    有时，您可能想检查是否定义了变量. 为此，您可以将变量与null关键字进行比较，例如$VARIABLE == null . 如果在使用==时未定义变量，则该表达式的值为 true；如果使用!=则该表达式的值为 false.

  3. 检查空变量

    Examples:

    • $VARIABLE == ""
    • $VARIABLE != "" (introduced in GitLab 11.11)

    如果要检查变量是否已定义但为空，则可以将其与空字符串（例如$VAR == ''或非空字符串$VARIABLE != "" .

  4. 比较两个变量

    Examples:

    • $VARIABLE_1 == $VARIABLE_2
    • $VARIABLE_1 != $VARIABLE_2 （在 GitLab 11.11 中引入）

    可以比较两个变量. 这将比较这些变量的值.

  5. 可变状态检查

    Example: $STAGING

    如果只想在存在某个变量时创建作业，这意味着它是已定义且非空的，则可以简单地使用变量名作为表达式，例如$STAGING . 如果$STAGING变量已定义且不为空，则表达式将求值为真. $STAGING值必须是长度大于零的字符串. 仅包含空格字符的变量不是空变量.

  6. 模式匹配（在 GitLab 11.0 中引入）

    Examples:

    • =~ ：如果模式匹配则为真. 例如： $VARIABLE =~ /^content.*/
    • !~ ：如果模式不匹配，则为 true. 例如： $VARIABLE_1 !~ /^content.*/ （在 GitLab 11.11 中引入 ）

    与正则表达式匹配的变量模式使用 . 如果满足以下条件，则表达式的计算结果为true ：

    • 使用=~时找到匹配项.
    • 当使用火柴都没有发现!~

    模式匹配默认情况下区分大小写. 使用i标志修饰符，例如/pattern/i ，使模式不区分大小写.

  7. Conjunction / Disjunction (introduced in GitLab 12.0)

    Examples:

    • $VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"
    • $VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3
    • $VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3

    可以使用&&或||加入多个条件 . 任何在其他情况下受支持的语法都可以在合并或不合并语句中使用. 运算符的优先级遵循 ，因此&&在||之前进行评估 .

可以将正则表达式存储在变量中，以用于模式匹配：

  1. variables:
  2.   STAGINGRELS: '/staging0|staging1/'
  4. deploy_staging:
  5.   script: do.sh deploy staging
  6.   environment: staging
  7.   rules:
  8.     - if: '$RELEASE  =~  $STAGINGRELS'

注意：可用的正则表达式语法受到限制. 有关更多详细信息，请参见相关问题 .

如果需要，您可以使用测试管道来确定正则表达式是否可以在变量中工作. 下面的示例直接从变量内部测试^mast.*正则表达式：

  1. variables:
  2.   MYSTRING: 'master'
  3.   MYREGEX: '/^mast.*/'
  5. testdirect:
  6.   script: /bin/true
  7.   rules:
  8.     - if: '$MYSTRING  =~  /^mast.*/'
  10. testvariable:
  11.   script: /bin/true
  12.   rules:
  13.     - if: '$MYSTRING  =~  $MYREGEX'

在 GitLab Runner 1.7 中引入.

警告：启用调试跟踪可能会严重影响安全性. 输出将包含所有变量和其他任何秘密的内容！ 输出将上传到 GitLab 服务器，并在作业日志中显示！

默认情况下，GitLab Runner 隐藏处理作业时所执行操作的大多数细节. 此行为使作业日志简短，并防止机密信息泄露到日志中，除非您的脚本将其写入屏幕.

如果一项工作没有按预期进行，则可能使问题难以调查. 在这种情况下，您可以在.gitlab-ci.yml启用调试跟踪. 在 GitLab Runner v1.7 +上可用，此功能启用外壳程序的执行日志，从而产生详细的作业日志，其中列出了所有已运行的命令，已设置的变量等.

在启用此功能之前，您应确保作业可见. 您还应该清除所有生成的作业日志，然后才能再次显示它们.

要启用调试日志（跟踪），请将CI_DEBUG_TRACE变量设置为true ：

  1. job_name:
  2.   variables:
  3.     CI_DEBUG_TRACE: "true"

将CI_DEBUG_TRACE设置为示例截断输出：

Video walkthrough of a working example

使用 GitLab 管理复杂配置数据管理怪兽视频是工作示例项目的演练. 它解释了如何将多个级别的组 CI / CD 变量与环境范围的项目变量组合在一起，以实现应用程序构建或部署的复杂配置.