Orb のオーサリングのベスト プラクティス

全般

Give your orb a descriptive name

An orb “slug” is made up of a namespace and orb name separated by a forward slash. The namespace represents, the individual, company, or organization that owns and maintains the orb, while the orb name itself should describe the product, service, or action provided by the individual orb.

Proper Orb Slug Bad Orb Slug
circleci/node circleci/node-orb
company/orb company/company

Categorize your orb

Categorizing your orb allows it to be searchable on the Orb Registry by category. To see how you can categorize your orb using the CircleCI CLI, refer to the relevant section in the Orb Authoring Process guide.

Ensure all orb components include descriptions

Commands, Jobs, Executors, Examples, and Parameters can all accepts descriptions. Ensure each and every component of your orb has a helpful description and provides any additional documentation that may be needed.

description: "このコマンドは UI のステップで Hello と出力するために使用します。"
steps:
  - run:
      name: "echo コマンドの実行"
      command: echo "Hello"

Create detailed descriptions that fully explain the benefit and usage of the orb element. Descriptions are an excellent place for more specific documentation related to each component.

Ensure your orb-publishing context is restricted

If using the Orb Developer Kit, your CircleCI Personal Access Token is saved to a context in your Organization. Ensure you restrict this context so that jobs accessing it will only run when triggered or approved by you or other approved users. For more information, see the Using Contexts guide.

構成

@orb.yml

The @orb.yml file acts as the “root” of our project and contains much of the meta-data for our orb, which will appear on the Orb Registry as well as the CLI.

All orbs should include a description

When orbs are published to the Orb Registry they are searchable by their name and description. Besides giving your users a better idea of the purpose and functionality of your orb, good descriptions are important for search optimization.

Orbs utilize a special config key display that can hold a source_url for linking to your Git repository, which in turn holds the orb source code and home_url to link to the product or service home page if applicable.

display:
  home_url: "https://www.website.com/docs"
  source_url: "https://www.github.com/EXAMPLE_ORG/EXAMPLE_PROJECT"

コマンド

Most orbs will contain at least one command

Most orbs will contain at least a single command. Commands are used to execute shell commands and special CircleCI steps automatically on the user’s behalf. In less common situations, for instance, if a tool requires the use of a particular Docker container, an orb may not contain commands and only provide jobs.

Use the minimal number of steps required.

When writing a Reusable Command for your orb, you may input any number of steps. Each step should be properly named as it will appear in the user’s UI. To limit the amount of “noise” in the UI, attempt to use as few steps as possible.


description: "CLI のインストール、アプリケーションの認証とデプロイを行うデモ用コマンド。"
parameters:
  api-token:
    type: env_var_name
    default: MY_SECRET_TOKEN
steps:
  - run:
      name: "アプリケーションのデプロイ"
      command: |
        pip install example
        example login $<<parameters.api-token>>
        example deploy my-app

description: "不適切なデプロイ コマンドの例。 可能であればステップには名前を付け、まとめるようにしてください。"
parameters:
  api-token:
    type: env_var_name
    default: MY_SECRET_TOKEN
steps:
  - run: pip install example
  - run: example login $<<parameters.api-token>>
  - run: example deploy my-app

Check for root

Before adding “sudo” to your commands, check to see if the user is already the root user. This can be done dynamically with environment variables.

if [[ $EUID == 0 ]]; then export SUDO=""; else # root ユーザーかどうかを確認
  export SUDO="sudo";
fi

$SUDO do_command

ジョブ

Consider “pass-through” parameters

Inside your job, if you are utilizing any commands or executors, you must include a copy of each parameter from each of those components into your job. You can then “pass-through” the parameters given to the job, to each referenced component.

For example, here is a partial snippet of the Node orb’s test job:

description: |
  Node.js アプリケーションを自動的にテストするシンプルなドロップイン ジョブ。
parameters:
  version:
    default: 13.11.0
    description: >
      完全なバージョン タグを指定してください。 例: "13.11.0"。リリースの全一覧は
      次を参照してください: https://nodejs.org/en/download/releases
    type: string
executor:
  name: default
  tag: << parameters.version >>
description: >
  使用する Node.js のバージョンを選択します。 CI 向けにキャッシュを活用して開発された
  CircleCI 製コンビニエンス イメージを使用します。

  次のリストにあるすべてのタグを使用できます。
  https://circleci.com/developer/images/image/cimg/node
docker:
  - image: 'cimg/node:<<parameters.tag>>'
parameters:
  tag:
    default: '13.11'
    description: >
      cimg/node イメージのバージョン タグを次から選択してください。
      https://circleci.com/developer/images/image/cimg/node
    type: string

As you can see, this job utilizes an executor named default which accepts a version parameter. In order to enable the user of this job to set the version parameter in the executor, we must create the parameter in our job, and pass the parameter to our other orb components.

A docker image parameter might be preferable to an executor

Does your orb have multiple jobs which require a specific execution environment? If so, you may choose to implement a custom executor. Will your job run on most linux platforms? Consider just using the docker executor directly in your job, and parameterize the image.

Consider post and pre steps, and step parameters

Jobs on CircleCI can have steps injected into them, either before or after the job, or somewhere in-between with the use of parameters. Jobs are often easier to set up for users than assembling commands into a custom job (where applicable). Injectable steps allow for more flexibility in jobs and may allow new functionalities in your orb.

See the following:

Executor

Orbs do not always require an executor

In orb development, executors are often used to either provide or utilize a specific execution environment when we have multiple jobs which can only run in that environment. For example, if your orb relies on a specific Docker container and includes two jobs and no commands, it makes sense to abstract the execution environment into a single Reusable Exeuctor to be used for both jobs.

Executors are especially useful outside of orbs, as a way to create matrix tests for custom jobs.

使用例を付ける

Orb Usage Examples provide an excellent way for orb developers to share use-cases and best practices with the community. Usage examples act as the main source of documentation users will reference when utilizing an orb, so it is important to include clear and useful examples.

All public orbs should contain at least one usage example.

Orbs intended for consumption by other organizations should include at least one usage example, with a description.

Use-case based examples

Each included usage example should be named for a specific use-case to instruct the user in how to accomplish a task. Example: install_cli_and_deploy, scan_docker_container, or test_application_with_this-tool

Show correct orb version

Each usage example must present a full example including showing the orb being imported. The version number displayed in the usage-example should match the currently published orb. If your orb is currently on version 0.1.0, and you were to open a pull request to publish version 1.0.0, your usage examples should be updated to reflect version 1.0.0 of the orb in use.

パラメーター

Secrets should never be directly entered

Any information that could be considered “secret” such as API keys, auth tokens and passwords, should never be entered directly as parameter values. Instead, the orb developer should use the env_var_name parameter type, which expects the string value of the name of the environment variable that contains the secret information.

Parameterize the installation path

When installing any binary into a potentially unknown user-defined Docker image, it is hard to know what permissions will be available. Create an install-path parameter, ideally with a default value of /usr/local/bin, and install binaries to this location (if possible). This often avoids the issue of requiring “root” privileges in environments where that may not possible.

デプロイメント

Always follow strict semantic versioning

Semantic versioning is a critical update and release practice in which version numbers communicate either bug fixes and patches, new functionality, or breaking changes. Introducing a breaking change as a patch update, for example, can lead to users of that orb automatically receiving updates that block their CI process. Before updating your orbs, make sure you have read over and understood semantic versioning.

Keep a changelog

Keeping a concise changelog allows users of an orb to quickly see what has changed in a particular version. While git does provide a log of changes, it can be difficult to discover the difference between two versions, especially when commits don’t neccesarily align to a release. Changelogs should conform to the Keep a Changelog guidelines.

宣伝

Share your orb with the community!

Have you published an orb to the Orb Registry? We’d love to hear about it. Come make a post on CircleCI Discuss.



Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.