ORBS创作最佳实践

一般
结构体
- @ Orb.yml.
- 命令
- 职位
- 执行人
- 例子
- 参数
部署
促销活动

一般

给你的ORB描述性名称

一个球体“蛞蝓”是由a名称空间和orb名称由正斜杠分隔。名称空间表示拥有和维护orb的个人、公司或组织，而orb名称本身应该描述单个orb提188bet娱乐官网供的产品、服务或操作。

适当的ORB SLUG.	糟糕的舷衫
circleci / node	Circleci / node-Orb
188bet娱乐官网公司/ orb	188bet娱乐官网公司/公司

分类您的ORB.

对您的ORB进行分类允许它可以搜索ORB注册表按类别。要查看如何使用Circleci CLI对ORB分类，请参阅相关部分Orb创作过程指南。

确保所有ORB组件包括描述

命令、作业、执行器、示例和参数都可以接受描述。确保orb的每个组件都有有用的描述，并提供可能需要的任何其他文档。

        描述：“利用这命令来回声你好来一种一步在该UI。”脚步：-运行：的名字：“运行回声命令”命令：回声“你好”
       

创建详细的描述，充分解释orb元素的好处和用法。描述是提供与每个组件相关的更具体文档的好地方。

确保您的ORB发布上下文受到限制

如果使用Orb Developer Kit，则您的CircleCI个人访问令牌将保存到组织中的上下文。确保您限制了此上下文，以便访问它的作业将仅在您或其他已批准的用户触发或批准时运行。有关更多信息，请参见使用上下文指南。

结构体

@ Orb.yml.

该@ Orb.yml.文件充当项目的“根目录”，包含orb的大部分元数据，这些元数据将出现在orb注册中心和CLI上。

所有球体应包括描述

当Orb被发布到Orb注册中心时，可以根据其名称和描述进行搜索。除了让用户更好地了解orb的用途和功能之外，良好的描述对于搜索优化也很重要。

包括显示链接

球体利用一个特殊的配置键显示这可以持有一个source_url要链接到您的Git存储库，又包含ORB源代码和home_url.链接到产品或服务主页(如适用)。

        显示：home_url.：“https://www.website.com/docs“source_url：“https://www.github.com/EXAMPLE_ORG/EXAMPLE_PROJECT”
       

命令

大多数ORB将包含至少一个命令

大多数球体将至少包含一个命令。命令用于代表用户自动执行shell命令和特殊的CircleCI步骤。在不太常见的情况下，例如，如果一个工具需要使用特定的Docker容器，orb可能不包含命令，而只提供作业。

使用所需的最小步骤数。

写A.可重复使用的命令对于您的ORB，您可以输入任何数量的脚步。每个步骤都应该按照它在用户UI中出现的方式正确命名。为了限制UI中“噪音”的数量，尝试使用尽可能少的步骤。

        描述：“一种演示的一种命令来安装一种CLI,进行身份验证,和部署一个应用程序”参数：api-token：类型：env_var_name.默认的：my_secret_token.脚步：-运行：的名字：“部署应用程序”命令：|pip安装示例示例登录$ < < parameters.api-token > >示例部署我的应用程序
       

        描述：“一种坏例的一种部署命令。步骤应该是命名，和合并当可能的。”参数：api-token：类型：env_var_name.默认的：my_secret_token.脚步：-运行：pip安装示例-运行：示例登录$ < < parameters.api-token > >-运行：示例部署我的应用程序
       

检查root.

在向命令添加“sudo”之前，请检查用户是否已是root用户。这可以用环境变量动态完成。

        如果[[EUID美元= =0.]];然后出口SUDO=“;其他#检查我们是否是根用户出口SUDO=“sudo”;FI.$ SUDOdo_command.
       

职位

考虑“直通”参数

在您的作业中，如果您正在使用任何命令或执行器，则必须将这些组件中的每个参数的副本包括到您的作业中。然后，您可以将给定给作业的参数“传递”给每个引用的组件。

例如，下面是节点ORB测试工作：

        描述：|简单的删除作业以自动测试NodeJS应用程序。参数：版：默认的：13.11.0描述：>必须指定完整版本标记。例如:“13.11.0”表示一个完整的列表对于版本，请参见以下内容:https://nodejs.org/en/download/releases类型：字符串执行者：的名字：默认的标签：< <参数。版本> >
       

        描述：>选择要使用的NodeJ的版本。使用Circleci的高速缓存方便为CI构建的图像。可以使用此列表中的任何可用标记：//www.drag240sx.com/developer/images/image/cimg/node.码头工人：-图片：'CIMG / node：<< parameters.tag >>'参数：标签：默认的：'13.11”描述：>选择特定的CIMG / Node Image版本标记：//www.drag240sx.com/developer/images/image/cimg/node.类型：字符串
       

如您所见，该作业利用了一个名为默认的接受一个版参数。为了使用户能够工作设置版参数执行者，我们必须在作业中创建参数，并将该参数传递给其他orb组件。

Docker Image参数可能对执行者优先

您的orb是否有多个需要特定执行环境的作业?如果是，您可以选择实现自定义执行器。您的作业可以在大多数linux平台上运行吗?考虑只使用码头工人直接执行器，并将映像参数化。

考虑帖子和精准医疗步骤和步骤参数

Circleci上的作业可以在工作之前或之后注入它们的步骤，或者在使用参数之间的某个地方。作业通常更容易为用户设置，而不是将命令组装到自定义作业中（如果适用）。可注射的步骤允许在作业中具有更大的灵活性，并且可以允许ORB中的新功能。

请参阅以下内容：

执行人

ORB并不总是要求执行者

在orb开发中，当我们有多个只能在该环境中运行的作业时，执行器通常用于提供或利用特定的执行环境。例如，如果您的orb依赖于一个特定的Docker容器，并且包含两个作业而没有命令，那么将执行环境抽象为单个环境是有意义的可重用Exeuctor用于两个作业。

在ORB外，执行者特别有用，作为创造的一种方式矩阵测试自定义工作。

例子

Orb用法示例为orb开发人员提供与社区共享用例和最佳实践的优秀方式。118金宝博娱乐城使用示例充当用户在使用orb时将引用的文档的主要来源，因此包含清晰而有用的示例非常重要。

所有公共结构应包含至少一个使用示例。

供其他组织使用的球体应该至少包含一个使用示例，并附有描述。

基于用例的例子

每个包含的使用示例都应该以特定的用例命名，以指导用户如何完成任务。例子:install_cli_and_deploy那scan_docker_container,或test_application_with_this-tool.

显示正确的orb版本

每个使用示例必须提供完整的示例，包括显示导入的orb。在use -example中显示的版本号应该与当前发布的orb匹配。如果您的orb当前处于版本上0.1.0.，而且您要为发布版本打开一个提取请求1.0.0.，应更新您的使用示例以反映版本1.0.0.正在使用的球体。

参数

秘密应该决不直接进入

任何可以被视为“秘密”的信息，例如API键，Auth令牌和密码，也不应该直接作为参数值输入。相反，ORB开发人员应该使用env_var_name.参数类型，它期望包含包含秘密信息的环境变量的名称的字符串值。

参数化安装路径

当将任何二进制文件安装到潜在未知的用户定义Docker映像中时，很难知道有哪些权限可用。创建一个安装路径参数，理想情况下，默认值/ usr / local / bin，并将二进制文件安装到此位置(如果可能)。这通常可以避免在不可能的环境中需要“根”权限的问题。

部署

始终遵循严格的语义版本化

语义版本控制是一种重要的更新和发布实践，在这种实践中，版本号可以传达错误修复和补丁、新功能或破坏更改。例如，将破坏性更改引入补丁更新，可能导致orb的用户自动接收到阻塞其CI进程的更新。在更新你的球体之前，确保你已经读过并且理解语义版本控制。

促销活动

您是否已将orb发布到orb注册中心?我们很想听听。来写个帖子吧CircleCI讨论。