可重用配置参考指南

本指南介绍了如何使用可重用命令,作业,执行者和ORB开始。本指南还涵盖了使用参数来创建参数化可重用元素。

有关可重用配置的注意事项

  • 安装Circleci CLI,以便您可以访问Circleci配置过程命令(可选)。此命令允许您查看扩展的配置,并处理所有可重用密钥。跟着使用circleci cli安装说明和提示的文档。

  • Circleci可重用配置元素需要一个版本:2.1.circleci / config.yml.文件。

  • 命令,作业,执行程序和参数名称必须以字母开头,只能包含小写字母(一种-Z.),数字(0.-9.)那underscores (_)和连字符(-)。

使用参数宣言

Parameters are declared by name under a job, command, or executor. The immediate children of the参数键是地图中的一组密钥。管道参数在项目配置的顶级定义。看看管道变量指南有关管道参数的更多信息。

在以下示例中,命令命名问候设计有一个名为的单个参数。这参数用于回声的步骤中使用你好回到用户。

版本2.1命令#具有参数的可重用命令问候参数默认world"type细绳脚步-echo“hello << parameters.to >>”职位我的工作Docker.-图像CI.mg/base:stable验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考脚步-问候我的名字”工作流程我的工作流程职位-我的工作

参数语法

参数可以具有以下键作为即时儿童:

关键名称 Description 默认值
描述 选修的。用于为ORB生成文档。 N / A.
type 必需的。看参数类型在下面的部分有关详细信息。 N / A.
默认 参数的默认值。如果不存在,则暗示参数是必需的。 N / A.

参数类型

本节介绍参数的类型及其用法。

ORB支持的参数类型是:

  • 细绳
  • boolean
  • 整数
  • 枚举
  • 执行者
  • 脚步
  • 环境变量名称

管道参数支持的参数类型是:

  • 细绳
  • boolean
  • 整数
  • 枚举

细绳

基本字符串参数如下所述:

版本2.1命令复制 -  Markdown.参数目的地描述目的地目录type细绳默认译文脚步-CP * .md << parameters.destination >>

字符串必须包含在引号中,否则它们会代表另一种类型(例如布尔值或数字),或者它们包含yaml中具有特殊含义的字符,特别是对于结肠字符。在所有其他情况下,引号是可选的。空字符串被视为评估中的伪造值什么时候条款,所有其他字符串都被视为真实。使用yaml解释为布尔的未引用的字符串值将导致类型错误。

布尔基

布尔参数对于条件有用:

版本2.1命令列表文件参数全部描述包括所有文件typeboolean默认错误的脚步-ls <<#parameters.all >> -a << / parameters.all >>

布尔参数评估基于YAML 1.1中指定的值

  • 真的:y是的真的
  • 错误的:N错误的离开

上述值的大写和大写版本也有效。

Integer

使用参数类型整数通过数字整数值。以下示例使用整数填充值的类型并行在一份工作中。

版本2.1职位建造参数P.type整数默认1并行<<参数.p >>机器真的脚步-退房工作流程工作流程职位-建造P.2

枚举

枚举参数可以是任何值的列表。使用枚举参数类型要强制执行该值必须是来自特定字符串值的值。以下示例使用枚举参数为二进制文件声明目标操作系统。

版本2.1命令列表文件参数OS.默认Linux“描述Heroku二进制的目标操作系统。必须是“Linux”,“Darwin”,“Win32”。type枚举枚举[Linux“达尔文“Win32“]

以下枚举类型声明无效,因为enum列表中未声明默认值。

版本2.1命令列表文件参数OS.type枚举默认视窗”#无效的默认不appe宣言一种r in the comma-separated enum list枚举[达尔文“Linux“]

执行者

用A.执行者参数类型允许作业的调用,以确定它将运行的执行器。

版本2.1执行者Xenial.参数一些价值type细绳默认Foo环境一些_var.<<参数.Some-Value >>Docker.-图像Ubuntu:Xenial.验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考仿生学Docker.-图像Ubuntu:仿生学验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考职位测试参数E.type执行者执行者<<参数..脚步-一些测试工作流程工作流程职位-测试E.仿生学-测试E.姓名Xenial.一些价值Foobar.

Steps

当您有需要混合预定义和用户定义的步骤的作业或命令时使用步骤。当传递到命令或作业调用时,通过作为参数传递的步骤始终被定义为序列,即使仅提供了一个步骤。

版本2.1命令跑-测试参数后面描述Stepswill执行依赖性安装了,测试跑”type脚步默认[]脚步-制作Deps.-脚步<<参数.AFT-DEPS >>-制作测试

以下示例演示了作为参数传递的步骤作为a的值脚步工作下的宣言脚步

版本2.1命令跑-测试参数后面描述Stepswill执行依赖性安装了,测试跑”type脚步默认[]脚步-制作Deps.-脚步<<参数.AFT-DEPS >>-制作测试职位建造机器真的脚步-跑-测试后面-E.cho "The dependencies are installed"-回声“现在我打算经过测试”

以上将解决以下问题:

版本2.1脚步-制作Deps.-E.cho "The dependencies are installed"-回声“现在我打算经过测试”-制作测试

环境变量名称

环境变量名称(env_var_name.)参数是一个字符串,必须匹配posix_name regexp(例如,可能没有空格或特殊字符)。这env_var_name.参数是一种更有意义的参数类型,使Circleci能够检查已传递的字符串可以用作环境变量名称。有关环境变量的更多信息,请参阅指南使用环境变量

下面的示例向您展示了如何使用env_var_name.使用可重用的AWS S3部署参数类型建造工作。此示例使用该示例显示aws_access_key.aws_secret_key.环境变量与访问密钥密钥参数。因此,如果您有一个运行的部署作业s3cmd.,可以创建一个使用所需身份验证的可重用命令,但部署到自定义存储桶。

原版的config.yml.file:

版本2.1职位建造Docker.-图像Ubuntu:最新验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考脚步-command|s3cmd --access_key $ {foo_bar} \--secret_key $ {bin_baz} \LS S3://一些/在哪里工作流程工作流程职位-建造

新的config.yml.file:

版本2.1职位建造参数访问密钥typeenv_var_name.默认aws_access_key.密钥typeenv_var_name.默认aws_secret_key.commandtype细绳Docker.-图像Ubuntu:最新验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考脚步-|s3cmd --access_key $ {<< parameters.access-key >>} \\--secret_key $ {<< parameters.secret-key >>} \\<< parameters.command >>工作流程工作流程职位-建造访问密钥Foo_Bar.密钥Bin_baz.commandLS S3://一些/在哪里

创作可重用命令

命令被宣布为命令钥匙的一种config.yml.文件。以下示例定义了一个调用的命令问好,接受字符串参数

版本2.1命令问好描述一种非常简单的command为了示范目的“参数type细绳默认世界”脚步-echo hello << parameters.to >>

命令钥匙

命令将一系列步骤定义为要在作业中执行的映射,使您能够在多个作业中重用单个命令定义。

钥匙 必需的 类型 Description
脚步 y Sequence 在调用命令的作业内运行的一系列步骤。
参数 N 地图 参数键的地图。看看参数语法部分详情。
描述 N 细绳 一个描述命令目的的字符串。用于生成文档。

调用可重复使用的命令

Reusable commands are invoked with specific parameters as steps inside a job. When using a command, the steps of that command are inserted at the location where the command is invoked. Commands may only be used as part of the sequence under脚步在一份工作中。

以下示例使用前一个示例的相同命令 -问好– and invokes it in the job我的工作,将它传递了一个值范围:

版本2.1命令问好描述一种非常简单的command为了示范目的“参数type细绳默认世界”脚步-echo hello << parameters.to >>职位我的工作Docker.-图像CIMG / BASE:稳定“验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考脚步-问好#Incoke命令“sayhello”lev“

在命令中调用其他命令

命令可以在执行范围内使用其他命令。例如,如果在ORB中声明了命令,则它可以使用该ORB中的其他命令。它还可以使用在您导入的其他ORB中定义的命令(例如一些 - Orb / some-command)。

Special keys

circleci有几个特殊的键可供所有Circleci.。com客户和Circleci Server安装中的默认情况下可用。这些键的示例是:

  • 退房
  • setup_remote_docker.
  • persist_to_workspace.

笔记:可以使用自定义命令覆盖特殊密钥。

命令使用示例

以下是部分的一个例子AWS-S3或者b where a command called同步被定义为:

版本2.1#AWS-S3 ORB命令同步描述一种简单的EN.capsulation正在做一个S3.同步”参数fromtype细绳type细绳覆盖默认错误的typeboolean脚步-姓名部署到S3.commandAWS S3同步<<参数。从>> << parameters.to >> <<#parameters.overwrite >> --delete << / parameters.overwrite >>“

调用这一点同步命令在2.1中.circleci / config.yml.文件,请参阅以下示例:

版本2.1绿色原子AWS-S3circleci/aws-s3@1.0.0职位部署2.S3Docker.-图像Circleci./:验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考脚步-AWS-S3 / SYNCfromS3:// mybucket_uri“覆盖真的工作流程构建 - 测试部署职位-部署2.S3

定义A.建造工作:

版本2.1绿色原子一种ws-cliCircleci./aws-cli@0.1.2AWS-S3circleci/aws-s3@1.0.0职位建造执行者AWS-CLI /默认脚步-退房-mkdir bucket && echo“lorum ipsum”>桶/ build_asset.txt-AWS-S3 / SYNCfromS3:// my-s3-batchet-name / prefix“覆盖真的-AWS-S3 / COPYfrom铲斗/ build_asset.txt.txt.S3:// my-s3-batchet-name“一种rguments- 德里伦

创作可重复使用的执行者

执行器定义将运行作业步骤的环境。宣布A.工作在Circleci配置中,您定义了执行环境类型(Docker.机器苹果系统。等)运行,以及该环境的任何其他参数,包括:填充环境变量,使用哪个shell,尺寸resource_class使用等。

外部执行程序声明职位所有作业都可以在该声明的范围内使用,允许您在多个作业中重用单个执行器定义。

执行器定义包括以下一个或多个键:

  • Docker.或者机器或者苹果系统
  • 环境
  • Working_Directory.
  • resource_class

在以下示例中我的执行者is used for running the job我的工作

版本2.1执行者我的执行者Docker.-图像Circleci / Ruby:2.5.1-节点浏览器验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考职位我的工作执行者我的执行者脚步-echo在执行者之外

执行者钥匙

执行器定义将运行作业步骤的环境,允许您在多个作业中重复使用单个执行器定义。

钥匙 必需的 类型 Description
Docker. y(1) 列表 选择Docker.执行者。
resource_class N 细绳 CPU和RAM在作业中分配给每个容器的RAM。(只提供Docker.执行者)笔记:需要付费帐户来访问此功能。基于付费容器的计划的客户可以请求访问开设支持票
机器 y(1) 地图 选择机器执行者。
苹果系统 y(1) 地图 选择苹果系统执行者。
N 细绳 shell在所有步骤中用于执行命令。可以被覆盖在每一步。
Working_Directory. N 细绳 运行步骤的目录。
环境 N 地图 环境变量名称和值的地图。

Example:

版本2.1执行者我的执行者Docker.-图像Circleci / Ruby:2.5.1-节点浏览器验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考职位我的工作执行者我的执行者脚步-echo在执行者之外

调用可重复使用的执行者

以下示例通过我的执行者作为a的价值姓名钥匙执行者- 当将参数传递给执行器调用时,此方法主要用于:

版本2.1执行者我的执行者Docker.-图像Circleci / Ruby:2.5.1-节点浏览器验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考职位我的工作执行者姓名我的执行者脚步-echo在执行者之外

还可以允许ORB定义其所有命令使用的执行器。这允许用户在ORB作者定义的执行环境中执行该ORB的命令。

使用executor声明的示例config.yml.用矩阵作业。

以下示例声明具有节点映像的Docker执行程序,node-docker.。这tag portion of the image string is parameterized with a版本范围。一种版本参数也包含在测试作业使其可以在从工作流中调用作业时通过作业传递到执行程序。

When calling the测试工作在矩阵测试工作流程,矩阵工作是used to run the job multiple times, concurrently, each with a different set of parameters. The node application is tested against many versions of Node.js:

版本2.1执行者node-docker.#声明可重用的执行程序参数版本描述版本标签”默认LTS“type细绳Docker.-图像CIMG / Node:<<参数.version >>验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考职位测试参数版本描述版本标签”默认LTS“type细绳执行者姓名node-docker.版本<<参数.Version >>脚步-退房-回声“你好吗?”工作流程矩阵测试职位-测试矩阵参数版本-13.11.0-12.16.0-10.19.0

使用在ORB中定义的执行器

您还可以从其他ORB中引用executors。ORB的用户可以调用其执行官。例如,Foo-Orb.可以定义这一点酒吧执行者:

版本2.1#yaml来自foo-orb执行者酒吧机器真的环境run_tests.Foobar.

Baz-Orb.可以定义这一点酒吧执行者也是:

版本2.1#来自Baz-Orb的Yaml执行者酒吧Docker.-图像CI.mg/base:stable验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考

您可以使用配置文件中的任何一个执行程序:

版本2.1#config.yml.绿色原子Foo-Orb.somenamespace / foo @ 1Baz-Orb.某些othernamespace/baz@3.3.1职位一些工作执行者foo-orb / bar#前缀executor.一些其他工作执行者Baz-Orb./bar#前缀executor.

笔记:foo-orb / barBaz-Orb./bar是不同的执行者。他们都有当地名字酒吧相对于他们的球体,但它们是在不同球体中定义的独立执行者。

调用executor时覆盖键

在调用executer时工作作业本身中的任何键都将覆盖调用的执行者的键。例如,如果您的工作声明了一个Docker.Stanza,它将完整地使用,而不是执行者中的。

笔记:环境可变地图是添加剂。如果执行者有一个相同的环境变量作为工作,将使用作业中的值。看看使用环境变量指南为了more information.

版本2.1执行者节点Docker.-图像CIMG / Node:LTS验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考环境env.CI.职位建造Docker.-图像CI.mg/base:stable验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考#下面的测试执行程序将被更明显的“docker”执行程序覆盖。将添加任何env变量。执行者节点脚步-echo“node将无法安装。”

上面的配置将解决以下问题:

版本2.1职位建造Docker.-图像CI.mg/base:stable验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考环境env.CI.来自executor#。脚步-echo“node将无法安装。”

创作参数化作业

在工作流节中,可以多次调用相同的工作config.yml.,将任何必要的参数作为小组传递给作业。有关语法使用的详细信息,请参阅上面的参数部分。

定义和调用参数化作业的示例config.yml.

版本2.1职位问好#定义参数化作业描述除了演示参数化作业看起来的看起来的看起来,这很少的工作参数说what描述我们你好?”默认世界”type细绳机器真的脚步-E.cho "Hello << parameters.saywhat >>"工作流程建造职位-问好#调用参数化作业说what每个人

笔记:在使用任意数量的工作流程中使用参数多次调用相同的作业时,将更改构建名称(即Sayhello-1Sayhello-2, 等等。)。为确保未附加构建号码,请利用姓名钥匙。您分配的名称需要是唯一的,否则数字仍将附加到作业名称。举个例子:

工作流程建造职位-问好姓名建造-问好说what每个人部署职位-问好姓名部署 -  sayhello.说what全部

在ORB中定义的作业

如果在ORB中声明作业,它可以在该ORB或全局命令中使用命令。无法在作业声明范围之外调用命令。

Hello-Orb.

版本2.1# partial yaml from hello-orb职位问好参数说what描述我们你好?”默认世界”type细绳机器真的脚步-说what<<参数..saywhat.>>“命令说what参数说whattype细绳脚步-echo“<<参数.saywhat >​​>”

Config leveraging hello-orb

#config.yml.版本2.1绿色原子Hello-Orb.somenamespace / hello-orb @ volatile工作流程建造职位-Hello-Orb / sayhello说what每个人

在executors中使用参数

要在executors中使用参数,请在给定的执行程序下定义参数。调用执行器时,将参数的键传递为键下的键映射执行者:宣言那E.一种ch of which has the value of the parameter to pass in.

Parameters in executors can be of the type细绳枚举, 或者boolean。默认值可以提供可选的默认钥匙。

Example build configuration using a parameterized executor

版本2.1执行者Python参数tagtype细绳默认最新的myspecialvar.type细绳Docker.-图像cimg / python:<< parameters.tag >>验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考环境my<< parameters.myspecialvar >>职位建造执行者姓名Pythontag2.7“myspecialvar.myspecialvalue“

以上将解决以下问题:

版本2.1职位建造脚步[]Docker.-图像CIMG / PYTHON:3.8验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD#上下文/项目UI ENV-VAR参考环境mymyspecialvalue“

这scope of parameters

Parameters are in-scope only within the job or command that defined them. If you want a job or command to pass its parameters to a command it invokes, they must be passed explicitly.

版本2.1职位问好参数说what描述我们你好?”默认世界”type细绳机器真的脚步-#由于命令“说”无法定义默认值#值为“saywhat”参数,它必须是#手动通过说what<<参数.Say >>命令参数说whattype细绳脚步-echo“<<参数.saywhat >​​>”工作流程建造职位-问好说what每个人

调用多次相同的作业

单个配置可以多次调用作业。在配置过程中构建过程中,如果没有提供,则Circleci将自动生成名称,或者您可以将重复的作业显示与之明确的姓名钥匙。

笔记:当重复作业应该在工作流程中的另一个作业的上游时,必须显式命名重复作业。例如,如果在下面使用作业需要工作流程中的作业调用键,您需要明确地命名它。

版本2.1工作流程建造职位-loadsay.#这不需要一个显式名称,因为它没有下游依赖项-问好说what每个人需要-loadsay.#这需要Saygoodbye的明确名称,要求它作为作业依赖性-问好姓名Sayhellochad.说whatChad#使用明确定义的“sayhello”-说再见需要-Sayhellochad.

使用预先和帖子步骤

每个作业调用都可以选择接受两个特殊参数:阶梯后步。下面的步骤阶梯在作业中的任何其他步骤之前执行。下面的步骤后步是执行后全部的the other steps.

预先和发布步骤允许您在不修改作业的情况下在给定作业中执行步骤。例如,这是有用的,以便在作业执行之前运行自定义设置步骤。

定义预先和帖子步骤

以下示例定义了步骤步骤和后步骤酒吧工作的工作建造工作流程:

#config.yml.版本2.1职位酒吧机器真的脚步-退房-command回声“建筑”-commandE.cho "testing"工作流程建造职位-酒吧阶梯-commandecho“安装自定义依赖项”后步-commandecho“将工件上传到S3”

笔记:按键阶梯后步在作业中,配置版本2.1及更高版本可用。

定义条件步骤

仅当在Config-Compile Time时满足条件时,条件步骤仅运行,在工作流程运行之前。例如,这意味着您可能无法使用条件来检查环境变量,因为在步骤在执行环境的shell中运行之前未注入其中的条件。

条件步骤可以位于常规步骤中的任何地方,也可以仅使用参数值作为输入。

例如,ORB可以定义运行一组步骤的命令如果调用myorb / foo:{dostuff:true}, 但不是myorb/foo: { dostuff: false }

此外,ORB作者可以定义条件步骤脚步工作或命令的键。

#infiguit.yml.版本2.1职位我的工作参数预先安装 -  Foo.typeboolean默认错误的机器真的脚步-echo“preinstall是<< presides.preinstall-foo >>”-什么时候健康)状况<<参数.preinstall-foo >>脚步-E.cho "preinstall"-除非健康)状况<<参数.preinstall-foo >>脚步-echo“不要预先安装”工作流程工作流程职位-我的工作预先安装 -  Foo.错误的-我的工作预先安装 -  Foo.真的-我的工作# The empty string is falsy

笔记:Conditional steps are available in configuration version 2.1 and later.

什么时候step

在下面什么时候键是子键健康)状况脚步。这subkey脚步只有当条件评估到真实值时才运行。

钥匙 必需的 类型 Description
健康)状况 y 逻辑 逻辑陈述
脚步 y Sequence 当条件是真实的时,执行的步骤列表。

除非step

在下面除非键是子键健康)状况脚步。这subkey脚步仅在条件评估到伪造值时才运行。

钥匙 必需的 类型 Description
健康)状况 y 逻辑 逻辑陈述
脚步 y Sequence 当条件是falsy时执行的步骤列表。

写入内联口交

When defining reusable configuration elements directly within your config, you can also wrap those elements within an inline orb. You may find inline orbs useful for development or for name-spacing elements that share names in a local config.

要编写内联ORB,请将ORB元素放在配置的ORB的键下配置。例如,如果要导入另一个ORB以在另一个内部使用,内联ORB,则配置可以看起来像下面显示的示例,其中内联图库我的袜子进口节点ORB:

版本2.1绿色原子我的袜子绿色原子节点Circleci./node@3.0命令my_command.脚步-echo“运行我的测试”职位我的工作执行者节点/默认值#节点ORB执行程序脚步-退房-my_command.-store_test_results.小路试验结果工作流程主要的职位-my-sorb / my_job

也可以看看

  • Refer to示例配置为了some sample configurations that you can use in your own CircleCI configuration.
  • Refer to配置食谱有关如何在配置中使用Circleci Orb配方的更多详细信息。
  • Refer to数据库示例对于数据库示例,您可以在Circleci配置中使用。