ORBS创作最佳实践

一般

给你的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_urlhttps://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_deployscan_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发布到orb注册中心?我们很想听听。来写个帖子吧CircleCI讨论