ドキュメント
Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

CircleCI ローカル CLI の使用方法

1 month ago1 min read
クラウド
Server v4.x
Server v3.x
このページの内容

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

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

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

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

コンテキストの管理

コンテキスト は、環境変数を保護し、プロジェクト間で共有するためのメカニズムを提供します。 これまで、コンテキストの管理は 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 をトークンで適切に認証する必要があります。

次のステップ

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.