CircleCI を設定する

config.yml ファイルで使用される CircleCI 2.x 構成キーのリファレンス ガイドです。 CircleCI によって承認されたリポジトリ ブランチに .circleci/config.yml ファイルが存在するということは、2.x インフラストラクチャを使用することを意味しています。

config.yml の全体は「サンプル コード」で確認できます。

メモ: 既に CircleCI 1.0 バージョンの設定ファイルが存在する場合は、config.yml ファイルを使用することで、独立した別のブランチで 2.x ビルドをテストできます。このとき、古い circle.yml スタイルの既存の構成は変更する必要がなく、CircleCI 1.0 インフラストラクチャの .circleci/config.yml を含まないブランチで実行できます。

目次

• version
• orbs (version: 2.1 が必須)
• commands (version: 2.1 が必須)
• parameters (version: 2.1 が必須)
• executors (version: 2.1 が必須)
• jobs
  • <job_name>
    • environment
    • parallelism
    • docker / machine / macos / windows (Executor)
      • 使用可能な machine イメージ
      • 使用可能な Linux GPU イメージ
      • 使用可能な Windows GPU イメージ
    • branches
    • resource_class
      • docker Executor
        • 例
      • machine Executor (Linux)
        • 例
      • macOS Executor
        • 例
      • windows Executor
        • 例
      • GPU Executor (Linux)
        • 例
      • GPU Executor (Windows)
        • 例
    • steps
      • run
        • デフォルトのシェル オプション
        • バックグラウンド コマンド
        • 省略構文
        • when 属性
        • step 内からのジョブの終了
        • 例
      • when ステップ (version: 2.1 が必須)
        • 例
      • checkout
      • setup_remote_docker
      • save_cache
        • 例
      • restore_cache
        • 例
      • deploy
        • 例
      • store_artifacts
        • 例
      • store_test_results
        • 例
      • persist_to_workspace
      • root キーの例
        • paths キーの例
      • attach_workspace
        • 例
      • add_ssh_keys
      • pipeline. 値の使用
• workflows
  • version
  • <workflow_name>
    • triggers
      • schedule
        • cron
        • filters
    • jobs
      • <job_name>
        • requires
        • context
        • type
        • filters
      • ワークフローでの when の使用

version

version フィールドは、非推奨または互換性を損なう変更について注意を促すために使用します。

orbs (version: 2.1 が必須)

以下の例では、承認済みの circleci 名前空間に格納された hello-build という名前の Orb を呼び出します。

version: 2.1
orbs:
    hello: circleci/hello-build@0.0.5
workflows:
    "Hello Workflow":
        jobs:
          - hello/hello-build

上の例で、hello は Orb の参照名と見なされます。circleci/hello-build@0.0.5 は完全修飾の Orb 参照です。

commands (version: 2.1 が必須)

commands では、ジョブ内で実行する一連のステップをマップとして定義します。これにより、複数のジョブで 1 つのコマンド定義を再利用できます。

例

commands:
  sayhello:
    description: "デモ用の簡単なコマンド"
    parameters:
      to:
        type: string
        default: "Hello World"
    steps:
      - run: echo << parameters.to >>

parameters (version: 2.1 が必須)

設定ファイル内で使用するパイプライン パラメーターを定義します。 使用方法の詳細については、パイプライン変数に関するドキュメントを参照してください。

executors (version: 2.1 が必須)

executors では、ジョブのステップを実行する環境を定義します。これにより、複数のジョブで 1 つの Executor 定義を再利用できます。

⁽¹⁾ 各ジョブにいずれか 1 つの Executor タイプを指定する必要があります。 2 つ以上指定するとエラーが発生します。

例

version: 2.1
executors:
  my-executor:
    docker:
      - image: circleci/ruby:2.5.1-node-browsers

jobs:
  my-job:
    executor: my-executor
    steps:

      - run: echo outside the executor

パラメーター化された Executor の使用例については、設定ファイルの再利用に関するドキュメントの「Executor でのパラメーターの使用」を参照してください。

jobs

実行処理は 1 つ以上の名前付きジョブで構成し、 それらのジョブは jobs マップで指定します。2.0 config.yml のサンプルで jobs マップの例を紹介しています。 ジョブの名前がマップのキーとなり、ジョブを記述するマップが値となります。

ワークフローを使用している場合は、.circleci/config.yml ファイル内でジョブの名前が一意である必要があります。

ワークフローを使用しない場合は、jobs マップに build という名前のジョブを含める必要があります。 この build ジョブは、VCS プロバイダーへのプッシュによってトリガーされる実行のデフォルトのエントリポイントです。 さらにその他のジョブを指定したり、CircleCI API からジョブを実行したりできます。

メモ: ジョブの最大実行時間は 5 時間です。 ジョブがタイムアウトになる場合は、並列実行も検討してください。

<job_name>

各ジョブは、キーとなるジョブ名と、値となるマップで構成されます。 名前は、その jobs リスト内で一意である必要があります。 値となるマップでは以下の属性を使用できます。

⁽¹⁾ 各ジョブにいずれか 1 つの Executor タイプを指定する必要があります。 2 つ以上指定するとエラーが発生します。

environment

環境変数の名前と値のマップです。 これらは、CircleCI アプリケーションで設定した環境変数をオーバーライドします。

parallelism

parallelism を 2 以上に設定すると、設定した数の Executor がそれぞれセットアップされ、そのジョブのステップを並列に実行します。 これにより、テスト ステップを最適化できます。CircleCI CLI を使用して並列コンテナにテスト スイートを分割すると、ジョブの実行時間を短縮できます。 並列処理を設定していても、特定のステップでは並列処理がオプトアウトされ、1 つの Executor でのみ実行される場合があります (たとえば deploy ステップ など)。 詳細については、並列ジョブのドキュメントを参照してください。

working_directory で指定したディレクトリが存在しない場合は、自動的に作成されます。

例

jobs:
  build:
    docker:
      - image: buildpack-deps:trusty
    environment:
      FOO: bar
    parallelism: 3
    resource_class: large
    working_directory: ~/my-app
    steps:
      - run: go test -v $(go list ./... | circleci tests split)

docker / machine / macos / windows (Executor)

Executor とは、簡単に言うと「ステップの実行環境」です。 CircleCI 2.0 では、必要な数の Docker コンテナを一度にローンチすることによって必要な環境を構築するか、完全な仮想マシンを使用します。 Executor の種類については、こちらを参照してください。

docker

docker キーは、以下のマップのリストで構成します。

ファイル内で最初に記述する image が、すべてのステップを実行するプライマリ コンテナ イメージとなります。

entrypoint は、Dockerfile のデフォルトのエントリポイントをオーバーライドします。

command は、エントリポイントが Dockerfile に指定されている場合、イメージのエントリポイントに渡す引数として扱われます。あるいは、このスコープにも Dockerfile ファイルにもエントリポイントが指定されていない場合は、実行するコマンドとして扱われます。

プライマリ コンテナ (最初に記述したもの) に対して command を指定しない場合、command とイメージ エントリポイントは無視されます。これにより、エントリポイントの実行可能ファイルによる大量のリソース消費や予期しない終了によって発生するエラーが回避されます。 現時点では、steps はすべてプライマリ コンテナでのみ実行されます。

name では、セカンダリ サービス コンテナにアクセスするための名前を定義します。 デフォルトでは、すべてのサービスが localhost で直接アクセスできる状態になっています。 たとえば、同じサービスのバージョン違いを複数立ち上げるときなど、ローカル ホスト以外のホスト名を使用したい場合に、このフィールドは適しています。

environment 設定は、初期化用の command だけでなく、この Executor で実行されるすべてのコマンドに適用されます。 この environment は、前述のジョブ マップでの設定よりも優先されます。

タグまたはダイジェストを使用して、イメージのバージョンを指定できます。 任意の公式 Docker レジストリ (デフォルトは Docker Hub) にある任意のパブリック イメージを使用できます。 詳細については、イメージの指定に関するドキュメントを参照してください。

例

jobs:
  build:
    docker:
      - image: buildpack-deps:trusty # プライマリ コンテナ
        environment:
          ENV: CI

      - image: mongo:2.6.8
        command: [--smallfiles]

      - image: postgres:9.4.1
        environment:
          POSTGRES_USER: root

      - image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673

プライベート イメージを使用する場合は、auth フィールドを使用してユーザー名とパスワードを指定できます。 パスワードを保護するために、プロジェクトの設定値として設定しておいて、以下のように参照することも可能です。

jobs:
  build:
    docker:
      - image: acme-private/private-image:321
        auth:
          username: mydockerhub-user  # 文字列リテラル値を指定するか
          password: $DOCKERHUB_PASSWORD  # UI から設定したプロジェクトの環境変数を参照するように指定します

AWS ECR でホストされているイメージを使用するには、AWS 認証情報を使用した認証が必要です。 デフォルトでは、CircleCI アプリケーションの [Project (プロジェクト)] > [Settings (設定)] > [AWS Permissions (AWS 権限)] ページで追加した AWS 認証情報、またはプロジェクト環境変数の AWS_ACCESS_KEY_ID と AWS_SECRET_ACCESS_KEY を使用します。 以下の例のように、aws_auth フィールドを使用して認証情報を設定することも可能です。

jobs:
  build:
    docker:
      - image: account-id.dkr.ecr.us-east-1.amazonaws.com/org/repo:0.1
        aws_auth:
          aws_access_key_id: AKIAQWERVA  # 文字列リテラル値を指定するか
          aws_secret_access_key: $ECR_AWS_SECRET_ACCESS_KEY  # UI から設定したプロジェクトの環境変数を参照するように指定します

バージョン 2.1 を使用している場合、宣言済みのコマンドをジョブで再利用できます。以下の例では sayhello コマンドを呼び出しています。

jobs:
  myjob:
    docker:
      - image: "circleci/node:9.6.1"
    steps:
      - sayhello:
          to: "Lev"

machine

machine Executor は、machine キーと以下のマップを用いて構成します。

例

version: 2.1
jobs:
  build:
    machine:
      image: ubuntu-1604:201903-01
    steps:
      - checkout
      - run:
          name: "テスト"
          command: echo "Hi"

使用可能な machine イメージ

CircleCI ではいくつかの machine イメージをサポートしており、image フィールドで指定できます。

• ubuntu-1604:201903-01 - Ubuntu 16.04、docker 18.09.3、docker-compose 1.23.1
• circleci/classic:latest (以前のデフォルト) - Ubuntu バージョン 14.04 イメージ。Docker バージョン 17.09.0-ce、docker-compose バージョン 1.14.0 に加え、CircleCI 1.0 ビルド イメージに含まれる共通言語ツールを含みます。 latest イメージに変更があるときには、1 週間前までに告知します。 Ubuntu 14.04 のサポートは終了しました。 Ubuntu 16.04 イメージの使用をお勧めします。
• circleci/classic:edge - Ubuntu バージョン 14.04 イメージ。Docker バージョン 17.10.0-ce、docker-compose バージョン 1.16.1 に加え、CircleCI 1.0 ビルド イメージに含まれる共通言語ツールを含みます。
• circleci/classic:201703-01 – docker 17.03.0-ce、docker-compose 1.9.0
• circleci/classic:201707-01 – docker 17.06.0-ce、docker-compose 1.14.0
• circleci/classic:201708-01 – docker 17.06.1-ce、docker-compose 1.14.0
• circleci/classic:201709-01 – docker 17.07.0-ce、docker-compose 1.14.0
• circleci/classic:201710-01 – docker 17.09.0-ce、docker-compose 1.14.0
• circleci/classic:201710-02 – docker 17.10.0-ce、docker-compose 1.16.1
• circleci/classic:201711-01 – docker 17.11.0-ce、docker-compose 1.17.1
• circleci/classic:201808-01 – docker 18.06.0-ce、docker-compose 1.22.0

machine Executor は、ジョブまたはワークフローで Docker イメージをビルドするときに便利な Docker レイヤー キャッシュをサポートします。

使用可能な Linux GPU イメージ

Linux GPU Executor では、次のイメージが使用可能です。

• ubuntu-1604-cuda-10.1:201909-23 - CUDA 10.1、docker 19.03.0-ce、nvidia-docker 2.2.2
• ubuntu-1604-cuda-9.2:201909-23 - CUDA 9.2、docker 19.03.0-ce、nvidia-docker 2.2.2

使用可能な Windows GPU イメージ

Windows GPU Executor では、次のイメージが使用可能です。

• windows-server-2019-nvidia:stable - Windows Server 2019、CUDA 10.1 （このイメージがデフォルトです)

例

version: 2.1
workflows:
  main:
    jobs:
      - build
jobs:
  build:
    machine:
      image: ubuntu-1604:201903-01
      docker_layer_caching: true    # デフォルトは false

macos

CircleCI は macOS 上でのジョブ実行をサポートしており、macOS、iOS、tvOS、および watchOS 用のアプリのビルド、テスト、デプロイが可能です。 macOS 仮想マシンでジョブを実行するには、macos キーをジョブ構成の最上位に追加し、使用する Xcode のバージョンを指定します。

例: macOS 仮想マシンを Xcode バージョン 11.3 で使用する場合

jobs:
  build:
    macos:
      xcode: "11.3.0"

windows

CircleCI は、Windows 上でのジョブ実行をサポートしています。 Windows マシンでジョブを実行するには、windows キーをジョブ構成の最上位に追加する必要があります。 Orb を使用すると、Windows ジョブを簡単にセットアップできます。 Windows ジョブを実行する際の前提条件と、Windows マシンで提供される機能の詳細については、「Windows での Hello World」を参照してください。

例: Windows Executor を使用して単純なジョブを実行する場合

version: 2.1

orbs:
  win: circleci/windows@2.3.0

jobs:
  build:
    executor: win/default
    steps:

      - checkout
      - run: echo 'Hello, Windows'

branches

ワークフローを構成せず、2.1 ではなく 2.0 の設定ファイルを使用している場合に、一部のブランチの実行を許可またはブロックするルールを定義できます。ワークフローを使用している場合、ジョブ レベルのブランチは無視されるため、config.yml ファイルの workflows セクションで構成する必要があります。 2.1 の設定ファイルを使用している場合にフィルターを使用するには、ワークフローを追加する必要があります。 詳細については、workflows セクションを参照してください。 ジョブ レベルの branch キーは、以下のマップで構成します。

only と ignore のリストには、完全一致のフル ネームと正規表現のどちらでも記述できます。 正規表現は、文字列全体に一致する必要があります。 たとえば、以下のようになります。

jobs:
  build:
    branches:
      only:
        - master
        - /rc-.*/

この場合は、”master” ブランチと、正規表現 “rc-.*” に一致するブランチのみが実行されます。

jobs:
  build:
    branches:
      ignore:
        - develop
        - /feature-.*/

こちらの例では、”develop” ブランチと正規表現 “feature-.*” に一致するブランチを除くすべてのブランチが実行されます。

設定ファイルに ignore と only の両方を記述している場合は、ignore のみが考慮されます。

構成されたルールによって実行されなかったジョブは、UI のジョブ一覧にスキップのマーク付きで表示されます。

すべてのブランチで確実にジョブを実行するには、branches キーを使用しないか、only キーに正規表現 /.*/ を指定してすべてのブランチを対象にします。

resource_class

resource_class 機能を使用すると、CPU と RAM のリソース量をジョブごとに構成できます。 下表に示すように、Executor ごとにさまざまなリソース クラスが提供されています。 CircleCI Server をオンプレミスでホスティングしている場合は、利用可能なリソース クラスについてシステム管理者に問い合わせてください。

CircleCI では、すべてのお客様がシステムを安定した状態で利用できるよう、リソース クラスごとに同時処理数のソフト制限を設けています。 Performance プランまたは Custom プランを使用していて、特定のリソース クラスで待機時間が発生している場合は、このソフト制限に達している可能性があります。 CircleCI サポート にお客様のアカウントの制限値引き上げを依頼してください。

メモ: この機能は、Free プランおよび Performance プランで自動的に有効化されています。 Free プランのお客様の場合、利用可能なリソース クラスは Linux が small または medium、Windows が medium に制限されています。 MacOS は Free プランでは利用できません。 コンテナ プランのお客様は、サポート チケットをオープンして、この機能の有効化について CircleCI 営業担当者にお問い合わせください。

docker Executor

例

jobs:
  build:
    docker:

      - image: buildpack-deps:trusty
    resource_class: xlarge
    steps:
      ... // 他の構成

machine Executor (Linux)

例

jobs:
  build:
    machine: true
    resource_class: large
    steps:
      ... // 他の構成

macOS Executor

例

jobs:
  build:
    macos:
      xcode: "11.3.0"
    resource_class: large
    steps:
      ... // 他の構成

windows Executor

例

version: 2.1

orbs:
  win: circleci/windows@2.3.0

jobs:
  build:
    executor: win/default
    steps:

      - run: Write-Host 'Hello, Windows'

Windows Executor の詳細と例については、Windows に関する入門ガイド を参照してください。

GPU Executor (Linux)

例

version: 2.1

jobs:
  build:
    machine:
      resource_class: gpu.nvidia.small
      image: ubuntu-1604-cuda-10.1:201909-23
    steps:

      - run: nvidia-smi
      - run: docker run --gpus all nvidia/cuda:9.0-base nvidia-smi

使用可能なイメージの一覧は、こちらのセクションを参照してください。

GPU Executor (Windows)

例

version: 2.1
orbs:
  win: circleci/windows@2.3.0

jobs:
  build:
    executor: win/gpu-nvidia
    steps:

      - checkout
      - run: '&"C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe"'

⁽²⁾ このリソースは、サポート チームによる確認が必要となります。 ご利用の際は、サポート チケットをオープンしてください。

メモ: Java、Erlang など、CPU 数に関する情報を /proc ディレクトリから入手する言語では、CircleCI 2.0 のリソース クラス機能を使用するときに、低速化を防ぐために追加の構成が必要になることがあります。 この問題が発生すると、32 個の CPU コアを要求していても、1 コアを要求する場合よりも実行速度が低下する場合があります。 この問題が発生する言語をお使いの場合は、保証された CPU リソースに基づいて CPU 数を固定する必要があります。 割り当てられているメモリ量を確認するには、grep hierarchical_memory_limit /sys/fs/cgroup/memory/memory.stat を実行して cgroup メモリ階層制限をチェックしてください。

steps

ジョブ内の steps は、キーと値のペアを 1 つずつ列挙する形で設定します。キーはステップの種類を表し、 値は (そのステップの種類の要件に従って) 構成マップまたは文字列で記述します。 たとえば、マップで記述する場合は以下のようになります。

jobs:
  build:
    working_directory: ~/canary-python
    environment:
      FOO: bar
    steps:
      - run:
          name: テストの実行
          command: make test

ここでは、run がステップの種類です。 name 属性は、UI に表示するために使用します。 command 属性は run ステップに固有の属性で、実行するコマンドを定義します。

一部のステップは省略構文を実装しており、 たとえば run を以下のように呼び出すことが可能です。

jobs:
  build:
    steps:
      - run: make test

省略形式の run ステップでは、どの command を実行するかを文字列値で直接指定できます。 この場合、他の属性に対しては、自動的に適切なデフォルト値が設定されます (たとえば、name は command と同じ値になります)。

さらに一部のステップには別の省略表記があり、キーと値のペアの代わりに単なる文字列のステップ名を使用できます。

jobs:
  build:
    steps:
      - checkout

この例の checkout ステップは、プロジェクトのソース コードをジョブの working_directory にチェックアウトします。

通常、ステップは以下のように記述します。

定義済みステップについて、以下に詳しく説明します。

run

すべてのコマンドライン プログラムの呼び出しに使用します。構成値のマップを記述するか、省略形式で呼び出した場合には command と name の両方に使用する文字列を記述します。 run コマンドは、デフォルトでは非ログイン シェルで実行されます。したがって、ドットファイルをコマンドの中で明示的に参照する必要があります。

それぞれの run 宣言で新しいシェルが立ち上がります。 複数行の command を指定でき、その場合はすべての行が同じシェルで実行されます。

- run:
    command: |
      echo Running test
      mkdir -p /tmp/test-results
      make test

デフォルトのシェル オプション

Linux で実行するジョブの場合、shell オプションのデフォルト値は、/bin/bash がビルド コンテナに存在すれば /bin/bash -eo pipefail、 存在しなければ /bin/sh -eo pipefail になります。 デフォルトのシェルはログイン シェルではありません (--login または -l は指定されません)。 そのため、このシェルは ~/.bash_profile、~/.bash_login、~/.profile といったファイルを読み込みません。

macOS で実行するジョブの場合、デフォルトのシェルは /bin/bash --login -eo pipefail になります。 このシェルは、非対話型のログイン シェルです。 シェルは、/etc/profile/ を読み込み、続いて ~/.bash_profile を読み込んでから、各ステップを実行します。

bash を呼び出したときに実行されるファイルの詳細については、bash のマニュアル ページの INVOCATION のセクションをご覧ください。

-eo pipefail オプションについては以下のように説明されています。

-e

パイプライン (1 つのコマンドで構成される場合を含む)、かっこ「()」で囲まれたサブシェル コマンド、または中かっこ「{}」で囲まれたコマンド リストの一部として実行されるコマンドの 1 つが 0 以外のステータスで終了した場合は、直ちに終了します。

したがって、前の例で mkdir がディレクトリの作成に失敗し、0 以外のステータスを返した場合は、コマンドの実行が終了し、ステップ全体が失敗として扱われます。 それとは反対の動作にする必要がある場合は、command に set +e を追加するか、run の構成マップでデフォルトの shell をオーバーライドします。 たとえば、以下のようになります。

<br />- run:
    command: |
      echo Running test
      set +e
      mkdir -p /tmp/test-results
      make test

- run:
    shell: /bin/sh
    command: |
      echo Running test
      mkdir -p /tmp/test-results
      make test

-o pipefail

pipefail を有効にすると、パイプラインの戻り値は、0 以外のステータスで終了した最後 (右端) のコマンドのステータス値か、すべてのコマンドが正しく終了した場合に 0 となります。 シェルは、パイプライン内のすべてのコマンドの終了を待って値を返します。

たとえば、以下のようになります。

<br />- run: make test | tee test-output.log

この例では、make test が失敗した場合、-o pipefail オプションによってステップ全体が失敗します。 -o pipefail オプションを指定していなければ、パイプライン全体の結果は最後のコマンド (tee test-output.log) によって決まり、これは常に 0 のステータスを返すため、ステップの実行は常に成功となります。

make test が失敗しても、パイプラインの残りの部分は実行されることに注意してください。

この動作を回避するには、コマンドで set +o pipefail を指定するか、shell 全体をオーバーライドします (前述の例を参照)。

デフォルト オプション (-eo pipefail) を使用すると、途中のコマンドのエラーが表示され、失敗したジョブのデバッグが容易になるため、通常はこちらをお勧めします。 UI には、使用されているシェルと各 run ステップのすべての有効なオプションが表示されるため便利です。

詳細については、「シェル スクリプトの使用」を参照してください。

バックグラウンド コマンド

background 属性を使用すると、コマンドをバックグラウンドで実行するように構成できます。 background 属性を true に設定した場合、コマンドの終了を待つことなく、ジョブの実行が直ちに次のステップに進みます。 以下は、Selenium テストにおいてよく必要となる、X 仮想フレームバッファをバックグラウンドで実行するための構成例です。

- run:
    name: X 仮想フレームバッファの実行
    command: Xvfb :99 -screen 0 1280x1024x24
    background: true

- run: make test

省略構文

run では、たいへん便利な省略構文を使用できます。

- run: make test

# 省略形式のコマンドは複数行にわたって記述可能です

- run: |
    mkdir -p /tmp/test-results
    make test

この例では、command と name に run の文字列値が割り当てられたことになり、この run の構成マップの残りの属性はデフォルト値になります。

when 属性

CircleCI のデフォルトでは、ジョブ ステップが config.yml に定義された順序で一度に 1 つずつ、いずれかのステップが失敗する (0 以外の終了コードを返す) まで実行されます。 コマンドが失敗すると、以降のジョブ ステップは実行されません。

ジョブ ステップに when 属性を追加すると、このデフォルトの動作をオーバーライドして、ジョブのステータスに応じてステップを実行するかスキップするかを選択できるようになります。

デフォルト値の on_success は、それまでのすべてのステップが成功した (終了コード 0 を返した) 場合にのみ、そのステップが実行されることを意味します。

always は、それまでのステップの終了ステータスに関係なく、そのステップが実行されることを意味します。 それまでのステップの成否にかかわらずタスクを実行したい場合に便利です。 例として、ログやコード カバレッジ データをどこかにアップロードする必要があるジョブ ステップが挙げられます。

on_fail は、それまでのステップの 1 つが失敗した (0 以外の終了コードを返した) 場合にのみ、そのステップが実行されることを意味します。 失敗したテストのデバッグに役立てるために何らかの診断データを保存したり、失敗に関するカスタム通知 (メールの送信やチャットルームへのアラートのトリガーなど) を実行したりする場合に、よく使用されます。

メモ: store_artifacts、store_test_results などの一部のステップは、それより前のステップが失敗しても常に実行されます。

- run:
    name: CodeCov.io データのアップロード
    command: bash <(curl -s https://codecov.io/bash) -F unittests
    when: always # 成功しても失敗しても、コード カバレッジの結果をアップロードします

step 内からのジョブの終了

run: circleci-agent step halt を使用することで、ジョブを失敗させずに終了できます。 これは、条件に従ってジョブを実行する必要がある場合に便利です。

以下の例では、halt を使用して、develop ブランチでジョブが実行されないようにしています。

run: |
    if [ "$CIRCLE_BRANCH" = "develop" ]; then
        circleci-agent step halt
    fi

例

steps:
  - run:
      name: アプリケーションのテスト
      command: make test
      shell: /bin/bash
      working_directory: ~/my-app
      no_output_timeout: 30m
      environment:
        FOO: bar

  - run: echo 127.0.0.1 devhost | sudo tee -a /etc/hosts

  - run: |
      sudo -u root createuser -h localhost --superuser ubuntu &&
      sudo createdb -h localhost test_db

  - run:
      name: 失敗したテストのアップロード
      command: curl --data fail_tests.log http://example.com/error_logs
      when: on_fail

when ステップ (version: 2.1 が必須)

条件付きステップは、when キーまたは unless キーを含むステップで構成されます。 when キーの下に、condition サブキーと steps サブキーを記述します。 when ステップの目的は、コマンドやジョブ構成が、ワークフローの実行前にチェックされるカスタム条件 (設定ファイルのコンパイル時に決定) に基づいて実行されるようにカスタマイズすることです。 詳細については、設定ファイルの再利用に関するドキュメントの「条件付きステップの定義」を参照してください。

例

version: 2.1

jobs: # 条件付きステップは `commands:` でも定義できます
  job_with_optional_custom_checkout:
    parameters:
      custom_checkout:
        type: string
        default: ""
    machine: true
    steps:

      - when:
          condition: <<parameters.custom_checkout>>
          steps:
            - run: echo "my custom checkout"
      - unless:
          condition: <<parameters.custom_checkout>>
          steps:
            - checkout
workflows:
  build-test-deploy:
    jobs:
      - job_with_optional_custom_checkout:
          custom_checkout: "any non-empty string is truthy"
      - job_with_optional_custom_checkout

checkout

設定済みの path (デフォルトは working_directory) にソース コードをチェックアウトするために使用する特別なステップです。 これが特別なステップである理由は、単なるヘルパー関数ではなく、コードを自動的に簡単にチェックアウトできるように設計されているからです。 このステップは SSH でチェックアウトするように git を設定するため、HTTPS で git を実行する必要がある場合は、このステップを使用しないでください。

path が既に存在する場合、次のように動作します。

• Git リポジトリ - ステップはリポジトリ全体をクローンするのではなく、オリジナルをプルします。
• Git リポジトリ以外 - ステップは失敗します。

checkout は、属性のない単なる文字列としてステップを記述します。

- checkout

メモ: CircleCI は、サブモジュールをチェックアウトしません。 サブモジュールが必要なプロジェクトの場合は、以下の例に示すように、適切なコマンドを実行する run ステップを追加します。

- checkout
- run: git submodule sync
- run: git submodule update --init

このコマンドは、SSH 経由で GitHub や Bitbucket を操作するために必要な認証鍵を自動的に挿入します。この詳細は、カスタム チェックアウト コマンドを実装する際に役に立つインテグレーション ガイドで解説しています。

メモ: checkout ステップは、自動ガベージ コレクションをスキップするように Git を構成します。 restore_cache で .git ディレクトリをキャッシュし、そのキャッシュ サイズをガベージ コレクションで縮小したい場合は、その前に git gc コマンドを指定した run ステップを実行してください。

setup_remote_docker

Docker コマンドを実行するように構成されたリモート Docker 環境を作成します。 詳細については、「Docker コマンドの実行手順」を参照してください。

メモ

• Docker レイヤー キャッシュを利用するには有料アカウントが必要です。 有料のプランをお使いの場合は、サポート チケットをオープンして機能を利用できるようリクエストしてください。 リクエスト時には、CircleCI 上のプロジェクトへのリンクもお送りください。
• setup_remote_docker は、machine Executor と互換性がありません。 machine Executor で Docker レイヤー キャッシュを有効化する方法については、こちらを参照してください。
• 現在、プライベート クラウドまたはデータセンターにインストールされている CircleCI では、version キーがサポートされていません。 お使いのリモート Docker 環境にインストールされている Docker バージョンについては、システム管理者にお問い合わせください。

save_cache

依存関係やソース コードなどのファイルのキャッシュ、または複数のファイルが入ったディレクトリのキャッシュを生成して、オブジェクト ストレージに格納します。 後続のジョブで、キャッシュを復元できます。 詳細については、キャッシュに関するドキュメントを参照してください。

key に指定したキャッシュは変更不可です。一度書き込むと変更できません。

メモ: key に指定した値が既存のキャッシュの識別子と重複する場合、そのキャッシュは変更されないまま、ジョブの実行が次のステップに進みます。

新しいキャッシュを格納する際に、key に特別なテンプレートの値を含めることも可能です。

ステップの実行中に、上記のテンプレートが実行時の値に置き換えられ、その置換後の文字列が key として使用されます。

テンプレートの例

• myapp-{{ checksum "package-lock.json" }} - package-lock.json ファイルの内容が変わるたびにキャッシュが再生成されます。このプロジェクトのさまざまなブランチで同じキャッシュ キーが生成されます。
• myapp-{{ .Branch }}-{{ checksum "package-lock.json" }} - 上の例と同じように、ファイルの内容が変わるたびにキャッシュが再生成されますが、各ブランチで個別のキャッシュが生成されます。
• myapp-{{ epoch }} - ジョブを実行するごとに個別のキャッシュが生成されます。

キャッシュの key に使用するテンプレートを選択するうえでは、キャッシュの保存にはコストがかかること、キャッシュを CircleCI ストレージにアップロードするにはある程度の時間がかかることに留意してください。 したがって、実際に何か変更があった場合にのみ新しいキャッシュが生成されるような key を使用し、ジョブを実行するたびに新しいキャッシュが生成されることがないようにします。

例

<br />- save_cache:
    key: v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
    paths:
      - /home/ubuntu/.m2

restore_cache

以前に保存したキャッシュを key に基づいて復元します。 あらかじめ save_cache ステップを使用して、そのキーでキャッシュを保存しておく必要があります。 詳細については、キャッシュに関するドキュメントを参照してください。

⁽¹⁾ 少なくとも 1 つの属性を指定する必要があります。 key と keys の両方を指定すると、最初に key がチェックされ、次に keys がチェックされます。

既存のキーを対象に前方一致で検索が行われます。

メモ: 複数が一致する場合は、一致度の高さに関係なく、一致する最新のものが復元されます。

たとえば、以下のようになります。

steps:
  - save_cache:
      key: v1-myapp-cache
      paths:
        - ~/d1

  - save_cache:
      key: v1-myapp-cache-new
      paths:
        - ~/d2

  - run: rm -f ~/d1 ~/d2

  - restore_cache:
      key: v1-myapp-cache

上記の例では、最初のキー (v1-myapp-cache) が正確に一致していますが、v1-myapp-cache との前方一致となる最新のキャッシュ v1-myapp-cache-new が復元されます。

キーの書式の詳細については、save_cache ステップの key に関する説明を参照してください。

keys リストが検出されると、既存のキャッシュに最初に一致するキャッシュが復元されます。 通常は、より特定度の高いキー (たとえば、package-lock.json ファイルの正確なバージョンに対応するキー) を最初に記述し、より汎用的なキー (たとえば、プロジェクトの任意のキャッシュが対象となるキー) をその後に記述します。 キーに該当するキャッシュが存在しない場合は、警告が表示され、ステップがスキップされます。

キャッシュは元々保存されていた場所に復元されるため、ここでパスは必要ありません。

例

<br />- restore_cache:
    keys:
      - v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
      # `project.clj` の正確なバージョンに対応するキャッシュが存在しない場合は、最新のキャッシュをロードします
      - v1-myapp-

# ... アプリケーションをビルドおよびテストするステップ ...

# `project.clj` のバージョンごとに一度だけキャッシュを保存します

- save_cache:
    key: v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
    paths:
      - /foo

deploy

アーティファクトをデプロイするための特別なステップです。

deploy は、run ステップと同じ構成マップおよび構文を用います。 ジョブに 2 つ以上の deploy ステップを記述できます。

通常、以下の 2 つの例外を除いて、deploy ステップは run と同じように動作します。

• parallelism を指定したジョブにおいて、deploy ステップは、すべてのノードが成功した場合にノード #0 でのみ実行されます。 #0 以外のノードは、このステップをスキップします。
• SSH を使用して実行するジョブでは、deploy ステップは実行されず、代わりに以下のアクションが表示されます。 > skipping deploy > Running in SSH mode. Avoid deploying.

deploy ステップを使用するときには、ワークフローを使用してジョブのオーケストレーションやトリガーを実行する方法を理解しておくことをお勧めします。 ワークフローの使用方法については、以下を参照してください。

• ワークフロー
• workflows

例

- deploy:
    command: |
      if [ "${CIRCLE_BRANCH}" == "master" ]; then
        ansible-playbook site.yml
      fi

メモ: run ステップでは run: my command のようなショートカットを使用できますが、deploy ステップで同様に deploy: my command のようにショートカットを使用すると、CircleCI から以下のエラー メッセージが出力されます。

In step 3 definition: This type of step does not support compressed syntax

store_artifacts

Web アプリまたは API からアクセスできるアーティファクト (ログ、バイナリなど) を格納するステップです。 詳細については、アーティファクトに関するドキュメントを参照してください。

1 つのジョブに複数の store_artifacts ステップを記述できます。 各ステップで一意のプレフィックスを使用すると、ファイルの上書きを防止できます。

例

- run:
    name: Jekyll サイトのビルド
    command: bundle exec jekyll build --source jekyll --destination jekyll/_site/docs/
- store_artifacts:
    path: jekyll/_site/docs/
    destination: circleci-docs

store_test_results

ビルドのテスト結果をアップロードおよび保存するための特別なステップです。 テスト結果は、CircleCI Web アプリケーションで各ビルドの「テスト サマリー」セクションに表示されます。 テスト結果を保存すると、テスト スイートのタイミング分析に役立ちます。

テスト結果をビルド アーティファクトとして保存することもできます。その方法については store_artifacts ステップを参照してください。

メモ: レポートの名前が CircleCI によって正しく推測されるよう、store_test_results パスのサブディレクトリにはなるべく特定のテスト スイートの名前と一致する名前を付けてテスト結果を書き込みます。 レポートをサブディレクトリに書き込まないと、「テスト サマリー」セクションに、たとえば、Your build ran 71 tests in rspec (ビルドは rspec の 71 のテストを実行しました) ではなく、Your build ran 71 tests in unknown (ビルドは不明の 71 のテストを実行しました) のようなレポートが表示されます。

例

ディレクトリ構造

test-results
├── jest
│   └── results.xml
├── mocha
│   └── results.xml
└── rspec
    └── results.xml

config.yml 構文

- store_test_results:
    path: test-results

persist_to_workspace

一時ファイルを永続化してワークフロー内の別のジョブで使用できるようにするための特別なステップです。

メモ: ワークスペースは、作成後最大 15 日間保存されます。 作成から 15 日以上が経過したワークスペースを使用するジョブは、すべて失敗します。これには、ワークフローの部分的な再実行や SSH による個別ジョブの再実行も含まれます。

root キーは、ワークスペースのルート ディレクトリとなる、コンテナ上のディレクトリを指定します。 paths の値は、すべてルート ディレクトリからの相対的パスです。

root キーの例

たとえば、以下のステップ構文は、/tmp/dir 内にある paths で指定している内容を、ワークスペースの /tmp/dir ディレクトリ内に相対パスで永続化します。

- persist_to_workspace:
    root: /tmp/dir
    paths:
      - foo/bar
      - baz

このステップが完了すると、以下のディレクトリがワークスペースに追加されます。

/tmp/dir/foo/bar
/tmp/dir/baz

paths キーの例

- persist_to_workspace:
    root: /tmp/workspace
    paths:
      - target/application.jar
      - build/*

paths リストは、Go の Glob とパターン マッチ filepath.Match を使用します。

pattern:
    { term } term:
        '*'         区切り文字を除く任意の文字シーケンスに一致します
        '?'         区切り文字を除く任意の 1 文字に一致します
        '[' [ '^' ] { character-range }
    ']'
                    文字クラス (空白は不可)
        c           文字 c に一致します ('*'、'?'、'\\'、'[' 以外)
        '\\' c      文字 c に一致します
character-range:
        c           文字 c に一致します ('\\'、'-'、']' 以外)
        '\\' c      文字 c に一致します
        lo '-' hi   lo <= c <= hi の範囲にある文字 c に一致します

Go のドキュメントによると、パターンには /usr/*/bin/ed (‘/’ は区切り文字) などの階層的な名前を記述できます。 メモ: すべての要素はワークスペースのルート ディレクトリからの相対パスです。

attach_workspace

ワークフローのワークスペースを現在のコンテナにアタッチするための特別なステップです。 ワークスペースのすべての内容がダウンロードされ、ワークスペースがアタッチされているディレクトリにコピーされます。

例

- attach_workspace:
    at: /tmp/workspace

各ワークフローには、それぞれに一時的なワークスペースが関連付けられています。 ワークスペースは、ジョブの実行中にビルドした固有のデータを、同じワークフローの他のジョブに渡すために使用します。 ジョブ内では、persist_to_workspace ステップを使用してワークスペースにファイルを追加でき、attach_workspace ステップを使用してワークスペースの内容をファイル システムにダウンロードできます。 ワークスペースは追加専用です。ジョブは、ワークスペースにファイルを追加することはできますが、ワークスペースからファイルを削除することはできません。 各ジョブでは、そのアップストリームのジョブによってワークスペースに追加された内容を参照することのみ可能です。 ワークスペースをアタッチすると、アップストリーム ジョブがワークフロー グラフに現れる順番で、各アップストリーム ジョブからの「レイヤー」が適用されます。 2 つのジョブが同時に実行される場合、それらのレイヤーが適用される順番は不定になります。 複数の同時ジョブが同じファイル名を永続化する場合、ワークスペースのアタッチはエラーになります。

ワークフローが再実行される場合、それは、元のワークフローと同じワークスペースを継承します。 失敗したジョブのみを再実行する場合、再実行されるジョブは、元のワークフロー内のジョブと同じワークスペースの内容を参照することになります。

アーティファクト、ワークスペース、キャッシュの各機能には下記のような違いがあります。

ワークスペース、キャッシュ、アーティファクトに関する詳細は、「Persisting Data in Workflows: When to Use Caching, Artifacts, and Workspaces (ワークフローでデータを保持するには: キャッシュ、アーティファクト、ワークスペース活用のヒント)」を参照してください。

add_ssh_keys

プロジェクトの設定からコンテナに SSH 鍵を追加するための特別なステップです。 指定する鍵を使用するように SSH を構成します。

steps:
  - add_ssh_keys:
      fingerprints:
        - "b7:35:a6:4e:9b:0d:6d:d4:78:1e:9a:97:2a:66:6b:be"

メモ: CircleCI は追加されたすべての SSH 鍵に ssh-agent を使用して署名しますが、ユーザーは add_ssh_keys キーを使用して実際にコンテナに鍵を追加する必要があります。

pipeline. 値の使用

パイプライン値はすべてのパイプライン構成で使用でき、事前の宣言なしに利用できます。 利用可能なパイプライン値は次のとおりです。

たとえば、以下のようになります。

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:latest
    environment:
      IMAGETAG: latest
    working_directory: ~/main
    steps:
      - run: echo "This is pipeline ID << pipeline.id >>"

workflows

すべてのジョブのオーケストレーションに使用します。 各ワークフローは、キーとなるワークフロー名と、値となるマップで構成します。 名前は、その config.yml 内で一意である必要があります。 ワークフロー構成の最上位のキーは version と jobs です。

version

ワークフローの version フィールドは、非推奨またはベータ版での互換性を損なう変更について注意を促すために記述します。

<workflow_name>

ワークフローに付与する一意の名前です。

triggers

ワークフローを実行するトリガーを指定します。 デフォルトの動作では、ブランチにプッシュされたときにワークフローがトリガーされます。

schedule

ワークフローに schedule を記述し、それを特定の時刻に実行するよう (たとえば、毎日 UTC 午前 0 時に夜間ビルドを実行するなど) 指示できます。

workflows:
   version: 2
   nightly:
     triggers:
       - schedule:
           cron: "0 0 * * *"
           filters:
             branches:
               only:
                 - master
                 - beta
     jobs:
       - test

cron

cron キーは、POSIX の crontab 構文で定義します。

filters

フィルターでは、branches キーを使用できます。

branches

branches キーは、現在のブランチについて、スケジュール実行すべきかどうかを制御します。この「現在のブランチ」とは、trigger スタンザがある config.yml ファイルを含むブランチです。 つまり、master ブランチでのプッシュは、master ブランチでのワークフローのみをスケジュールします。

branches では only キーと ignore キーを使用でき、どちらにもブランチ名を指す 1 つの文字列をマップさせます。 / で囲むことで正規表現でブランチに一致させたり、そのような文字列のリストでマップさせたりできます。 正規表現は、文字列全体に一致する必要があります。

• only を指定した場合、一致するブランチでジョブが実行されます。
• ignore を指定した場合、一致するブランチではジョブは実行されません。
• only と ignore のいずれも指定していない場合、すべてのブランチでジョブが実行されます。
• only と ignore の両方を指定した場合、ignore よりも only が先に処理されます。

jobs

ジョブでは、requires、context、type、filters の各キーを使用できます。

<job_name>

config.yml 内に存在するジョブの名前を記述します。

requires

ジョブはデフォルトで並列に実行されるため、依存関係がある場合は、ジョブ名に基づいて明示的に要求する必要があります。

context

ジョブは、組織に設定されたグローバル環境変数を使用するように構成できます。アプリケーション設定にコンテキストを追加するには、コンテキストに関するドキュメントを参照してください。

type

ジョブで approval という type を使用できます。これは、ダウンストリーム ジョブに進む前に手動で承認を行う必要があることを示します。 ワークフローが type: approval キーを持つジョブと、そのジョブが依存するジョブを処理するまでは、依存関係の順序でジョブが実行されます。以下に例を示します。

      - hold:
          type: approval
          requires:
            - test1
            - test2
      - deploy:
          requires:
            - hold

メモ: このジョブ名 hold がメインの構成に存在してはなりません。

filters

フィルターでは、branches キーまたは tags キーを使用できます。 メモ: ワークフローは、ジョブレベルのブランチを無視します。 ジョブ レベルでブランチを指定していて、後で config.yml にワークフローを追加する場合は、ジョブ レベルのブランチを削除し、代わりにそれをワークフロー セクションで宣言する必要があります。

branches

Branches では、only キーと ignore キーを使用でき、どちらにもブランチ名を指す 1 つの文字列をマップさせます。 スラッシュで囲むことで正規表現でブランチに一致させたり、そのような文字列のリストでマップさせたりできます。 正規表現は、文字列全体に一致する必要があります。

• only を指定した場合、一致するブランチでジョブが実行されます。
• ignore を指定した場合、一致するブランチではジョブは実行されません。
• only と ignore のいずれも指定していない場合、すべてのブランチでジョブが実行されます。
• only と ignore の両方を指定した場合、ignore よりも only が先に処理されます。

tags

CircleCI では、明示的にタグ フィルターを設定しない限り、タグに対してワークフローは実行されません。 さらに、ジョブが (直接的または間接的に) 他のジョブを必要とする場合は、それらのジョブにタグ フィルターを指定する必要があります。

タグでは、only キーと ignore キーを使用できます。 スラッシュで囲むことで正規表現でタグに一致させたり、そのような文字列のリストでマップさせたりできます。 正規表現は、文字列全体に一致する必要があります。 軽量のタグと注釈付きのタグがサポートされています。

• only を指定した場合、一致するタグの場合にジョブが実行されます。
• ignore を指定した場合、一致するタグの場合にはジョブは実行されません。
• only と ignore のいずれも指定していない場合は、すべてのタグでジョブが実行されます。
• only と ignore の両方を指定した場合、ignore よりも only が先に処理されます。

詳細については、ワークフローに関するドキュメントの「Git タグに対応するワークフローを実行する」を参照してください。

ワークフローでの when の使用

CircleCI 設定ファイル v2.1 では、ワークフロー宣言内で真偽値を取る when 句を使用して (逆の条件となる unless 句も使用可)、そのワークフローを実行するかどうかを決めることができます。 最も一般的な when の用途は、パラメーターを使用した CircleCI API v2 パイプラインのトリガーです。

以下の構成例では、パイプライン パラメーター run_integration_tests を使用して integration_tests ワークフローの実行を制御しています。

version: 2.1

parameters:
  run_integration_tests:
    type: boolean
    default: false

workflows:
  version: 2
  integration_tests:
    when: << pipeline.parameters.run_integration_tests >>
    jobs:

      - mytestjob

jobs:
...

この例では、POST 本体に以下が含まれた状態でパイプラインがトリガーされたときに、テストが明示的に呼び出されない限りは integration_tests ワークフローは実行されないようにしています。

{
    "parameters": {
        "run_integration_tests": true
    }
}

いくつかの例と概念的な情報については、ワークフローに関するドキュメントを参照してください。

サンプル コード

version: 2
jobs:
  build:
    docker:

      - image: ubuntu:14.04

      - image: mongo:2.6.8
        command: [mongod, --smallfiles]

      - image: postgres:9.4.1
        # 一部のコンテナでは環境変数の設定が必要です
        environment:
          POSTGRES_USER: root

      - image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673

      - image: rabbitmq:3.5.4

    environment:
      TEST_REPORTS: /tmp/test-reports

    working_directory: ~/my-project

    steps:

      - checkout

      - run:
          command: echo 127.0.0.1 devhost | sudo tee -a /etc/hosts

      # Postgres のユーザーとデータベースの作成
      # YAML ヒアドキュメント '|' を使用して体裁を整えています

      - run: |
          sudo -u root createuser -h localhost --superuser ubuntu &&
          sudo createdb -h localhost test_db

      - restore_cache:
          keys:
            - v1-my-project-{{ checksum "project.clj" }}
            - v1-my-project-

      - run:
          environment:
            SSH_TARGET: "localhost"
            TEST_ENV: "linux"
          command: |
            set -xu
            mkdir -p ${TEST_REPORTS}
            run-tests.sh
            cp out/tests/*.xml ${TEST_REPORTS}

      - run: |
          set -xu
          mkdir -p /tmp/artifacts
          create_jars.sh ${CIRCLE_BUILD_NUM}
          cp *.jar /tmp/artifacts

      - save_cache:
          key: v1-my-project-{{ checksum "project.clj" }}
          paths:
            - ~/.m2

      # アーティファクトの保存

      - store_artifacts:
          path: /tmp/artifacts
          destination: build

      # テスト結果のアップロード

      - store_test_results:
          path: /tmp/test-reports

  deploy-stage:
    docker:

      - image: ubuntu:14.04
    working_directory: /tmp/my-project
    steps:
      - run:
          name: テストに合格し、ブランチがステージングならデプロイ
          command: ansible-playbook site.yml -i staging

  deploy-prod:
    docker:

      - image: ubuntu:14.04
    working_directory: /tmp/my-project
    steps:
      - run:
          name: テストに合格し、ブランチが master ならデプロイ
          command: ansible-playbook site.yml -i production

workflows:
  version: 2
  build-deploy:
    jobs:

      - build:
          filters:
            branches:
              ignore:
                - develop
                - /feature-.*/
      - deploy-stage:
          requires:
            - build
          filters:
            branches:
              only: staging
      - deploy-prod:
          requires:
            - build
          filters:
            branches:
              only: master

関連項目

設定ファイルの概要