無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

CircleCI の設定

11 months ago
クラウド
Server v4.x
Server v3.x
Helpful Resources
このページの内容

このドキュメントは、.circleci/config.yml ファイルで使用される CircleCI 2.x 設定キーのリファレンスガイドです。

config.yml の全体は「 コード例全文」で確認できます。


version

キー必須タイプ説明
version文字列22.0、または 2.1.circleci/config.yml ファイルの簡素化、再利用、パラメータ化ジョブの利用に役立つバージョン 2.1 の新しいキーの概要については、 設定ファイルの再利用に関するドキュメントを参照してください。

version フィールドは、将来的にサポートの終了や 破壊的変更があった場合に警告するかどうかの判断に用いられます。


setup

キー必須タイプ説明
setup×ブール値config.yaml で ダイナミックコンフィグ機能を使用するように指定します。

setup フィールドでは、プライマリ .circleci 親ディレクトリの外にある設定ファイルを条件を指定してトリガーしたり、パイプラインパラメーターを更新したり、カスタム設定ファイルを生成したりできます。


orbs

キー必須タイプ説明
orbs×マップユーザーが選択した名前から Orb 参照 (文字列) または Orb 定義 (マップ) へのマップ。 Orb 定義は、2.1 設定ファイルの Orb 関連サブセットである必要があります。 詳細については、 Orb の作成に関するドキュメントを参照してください。
executors×マップExecutor を定義する文字列のマップ。 下記の executors のセクションを参照してください。
commands×マップコマンドを定義するコマンド名のマップ。 下記の commands のセクションを参照してください。

以下のコード例では、circleci という承認済みの名前空間に置かれた node Orb が使用されてます。 他のコード例や詳細な情報については、 Orb レジストリ の Node Orb のページを参照して下さい。

version: 2.1

orbs:
  node: circleci/node@x.y

jobs:
  install-node-example:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - node/install:
          install-yarn: true
          node-version: '16.13'
      - run: node --version
workflows:
  test_my_app:
    jobs:
      - install-node-example

Orb の使用 および Orb の作成 に関するドキュメントもご覧ください。 パブリック Orb のリストは、 Orb レジストリをご覧ください。


commands

コマンドは、ジョブ内で実行される一連のステップをマップとして定義します。これにより、1 つのコマンド定義を複数のジョブで再利用できます。 詳細については、 再利用可能な設定ファイルのリファレンスガイドを参照してください。

キー必須タイプ説明
stepsシーケンスコマンドの呼び出し元のジョブ内で実行される一連のステップ。
parameters×マップparameter キーのマップ。 詳細は、 設定ファイルの再利用 パラメーター構文を参照してください。
description×文字列コマンドの目的を記述する文字列。

コード例

commands:
  sayhello:
    description: "A very simple command for demonstration purposes"
    parameters:
      to:
        type: string
        default: "Hello World"
    steps:
      - run: echo << parameters.to >>

parameters

使用するパイプラインパラメーターを設定ファイル内で宣言します。 使用方法の詳細については、 パイプラインの値とパラメーターを参照してください。

キー必須タイプ説明
parameters×マップparameter キーのマップ。 文字列ブール値整数列挙型がサポートされています。 詳細については「 パラメーターの構文」セクションを参照してください。

executors

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

キー必須タイプ説明
docker(1)リスト Docker Executor 用のオプション。
resource_class×文字列ジョブ内の各コンテナに割り当てられる CPU と RAM の量
machine(1)マップ Machine Executor 用のオプション。
macos(1)マップ macOS Executor 用のオプション。
windows(1)マップ現在、 Windows Executor は Orb に対応しています。 対応する <ahref=”https://circleci.com/developer/orbs/orb/circleci/windows”>Orb</a> をご確認ください。
shell×文字列すべてのステップで実行コマンドに使用するシェル。 各ステップ内の shell でオーバーライドできます (デフォルト設定については、 デフォルトのシェルオプションを参照してください)。
working_directory×文字列ステップを実行するディレクトリ。 絶対パスとして解釈されます。
environment×マップ環境変数の名前と値のマップ。

(1) 各ジョブに Executor タイプを 1 つ指定する必要があります。 2 つ以上指定するとエラーが発生します。

コード例

version: 2.1
executors:
  my-executor:
    docker:
      - image: cimg/ruby:3.0.3-browsers
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

jobs:
  my-job:
    executor: my-executor
    steps:
      - run: echo "Hello executor!"

パラメーター付き Executor の例は、 設定ファイルの再利用 Executor でパラメーターを使う のセクションをご覧ください。


jobs

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


<job_name>

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

キー必須タイプ説明
docker(1)リスト Docker Executor 用のオプション。
machine(1)マップ Machine Executor 用のオプション。
macos(1)マップ macOS Executor 用のオプション。
shell×文字列すべてのステップで実行コマンドに使用するシェル。 各ステップ内の shell でオーバーライドできます (デフォルト設定については、 デフォルトのシェルオプションを参照してください)。
parameters×マップworkflow において job を明示的に設定可能にする パラメーター
stepsリスト実行する ステップのリスト。
working_directory×文字列ステップを実行するディレクトリ。 絶対パスとして解釈されます。 デフォルトは ~/project です (この project は文字列リテラルで、特定のプロジェクト名ではありません)。 ジョブ内の実行プロセスは、このディレクトリを参照するために環境変数 $CIRCLE_WORKING_DIRECTORY を使えます。 注: YAML 設定ファイルに記述したパスは展開_されません_。store_test_results.path$CIRCLE_WORKING_DIRECTORY/tests と設定しても、CircleCI は文字どおり "$CIRCLE_WORKING_DIRECTORY、ドル記号 $、およびすべての名前のディレクトリのテストサブディレクトリを格納しようとします。 working_directory で指定したディレクトリが存在しない場合は自動的に作成されます。
parallelism×整数このジョブを実行する並列インスタンスの数 (デフォルトは 1)。
environment×マップ環境変数の名前と値のマップ。
branches×マップワークフローまたはバージョン 2.1 の設定ファイル以外の構成に含まれる 1 つのジョブに対し、特定のブランチでの実行を許可またはブロックするルールを定義するマップ (デフォルトではすべてのブランチでの実行が許可されます)。 ワークフロー内またはバージョン 2.1 の設定ファイル内のジョブに対するブランチ実行の設定については、 workflows のセクションを参照してください。
resource_class×文字列ジョブ内の各コンテナに割り当てられる CPU と RAM の量

(1) 各ジョブに Executor タイプを 1 つ指定する必要があります。 2 つ以上指定するとエラーが発生します。


environment

環境変数の名前と値のマップ。 環境変数の定義と使用について、また様々な設定方法の優先順位については、 環境変数のページを参照してください。


parallelism

parallelism を 2 以上に設定すると、設定した数の Executor がそれぞれセットアップされ、そのジョブのステップを並列に実行します。 この機能はテストステップを最適化するために使用します。 CircleCI CLI を使って並列コンテナにテストスイートを分割すると、ジョブの実行時間を短縮できます。 ただし、並列実行をするように設定していても 1 つの Executor でしか実行されない場合もあります。 詳しくは テストの並列実行を参照してください。

コード例

jobs:
  build:
    docker:
      - image: cimg/base:2022.09
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    environment:
      FOO: bar
    parallelism: 3
    resource_class: large
    working_directory: ~/my-app
    steps:
      - run: go test -v $(go list ./... | circleci tests split)

parameters

ジョブレベルでの parameters は、 jobworkflow で呼び出すときに使用できます。

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

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

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


Executor docker / machine / macos

CircleCI ではジョブを実行する実行環境を複数ご用意しています。 実行環境を指定するには、Executor を選択し、イメージとリソースクラスを指定します。 Executor により、ジョブを実行する基盤テクノロジーや環境、オペレーションシステムが決まります。

docker (Linux)、machine (LinuxVM、Windows、GPU、Arm)、または macos Executor を使って実行ジョブを設定し、必要なツールとパッケージを使ってイメージとリソースクラスを指定します。

実行環境やイメージに関する詳細は、 実行環境の概要をご覧ください。


docker

マップのリストを取得する docker キーにより設定します。

キー必須タイプ説明
image文字列使用するカスタム Docker イメージの名前。 ジョブで最初に記述した image は、すべてのステップを実行するプライマリコンテナとなります。
name×文字列name では、セカンダリサービスコンテナにアクセスする際の名前を定義します。  デフォルトはどのサービスも localhost 上で直接見える状態になっています。 これは、例えば同じサービスのバージョン違いを複数立ち上げる場合など、localhost とは別のホスト名を使いたい場合に適しています。
entrypoint×文字列またはリストコンテナのローンチ時に実行するコマンド。 entrypoint は、イメージの ENTRYPOINT をオーバーライドします。
command×文字列またはリストコンテナのローンチ時に PID 1 として使用するコマンド (または entrypoint の引数)。 command は、イメージの COMMAND をオーバーライドします。 イメージに ENTRYPOINT がある場合は、それに渡す引数として扱われます。イメージに ENTRYPOINT がない場合は、実行するコマンドとして扱われます。
user×文字列Docker コンテナ内でコマンドを実行するユーザー。
environment×マップ環境変数の名前と値のマップ。 environment 設定は、ジョブステップではなく Docker コンテナによって実行されるエントリポイントとコマンドに適用されます。
auth×マップ標準の docker login 認証情報を用いたレジストリの認証情報。
aws_auth×マップAWS Elastic Container Registry (ECR) の認証情報。

プライマリコンテナ (リストの最初にあるコンテナ) については、設定ファイルで commandentrypoint も指定されていない場合、イメージ内のすべての ENTRYPOINTCOMMAND が無視されます。 これは、通常プライマリコンテナは steps の実行のみに使用され、ENTRYPOINT には使用されないためです。ENTRYPOINT は大量のリソースを消費したり、途中で終了したりする可能性があります。 [カスタムイメージ](/docs/ja/custom-images/#adding-an-entrypoint) はこの動作を無効にし、強制的に ENTRYPOINT を実行する場合があります。

タグやハッシュ値でイメージのバージョンを指定することもできます。 任意の Docker パブリックレジストリ (デフォルトは Docker Hub) にある任意のパブリックイメージを使用できます。 イメージの指定方法の詳細については、 Docker 実行環境の使用 のページを参照してください。

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

コード例

jobs:
  build:
    docker:
      - image: buildpack-deps:trusty # primary container
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        environment:
          ENV: CI

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

      - image: postgres:14.2
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        environment:
          POSTGRES_USER: user

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

      - image: acme-private/private-image:321
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference

AWS ECR でホストされているイメージを使用するには、AWS 認証情報を使用した認証が必要です。 デフォルトでは、CircleCI はプロジェクト環境変数で指定した AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEY を AWS 認証情報に使用します。 以下の例のように、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 から設定したプロジェクトの環境変数を参照するように指定します

machine

Machine Executor は machine キーを使用して設定します。このキーは以下のマップを取得します。

キー必須タイプ説明
image文字列使用する仮想マシンイメージ。 使用可能なイメージ を参照してください。 注: このキーは、CircleCI Server 上での Linux VM ではサポートされていません。 プライベート環境における michine Executor のイメージのカスタマイズに関する詳細は、 VM サービスを参照してください。
docker_layer_caching×ブール値true に設定すると、 Docker レイヤーキャッシュが有効になります。

コード例

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

使用可能な Linux machine イメージ

設定ファイルでイメージを指定することを強くおすすめします。CircleCI は、image フィールドで指定可能な Linux マシンイメージを複数サポートしています。 サポートされているイメージタグの全リストは、以下の Developer Hub のページで確認できます。

各イメージで使用可能なソフトウェアについての詳細な情報は、 Discuss フォーラム でご確認ください。

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


CircleCI Server で使用可能な Linux machine イメージ

CircleCI Server をご利用の場合、使用可能な Linux マシンイメージについては、システム管理者にお問い合わせ下さい。


使用可能な Linux GPU machine イメージ

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

  • ubuntu-2004-cuda-11.4:202110-01 - CUDA v11.4.2, Docker v20.10.7, nvidia-container-toolkit v1.5.1-1
  • ubuntu-2004-cuda-11.2:202103-01 - CUDA v11.2.1, Docker v20.10.5, nvidia-container-toolkit v1.4.2-1
  • 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

使用可能な Android machine イメージ

CircleCI では、Android でのジョブの実行をサポートしており、Android アプリケーションのテストやデプロイが可能です。

Machine Executor で直接 Android イメージを使うには、ジョブに以下を追加します。

version: 2.1

jobs:
  build:
    machine:
      image: android:2022.09.1

Android イメージは、 Android Orb を使ってアクセスすることも可能です。

コード例については、 Machine Executor での Android イメージの使用を参照してください。


使用可能な Windows machine イメージ

**設定ファイルでイメージを指定することを強くおすすめします。 **CircleCI は、image フィールドで指定可能な Windows マシンイメージを複数サポートしています。

サポートしているイメージの全リストは、以下のいずれかでご確認ください。

各イメージで使用可能なソフトウェアについての詳細な情報は、 Discuss フォーラム でご確認ください。

または Windows Orb を使って Windows 実行環境を管理することもできます。 コード例については、 Windows 実行環境の使用のページをご覧ください。


CircleCI Server で使用可能な Windows machine イメージ

CircleCI Server をご利用の場合、使用可能な Windows マシンイメージについては、システム管理者にお問い合わせ下さい。


使用可能な Windows GPU machine イメージ

Windows GPU Executor では、以下のイメージを使用できます。

コード例

version: 2.1

jobs:
  build:
    machine:
      image: windows-server-2019-cuda:current

macos

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

キー必須タイプ説明
xcode文字列仮想マシンにインストールする Xcode のバージョン。全リストは、 iOS のテストのサポートされている Xcode のバージョンでご確認ください。

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

jobs:
  build:
    macos:
      xcode: "14.2.0"

branches – 廃止予定

このキーは廃止されます。 ワークフローのフィルタリング機能を使用して、どのジョブがどのブランチに対して実行されるかを制御することができます。


resource_class

resource_class 機能を使用すると、CPU と RAM のリソース量をジョブごとに構成できます。 実行環境では下記表のリソースクラスがご利用いただけます。

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


セルフホストランナー

resource_class を使って セルフホストランナー インスタンスを設定します。

例えば以下のようにします。

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

Docker 実行環境
クラスvCPURAM
small12 GB
medium24 GB
medium+36 GB
large48 GB
xlarge816 GB
2xlarge(2)1632 GB
2xlarge+(2)2040 GB

jobs:
  build:
    docker:
      - image: cimg/base:2022.09
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    resource_class: xlarge
    steps:
      ... // other config

Linux VM 実行環境
クラスvCPURAMディスクサイズ
medium27.5 GB150 GB
large415 GB150 GB
xlarge832 GB150 GB
2xlarge1664 GB150 GB
2xlarge+3264 GB150 GB


macOS 実行環境
クラスvCPURAM
medium4 @ 2.7 GHz8 GB
macos.x86.medium.gen24 @ 3.2 GHz8 GB
macos.m1.medium.gen14 @ 3.2 GHz6GB
macos.m1.large.gen18 @ 3.2 GHz12GB

jobs:
  build:
    macos:
      xcode: "14.2.0"
    resource_class: macos.x86.medium.gen2
    steps:
      ... // other config

CircleCI Server での macOS 実行環境

CircleCI Server v3.1 以降をご利用の場合、macOS 実行環境に セルフホストランナーを使用してアクセスできます。


Windows 実行環境
クラスvCPURAMディスクサイズ
medium (デフォルト)415GB200 GB
large830GB200 GB
xlarge1660GB200 GB
2xlarge32128GB200 GB


GPU 実行環境 (Linux)
クラスvCPURAMGPUGPU モデルGPU メモリ (GiB)ディスクサイズ (GiB)
gpu.nvidia.small4151NVIDIA Tesla P48300
gpu.nvidia.medium8301NVIDIA Tesla T416300
gpu.nvidia.large8301NVIDIA Tesla V10016300

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

version: 2.1

jobs:
  build:
    machine:
      image: ubuntu-1604-cuda-10.1:201909-23
    resource_class: gpu.nvidia.small
    steps:
      - run: nvidia-smi
      - run: docker run --gpus all nvidia/cuda:9.0-base nvidia-smi

使用可能なイメージの一覧は、 使用可能な Linux GPU イメージ を参照してください。


GPU 実行環境 (Windows)
クラスvCPURAMGPUGPU モデルGPU メモリ (GiB)ディスクサイズ (GiB)
windows.gpu.nvidia.medium16601NVIDIA Tesla T416200

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

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

jobs:
  build:
    executor: win/server-2019-cuda
    steps:
      - checkout
      - run: '&"C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe"'

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


Arm 実行環境 (LinuxVM)
クラスvCPURAMディスクサイズ
arm.medium (デフォルト)28 GB100 GB
arm.large416 GB100 GB
arm.xlarge832 GB100 GB
arm.2xlarge1664 GB100 GB


steps

ジョブにおける steps の設定は、キーと値のペアを 1 つずつ列挙する形で行います。キーはステップのタイプを表し、 値は設定内容を記述するマップか文字列(ステップのタイプによって異なる)のどちらかになります。 たとえば、マップで記述する場合は以下のようになります。

jobs:
  build:
    working_directory: ~/canary-python
    environment:
      FOO: bar
    steps:
      - run:
          name: Running tests
          command: make test

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

場合によっては steps をより簡便に記述できます。 例えば run ステップを下記のように記述することが可能です。

jobs:
  build:
    steps:
      - run: make test

簡略化した表記方法では、実行する command を文字列値のようにして、run ステップをダイレクトに指定できるようになります。 このとき、省略された他の属性に対してはデフォルトの値が自動で設定されます(例えば name 属性には command と同じ値が設定されます)。

もう 1 つ、キーと値のペアの代わりにステップ名を文字列として使うシンプルな方法もあります。

jobs:
  build:
    steps:
      - checkout

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

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

キー必須タイプ説明
<step_type>マップまたは文字列ステップの構成マップ、またはステップによって規定された文字列。

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


run

あらゆるコマンドラインプログラムを呼び出すのに使います。設定値を表すマップを記述するか、簡略化した表記方法では、commandname として扱われる文字列を記述します。 run コマンドはデフォルトでは非ログインシェルで実行されます。そのため、いわゆる dotfiles をコマンド内で明示的に指定するといった工夫が必要になります。

キー必須タイプ説明
command文字列シェルから実行するコマンド。
name×文字列CircleCI の UI に表示されるステップのタイトル (デフォルトは command 文字列全体)。
shell×文字列コマンド実行に使用するシェル (デフォルトについては「 デフォルトのシェル オプション」を参照)。
environment×マップコマンドに対するローカル スコープとなる追加の環境変数。
background×ブール値このステップをバックグラウンドで実行するかどうかの設定 (デフォルトは false)。
working_directory×文字列このステップを実行するディレクトリ。 ジョブの working_directory からの相対パスとして解釈されます。 (デフォルトは .)
no_output_timeout×文字列出力のないままコマンドを実行できる経過時間。 「20m」「1.25h」「5s」のように、数字の後に単位を付けた文字列で記述します。 「20m」「1.25h」「5s」のように、数字の後に単位を付けた文字列で記述します (デフォルトは 10 分) デフォルトは10分で、最大値は ジョブの実行が許される最大時間に制限されます。
when×文字列 このステップを有効または無効にする条件。 値は alwayson_success、または on_fail です (デフォルトは on_success)。

run を宣言するたびに新たなシェルが立ち上がることになります。 複数行の command を指定でき、その場合はすべての行が同じシェルで実行されます。

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

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


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

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 によるディレクトリ作成が失敗し、ゼロ以外の終了ステータスを返したときは、コマンドの実行は中断され、ステップ全体としては失敗として扱われることになります。 それとは反対の挙動にしたいときは、commandset +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 属性はコマンドをバックグラウンドで実行するように設定するものです。 background 属性を true に設定した場合、コマンドの終了を待つことなく、ジョブの実行が直ちに次のステップに進みます。 以下は、Selenium テストにおいてよく必要となる、X 仮想フレームバッファをバックグラウンドで実行するための構成例です。

- run:
    name: Running X virtual framebuffer
    command: Xvfb :99 -screen 0 1280x1024x24
    background: true

- run: make test

省略構文

run では、大変便利な省略構文を使用できます。

- run: make test

# 簡略化したうえで複数行のコマンドを実行
- run: |
    mkdir -p /tmp/test-results
    make test

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


when 属性

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

when 属性を追加することで、このデフォルトのジョブステップの挙動を変えることができます。ジョブのステータスに応じてステップを続行するか、スキップするかを選択することも可能になります。

デフォルト値である on_success は、それまでのステップが全て成功している(終了コード 0 を返した)ときのみ処理を続けます。

always はそれまでのステップの終了ステータスにかかわらず処理を続けます。 前のステップが成功したか否かに関係なく処理を続けたいタスクがあるときに都合の良い設定です。 例えば、ログやコードカバレッジのデータをどこかのサーバーにアップロードするようなジョブステップに利用できます。

on_fail は、それまでのステップの 1 つが失敗した (0 以外の終了コードを返した) 場合にのみ、そのステップが実行されることを意味します。 デバッグを支援するなんらかの診断データを保存したいとき、あるいはメールやチャットなどで失敗に関する通知をしたいときなどに on_fail が使えます。

- 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

when ステップ

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

キー必須タイプ説明
conditionロジック ロジック ステートメント
stepsシーケンス条件が true のときに実行されるステップの一覧

version: 2.1

jobs: # conditional steps may also be defined in `commands:`
  job_with_optional_custom_checkout:
    parameters:
      custom_checkout:
        type: string
        default: ""
    machine:
      image: ubuntu-2004:202107-02
    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×文字列チェックアウト ディレクトリ。 ジョブの working_directory からの相対パスとして解釈されます。 (デフォルトは .)

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

  • Ubuntu 16.04、Docker v18.09.3、Docker Compose v1.23.1
  • Git リポジトリ以外 - ステップは失敗します。

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

- checkout

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

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

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

setup_remote_docker

Docker コマンド実行用のリモート Docker 環境を作成します。 詳細は Docker コマンドを実行するを参照してください。

キー必須タイプ説明
docker_layer_caching×ブール値true に設定すると、リモート Docker 環境で Docker レイヤーキャッシュ が有効になります (デフォルトは false)。
version×文字列使用する Docker のバージョン文字列 (デフォルトは 20.10.17)。 サポートされている Docker バージョンについては、 こちらを参照してください。

注:

  • setup_remote_docker は、machine Executor と互換性がありません。 machine Executor における Docker レイヤーキャッシングの方法について、詳細は「Docker レイヤーキャッシング」の「 Machine Executor」を参照してください。
  • CircleCI Server では現在のところ version キーをサポートしていません。 リモート環境にインストールされている Docker のバージョンについては、システム管理者に問い合わせてください。

save_cache

CircleCI のオブジェクトストレージにある、依存関係やソースコードなどのファイル、ディレクトリのキャッシュを生成し、保存します。 キャッシュはその後のジョブで 復元することができます。 詳細については、 依存関係のキャッシュを参照してください。

保存期間は、 CircleCI Web アプリPlan > Usage Controls からカスタマイズ可能です。

キー必須タイプ説明
pathsリストキャッシュに追加するディレクトリのリスト。
key文字列このキャッシュの一意の識別子。
name×文字列CircleCI の UI に表示されるステップのタイトル (デフォルトは「Saving Cache」)。
when×文字列 このステップを有効または無効にする条件。 値は alwayson_success、または on_fail です (デフォルトは on_success)。

key で割り当てたキャッシュは、一度書き込むと書き換えられません。

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

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

テンプレート説明
{{ .Branch }}現在ビルド中の VCS ブランチ。
{{ .BuildNum }}このビルドの CircleCI ビルド番号。
{{ .Revision }}現在ビルド中の VCS リビジョン。
{{ .CheckoutKey }}リポジトリのチェックアウトに使用する SSH キー。
{{ .Environment.variableName }}環境変数 variableName ( CircleCI からエクスポートされた環境変数、または特定の コンテキストに追加された環境変数がサポートされ、任意の環境変数は使用できません)。
{{ checksum "filename" }}filename で指定したファイルの内容の SHA256 ハッシュを Base64 エンコードした値。 このファイルはリポジトリでコミットしたものであり、かつ現在の作業ディレクトリからの絶対・相対パスで指定する必要があります。 依存関係マニフェスト ファイル (package-lock.jsonpom.xmlproject.clj など) の使用をお勧めします。 restore_cachesave_cache の間でこのファイルが変化しないのが重要なポイントです。ファイル内容が変化すると、restore_cache のタイミングで使われるファイルとは異なるキャッシュキーを元にしてキャッシュを保存するためです。
{{ epoch }}UNIX エポックからの秒数で表される現在時刻。
{{ arch }}OS と CPU の情報。 OS や CPU アーキテクチャに合わせてコンパイル済みバイナリをキャッシュする場合に便利です (darwin amd64linux i386/32-bit など)。

ステップの実行中に、上記のテンプレートが実行時の値に置き換えられ、その置換後の文字列が 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

注:

  • save_cache パスは現在のところ、ワイルドカードをサポートしていません。 お客様やお客様の組織にとってワイルドカードが有益でしたら、 Ideas board にご意見をお寄せください。

  • インスタンスによっては、特定のワークスペースをキャッシュに保存する回避策もあります。

- save_cache:
    key: v1-{{ checksum "yarn.lock" }}
    paths:
      - node_modules/workspace-a
      - node_modules/workspace-c

restore_cache

key を元に、以前に保存したキャッシュを復元します。 先に save_cache ステップを利用して、この key に該当するキャッシュを保存しておかなければなりません。 詳細については、 キャッシュに関するドキュメントを参照してください。

キー必須タイプ説明
key(1)文字列復元するキャッシュ キーを 1 つだけ指定します。
keys(1)リスト復元するキャッシュを検索するためのキャッシュ キーのリスト。 最初に一致したキーのみが復元されます。
name×文字列CircleCI の UI に表示されるステップのタイトル (デフォルトは “Restoring Cache”)。

(1) 少なくとも 1 つの属性を指定する必要があります。 keykeys の両方を指定すると、最初に 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 が復元されます。

key の詳しい書式については、 save_cache ステップkey セクションをご覧ください。

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

元々のキャッシュの保存場所に復元されるため、restore_cache では path の指定は不要です。

- restore_cache:
    keys:
      - v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
      # if cache for exact version of `project.clj` is not present then load any most recent one
      - v1-myapp-

# ... Steps building and testing your application ...

# cache will be saved only once for each version of `project.clj`
- save_cache:
    key: v1-myapp-{{ arch }}-{{ checksum "project.clj" }}
    paths:
      - /foo

deploy - 廃止予定

現在のプロセスに関しては、 run をご覧ください。 parallelism > 1 (ジョブで指定している並列実行の数が 2 以上) の場合は、 deploy から run への移行 を確認して下さい。


store_artifacts

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

キー必須タイプ説明
path文字列ジョブ アーティファクトとして保存するプライマリ コンテナ内のディレクトリ。
destination×文字列アーティファクト API でアーティファクトの保存先パスに追加するプレフィックス (デフォルトは path で指定したファイルのディレクトリ)。

ジョブでは複数の store_artifacts ステップを指定することもできます。 各ステップで一意のプレフィックスを使用すると、ファイルの上書きを防止できます。

アーティファクトの保存期間は、 CircleCI Web アプリPlan > Usage Controls からカスタマイズ可能です。

- 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 ステップを参照してください。

キー必須タイプ説明
path文字列JUnit XML のテストメタデータファイルが格納されたサブディレクトリを含むディレクトリ、またはシングル テストへのパス (絶対パス、または working_directory からの相対パス)。

ディレクトリ構造

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

config.yml の構文

- store_test_results:
    path: test-results

persist_to_workspace

一時ファイルを永続化してワークフロー内の別のジョブで使用できるようにするための特別なステップです。 ワークスペースの使用についての詳細は、 ワークスペースを使ったジョブ間でのデータの共有のページを参照してください。

persist_to_workspace により、CircleCI Web アプリのストレージカスタマイズコントロールのストレージ設定が適用されます。 カスタマイズ設定がない場合は、persist_to_workspace によりデフォルトで 15 日に設定されます。

ワークスペースのストレージ保存期間は、 CircleCI Web アプリPlan > Usage Controls からカスタマイズ可能です。

キー必須タイプ説明
root文字列絶対パス、または working_directory からの相対パス。
pathsリスト共有ワークスペースに追加する、グロブで認識されるファイル、またはディレクトリへの非グロブ パス。 ワークスペースのルート ディレクトリへの相対パスと解釈され、 ワークスペースのルート ディレクトリ自体を指定することはできません。

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

ワークフローで使用しているワークスペースを現在のコンテナにアタッチするのに利用する特殊なステップです。 ワークスペースのすべての内容がダウンロードされ、ワークスペースがアタッチされているディレクトリにコピーされます。 ワークスペースの使用についての詳細は、 ワークスペースを使ったジョブ間でのデータの共有のページを参照してください。

キー必須タイプ説明
at文字列ワークスペースのアタッチ先のディレクトリ。

ワークスペースのストレージ保存期間は、 CircleCI Web アプリPlan > Usage Controls からカスタマイズ可能です。

- attach_workspace:
    at: /tmp/workspace

add_ssh_keys

プロジェクト設定でコンテナに対して SSH キーを登録する特殊なステップです。 下記のキーを使って SSH に関する設定を行えます。 SSH キーの詳細は、 GitHub と Bitbucket の連携のページを参照してください。

キー必須タイプ説明
fingerprints×リスト追加するキーに対応するフィンガープリントのリスト (デフォルトでは、追加されるすべてのキーが対象)。
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 値の使用

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

変数VCSタイプ
pipeline.idGitHub, BitbucketStringパイプラインを表す、 グローバルに一意のID
pipeline.numberGitHub, Bitbucket整数型パイプラインを表す、プロジェクトで一意の整数の ID。
pipeline.project.git_urlGitHub, BitbucketString現在のプロジェクトがホストされている URL 。 たとえば、https://github.com/circleci/circleci-docs
pipeline.project.typeGitHub, BitbucketString小文字の VCS プロバイダ名。 例: “github”、“bitbucket”
pipeline.git.tagGitHub, BitbucketStringパイプラインをトリガーするためにプッシュされた git タグの名前。 タグでトリガーされたパイプラインでない場合は、文字列は空です。
pipeline.git.branchGitHub, BitbucketStringパイプラインをトリガーするためにプッシュされた git タグの名前。
pipeline.git.revisionGitHub, BitbucketString現在ビルドしている長い git SHA(40文字)
pipeline.git.base_revisionGitHub, BitbucketString現在ビルドしているものより前のビルドの長い git SHA (40 文字) **注: ** 多くの場合、pipeline.git.base_revision は、現在実行しているパイプラインより前のパイプラインを実行する SHA ですが、いくつか注意事項があります。 ブランチの最初のビルドの場合、変数は表示されません。 また、ビルドが API からトリガーされた場合も変数は表示されません。
pipeline.trigger_sourceGitHub, BitbucketStringパイプラインをトリガーするソース、現在の値は webhookapischeduled_pipeline です。
pipeline.schedule.nameGitHub, BitbucketStringパイプラインのスケジュール実行の場合はスケジュール名です。 他のソースがこのパイプラインをトリガーすると、値は空の文字列になります。
pipeline.schedule.idGitHub, BitbucketStringパイプラインのスケジュール実行の場合は当該スケジュールの一意の ID です。 他のソースがこのパイプラインをトリガーすると、値は空の文字列になります。

例えば、下記のようになります。

version: 2.1
jobs:
  build:
    docker:
      - image: cimg/node:17.2.0
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    environment:
      IMAGETAG: latest
    working_directory: ~/main
    steps:
      - run: echo "This is pipeline ID << pipeline.id >>"

circleci_ip_ranges

ジョブで使用される IP アドレスを、明確に定義された範囲のみに限定できます。 詳しくは IP アドレスの範囲機能をご確認ください。

version: 2.1

jobs:
  build:
    circleci_ip_ranges: true # opts the job into the IP ranges feature
    docker:
      - image: curlimages/curl
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
    steps:
      - run: echo “Hello World”
workflows:
  build-workflow:
    jobs:
      - build

注:


workflows

すべてのジョブのオーケストレーションに使用します。 各ワークフローは、キーとなるワークフロー名と、値となるマップで構成します。 名前は、その config.yml 内で一意である必要があります。 ワークフロー設定でトップレベルに置くキーは versionjobs です。 詳細については、 ワークフローを使ったジョブのオーケストレーションのページを参照してください。


version

ワークフローの version フィールドは、サポートの終了または互換性を損なう変更について注意を促すために記述します。

キー必須タイプ説明
version設定ファイルのバージョンが 2 の場合は必須文字列現在は 2 を指定する必要があります。

<workflow_name>

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


triggers

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

キー必須タイプ説明
triggers×配列現在は schedule を指定する必要があります。

schedule

ワークフローでは、一定時刻に実行を指示する schedule を記述することもできます。利用者の少ない毎日夜12時にビルドする、といったことが可能です。

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

cron

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

キー必須タイプ説明
cron文字列 crontab のマニュアル ページを参照してください。

filters

トリガーのフィルタリングでは、branches キーを使用できます。

キー必須タイプ説明
filtersマップ特定のブランチでの実行ルールを定義するマップ。

branches

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

branches では、ブランチ名を指す文字列をマップさせるための only キーと ignore キーが使えます。 文字列を / で囲み、正規表現を使ってブランチ名をマッチさせたり、文字列のリストを作ってマップさせることも可能です。 正規表現は、文字列全体に一致させる必要があります。

  • only を指定した場合、一致するブランチでジョブが実行されます。
  • ignore を指定した場合、一致するブランチではジョブは実行されません。
  • onlyignore のどちらも指定していない場合、全てのブランチでジョブを実行します。 onlyignore の両方を指定した場合、only が使用され、 ignore は使われません。
キー必須タイプ説明
branchesマップ特定のブランチでの実行ルールを定義するマップ。
only文字列、または文字列のリスト単一のブランチ名、またはブランチ名のリスト。
ignore×文字列、または文字列のリスト単一のブランチ名、またはブランチ名のリスト。

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

ワークフロー宣言内で 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:
...

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

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

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


jobs

ジョブでは、requiresnamecontexttypefilters の各キーを使用できます。

キー必須タイプ説明
jobsリスト依存関係に従って実行するジョブのリスト。

<job_name>

config.yml ファイルで定義するジョブの名前です。


requires

デフォルトでは、複数のジョブは並列で実行されます。そのため、依存関係がある場合はジョブ名を使って明確に指定する必要があります。

キー必須タイプ説明
requires×リストそのジョブを開始するために成功する必要があるジョブのリスト。 注: 現在のワークフローで依存関係としてリストされているジョブが (フィルタリング機能などの影響で) 実行されなかった場合、他のジョブの requires オプションでは、これらのジョブの必須設定は無視されます。 しかし、ジョブのすべての依存関係がフィルター処理されると、そのジョブは実行されません。

name

name キーを使用すると、任意の数のワークフローで再利用可能なジョブを呼び出すことができます。 このキーを使うと、ジョブ名に番号は付与されません (例: sayhello-1、sayhello-2)。 この name キーに割り当てる名前は一意である必要があります。重複する場合は、ジョブ名に数字が付与されます。

キー必須タイプ説明
name×文字列ジョブ名の代替名。 ジョブを複数回呼び出す場合に便利です。 同じジョブを複数回呼び出したいとき、あるジョブで同じ内容のジョブが必要なときなどに有効です (2.1 のみ)。

context

ジョブは、組織において設定したグローバル環境変数を使えるようにすることも可能です。設定画面で context を追加する方法については コンテキストを参照してください。

キー必須タイプ説明
context×文字列/リストコンテキストの名前。 初期のデフォルト名は org-global です。 各コンテキスト名は一意である必要があります。 CircleCI Server を使用している場合、ワークフローごとに使用できるコンテキストは 1 つのみです。 注: 一意のコンテキストは、すべてのワークフローを合わせて 100 個まで使用できます。

type

ジョブでは approval という type を使用できます。これは、後続のジョブに進む前に手動で承認を行う必要があることを示します。 詳細については、 ワークフローを使ったジョブのオーケストレーションのページを参照してください。

下記の例にある通り、ワークフローが type: approval キーを処理するまで、ジョブは依存関係通りの順番で実行されます。

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

filters

ジョブのフィルタリングでは、branches キーまたは tags キーを使用できます。

キー必須タイプ説明
filters×マップ特定のブランチでの実行ルールを定義するマップ。

以下は、CircleCI ドキュメントに含まれるサンプルから、正規表現を使用して PDF ドキュメントの作成ワークフローのみを実行するようにフィルタリングするための例です。

# ...
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\/.*/

上記のスニペットでは、build_server_pdfs ジョブは、ビルド対象のブランチのパスが “server/” から始まる場合にのみ実行されます。

設定ファイルでの正規表現の使い方の詳細については、 ワークフローを使ってジョブのスケジュール実行を参照してください。


branches

branches では、ブランチ名を指す文字列をマップさせるための only キーと ignore キーが使えます。 文字列を / で囲み、正規表現を使ってブランチ名をマッチさせたり、文字列のリストを作ってマップさせることも可能です。 正規表現は、文字列全体に一致させる必要があります。

  • only を指定した場合、一致するブランチでジョブが実行されます。
  • ignore を指定した場合、一致するブランチではジョブは実行されません。
  • onlyignore のいずれも指定していない場合、すべてのブランチでジョブが実行されます。
  • onlyignore の両方を指定した場合は、only を処理してから ignore の処理に移ります。
キー必須タイプ説明
branches×マップ特定のブランチでの実行ルールを定義するマップ。
only×文字列、または文字列のリスト単一のブランチ名、またはブランチ名のリスト。
ignore×文字列、または文字列のリスト単一のブランチ名、またはブランチ名のリスト。

tags

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

tags では only キーと ignore キーが使えます。 スラッシュで囲むことで正規表現でタグに一致させたり、そのような文字列のリストでマップさせたりできます。 正規表現は、文字列全体に一致させる必要があります。 CircleCI は軽量版と注釈付き版のどちらのタグにも対応しています。

  • only の値にマッチするタグはすべてジョブを実行します。
  • ignore の値にマッチするタグはすべてジョブを実行しません。
  • onlyignore のどちらも指定していない場合、すべてのタグのジョブがスキップされます。
  • onlyignore の両方を指定した場合は、only を処理してから ignore の処理に移ります。
キー必須タイプ説明
tags×マップ実行するタグを定義するマップ。
only×文字列、または文字列のリスト単一のタグ名、またはタグ名のリスト。
ignore×文字列、または文字列のリスト単一のタグ名、またはタグ名のリスト。

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


matrix

matrix スタンザを使用すると、パラメーター化したジョブを、引数を変えながら複数回実行できます。 詳細については、 マトリックスジョブの使用を参照してください。 matrix スタンザを使用するには、パラメーター化したジョブを使用する必要があります。

キー必須タイプ説明
parametersマップジョブの呼び出しで使用するすべてのパラメーター名と値のマップ
exclude×リストマトリックスから除外する引数マップのリスト
alias×文字列マトリックスのエイリアス。別のジョブの requires スタンザで使用できます。 デフォルト値は実行するジョブの名前です。

以下に、マトリックス ジョブの基本的な使用例を示します。

workflows:
  workflow:
    jobs:
      - build:
          matrix:
            parameters:
              version: ["0.1", "0.2", "0.3"]
              platform: ["macos", "windows", "linux"]

上記コードは 9 つの build ジョブに展開されます。

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

マトリックスから一部のパラメーターを除外する

一部の値を_除き_、あらゆる引数の組み合わせについてジョブを実行したいことがあります。 これを行うには、exclude スタンザを使用します。

workflows:
  workflow:
    jobs:
      - build:
          matrix:
            parameters:
              a: [1, 2, 3]
              b: [4, 5, 6]
            exclude:
              - a: 3
                b: 5

上記のマトリックスは、パラメーター ab の組み合わせのうち、{a: 3, b: 5} の組み合わせを除いた 8 個のジョブに展開されます。


依存関係とマトリックスジョブ

マトリックス全体 (マトリックス内のすべてのジョブ) に requires キーを適用するには、マトリックスの alias を指定します。 alias のデフォルト値は、呼び出すジョブの名前です。

workflows:
  workflow:
    jobs:
      - deploy:
          matrix:
            parameters:
              version: ["0.1", "0.2"]
      - another-job:
          requires:
            - deploy

上記の場合、another-job を実行するには、マトリックス内の deploy ジョブが完了している必要があります。

また、マトリックス ジョブのパラメーター値を << matrix.* >> で公開し、より複雑なワークフローを作成することもできます。 たとえば、次のコードでは、deploy ジョブをマトリックス化したうえで、それぞれのジョブが、build マトリックス内の対応するジョブが完了してから実行されるようにしています。

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

上記ワークフローは次のように展開されます。

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

pre-stepspost-steps

ワークフローでは、すべてのジョブ呼び出しは、オプションで 2つの特別な引数 pre-stepspost-steps を受け取ることができます。

pre-steps の下のステップは、ジョブ内の他のすべてのステップよりも前に実行されます。 post-steps の下のステップは、他のすべてのステップよりも後に実行されます。

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

version: 2.1

jobs:
  bar:
    machine:
      image: ubuntu-2004:202107-02
    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"

ロジックステートメント

一部のダイナミックコンフィグ機能では、ロジックステートメントを引数として使用できます。 ロジックステートメントとは、設定ファイルのコンパイル時 (ワークフローの実行前) に真偽の評価が行われるステートメントです。 ロジックステートメントには次のものがあります。

TypeArgumentstrue ifExample
YAML literalNoneis truthytrue/42/"a string"
YAML aliasNoneresolves to a truthy value*my-alias
Pipeline ValueNoneresolves to a truthy value<< pipeline.git.branch >>
Pipeline ParameterNoneresolves to a truthy value<< pipeline.parameters.my-parameter >>
andN logic statementsall arguments are truthyand: [ true, true, false ]
orN logic statementsany argument is truthyor: [ false, true, false ]
not1 logic statementthe argument is not truthynot: true
equalN valuesall arguments evaluate to equal valuesequal: [ 42, << pipeline.number >>]
matchespattern and valuevalue matches the patternmatches: { pattern: "^feature-.+$", value: << pipeline.git.branch >> }

次の論理値は偽とみなされます。

  • false
  • null
  • 0
  • NaN
  • 空の文字列 (“”)
  • 引数を持たないステートメント

上記以外の値はすべて真とみなされます。 ただし、空のリストを引数とするロジックステートメントはバリデーションエラーとなるので注意してください。

ロジックステートメントの真偽の評価は常に最上位レベルで行われ、必要に応じて強制することもできます。 また、最大 100 レベルの深さまで、引数の仕様に応じた任意の方法でネストできます。

matchespattern には、 Java 正規表現を使用します。 パターンは完全一致で指定する必要があります。前方一致は使用できません。 意図せぬ部分一致を防ぐため、パターンは ^$ で囲むことをお勧めします。

注: ワークフローレベルでロジックステートメントを使用する場合、condition: キーは含めないようにしてください (condition キーはジョブ レベルのロジックステートメント以外では必要ありません)。


ロジックステートメントの例

workflows:
  my-workflow:
    when:
      or:
        - equal: [ main, << pipeline.git.branch >> ]
        - equal: [ staging, << pipeline.git.branch >> ]
workflows:
  my-workflow:
    when:
      and:
        - not:
            matches:
              pattern: "^main$"
              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: 14.2.0

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"

サンプル設定ファイル全文

version: 2.1
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:14.2
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        # some containers require setting environment variables
        environment:
          POSTGRES_USER: user

      - 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 << pipeline.number >>
          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 Main
          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: main

Suggest an edit to this page

Make a contribution
Learn how to contribute