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 を含まないブランチで実行できます。

• setup
• version
• orbs (version: 2.1 が必須)
• commands (version: 2.1 が必須)
• parameters (version: 2.1 が必須)
• executors (version: 2.1 が必須)
• jobs
  • <job_name>
    • environment
    • parallelism
    • parameters
    • 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
        • orbs (version: 2.1 が必須)
        • メモ: store_artifacts、store_test_results などの一部のステップは、それより前のステップが失敗しても常に実行されます。
      • ワークフローでの when の使用
• Logic statements
  • Logic statement examples
• Example full configuration

setup

setup フィールドを指定すると、プライマリ .circleci 親ディレクトリ外部にある設定ファイルのトリガー、パイプライン パラメーターの更新、およびカスタマイズされた設定ファイルの生成を、条件に従って実行できます。

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 参照です。 circleci/hello-build@0.0.5 は完全修飾の Orb 参照です。

commands (version: 2.1 が必須)

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

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

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
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照

jobs:
  my-job:
    executor: my-executor
    steps:
      - run: echo outside the executor

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

jobs

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

注: ジョブの最大実行時間は 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
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    environment:
      FOO: bar
    parallelism: 3
    resource_class: large
    working_directory: ~/my-app
    steps:
      - run: go test -v $(go list ./... | circleci tests split)

parameters

parameters は、このジョブをワークフローで呼び出すときに使用できます。

予約されているパラメーター名は以下のとおりです。

• name
• requires
• context
• type
• filters
• matrix

定義の詳細については、「パラメーターの構文」を参照してください。

docker/machine/macos/windows (Executor)

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

docker

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

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

entrypoint は、イメージの ENTRYPOINT をオーバーライドします。

command はイメージの CMD をオーバーライドし、イメージに ENTRYPOINT があれば、それに渡す引数として扱われます。イメージに ENTRYPOINT がない場合は、実行するコマンドとして扱われます。

プライマリ コンテナ (リストの最初にあるコンテナ) については、設定ファイルで command も entrypoint も指定されていない場合、イメージ内のすべての ENTRYPOINT と CMD が無視されます。 というのも、プライマリ コンテナは通常 steps の実行のみに使用されるもので ENTRYPOINT 用ではなく、ENTRYPOINT は大量のリソースを消費したり、予期せず終了したりする可能性があるためです (カスタム イメージはこの挙動を無効にし、ENTRYPOINT を強制的に実行する場合があります)。ジョブの steps はプライマリ コンテナでのみ実行されます。

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

environment 設定は、ジョブ ステップではなく Docker コンテナによって実行される ENTRYPOINT と CMD に適用されます。

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

Docker Hub など、一部のレジストリでは、匿名ユーザーによる Docker のプル回数に上限が設定されている場合があります。 こうした場合にプライベート イメージとパブリック イメージをプルするには、認証を行うことをお勧めします。 ユーザー名とパスワードは auth フィールドで指定できます。 詳細については、「Docker の認証付きプルの使用」を参照してください。

例

jobs:
  build:
    docker:
      - image: buildpack-deps:trusty # プライマリ コンテナ
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
        environment:
          ENV: CI

      - image: mongo:2.6.8
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
        command: [--smallfiles]

      - image: postgres:9.4.1
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
        environment:
          POSTGRES_USER: root

      - image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照

      - 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"
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    steps:
      - sayhello:
          to: "Lev"

machine

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

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

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

使用可能な machine イメージ

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

• ubuntu-2004:202104-01 - Ubuntu 20.04、Docker v20.10.6、Docker Compose v1.29.1
• ubuntu-2004:202101-01 - Ubuntu 20.04、Docker v20.10.2、Docker Compose v1.28.2

• ubuntu-2004:202010-01 - Ubuntu 20.04、Docker v19.03.13、Docker Compose v1.27.4 (ubuntu-2004:202008-01 はエイリアス)

• circleci/classic:201710-01 – docker 17.09.0-ce、docker-compose 1.14.0
• ubuntu-1604:202101-01 - Ubuntu 16.04、Docker v19.03.14、Docker Compose v1.28.2 (最新版の 1 つ前のリリース)
• ubuntu-1604:202010-01 - Ubuntu 16.04、Docker v19.03.13、Docker Compose v1.27.4
• ubuntu-1604:202007-01 - Ubuntu 16.04、Docker v19.03.12、Docker Compose v1.26.1
• ubuntu-1604:202004-01 - Ubuntu 16.04、Docker v19.03.8、Docker Compose v1.25.5
• ubuntu-1604:201903-01 - Ubuntu 16.04、Docker v18.09.3、Docker Compose v1.23.1

Note: Ubuntu 16.04 has reached the end of its LTS window as of April 2021 and will no longer be supported by Canonical. As a result, ubuntu-1604:202104-01 is the final Ubuntu 16.04 image released by CircleCI. We suggest upgrading to the latest Ubuntu 20.04 image for continued releases and support past April 2021.

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

使用可能な Linux GPU イメージ

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

• ubuntu-1604-cuda-11.1:202012-01 - CUDA v11.1、Docker v19.03.13、nvidia-container-toolkit v1.4.0-1
• ubuntu-1604-cuda-10.2:202012-01 - CUDA v10.2、Docker v19.03.13、nvidia-container-toolkit v1.3.0-1
• ubuntu-1604-cuda-10.1:201909-23 - CUDA v10.1、Docker v19.03.0-ce、nvidia-docker v2.2.2
• ubuntu-1604-cuda-9.2:201909-23 - CUDA v9.2、Docker v19.03.0-ce、nvidia-docker v2.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: windows-server-2019-nvidia:stable
      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 – 非推奨

このキーは非推奨になりました。 Use workflows filtering to control which jobs run for which 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 では、すべてのお客様がシステムを安定した状態で利用できるよう、リソース クラスごとに同時処理数のソフト制限を設けています。 Performance プランまたは Custom プランを使用していて、特定のリソース クラスで待機時間が発生している場合は、このソフト制限に達している可能性があります。 CircleCI サポートにお客様のアカウントの制限値引き上げを依頼してください。

注: この機能は、Free プランおよび Performance プランでは自動的に有効化されています。 Free プランのお客様の場合、利用可能なリソース クラスは Linux が small または medium、Windows が medium に制限されています。 MacOS は Free プランでは利用できません。

CircleCI Server をオンプレミスでホスティングしている場合は、利用可能なリソース クラスについてシステム管理者に問い合わせてください。 詳細については、サーバーの管理に関するドキュメントで Nomad クライアントのシステム要件とサーバーのリソース クラスのセクションを参照してください。

Docker Executor

例

jobs:
  build:
    docker:
      - image: buildpack-deps:trusty
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数の参照
    resource_class: xlarge
    steps:
      ... // 他の構成

resource_class を使用してランナー インスタンスを構成することもできます。

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

jobs:
  job_name:
    machine: true
    resource_class: my-namespace/my-runner

machine Executor (Linux)

例

jobs:
  build:
    machine:
      image: ubuntu-2004:202010-01 # 推奨 Linux イメージ
    resource_class: large
    steps:
      ... // 他の構成

machine クラスを使用してランナー インスタンスを構成することも可能です。

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

jobs:
  job_name:
    machine: true
    resource_class: my-namespace/my-runner

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:
      name: win/default
      size: "medium" # "medium"、"large"、"xlarge"、"2xlarge" のいずれを指定可能
    steps:
      - run: Write-Host 'Hello, Windows'

Executor が Windows Orb 内で定義されているため、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

あるステップの完了を待つことなく後続の run ステップを実行したい場合は、バックグラウンドでコマンドを実行するように設定することもできます。

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

Linux で実行するジョブの場合、shell オプションのデフォルト値は、/bin/bash<code> がビルド コンテナに存在すれば /bin/bash -eo pipefail</code>、 存在しなければ /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 をオーバーライドします。 たとえば、以下のようになります。

- 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 となります。 シェルは、パイプライン内のすべてのコマンドの終了を待って値を返します。

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

- 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 などの一部のステップは、それより前のステップが失敗しても (0 以外の終了コードが返された場合でも) 常に実行されます。 ただし、ジョブがキャンセル要求により強制終了された場合、または実行時間がグローバル タイムアウト上限である 5 時間に達した場合、when 属性、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 "独自のチェックアウト処理"
      - unless:
          condition: <<parameters.custom_checkout>>
          steps:
            - checkout
workflows:
  build-test-deploy:
    jobs:
      - job_with_optional_custom_checkout:
          custom_checkout: "空文字列でなければ正常に終了"
      - 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 レイヤー キャッシュを利用するには、Performance プランまたは Custom プランに登録済みの有料アカウントが必要です。
• 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 を使用し、ジョブを実行するたびに新しいキャッシュが生成されることがないようにします。

例

- 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 ファイルの正確なバージョンに対応するキー) を最初に記述し、より汎用的なキー (たとえば、プロジェクトの任意のキャッシュが対象となるキー) をその後に記述します。 キーに該当するキャッシュが存在しない場合は、警告が表示され、ステップがスキップされます。

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

例

- 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 – 非推奨

このキーは非推奨になりました。 デプロイの制御性を高めるため、workflows と filters キーおよび schedule キーを適切に組み合わせて使用してください。

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

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 つのジョブが同時に実行される場合、それらのレイヤーが適用される順番は不定になります。 複数の同時ジョブが同じファイル名を永続化する場合、ワークスペースのアタッチはエラーになります。

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

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

ワークスペース、キャッシュ、アーティファクトに関する詳細は、「ワークフローでのデータの保持: キャッシュ、アーティファクト、およびワークスペースの使用方法」を参照してください。

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
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/UI 環境変数の参照
    environment:
      IMAGETAG: latest
    working_directory: ~/main
    steps:
      - run: echo "This is pipeline ID << pipeline.id >>"

workflows

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

version

The Workflows version field is used to issue warnings for deprecation or breaking changes during Beta.

<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 構文で定義します。 The cron key is defined using POSIX crontab syntax.

filters

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

branches

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

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

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

jobs

A job can have the keys requires, context, type, and filters.

<job_name>

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

requires

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

context

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

type

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

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

Note: The hold job name must not exist in the main configuration.

filters

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

The following is an example of how the CircleCI documentation uses a regex to filter running a workflow for building PDF documentation:

# ...
workflows:
  build-deploy:
    jobs:
      - js_build
      - build_server_pdfs: # << the job to conditionally run based on the filter-by-branch-name.
          filters:
            branches:
              only: /server\/.*/

The above snippet causes the job build_server_pdfs to only be run when the branch being built starts with “server/” in it.

これにより、複数のジョブで 1 つのコマンド定義を再利用できます。

branches

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

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

tags

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

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

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

For more information, see the Executing Workflows For a Git Tag section of the Workflows document.

orbs (version: 2.1 が必須)

The matrix stanza allows you to run a parameterized job multiple times with different arguments.

The following is a basic example of using matrix jobs.

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

This expands to 9 different build jobs, and could be equivalently written as:

workflows:
  workflow:
    jobs:
      - build:
          name: build-macos-0.1
          version: 0.1
          platform: macos
      - build:
          name: build-macos-0.2
          version: 0.2
          platform: macos
      - build:
          name: build-macos-0.3
          version: 0.3
          platform: macos
      - build:
          name: build-windows-0.1
          version: 0.1
          platform: windows
      - ...

Excluding sets of parameters from a matrix

Sometimes you may wish to run a job with every combination of arguments except some value or values. You can use an exclude stanza to achieve this:

- build:
      filters:
        branches:
          ignore:

            - develop
            - /feature-.*/
  - deploy-stage:
      requires:

        - build
      filters:
        branches:
          only: staging

  - deploy-prod:
      requires:

        - build
      filters:
        branches:
          only: master

The matrix above would expand into 8 jobs: every combination of the parameters a and b, excluding {a: 3, b: 5}

Dependencies and matrix jobs

To require an entire matrix (every job within the matrix), use its alias. The alias defaults to the name of the job being invoked.

workflows:
   version: 2
   nightly:
     triggers:

       - schedule:
           cron: "0 0 * * *"
           filters:
             branches:
               only:

                 - master
                 - beta
     jobs:

       - test

This means that another-job will require both deploy jobs in the matrix to finish before it runs.

Additionally, matrix jobs expose their parameter values via << matrix.* >> which can be used to generate more complex workflows. For example, here is a deploy matrix where each job waits for its respective build job in another matrix.

workflows:
  workflow:
    jobs:
      - build:
          name: build-v<< matrix.version >>
          matrix:
            parameters:
              version: ["0.1", "0.2"]
      - deploy:
          name: deploy-v<< matrix.version >>
          matrix:
            parameters:
              version: ["0.1", "0.2"]
          requires:
            - build-v<< matrix.version >>

This workflow will expand to:

workflows:
  workflow:
    jobs:
      - build:
          name: build-v0.1
          version: 0.1
      - build:
          name: build-v0.2
          version: 0.2
      - deploy:
          name: deploy-v0.1
          version: 0.1
          requires:
            - build-v0.1
      - deploy:
          name: deploy-v0.2
          version: 0.2
          requires:
            - build-v0.2

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

Every job invocation in a workflow may optionally accept two special arguments: pre-steps and post-steps.

Steps under pre-steps are executed before any of the other steps in the job. post-steps の下のステップは、他のすべてのステップよりも後に実行されます。

事前ステップと事後ステップを使用すると、特定のジョブ内で、そのジョブを変更せずにいくつかのステップを実行できます。 これは、たとえば、ジョブの実行前にカスタムのセットアップ ステップを実行したいときに便利です。

version: 2.1

jobs:
  bar:
    machine: true
    steps:
      - checkout
      - run:
          command: echo "building"
      - run:
          command: echo "testing"

workflows:
  build:
    jobs:
      - bar:
          pre-steps: # steps to run before steps defined in the job bar
            - run:
                command: echo "install custom dependency"
          post-steps: # steps to run after steps defined in the job bar
            - run:
                command: echo "upload artifact to s3"

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

CircleCI 設定ファイル v2.1 では、ワークフロー宣言内で真偽値を取る when 句を使用して (逆の条件となる unless 句も使用可)、そのワークフローを実行するかどうかを決めることができます。

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

version: 2.1

parameters:
  run_integration_tests:
    type: boolean
    default: false

workflows:
  integration_tests:
    when: << pipeline.parameters.run_integration_tests >>
    jobs:
      - mytestjob

jobs:
...

This example prevents the workflow integration_tests from running unless the tests are invoked explicitly when the pipeline is triggered with the following in the POST body:

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

Refer to the Orchestrating Workflows document for more examples and conceptual information.

Logic statements

Certain dynamic configuration features accept logic statements as arguments. Logic statements are evaluated to boolean values at configuration compilation time, that is - before the workflow is run. The group of logic statements includes:

The following logic values are considered falsy:

• false
• null
• 0
• NaN
• 文字列
• statements with no arguments

All other values are truthy. Further, Please also note that using logic with an empty list will cause a validation error.

Logic statements always evaluate to a boolean value at the top level, and coerce as necessary. They can be nested in an arbitrary fashion, according to their argument specifications, and to a maximum depth of 100 levels.

matches uses Java regular expressions for its pattern. It is recommended to enclose a pattern in ^ and $ to avoid accidental partial matches.

Note: When using logic statements at the workflow level, do not include the condition: key (the condition key is only needed for job level logic statements).

Logic statement examples

workflows:
  my-workflow:
      when:
        or:
          - equal: [ master, << pipeline.git.branch >> ]
          - equal: [ staging, << pipeline.git.branch >> ]

workflows:
  my-workflow:
    when:
      and:
        - not:
            matches:
              pattern: "^master$"
              value: << pipeline.git.branch >>
        - or:
            - equal: [ canary, << pipeline.git.tag >> ]
            - << pipeline.parameters.deploy-canary >>

version: 2.1

executors:
  linux-13:
    docker:
      - image: cimg/node:13.13
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
  macos: &macos-executor
    macos:
      xcode: 11.4

jobs:
  test:
    parameters:
      os:
        type: executor
      node-version:
        type: string
    executor: << parameters.os >>
    steps:
      - checkout
      - when:
          condition:
            equal: [ *macos-executor, << parameters.os >> ]
          steps:
            - run: echo << parameters.node-version >>
      - run: echo 0

workflows:
  all-tests:
    jobs:
      - test:
          os: macos
          node-version: "13.13.0"

Example full configuration

version: 2
jobs:
  build:
    docker:
      - image: ubuntu:14.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

      - image: mongo:2.6.8
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        command: [mongod, --smallfiles]

      - image: postgres:9.4.1
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        # some containers require setting environment variables
        environment:
          POSTGRES_USER: root

      - image: redis@sha256:54057dd7e125ca41afe526a877e8bd35ec2cdd33b9217e022ed37bdcf7d09673
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

      - image: rabbitmq:3.5.4
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

    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

      # Create Postgres users and database
      # Note the YAML heredoc '|' for nicer formatting
      - 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

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

      # Upload test results
      - store_test_results:
          path: /tmp/test-reports

  deploy-stage:
    docker:
      - image: ubuntu:14.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    working_directory: /tmp/my-project
    steps:
      - run:
          name: Deploy if tests pass and branch is Staging
          command: ansible-playbook site.yml -i staging

  deploy-prod:
    docker:
      - image: ubuntu:14.04
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    working_directory: /tmp/my-project
    steps:
      - run:
          name: Deploy if tests pass and branch is 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

関連項目

設定ファイルの概要

---

Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.

• Suggest an edit to this page (please read the contributing guide first).
• To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
• CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

---

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