使用环境变量

This document describes using environment variables in CircleCI in the following sections:

概要

有几种方法可以在Circleci中使用环境变量来提供范围和授权级别的变化。环境变量受到了一个优先顺序, depending on how they are set, allowing control at each level in your configuration.

To addprivate keysor秘密环境变量for use throughout your private project, use the环境变量page under Project Settings在CircleCI应用程序。这个变量的值re neither readable nor editable in the app after they are set. To change the value of an environment variable, delete the current variable and add it again with the new value.

私有环境变量使您能够在公共项目时安全地存储秘密。参考Building Open Source Projects关联设置信息的页面。

使用上下文到further restrict access to environment variables。背景are set from the Organization Settings in the CircleCI application. For more information about controlling access to env vars with Contexts, refer to the限制上下文文档。

掩蔽掩蔽

掩蔽掩蔽是不currently available on self-hosted installations of CircleCI Server

秘密屏蔽应用于项目设置或上下文中设置的环境变量。环境变量可以保留对应用程序执行重要函数的项目秘密或键。秘密屏蔽通过在作业输出中暗示环境变量时,为Circleci提供了额外的安全性echoor打印使用。

if中的环境变量的值将不会在构建输出中屏蔽:

  • 环境变量的值少于4个Characaters
  • 环境变量的值等于其中一个真正,真正,or

Note:Secrets Masking will only prevent the value of the environment variable from appearing in your build output. The value of the environment variable is still accessible to users调试与ssh构建

重命名组织和存储库

如果您发现您需要重命名您之前已连接到Circleci的Org或Repo,则最佳实践是按照下列步骤操作:

  1. Rename org/repo in VCS.
  2. 例如,使用新的ORG / repo名称,使用新的ORG / repo名称,app.www.drag240sx.com/pipelines/ / /
  3. 确认您的计划,项目和设置已成功转移。
  4. 然后,您可以自由地使用VCS中的先前使用的名称创建新的ORG / repo,如果需要。

Note: If you do not follow these steps, it is possible that you may lose access to your org or repo settings, including环境var.iablesand背景s

Environment variable usage options

Circleci.uses Bash, which follows the POSIX naming convention for environment variables. Valid characters include letters (uppercase and lowercase), digits, and the underscore. The first character of each environment variable must be a letter.

Order of precedence

环境变量根据特定的优先顺序使用,如下所示:

  1. 环境变量声明在side a shell command在arun例如,步骤foo = bar制作安装
  2. 与...宣布的环境变量环境key为一个run
  3. 环境变量设置环境key为工作
  4. Special CircleCI environment variables defined in theCircleci内置环境变量section of this document.
  5. Context environment variables (assuming the user has access to the Context). See the背景documentation for instructions.
  6. Project-level environment variables设置在项目设置页面上。

shell命令中声明的环境变量run step, for examplefoo = bar制作安装,将覆盖与之声明的环境变量环境and背景skeys. Environment variables added on the Contexts page will take precedence over variables added on the Project Settings page.

Env Var Order

安全注意事项

不要在里面添加秘密或钥匙.circleci / config.yml.file. The full text ofconfig.yml开发人员可以访问Circle118金宝博娱乐城ci项目的开发人员。存储秘密或钥匙projector背景设置在the CircleCI app. For more information, see the加密安全文件的一部分。

在配置中运行脚本可能会公开秘密环境变量。看看使用shell脚本document for best practices for secure scripts.

环境变量的示例配置

Consider the exampleconfig.yml下面:

version:2.1jobs:#基本单位运行建立:Docker.:#使用Docker Executor#circleci节点映像可用:https://hub.docker.com/r/circleci/node/-image:Circleci./node:10.0-browsers验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference脚步:# steps that comprise the `build` job-查看# check out source code to working directory#运行步骤来设置环境变量# Redirect MY_ENV_VAR into $BASH_ENV-run:名称:"Setup习俗环境var.iables"命令:Echo'Export My_env_var =“foo”'>> $ bash_env-run:# print the name of the branch we're on名称:"什么branchamIon?"命令:echo ${CIRCLE_BRANCH}# Run another step, the same as above; note that you can#Invoke环境变量没有卷曲的括号。-run:名称:"什么branchamIon现在?”命令:echo $CIRCLE_BRANCH-run:名称:"什么我的习俗环境var.iable?"命令:echo $ {my_env_var}-run:名称:"Printanenv.var.储存theProject"命令:echo ${PROJECT_ENV_VAR}-run:名称:"Printanenv.var.储存aContext"命令:echo ${CONTEXT_ENV_VAR}workflows:# a single workflow with a single job called build建立:jobs:-建立:背景:测试 -  env-vars

以上config.ymldemonstrates the following:

  • 设置自定义环境变量
  • Reading a built-in environment variable that CircleCI provides (circle_branch.)
  • 如何使用(或插值)在您的变量config.yml
  • 掩蔽掩蔽, applied to environment variable set in the project or within a Context.

When the above config runs, the output looks like this. Notice the env var stored in the Project is masked, and displays as****:

Env Vars Interpolation Example

Notice there are two similar steps in the above image and config - “What branch am I on?”. These steps illustrate two different methods to read environment variables. Note that both$ {var}and$VARsyntaxes are supported. You can read more about shell parameter expansion in the抨击文档

使用参数和Bash环境

通常,Circleci不支持将内插环境变量进行构建配置。使用的值被视为文字。这可能会在定义时造成问题working_directory,修改路径, and sharing variables across multiplerun脚步。

An exception to this rule is the docker image section in order to support私人图像

In the example below,$ORGNAMEand$ reponame.不会插入。

working_directory:/go/src/github.com/WRORGNAME/WRREPONAME.

Using版本:2.1config, you can reuse pieces of config across yourconfig.yml。通过使用参数声明,您可以将(或,将值“)插入可重用命令sjobsand执行者:

version:2.1jobs:参数:org_name.:类型:default:my_org.repo_name.:类型:default:my_repo.我的_job:Docker.:-Circleci./node:12.15.0working_directory:/go/src/github.com/<< parameters.org_name >>/<< parameters.repo_name >>

有关更多信息,请阅读文档使用参数声明

将值插入配置中的另一种可能的方法是使用arun将环境变量导出到BASH_ENV, 如下所示。

脚步:-run:名称:设置环境变量命令:|Echo“Export Path = $ Gopath / Bin:$ Path”>> $ Bash_EnvEcho“Export Git_sha1 = $ cifor_sha1”>> $ bash_env

在每一步中,Circleci使用抨击BASH_ENV。This means thatBASH_ENV被自动加载并运行,允许您使用插值和共享环境变量run脚步。

Note:The$ bash_env.替代方法仅适用抨击。Other shells probably won’t work.

Alpine Linux

一个基于的图像Alpine Linux(likeDocker.),使用ashshell.

To use environment variables with抨击,只需将这两个参数添加到您的工作中。

version:2.1jobs:建立:shell:/ bin / sh-leo pipefail环境:-BASH_ENV:/ etc / specess

在shell命令中设置环境变量

虽然Circleci在设置环境变量时不支持插值,但是可以为当前shell设置变量usingBASH_ENV。这对于修改您的方式是有用的路径并设置引用其他变量的环境变量。

version:2.1jobs:建立:Docker.:-image:Smaant / Lein-Flyway:2.7.1-4.0.3验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference脚步:-run:名称:更新路径并在运行时定义环境变量命令:|Echo'Export Path = / path / to / foo / bin:$ path'>> $ bash_envecho'出口非常_important = $(cat mainsign_value)'>> $ bash_env来源$ bash_env.

Note: Depending on your shell, you may have to append the new variable to a shell startup file like〜/ .tcshrc.or~/.zshrc

For more information, refer to your shell’s documentation on setting environment variables.

Setting an environment variable in a step

要在步骤中设置环境变量,请使用环境key

version:2.1jobs:建立:Docker.:-image:Smaant / Lein-Flyway:2.7.1-4.0.3验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference脚步:-查看-run:名称:Run migrations命令:SQL / docker-entrypoint.sh sql#lional变量为单个命令shell环境:DATABASE_URL:postgres://conductor:@localhost:5432/conductor_test

Note:Since everyrun步骤是一个新的shell,环境变量不在步骤中共享。如果需要在多个步骤中可以访问环境变量,导出值usingBASH_ENV

在作业中设置环境变量

To set an environment variable in a job, use the环境key

version:2.1jobs:建立:Docker.:-image:buildpack-deps:可靠验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference环境:FOO:bar

Setting an environment variable in a context

  1. In the CircleCI application, go to your organization settings by clicking the link in the left hand navigation.

    背景

  2. 选择要将环境变量关联的上下文,或通过单击“创建上下文”按钮创建新的上下文。
  3. 单击“添加环境变量”并输入名称和值。
  4. 采用your new environment variable in your.circleci / config.yml.在Workflows密钥下添加上下文后,如下:
version:2.1workflows:test-env-vars:jobs:-建立:背景:my_context_name.#有一个名为my_env_var的env varjobs:建立:Docker.:-image:CIMG / BASE:2020.01验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference脚步:-查看-run:名称:"echoanenv.var.部分of我们的背景"命令:|echo $MY_ENV_VAR

Creating a context allows you to share environment variables across multiple projects, and control who has access. For more information, see the上下文文件

在项目中设置环境变量

  1. 在Circleci应用程序中,通过单击管道页面上的齿轮图标或应用程序中其他页面上的三个点来转到项目的设置。

    环境变量

  2. 单击环境变量。
  3. Add new variables by clicking the Add Variable button and enter a name and value.
  4. 使用您的新环境变量.circleci / config.yml.如下:
version:2.1workflows:test-env-vars:jobs:-建立jobs:建立:Docker.:-image:CIMG / BASE:2020.01验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference脚步:-查看-run:名称:"echoanenv.var.部分of我们的project"命令:|echo $MY_ENV_VAR # this env var must be set within the project

一旦创建,应用程序中的环境变量是隐藏和不可分辨率的。仅通过删除和重新创建才能更改环境变量。

Setting an environment variable in a container

也可以为Docker容器设置环境变量。为此,使用环境key

Note:不可用的环境变量设置脚步run within the container, they are only available to the entrypoint/command runby容器。默认情况下,Circleci将忽略作业主容器的入口点。对于主容器的环境变量有用,您需要保留entrypoint。有关更多信息,请参阅adding an entrypoint自定义图像指南的一部分

version:2.1jobs:建立:Docker.:-image:验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference#环境变量可用于Docker Container运行的EntryPoint /命令环境:MY_ENV_VAR_1:我的价值-1MY_ENV_VAR_2:我的价值-2

以下示例显示了主容器图像(列出的第一个)和辅助或服务容器图像的单独环境变量设置。

version:2.1jobs:建立:Docker.:-image:验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference环境:MY_ENV_VAR_1:我的价值-1MY_ENV_VAR_2:我的价值-2-image:验证:用户名:mydockerhub-user.password:$ dockerhub_password.# context / project UI env-var reference环境:MY_ENV_VAR_3:我的价值-3MY_ENV_VAR_4:我的价值4

Encoding multi-line environment variables

如果您难以添加多行环境变量,请使用Base64.to encode it.

$echo"foobar"|Base64.--wrap=0ZM9VYMFYCG.==.

将生成的值存储在Circleci环境变量中。

$echo$MYVARZM9VYMFYCG.==.

在任何使用变量的命令中解码变量。

$echo$MYVAR|Base64.- 解码|docker登录-umy_docker_user.- 偏相 -  Stdin.Login Succeeded

Note:并非所有命令行程序以相同的方式占用凭据Docker.做。

注入环境variables with API v2

Pipeline parameters can be used to pass variables using the CircleCI API v2.

管道可以用具体触发参数使用API​​ V2端点的值触发管道。这可以通过传递一个参数key in the JSON packet of thePOST身体。

The example below triggers a pipeline with the parameters described in the above config example (NOTE: To pass a parameter when triggering a pipeline via the API the parameter must be declared in the configuration file.).

curl-u$ {CIRCLECI_TOKEN}:-XPOST--header"Content-Type: application/json"-d'{ "parameters": { "workingdir": "./myspecialdir", "image-tag": "4.8.2" } }'//www.drag240sx.com/api/v2/project/:project_slug/pipeline.

重要管道参数不被视为敏感数据,不得被客户使用敏感值(秘密)。您可以找到此敏感信息项目设置and背景

阅读更多管道变量指南。

注入环境variables with API v1

构建参数是环境变量,因此它们的名称必须满足以下限制:

  • They must contain only ASCII letters, digits and the underscore character.
  • 他们不能以数字开头。
  • 它们必须包含至少一个字符。

Aside from the usual constraints for environment variables there are no restrictions on the values themselves and are treated as simple strings. The order that build parameters are loaded in is保证,请避免将一个构建参数插入另一个构建参数。最好的做法是将构建参数设置为独立环境变量的无序列表。

重要Build parameters are not treated as sensitive data and must not be used by customers for sensitive values (secrets). You can find this sensitive information in项目设置and背景

例如,当您传递参数时:

{“build_parameters”:{“foo”:“酒吧”,"baz": 5,“qux”:{"quux": 1},"list":[“一种”,"list","of","strings"]}}

您的构建将看到环境变量:

exportfoo=“酒吧”exportbaz="5"exportQUX.="{\QUUX.\:1}“exportlist="[\a\,\list\,\of\,\\]“

构建参数将导出为每个作业容器中的环境变量,并且可以由脚本/程序和命令使用config.yml。注入的环境变量可用于影响在作业期间运行的步骤。值得注意的是,注入的环境变量不会覆盖定义的值config.yml也没有项目设置。

您可能希望使用该环境变量注入环境变量build_parameters.key to enable your functional tests to build against different targets on each run. For example, a run with a deploy step to a staging environment that requires functional testing against different hosts. It is possible to includebuild_parameters.by sending a JSON body withContent-type: application/json如在以下示例中使用抨击andcurl(虽然您也可以使用您的语言中的HTTP库)。

{“build_parameters”:{"param1":“value1”,“param2”:500.}}

例如使用curl

curl\--header"Content-Type: application/json"\--header"Circle-Token:$ circle_token."\--data'{“build_parameters”:{param1“:”value1“,”param2“:500}}'\- 请求POST\//www.drag240sx.com/api/v1.1/project/github/circleci/mongofinil/tree/master

In the above example,$ circle_token.是A.个人API令牌

构建将看到环境变量:

exportparam1=“value1”exportparam2=“500”

使用Post API调用开始运行,请参阅新建section of the API documentation for details. A POST with an empty body will start a new run of the named branch.

Built-in environment variables

在每个构建中导出以下环境变量,可用于更复杂的测试或部署。

Note:您无法使用内置环境变量来定义另一个环境变量。相反,你必须使用一个run步to export the new environment variables usingBASH_ENV

有关更多详细信息,请参阅Setting an Environment Variable in a Shell Command

变量 类型
CI 布尔基 真正(表示当前环境是CI环境)
CIRCLECI 布尔基 真正(represents whether the current environment is a CircleCI environment)
circle_branch. String The name of the Git branch currently being built.
circle_build_num. 整数 The number of the current job. Job numbers are unique for each job.
circle_build_url. String The URL for the current job on CircleCI.
circle_job. String 当前作业的名称。
circle_node_index. 整数 对于启用并行性运行的作业,这是当前并行运行的索引。该值范围为0到(CIRCLE_NODE_TOTAL- 1)
CIRCLE_NODE_TOTAL 整数 对于启用并行性运行的作业,这是并行运行的数量。这是对价值等于的parallelism在您的配置文件中。
CIRCLE_PR_NUMBER 整数 The number of the associated GitHub or Bitbucket pull request. Only available on forked PRs.
circle_pr_reponame. String 创建拉出请求的GitHub或Bitbucket存储库的名称。仅适用于叉子PRS。
CIRCLE_PR_USERNAME String 创建拉请求的用户的GitHub或Bitbucket用户名。仅适用于叉子PRS。
CIRCLE_PREVIOUS_BUILD_NUM 整数 The number of previous builds on the current branch.
CIRCLE_PROJECT_REPONAME String 当前项目的存储库的名称。
CIRCLE_PROJECT_USERNAME String 当前项目的GitHub或Bitbucket用户名。
CIRCLE_PULL_REQUEST String The URL of the associated pull request. If there are multiple associated pull requests, one URL is randomly chosen.
circle_pull_request. List 逗号分隔的当前构建关联请求的URL列表。
circle_repository_url. String GitHub或Bitbucket存储库的URL。
circle_sha1. String SHA1散列当前构建的最后一次提交。
circle_tag. String 如果将当前构建标记,则GIT标记的名称。有关更多信息,请参阅Git Tag Job Execution
circle_username. String 触发管道的用户的GitHub或Bitbucket用户名。
circle_workflow_id. String 当前作业的工作流实例的唯一标识符。在给定工作流实例中的每个作业都是相同的该标识符。
circle_working_directory. String The value of theworking_directory当前工作的关键。
CIRCLE_INTERNAL_TASK_DATA String 内部。存储与作业相关的内部数据的目录。我们不会记录此目录的内容;数据模式可能会有所变化。
CIRCLE_COMPARE_URL String Deprecated。The GitHub or Bitbucket URL to compare commits of a build. Available in config v2 and below. For v2.1 we will introduce“管道值”作为备选。
CI_PULL_REQUEST String Deprecated。保持与Circleci 1.0的向后兼容性。采用CIRCLE_PULL_REQUEST在stead.
ci_pull_requests. List Deprecated。保持与Circleci 1.0的向后兼容性。采用circle_pull_request.在stead.

Note:有关流水线值和参数的列表,请参阅管道变量页。

See also

背景Keep environment variables private with secret masking