CircleCI ローカル CLI の使用方法

9 months ago1 min read

クラウド

Server v4.x

Server v3.x

このページの内容

このページでは、CircleCI CLI の機能の使用方法を説明します。

Orb 開発キット

このページのガイドに従うには、以下のものが必要です：

CircleCI のアカウント：アカウントをお持ちでない方は、こちらよりサインアップして下さい。
CircleCI CLIのローカルインストール。ステップとオプションは、ローカルCLIのインストールページでご覧いただけます。
CircleCI CLIを設定する。

CircleCI の設定（コンフィグ）ファイルのバリデーション

CLI を使用して設定をローカルでバリデーションすると、.circleci/config.yml をテストするために追加のコミットをプッシュする必要がなくなります。

設定をバリデーションするには、.circleci/config.yml ファイルがあるディレクトリに移動し、以下を実行します。

circleci config validate
# Config file at .circleci/config.yml is valid

Orb 開発キット

Orb 開発キットは、相互に連携する複数のツールをセットにしたものです。キットを使うと CircleCI でのテストとデプロイが自動化されるため、 Orb の開発プロセスが容易になります。 Orb 開発キットに含まれる CLI には 2 つのコマンドがあります。

次のコマンドは新しい Orb プロジェクトを初期化します。

circleci orb init

次のコマンドはローカルスクリプトを使用して Orb をパッケージ化します。

circleci orb pack

Orb のパッケージ化について詳しくは、 Orb のコンセプトページを参照してください。

設定ファイルの Orb を検証する

ご自身の Orb を検証するには、以下の方法があります:

circleci orb validate /tmp/my_orb.yml

このコマンドは、コマンドを実行したディレクトリの /tmp フォルダーから my_orb.yml という Orb を検索します。

コンフィグのパッケージ化

circleci config pack

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

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

設定ファイルの処理

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

circleci config process

node Orb を使用する次の設定を例に考えます。

version: 2.1

orbs:
  node: circleci/node@4.7.0

workflows:
  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
    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

マシン上のコンテナ内でのジョブの実行

CLI を使用すると、Docker を使用して設定ファイル内のジョブを実行できます。設定ファイルの変更をプッシュする前にテストを実行したり、ビルドキューに影響を与えずにビルドプロセスをデバッグする際に便利です。

前提条件

システムに Docker と CLI の最新バージョンをインストールしている必要があります。また、有効な .circleci/config.yml ファイルを含むプロジェクトが必要です。

ジョブの実行

CLI により、以下のコマンドを使って Docker を使用してデスクトップ上の CircleCI から単一のジョブを実行することができます。

$ circleci local execute JOB_NAME

CircleCI の設定ファイルをバージョン 2.1 以上に設定している場合は、まず設定ファイルを process.yml にエクスポートし、以下のコマンドで実行する際にそのファイルを指定する必要があります。

circleci config process .circleci/config.yml > process.yml
circleci local execute -c process.yml JOB_NAME

以下のコマンドにより、CircleCI のデモアプリケーションのいずれかを使って、ローカルマシン上でサンプルビルドを実行します。

git clone https://github.com/CircleCI-Public/circleci-demo-go.git
cd circleci-demo-go
circleci local execute build

これらのコマンドは、build ジョブ全体を実行します (ローカルではジョブのみを実行でき、ワークフローは実行できません)。 CLI は、Docker を使用してビルドの要件をプルダウンしてから、CI ステップをローカルで実行します。この例では、Golang および Postgres の Docker イメージをプルダウンして、ビルド中に依存関係のインストール、単体テストの実行、サービスの実行テストなどを行えるようにしています。

ローカルでのジョブ実行時の制限事項

circleci を使用してジョブをローカルで実行できるのは非常に便利ですが、いくつかの制限事項があります。

Machine Executor

ローカルジョブでは Machine Executor は使用できません。 Machine Executor でジョブを実行するには、別の VM が必要になるためです。

SSH キーの追加

現時点では、add_ssh_keys CLI コマンドにより SSH キーを追加することはできません。

ワークフロー

CLI ツールでは、ワークフローの実行がサポートされていません。ワークフローは本来、複数のマシンでジョブを同時実行することで、より高速で複雑なビルドを可能にします。 CLI はユーザーのマシンでのみ動作するため、単一のジョブ (ワークフローを構成する一要素) しか実行できません。

キャッシュとオンライン限定コマンド

現在、ローカルジョブではキャッシュはサポートされていません。設定ファイルに save_cache または restore_cache のステップがあると、circleci ではそれらをスキップし、警告が表示されます。

また、オンラインでは機能しても、ローカルマシンでは機能しないコマンドもあります。たとえば、上記の Golang ビルドの例では store_artifacts ステップを実行していますが、ローカルでビルドした場合、アーティファクトはアップロードされません。ローカルのビルドで利用できないステップがあると、コンソールにエラーが表示されます。

環境変数

セキュリティ上の理由から、 Web アプリケーションで設定した暗号化された環境変数は、ローカルのビルドにはインポートされません。代わりに、-e フラグを使用して CLI に環境変数を指定できます。詳しくは、以下のコマンドの出力を参照してください。

circleci help build

環境変数が複数ある場合は、変数ごとに、次のようにフラグを使用する必要があります。

circleci build -e VAR1=FOO -e VAR2=BAR

次のステップ

CircleCI CLI は、ジョブ実行中の高度な機能、たとえばビルド時間を最適化するためのテストの分割にも使用できます。

コンテキストの管理

<<contexts#,コンテキスト>> は、環境変数を保護し、プロジェクト間で共有するためのメカニズムを提供します。 これまで、コンテキストの管理は CircleCI Web アプリケーションのみで行われて来ましたが、CircleCI CLI でも、プロジェクトにおけるコンテキストの使用を管理できるようになりました。 CLI には、以下のようにコンテキスト向けのコマンドが複数用意されています。

create - 新規コンテキストの作成
delete - 指定したコンテキストの削除
list - 全コンテキストの一覧表示
remove-secret - 指定したコンテキストからの環境変数の削除
show - コンテキストの表示
store-secret - 指定したコンテキストへの新しい環境変数の格納

これらは CLI の "サブコマンド" であり、以下のように実行されます。

circleci context create

# Returns the following:
List all contexts

Usage:
  circleci context list <vcs-type> <org-name> [flags]

多くのコマンドでは、< > で区切ったパラメーターとして詳細情報を入力するように求められます。

大部分の CLI コマンドと同様、コンテキスト関連の操作を実行するには、お使いのバージョンの CLI をトークンで適切に認証する必要があります。

次のステップ

実行環境の概要

Suggest an edit to this page

Make a contribution

Learn how to contribute

Still need help?

Ask the CircleCI community

Join the research community

Visit our Support site