設定ファイルの概要

1+ year ago2 min read

クラウド

Server v4.x

Server v3.x

このページの内容

このガイドでは、CircleCI config.yml ファイルの使用方法を説明します。

CircleCI 設定ファイル入門

このガイドでは、以下のトピックについて説明します。

CircleCI config.yml を検索、実行する方法
シェルコマンドを使ってアクションを実行する方法
config.yml がコードとやり取りする方法
ビルドをトリガーする方法
Docker コンテナを使用して、特定の環境でジョブを実行する方法
ワークフローを使用して、ビルドをオーケストレーションする方法
ワークフローに承認ステップを追加する方法

CircleCI は Configuration as Code を貫いています。その結果として、ビルドからデプロイまでのデリバリープロセス全体が config.yml という 1 つのファイルを通じてオーケストレーションされます。 config.yml ファイルは、リポジトリプロジェクトの最上部にある .circleci というフォルダーに置かれます。 CircleCI の設定には YAML 構文が使われます。その基本的な内容については、 YAML の記述を参照してください。

パート 1: シェルの使用

CircleCI では、オンデマンドのシェルによりコマンドを実行します。パート 1 では、ビルドをセットアップし、シェルコマンドを実行します。

ユーザー登録がお済みでない場合は、 CircleCI のユーザー登録を行い、バージョン管理システム (VCS) を選択します。メールアドレスで登録することもできます。
プロジェクトのルートに、.circleci フォルダーを作成します。フォルダー名は、CircleCI が認識できるように、必ずピリオドで始めてください。

config.yml ファイルを .circleci フォルダー内に作成し、以下のコードをペーストします。

Docker実行環境を使用する場合は、イメージ・レジストリ（image registries）から Docker プルを認証することを推奨します。認証されたプルでは、プライベートな Docker イメージにアクセスすることができ、レジストリのプロバイダによっては、より高いレート制限が付与される場合もあります。詳細は、 Docker の認証付きプルの使用を参照して下さい。

version: 2.1
jobs:
  build:
    docker:
      - image: alpine:3.15
    steps:
      - run:
          name: The First Step
          command: |
            echo 'Hello World!'
            echo 'This is the delivery pipeline'

上記サンプルコードの各行について、以下で解説します。 * 1 行目: 使用している CircleCI プラットフォームのバージョンを示します。 2.1 が最新のバージョンです。 * 2 行目: jobs レベルには、子ジョブのコレクションが含まれ、ジョブを表しています。これらのジョブの名前を指定します (build、test、deploy など) 。 * 3 行目: build は、jobs コレクションの最初の子ジョブです。このサンプルでは、build は唯一のジョブでもあります。 * 4 行目: これは、ジョブのコマンドが実行されるコンテナに対し Docker イメージを使用していることを示します。 * 5 行目: これが Docker イメージです。このサンプルでは、Alpine Linux に基づいたミニマムイメージである alpine:3.15 を示します。 * 6-8 行目: Docker レジストリの認証情報を記載します。この部分はオプションです。詳細は、 Docker の認証付きプルの使用を参照して下さい。 * 9 行目: steps コレクションは、run ディレクティブのリストです。 * 10 行目: 各 run ディレクティブは、宣言された順に実行されます。 * 11 行目: name 属性は、警告、エラー、出力などを返す際に関連情報を提供します。 name は、ビルドプロセス内のアクションとしてわかりやすいものにする必要があります。 * 12 行目: command 属性は、実行するシェルコマンドのリストです。最初のパイプ | は、複数行のシェルコマンドがあることを示します。 * 13 行目: ビルドシェルに Hello World! を出力します。 * 14 行目: This is the delivery pipeline と出力します。

config.yml ファイルをコミット (リモートで作業している場合は、コミット後にプッシュ) します。

CircleCI の Projects ページで、プロジェクトを検索し、横にある青色の Set Up Project ボタンをクリックします。

バージョン管理システム (VCS) で、CircleCI で管理するプロジェクトへのアクセスが承認されていることを確認します (GitHub では、CircleCI によるプライベートリポジトリへのアクセスをブロックするオプションがあります)。

ポップアップウィンドウで、config.yml ファイルを選択するためにデフォルトの Fastest オプションを選択します。次に、コミットしたブランチの名前を入力します。ステップ 2 とステップ 3 に従うと、緑色のチェックマークが表示され、CircleCI が config.yml ファイルをプロジェクトの .circleci ディレクトリに配置したことを確認できます。ここで、青色の Set Up Project ボタンをクリックします。
CircleCI は、config.yml ファイルを使用してパイプラインを実行します。その出力は、CircleCI ダッシュボードで確認できます。緑色のチェックマークは、パイプラインに成功したことを意味します。赤色のエクスクラメーションマークは、失敗を意味します。詳細については、ジョブをクリックします。

コマンドの出力で、ご自分のステップである最初のステップを確認します。

config.yml の構文そのものは簡単ですが、インデントは複雑です。そのため、インデントの誤りが最も一般的なエラーとなっています。この例で問題が発生した場合は、インデントを注意して確認するか、サンプルコードをコピー & ペーストしてください。

パート 2: リポジトリのコードの使用

複雑なアクションを簡素化するため、CircleCI は複数のコマンドを提供しています。ここでの例では、checkout コマンドを使用します。このコマンドは、Git リポジトリからコードをフェッチします。このコードを取得すると、その後のステップで使用して作業できます。

まだ取得していない場合は、.circleci ディレクトリをプロジェクトに作成し、config.yml ファイルを追加して、以下の例からコードを入力するかペーストします。

上述の例の config.yml ファイルがすでにある場合は、次のように変更を加えます。

5 行目で、イメージを cimg/base:2021.04 に変更します。
7 行目で、checkout コマンドを追加します。
最後に、2 つ目の run ステップ (13-17 行目) を追加します。

インデントが守られていることを確認します。

version: 2.1
jobs:
  build:
    docker:
      - image: cimg/base:2021.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - run:
          name: The First Step
          command: |
            echo 'Hello World!'
            echo 'This is the delivery pipeline'
      - run:
          name: The Second Step
          command: |
            ls -al
            echo '^^^The files in your repo^^^'

この 2 つの小さな変更により、設定ファイルの機能が著しく向上します。

5 行目: この行は、Git をサポートする Docker イメージを示します。 cimg/base:2021.04 は、基本的なジョブを実行する Ubuntu ベースの小さなイメージです。
10 行目: checkout コマンドは、Git リポジトリからコードをフェッチします。
16-20 行目: build ジョブのこの 2 つ目のステップは、すでにチェックアウトされているリポジトリの内容を、(ls -al を使用して) リストします。これで、このリポジトリでさらに多くのアクションを実行できます。

前回と同じように、更新した config.yml ファイルをコミットし、プッシュします。

CircleCI ダッシュボードには、その他のステップも表示されます。

Checkout code により、Git リポジトリからコードがクローンされています。
The Second Step は、Git リポジトリで確認されたファイルをリストしています。

パート 3: さまざまな環境の使用とワークフローの作成

パート 1 とパート 2 では、Linux ベースの基本的な Docker コンテナでジョブを実行しました。

CircleCI を使用すると、仮想マシンや Docker コンテナなどのさまざまな実行環境で、各種ジョブを実行できます。 Docker イメージを変更することで、環境のバージョンを素早く更新したり、言語を変更したりできます。

このパートでは、さまざまな Docker イメージを使用してさらにジョブを作成、実行します。

まだ実施していない場合は、.circleci ディレクトリをプロジェクトに作成し、config.yml ファイルを追加して、以下の例からコードを入力するかペーストします。

version: 2.1
jobs:
  # running commands on a basic image
  Hello-World:
    docker:
      - image: cimg/base:2021.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run:
          name: Saying Hello
          command: |
            echo 'Hello World!'
            echo 'This is the delivery pipeline'
  # fetching code from the repo
  Fetch-Code:
    docker:
      - image: cimg/base:2021.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - run:
          name: Getting the Code
          command: |
            ls -al
            echo '^^^Your repo files^^^'
  # running a node container
  Using-Node:
    docker:
      - image: cimg/node:17.2
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run:
          name: Running the Node Container
          command: |
            node -v
workflows:
  Example-Workflow:
    jobs:
      - Hello-World
      - Fetch-Code:
          requires:
            - Hello-World
      - Using-Node:
          requires:
            - Fetch-Code

この例は他の例と比べるとより複雑になっていますが、いくつかの重要なコンセプトが導入されています。パート 1 およびパート 2 には build というジョブが 1 つ含まれており、そのジョブには複数のステップがありました。しかし、この例では 3 つのジョブが含まれています。こうしたステップをジョブに分離することで、そのそれぞれを異なる環境で実行できるようになります。

上記サンプルコードの各行について、以下で解説します。

3 行目: # (ハッシュ) 記号をコメントの前に置くことにより、config.yml ファイルにコメントを追加できます。
4-15 行目: 最初のジョブは Hello-World です。パート 1 でのように、基本的なイメージ内で 2 つのコマンドを実行します。
17 行目: 2 つ目のジョブは Fetch-Code です。これは、_Hello-World_job に合わせてインデントされます。
18-19 行目: Fetch-Code ジョブは、Git 互換の基本的なイメージを使用します。
23-29 行目: このコードはパート 2 から繰り返されていますが、ここでは別個のジョブです。
31 行目: 3 つ目のジョブは Using-Node です。
32-33 行目: この Using-Node ジョブは、cimg/node:17.2 という Docker イメージを使用します。このイメージには、ブラウザーと他の便利なツールと共に、Node のバージョン 17.2 が含まれています。
37-41 行目: これまでのジョブ同様に、run ステップがあります。ここでは、コマンド node -v がコンテナで実行する Node のバージョンを出力します。
42-43 行目: この行は、Example-Workflow というワークフローを作成します。ワークフローは、ジョブのリストとその実行順を定義します。
44-45 行目: これらの行は最初のジョブである Hello-World を指定します。
46-48 行目: Fetch-Code ジョブ用の構文は少し異なります。ジョブ名の後ろには requires: が続き、その後ろに requires ステートメントが続きます。この行は、Fetch-Code ジョブを実行する前に、Hello-World ジョブを正常に実行する必要があることを示します。
49-51 行目: 最初のジョブは Using-Node です。上記と同様に、このジョブもその前のジョブ、 Fetch-Code が正常に完了している必要があります。

前回と同じように、更新した config.yml ファイルをコミットし、プッシュします。

CircleCI では、パイプラインは異なって見えます。これで、ワークフローは Example-Workflow という名前となり、ジョブは 1 つだけではなく、3 つになりました。

Using-Node ジョブをクリックし、続いて Running the Node Container ステップをクリックすると、コマンド node -v により Node のバージョンが出力されたのが確認できます。

この例では、次のことを行いました。

ジョブをドキュメント化するためにコメントを追加
複数のジョブを作成し、さまざまな Docker コンテナで実行
ワークフローを作成し、ジョブの実行順序を定義
次のジョブの実行に、前のジョブの正常な完了を条件とするロジックを導入

さらに理解を深めるために、他の CircleCI イメージを試すか、ワークフローにジョブをもう少し追加することをお勧めします。

パート 4: 手動による承認の追加

CircleCI のワークフローモデルは、先行ジョブのオーケストレーションに基づいています。パート 3 で説明したように、requires ステートメントはその前のジョブが正常に実行された場合にのみ、ジョブを実行するように指定しています。

パート 3 では、パイプラインをトリガーするイベントにより、Hello-World ジョブがすぐに実行されました。 Hello-World が正常に完了した後、残りのジョブが自動的に実行されました。

このパートでは、手動による承認ステージを作成します。これは、CircleCI アプリで次のステップを承認した場合にのみ、後続のジョブが実行されることを意味します。

version: 2.1
jobs:
  # running commands on a basic image
  Hello-World:
    docker:
      - image: alpine:3.15
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run:
          name: Saying Hello
          command: |
            echo 'Hello World!'
            echo 'This is the delivery pipeline'
  # fetching code from the repo
  Fetch-Code:
    docker:
      - image: cimg/base:2021.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - checkout
      - run:
          name: Getting the Code
          command: |
            ls -al
            echo '^^^Your repo files^^^'
  # running a node container
  Using-Node:
    docker:
      - image: cimg/node:17.2
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run:
          name: Running the Node Container
          command: |
            node -v
  Now-Complete:
    docker:
      - image: alpine:3.15
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run:
          name: Approval Complete
          command: |
            echo 'The work is now complete.'

workflows:
  Example-Workflow:
    jobs:
      - Hello-World
      - Fetch-Code:
          requires:
            - Hello-World
      - Using-Node:
          requires:
            - Fetch-Code
      - Hold-for-Approval:
          type: approval
          requires:
            - Using-Node
            - Fetch-Code
      - Now-Complete:
          requires:
            - Hold-for-Approval

このコードの多くは今後何度も登場します。重要な追加事項がいくつかあります。

64-68 行目: これにより、Hold-for-Approval という新しいジョブが作成されます。 type で approval と指定されています。そのため、CircleCI でこのジョブを手動で承認することが求められます。これは、それまでのジョブが期待どおりに実行されたかどうかを確認する場合に便利です。例えば、Web サイトを公開する前にテストサーバー上で正常に見えるかどうかを確認できます。または、高コストのジョブを実行する前に、人間による確認を行いたい場合などです。
69-71 行目: この最後のジョブ Now-Complete は、Hold-for-Approval が正常に完了していることを前提とし、CircleCI でその前のジョブを承認した場合にのみ実行されます。

これまでのように、更新した config.yml ファイルをコミットし、プッシュします。

CircleCI でパイプラインを見ると、 On Hold という紫色のステータスバッジが表示されています。

ジョブを承認するには、Actions 列の Hold-for-Approval ジョブの右にある Thumbs up アイコンをクリックします。ポップアップメッセージで、青色の Approve ボタンをクリックします。

これで、Actions 列にチェックマークが表示され、ジョブが完了します。

Now-Complete ジョブをクリックし、続いて Approval Complete ステップをクリックします。コマンドの出力である The work is now complete が確認できます。

エラーの場合、問題は誤ったインデントにより引き起こされていることがあります。 CircleCI 設定ファイルエディターにより構文が検証され、オートコンプリートによる提案とともにヒントが表示されます。

この例では、次のことを行いました。

新たなロジックを導入してワークフローを制御
ワークフロー内で手動による承認を要求するため、approval ジョブタイプを実行

上記で習得した内容を活用すると、強力なパイプラインを作成することができます。