無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

Orb の手動作成プロセス

1+ year ago1 min read
クラウド
このページの内容

ここでは、Orb 開発キットを使わずにシンプルな Orb を手動で作成する手順について説明します。 ほとんどの Orb プロジェクトでは Orb 開発キットを使用することを推奨しています。

1. 名前空間の作成

まだ名前空間を作成していない場合は、次のコマンドでユーザー/組織の名前空間を作成します。 希望する名前空間と GitHub 組織名を入力して実行してください。

circleci namespace create <name> --org-id <your-organization-id>

2. Orb の作成

名前空間内に Orb を作成します。 この段階では Orb のコンテンツは何も生成されませんが、Orb をパブリッシュするときために名前が予約されます。 **CircleCI Server をご利用の場合は、--private フラグが使われており、Orb がインストール環境内でプライベートになっていることを確認してください。 パブリック Orb を作成する場合:

circleci orb create <my-namespace>/<my-orb-name>

プライベート Orb を作成する場合:

circleci orb create <my-namespace>/<my-orb-name> --private

YAML ファイル形式で Orb のコンテンツを作成します。 以下のシンプルな例を参考にしてください。

version: 2.1
description: あいさつコマンド Orb
commands:
    greet:
        description: 相手に "Hello" とあいさつします。
        parameters:
            to:
                type: string
                default: World
        steps:
            - run: echo "Hello, << parameters.to >>"

3. 設定のパッケージ化 (オプション)

CLI パッケージ化コマンド (circleci orb packとは異なる) を使うと、複数の個別ファイルから (ディレクトリ構造とファイルの内容に基づいて) 1 つの YAML ファイルを作成できます。 pack コマンドには、ディレクトリツリー内の複数ファイルにまたがる YAML ドキュメントを解析する FYAML が実装されています。 これは、容量の大きな Orb のソースコードを分割する際に特に便利で、Orb の YAML 設定ファイルの編成をカスタマイズできます。

circleci config pack

pack コマンドを使用するときのファイルの名前編成に応じて、最終的にどのような orb.yml が出力されるかが決まります。 次のフォルダー構造を例に考えてみましょう。

$ tree
.
└── your-orb-source
    ├── @orb.yml
    ├── commands
    │   └── foo.yml
    └── jobs
        └── bar.yml

3 directories, 3 files

Unix の tree コマンドは、フォルダー構造の出力に大変便利です。 上記のツリー構造の例の場合、pack コマンドは、フォルダー名とファイル名を YAML キーにマップし、ファイルの内容をとして対応するキーにマップします。

次のコマンドにより、前述のフォルダー例が pack されます。

$ circleci config pack your-orb-source

出力は .yml ファイルに格納されます。

# Contents of @orb.yml appear here
commands:
  foo:
    # contents of foo.yml appear here
jobs:
  bar:
    # contents of bar.yml appear here

その他の設定ファイルのパッケージ化機能

@ で始まるファイルの内容は、その親フォルダーのレベルにマージされます。 この機能は、汎用的な orb.yml にメタデータを格納したいものの、orb のキーと値のペアにはマップしたくない場合に、トップレベルの Orb で使用すると便利です。

たとえば以下のような場合、

$ cat foo/bar/@baz.yml
{baz: qux}

このファイルは、次のようにマップされます。

bar:
  baz: qux

4. Orb のバリデーション

CLI を使用して、Orb コードをバリデーションします。

circleci orb validate /tmp/orb.yml

設定の処理 (オプション)

次のコマンドを実行すると設定ファイルがバリデーションされると共に、展開されたソース設定ファイルが元の設定ファイルと一緒に表示されます (Orb を使用している場合に便利です)。

circleci config process

下記の node を使用する設定を例に考えます。

version: 2.1

orbs:
  node: circleci/node@4.7.0

workflows:
  version: 2
  example-workflow:
      jobs:
        - node/test

次のコマンドを実行すると、下記の例のような YAML ファイルが出力されます (展開されたソースとコメントアウトされた元の設定が混在しています)。

circleci config process .circleci/config.yml

# Orb 'circleci/node@4.7.0' resolved to 'circleci/node@4.7.0'
version: 2
jobs:
  node/test:
    docker:
    - image: cimg/node:13.11.0
      auth:
        username: mydockerhub-user
        password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
    - checkout
    - run:
        command: |
          if [ ! -f "package.json" ]; then
            echo
            echo "---"
            echo "Unable to find your package.json file. Did you forget to set the app-dir parameter?"
            echo "---"
            echo
            echo "Current directory: $(pwd)"
            echo
            echo
            echo "List directory: "
            echo
            ls
            exit 1
          fi
        name: Checking for package.json
        working_directory: ~/project
    - run:
        command: |
          if [ -f "package-lock.json" ]; then
            echo "Found package-lock.json file, assuming lockfile"
            ln package-lock.json /tmp/node-project-lockfile
          elif [ -f "npm-shrinkwrap.json" ]; then
            echo "Found npm-shrinkwrap.json file, assuming lockfile"
            ln npm-shrinkwrap.json /tmp/node-project-lockfile
          elif [ -f "yarn.lock" ]; then
            echo "Found yarn.lock file, assuming lockfile"
            ln yarn.lock /tmp/node-project-lockfile
          fi
          ln package.json /tmp/node-project-package.json
        name: Determine lockfile
        working_directory: ~/project
    - restore_cache:
        keys:
        - node-deps-{{ arch }}-v1-{{ .Branch }}-{{ checksum "/tmp/node-project-package.json" }}-{{ checksum "/tmp/node-project-lockfile" }}
        - node-deps-{{ arch }}-v1-{{ .Branch }}-{{ checksum "/tmp/node-project-package.json" }}-
        - node-deps-{{ arch }}-v1-{{ .Branch }}-
    - run:
        command: "if [[ ! -z \"\" ]]; then\n  echo \"Running override package installation command:\"\n  \nelse\n  npm ci\nfi\n"
        name: Installing NPM packages
        working_directory: ~/project
    - save_cache:
        key: node-deps-{{ arch }}-v1-{{ .Branch }}-{{ checksum "/tmp/node-project-package.json" }}-{{ checksum "/tmp/node-project-lockfile" }}
        paths:
        - ~/.npm
    - run:
        command: npm run test
        name: Run NPM Tests
        working_directory: ~/project
workflows:
  version: 2
  example-workflow:
    jobs:
    - node/test

# Original config.yml file:
# version: 2.1
#
# orbs:
#   node: circleci/node@4.7.0
#
# workflows:
#   version: 2
#   example-workflow:
#       jobs:
#         - node/test

5. Orb のパブリッシュ

開発版の Orb をパブリッシュします。

circleci orb publish /tmp/orb.yml <my-namespace>/<my-orb-name>@dev:first

Orb を安定版にプッシュする準備が整ったら、circleci orb publish を使用して手動でパブリッシュするか、開発版から直接プロモートすることができます。 以下のコマンドを使用すると、開発版のバージョン番号を 0.0.1 にインクリメントできます。

circleci orb publish promote <my-namespace>/<my-orb-name>@dev:first patch

安定版の Orb が変更不可形式でパブリッシュされ、CircleCI プロジェクトで安全に使用できるようになりました。 以下のコマンドを使用して、Orb のソースをプルします。

circleci orb source <my-namespace>/<my-orb-name>@0.0.1

利用可能な Orb の一覧

CLI を使用して、公開されている Orb を一覧表示できます。

パブリック Orb を一覧表示する場合:

circleci orb list <my-namespace>

プライベート Orb を一覧表示する場合:

circleci orb list <my-namespace> --private

次のステップ

circleci orb コマンドの使用方法の詳細については、 CLI に関するドキュメントを参照してください。


Suggest an edit to this page

Make a contribution
Learn how to contribute