Orbs概念

Quick start

Circleci Orbs.are shareable packages of configuration elements, including职位commands, 和执行者。ORBS制作写作和自定义CIRCLECI配置简单。在ORB中使用的可重用配置元素是完全解释的可重用配置Reference

ORB配置元素

圆CI’s可重用配置功能允许您定义可参数化配置元素并在整个项目配置文件中重新使用这些元素。建议你熟悉完整的配置Referencefeatures before moving on to the可重用配置Reference

命令

命令包含一个或多个步骤parameterscan be used to modify behavior. Commands are the logic of orbs and are responsible for executing steps such as检查代码那或者running shell code, for example, running bash or CLI tools. For more information see the创作可重用命令guide.

一种s an example, the AWS S3 orb includes acommand将文件或对象复制到新位置:AWS-S3 / COPY。如果您的AWS身份验证详细信息存储为环境变量,则在配置中使用此命令的语法只是:

版本2.1绿色原子aws-s3circleci/aws-s3@x.y.z.职位builddocker-图像'CIMG / PYTHON:3.6'验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD# context / project UI env-var reference脚步-checkout-runmkdir bucket && echo "lorem ipsum" > bucket/build_asset.txt#使用AWS-S3 ORB的“复制”命令。-AWS-S3 / COPYfrombucket/build_asset.txtto's3://my-s3-bucket-name'#... workflows , other jobs etc.

See theAWS-S3 ORB注册表中的页面以获取更多信息。

Executors

Executors are parameterized execution environments in which职位可以运行。Circleci提供多个执行者选项

  • Docker.
  • 苹果系统
  • 视窗
  • 机器(Linux VM)

在ORB中定义的执行器可用于在项目配置中运行作业,或在ORB中定义的作业中运行作业。

Executor definition example

description>选择要使用的NodeJ的版本。使用Circleci的高速缓存方便为CI构建的图像。docker-图像'CIMG / node:<< parameters.tag >>'验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD# context / project UI env-var referenceparameterstag默认'13.11'description>选择特定的CIMG / Node Image版本标记:https://hub.docker.com/r/cimg/nodetypestring
description>Select the version of Ruby to use. Uses CircleCI's highly cached convenience为CI构建的图像。可以使用此列表中的任何可用标记:https://hub.docker.com/r/cimg/ruby/tagsdocker-图像'cimg/ruby:<<parameters.tag.>>'验证用户名mydockerhub-user.密码$DOCKERHUB_PASSWORD# context / project UI env-var referenceparameterstag默认'2.7'description这`circleci/ruby` Docker image version tag.typestring

在里面节点ORB.例如,提供了参数化的基于Docker的执行器,通过您可以设置Docker标记。这提供了一种在与节点ORB一起使用时测试应用程序对任何版本的Node.js的简单方法测试工作

有关更多信息,请参阅指南创作可重复使用的执行者和注册页面的节点ORB.

职位

职位定义一系列脚步在给定的情况下运行执行者, 和are orchestrated using工作流程。工作也将单独返回其状态GitHub检查

导入具有作业的ORB时,您可以直接从工作流程引用。

版本:2.1 ORB: /  @ x.y #orb version工作流程:使用 -  ORB-JOB:作业: -   / 

See the编写可重用的工作guide for more information, and the使用节点测试作业example in the orb registry.

Usage examples

使用ORB开发套件,添加一个新的使用示例是创建新文件的简单name-of-example.yml在ORB项目中src/examples目录。使用示例不直接在项目配置中使用,但是是一种ORB元数据,用于共享用户如何最好地利用它们的配置,并显示参考ORB注册表。以下是示例使用示例:

# Source https://github.com/circleci-public/orb-project-template/blob/master/src/examples/example.ymldescription>Sample example description.usage版本2.1绿色原子 /  @ 1.2.3工作流程use-my-orb职位-/

名称空间

一种namespace是由用户或组织声明的唯一标识符,用于组由作者组组一组ORB。每个用户或组织都可以申请unique and immutable namespace. Each namespace can contain many uniquely named orbs.

例如,Circleci / Rails.ORB可能会使用ORB调用的注册表中共存<其他 - 命名空间> / Rails因为它们是单独的名称空间。

Organizations are, by default, limited to claiming only one namespace. This policy is designed to limit name-squatting and namespace noise. If you need to change your namespace, please contact support.

By default, created namespaces appear as “community” namespaces in theORB注册表

语义版本化

orbs利用这一点塞缪弗发布过程,其中每个ORB更新遵循标准化的版本控制模式,ORB作者和用户应该利用。

在语义版本控制中,发行版本由三个整数表示由一个分隔的,其中每个整数表示添加了不同类型的更改。

[主要]。[次要]。[补丁]
Semver Description
主要的 Breaking changes.
Minor 向后兼容其他功能。
修补 Bug fixes.

导入ORB时,可以将其引导到特定的SEMV组件。

导入版本 Description
1.2.3 Will match full semver version. No changes will be introduced.
1.2 锁定到主要版本1那次要的版本2那will receive all patch updates.
1 锁定到主要版本1。Will receive all minor and patch updates. Major version will not change automatically.
volatile Not RecommendedWill pull the last published version of the orb, may be useful in testing. Not a part of semver versioning.

为了避免对用户的CI进程产生负面影响,ORB作者应严格遵守SEMVER版本,以确保在此期间不会介绍破坏次要的或者修补更新级别。

笔记:Circleci目前不支持非数字语义版本控制元素。我们建议您在x.y.z格式中使用semver样式版本字符串,或dev:*格式的开发式版本字符串。

ORB版本(开发VS生产与内联)

生产球体

生产球体是不可变的,可以在ORB注册表

  • 生产ORB是不可变的,无法删除或编辑它们,并且必须在新的SEMV释放中提供更新
  • 例如,版本字符串必须是SEMV格式,/@1.2.3
  • 生产ORB只能由命名空间组织的所有者发布
  • Published to the Orb Registry
  • 开源,释放麻省理工学院执照
  • 可通过Circleci CLI获得

产品开发lopment orbs

开发模板是临时覆盖能够的ORB标签版本,可在部署Semver部署的生产变化之前快速开发和测试。

  • 产品开发lopment orbs are mutable, can be overwritten, and automatically expire 90 days after they are published
  • Version string must begin withdev:然后是任何字符串,例如, / @dev:my-feature-branch
  • 产品开发lopment orbs may be published by any member of the namespace organization
  • 不会出现在ORB注册表上
  • 开源,释放麻省理工学院执照
  • 可通过Circleci CLI获得(if the development tag name is known)

内联球体

内联轨道在用户配置中直接定义,完全本地本地并将其范围用于个体项目。

请参阅:写入inline Orbs有关内联轨道的更多信息。

  • 未发布到ORB服务
  • 没有版本化
  • 仅存在于用户配置中
  • Not accessible outside of the repository
  • 不公共
  • 通过circleci cli无法访问

Orb packing

一种ll CircleCI orbs are singular YAML files, typically named或者b.yml。但是,对于开发来说,将代码分解为更可管理的块通常更容易。这circleci orb pack命令,一个组成部分ORB开发套件那is used to “pack” or condense the separate YAML files together.

如果you are using the orb development kit, orb packing is handled automatically, by the included CI/CD pipeline, with theORB-Tools / Pack工作。

示例:ORB项目结构

type name
commands
examples
执行者
职位
@ Orb.yml.

In order to一个室外,一个@ Orb.yml.文件必须存在。这@signifies theof our orb project. Within the same directory, you can include additional directories for each orb component’s type, such ascommands职位执行者, 和examples。任何其他文件或文件夹都将安全忽略。

此外,这是命令为ORB开发人员提供了一个特殊的预处理器,允许您使用使用外部文件导入代码118金宝博娱乐城文件包括语法<<包括(文件)>>)。

CLI命令

Circleci Orb包

> orb.yml

对于ORB开发套件用户,此步骤自动处理。

文件包括语法

file include句法 (< <包括(dir /文件)> >)是一个特殊的配置增强功能,允许您将文件的内容导入到位于Circleci Orb配置文件中的任何键的值。这< <包括(dir /文件)> >语法是与之使用的特殊键circleci orb packcommandwill notwork more widely on CircleCI.

WhenCircleci Orb包

> orb.ymlis run against a directory containing an@ Orb.yml.文件,pack命令开始将文件的内容组合成单个或者b.yml文件。在包装过程中,每个实例< <包括(dir /文件)> >值将由在内部引用的文件的内容替换。

Included files are always referenced from the relative location of the@ Orb.yml.文件。

description一种simple command that imports from a file when packed.脚步-runnameHello Greetingcommand<>
# This is a bash file, but could really be any text-based file回声“你好,世界”
description一种simple command that imports from a file when packed.脚步-runnameHello Greetingcommand|# This is a bash file, but could really be any text-based file回声“你好世界”

文件包含对于将配置的Bash逻辑与YAML分离,尤其有用。包括Bash脚本将允许您在ORB之外开发和测试BASH。

View more about including bash scripts in theORB作者guide.

在ORB和注册时间分辨率内使用ORBS

Orbs Stanza可以在ORB内使用。由于生产ORB发布是不可变的,因此系统将在注册ORB时的所有ORB依赖项,而不是在运行构建时解决所有ORB依赖项。

For example, orbfoo / bar.is published at version 1.2.3 with an orbs stanza that importsbiz / baz @ volatile。在您注册的时候foo/bar@1.2.3系统将解决biz / baz @ volatileas the latest version and include its elements directly into the packaged version offoo/bar@1.2.3

如果biz/bazis updated to3.0.0那anyone usingfoo/bar@1.2.3不会看到变化biz/baz@3.0.0直到foo / bar.发表于较高的版本1.2.3

ORB元素可以直接与其他ORB的元素组成。例如,您可能有一个看起来像下面的例子的ORB。

版本2.1绿色原子some-orbsome-ns/some-orb@volatile执行者我的执行者某些ORB /他们的执行者commandsmy-command一些 -  Orb /他们的命令职位我的工作一些或足月/他们的工作another-job执行者我的执行者脚步-my-commandparam1hello"

也可以看看