CircleCI の設定
On This Page
- 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 (executor)
- docker
- machine
- 使用可能な Linux machine イメージ
- 使用可能な Linux GPU machine イメージ
- 使用可能な Windows machine イメージ
- 使用可能な Windows GPU machine イメージ
- macos
- branches – 廃止予定
- resource_class
- セルフホストランナー
- Docker 実行環境
- Linux VM 実行環境
- macOS 実行環境
- Windows 実行環境
- GPU 実行環境 (Linux)
- GPU 実行環境 (Windows)
- Arm 実行環境 (LinuxVM)
- steps
- run
- デフォルトのシェルオプション
- background コマンド
- 省略構文
- when 属性
- step 内からのジョブの終了
- when ステップ (version: 2.1 が必須)
- checkout
- setup_remote_docker
- save_cache
- restore_cache
- deploy - 廃止予定
- deploy から run への移行
- store_artifacts
- store_test_results
- persist_to_workspace
- attach_workspace
- add_ssh_keys
- pipeline 値の使用
- circleci_ip_ranges
- workflows
- version (v2.1 の設定ファイルでは不要)
- <workflow_name>
- triggers
- schedule
- cron
- filters
- branches
- jobs
- <job_name>
- requires
- name
- context
- type
- filters
- branches
- tags
- matrix (version: 2.1 が必須)
- マトリックスから一部のパラメーターを除外する
- 依存関係とマトリックスジョブ
- pre-steps と post-steps (version: 2.1 が必須)
- ワークフローでの when の使用
- ロジックステートメント
- ロジックステートメントの例
- サンプル設定ファイル全文
- 関連項目
このドキュメントは、.circleci/config.yml
ファイルで使用される CircleCI 2.x 設定キーのリファレンスガイドです。
config.yml
の全体は「 サンプルコード」で確認できます。
setup
キー | 必須 | タイプ | 説明 |
---|---|---|---|
setup | × | ブール値型 | config.yaml で ダイナミック コンフィグ機能を使用するように指定します。 |
setup
フィールドを指定すると、プライマリ .circleci
親ディレクトリ外部にある設定ファイルのトリガー、パイプライン パラメーターの更新、およびカスタマイズされた設定ファイルの生成を、条件に従って実行できます。
version
キー | 必須 | タイプ | 説明 |
---|---|---|---|
version | ○ | 文字列型 | 2 、2.0 、または 2.1 。.circleci/config.yml ファイルの簡素化、再利用、パラメータ化ジョブの利用に役立つバージョン 2.1 の新しいキーの概要については、 設定ファイルの再利用に関するドキュメントを参照してください。 |
version
フィールドは、将来的にサポートの終了や 破壊的変更に対して警告するかどうかの判断に用いられます。
orbs
(version: 2.1 が必須)
キー | 必須 | タイプ | 説明 |
---|---|---|---|
orbs | × | マップ | ユーザーが選択した名前から Orb 参照 (文字列) または Orb 定義 (マップ) へのマップ。 Orb 定義は、2.1 設定ファイルの Orb 関連サブセットである必要があります。 詳細については、 Orb の作成に関するドキュメントを参照してください。 |
executors | × | マップ | Executor 定義への文字列のマップ。 後述の Executors セクションも参照してください。 |
commands | × | マップ | コマンドを定義するコマンド名のマップ。 下記 commands のセクションを参照してください。 |
以下の例は、承認済みの circleci
名前空間に置かれた hello-build
という名前の Orb を呼び出します。
version: 2.1
orbs:
hello: circleci/hello-build@0.0.5
workflows:
"Hello Workflow":
jobs:
- hello/hello-build
circleci/hello-build@0.0.5
が完全認証された Orb の参照先ですが、この例では hello
がその Orb の参照名となります。 Orb の詳細については こちらを参照してください。 Orb の使用 および Orb のオーサリング に関するドキュメントもご覧ください。 パブリック Orb のリストは、 Orb レジストリをご覧ください。
commands
(version: 2.1 が必須)
commands では、ジョブ内で実行する一連のステップをマップとして定義します。これにより、複数のジョブで 1 つのコマンド定義を再利用できます。 詳細については、 再利用可能な設定ファイルリファレンスガイドを参照してください。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
steps | ○ | シーケンス | コマンドの呼び出し元のジョブ内で実行される一連のステップ。 |
parameters | × | マップ | パラメーター キーのマップ。 詳細は「 コンフィグを再利用する」内の「 パラメーター構文」を参照してください。 |
description | × | 文字列型 | コマンドの目的を記述する文字列。 |
例
commands:
sayhello:
description: "デモ用の簡単なコマンド"
parameters:
to:
type: string
default: "Hello World"
steps:
- run: echo << parameters.to >>
parameters
(version: 2.1 が必須)
設定ファイル内で使用するパイプラインパラメーターが宣言されます。 使用方法の詳細については、 パイプラインの値とパラメーターを参照してください。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
parameters | × | マップ | パラメーター キーのマップ。 文字列 、ブール値 、整数 、列挙型 がサポートされています。 詳細については「 パラメーターの構文」セクションを参照してください。 |
executors
(version: 2.1 が必須)
Executor は、ジョブステップの実行環境を定義するものです。Executor を 1 つ定義すると複数のジョブで再利用できます。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
docker | ○ (1) | リスト | docker Executor 用のオプション。 |
resource_class | × | 文字列型 | ジョブ内の各コンテナに割り当てられる CPU と RAM の量 |
machine | ○ (1) | マップ | machine Executor 用のオプション。 |
macos | ○ (1) | マップ | macOS Executor 用のオプション。 |
windows | ○ (1) | マップ | 現在、 Windows Executor は Orb に対応しています。 こちらの Orb を参照してください。 |
shell | × | 文字列型 | すべてのステップで実行コマンドに使用するシェル。 各ステップ内の shell でオーバーライドできます (デフォルト設定については、 デフォルトのシェル オプションを参照してください)。 |
working_directory | × | 文字列型 | ステップを実行するディレクトリ。 絶対パスとして解釈されます。 |
environment | × | マップ | 環境変数の名前と値のマップです。 |
(1) 各ジョブにいずれか 1 つの Executor タイプを指定する必要があります。 2 つ以上指定するとエラーが発生します。
例
version: 2.1
executors:
my-executor:
docker:
- image: cimg/ruby:3.0.3-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
マップの例を 2 つ紹介しています。 ジョブの名前がマップのキーとなり、ジョブを記述するマップが値となります。
注: ジョブの最大実行時間は、Free プランでは 1 時間、Performance プランでは 3 時間、Scale プランでは 5 時間となります。 ジョブがタイムアウトする場合は、より大きな リソースクラスの使用や、 並列実行を検討してください。 また、料金プランのアップグレードや、 ワークフローを利用した複数のジョブの同時実行も可能です。
<job_name
>
各ジョブは、キーとなるジョブ名と値となるマップで構成されます。 名前は、その jobs
リスト内で一意である必要があります。 値となるマップでは下記の属性を使用できます。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
docker | ○ (1) | リスト | docker Executor 用のオプション。 |
machine | ○ (1) | マップ | machine Executor 用のオプション。 |
macos | ○ (1) | マップ | macOS Executor 用のオプション。 |
shell | × | 文字列型 | すべてのステップで実行コマンドに使用するシェル。 各ステップ内の shell でオーバーライドできます (デフォルト設定については、 デフォルトのシェル オプションを参照してください)。 |
parameters | × | マップ | ワークフロー において job を明示的に構成可能にする パラメーター。 |
steps | ○ | リスト | 実行する ステップのリスト。 |
working_directory | × | 文字列型 | ステップを実行するディレクトリ。 絶対パスとして解釈されます。 デフォルトは ~/project となります(この project は文字列リテラルで、特定のプロジェクト名ではありません)。 ジョブ内の実行プロセスは、このディレクトリを参照するために環境変数 $CIRCLE_WORKING_DIRECTORY を使えます。 注: YAML 設定ファイルに記述したパスは展開_されません_。store_test_results.path を $CIRCLE_WORKING_DIRECTORY/tests と設定しても、CircleCI は文字どおり “$CIRCLE_WORKING_DIRECTORY ” という、$ 記号を含む名前のディレクトリ内に、サブディレクトリ test を格納しようとします。 working_directory で指定したディレクトリが存在しないときは自動で作成されます。 |
parallelism | × | 整数型 | このジョブを実行する並列インスタンスの数 (デフォルトは 1)。 |
environment | × | マップ | 環境変数の名前と値のマップです。 |
branches | × | マップ | ワークフローまたはバージョン 2.1 の設定ファイル以外の構成に含まれる 1 つのジョブに対し、特定のブランチでの実行を許可またはブロックするルールを定義するマップ (デフォルトではすべてのブランチでの実行が許可されます)。 Workflows やバージョン 2.1 のコンフィグにおけるジョブやブランチに関する設定については Workflows を参照してください。 |
resource_class | × | 文字列型 | ジョブ内の各コンテナに割り当てられる CPU と RAM の量 |
(1) 各ジョブにいずれか 1 つの Executor タイプを指定する必要があります。 2 つ以上指定するとエラーが発生します。
environment
環境変数の名前と値のマップです。 環境変数の定義と使用について、また様々な設定方法の優先順位については、 環境変数の使用のページを参照してください。
parallelism
parallelism
を 2 以上に設定すると、設定した数の Executor がそれぞれセットアップされ、そのジョブのステップを並列に実行します。 この機能はテストステップを最適化するために使用します。 CircleCI CLI を使って並列コンテナにテス スイートを分割すると、ジョブの実行時間を短縮できます。 ただし、並列実行をするように設定していても 1 つの Executor でしか実行されない場合もあります。 詳しくは テストの並列実行を参照してください。
例
jobs:
build:
docker:
- image: buildpack-deps:trusty
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
は、 job
を workflow
で呼び出すときに使用できます。
予約されているパラメーター名は以下のとおりです。
name
requires
context
type
filters
matrix
詳細については、「 パラメーターの構文」を参照してください。
docker
/ machine
/ macos
(executor)
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) の認証情報。 |
プライマリコンテナ (リストの最初にあるコンテナ) については、設定ファイルで command
も entrypoint
も指定されていない場合、イメージ内のすべての ENTRYPOINT
と COMMAND
が無視されます。 というのも、プライマリコンテナは通常 steps
の実行のみに使用されるもので ENTRYPOINT
用ではなく、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_ID
と AWS_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 | ○ | 文字列型 | 使用する仮想マシンイメージ。 使用可能なイメージ を参照してください。 注: このキーは、オンプレミス環境における 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: "テスト"
command: echo "Hi"
使用可能な Linux machine
イメージ
**設定ファイルでイメージを指定することを強くおすすめします. **CircleCI は、image
フィールドで指定可能な Linux マシンイメージを複数サポートしています。 イメージの一覧は、Developer Hub の Ubuntu 20.04 ページ で確認できます。 各イメージで使用可能なソフトウェアについての詳細な情報は、 Discuss フォーラム でご確認ください。
ubuntu-2204:2022.04.1
- Ubuntu 22.04, Docker v20.10.14, Docker Compose v2.4.1,ubuntu-2004:2022.04.1
- Ubuntu 20.04, Docker v20.10.14, Docker Compose v2.4.1,ubuntu-2004:202201-02
- Ubuntu 20.04, Docker v20.10.12, Docker Compose v1.29.2, Google Cloud SDK updatesubuntu-2004:202201-01
- Ubuntu 20.04, Docker v20.10.12, Docker Compose v1.29.2ubuntu-2004:202111-02
- Ubuntu 20.04, Docker v20.10.11, Docker Compose v1.29.2, log4j updatesubuntu-2004:202111-01
- Ubuntu 20.04, Docker v20.10.11, Docker Compose v1.29.2,ubuntu-2004:202107-02
- Ubuntu 20.04, Docker v20.10.7, Docker Compose v1.29.2,ubuntu-2004:202104-01
- Ubuntu 20.04、Docker v20.10.6、Docker Compose v1.29.1ubuntu-2004:202101-01
- Ubuntu 20.04、Docker v20.10.2、Docker Compose v1.28.2ubuntu-2004:202010-01
- Ubuntu 20.04、Docker v19.03.13、Docker Compose v1.27.4 (ubuntu-2004:202008-01
はエイリアス)
注: Ubuntu 16.04 LTS は 2021 年 4 月にサポート期間が終了し、Canonical によるサポートが終了しました。 その結果、ubuntu-1604:202104-01
が CircleCI がリリースする最後の Ubuntu 16.04 イメージとなります。
Ubuntu 14.04 および 16.04 マシンイメージはすでにサポートが終了し、 2022 年 5 月 31 日に提供を終了しました。 現在も 14.04 および 16.04 イメージを使用している場合は、できるだけ早く移行をお願いいたします。 詳細については、 CircleCI サポートまたはアカウント担当者にお問合せください。
machine Executor は、ジョブまたはワークフローで Docker イメージをビルドするときに便利な Docker レイヤー キャッシュをサポートします。
使用可能な 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-1ubuntu-2004-cuda-11.2:202103-01
- CUDA v11.2.1, Docker v20.10.5, nvidia-container-toolkit v1.4.2-1ubuntu-1604-cuda-11.1:202012-01
- CUDA v11.1、Docker v19.03.13、nvidia-container-toolkit v1.4.0-1ubuntu-1604-cuda-10.2:202012-01
- CUDA v10.2、Docker v19.03.13、nvidia-container-toolkit v1.3.0-1ubuntu-1604-cuda-10.1:201909-23
- CUDA v10.1、Docker v19.03.0-ce、nvidia-docker v2.2.2ubuntu-1604-cuda-9.2:201909-23
- CUDA v9.2、Docker v19.03.0-ce、nvidia-docker v2.2.2
使用可能な Windows machine
イメージ
**設定ファイルでイメージを指定することを強くおすすめします. **CircleCI は、image
フィールドで指定可能な Windows マシンイメージを複数サポートしています。
サポートしているイメージの全リストは、以下のいずれかでご確認ください。
各イメージで使用可能なソフトウェアについての詳細な情報は、 Discuss フォーラム でご確認ください。
または Windows Orb を使って Windows 実行環境を管理します。 例えば、 Windows 実行環境の使用のページをご覧ください。
使用可能な Windows GPU machine
イメージ
Windows GPU Executor では、次のイメージが使用可能です。
windows-server-2019-nvidia:stable
- Windows Server 2019、CUDA 10.1。 このイメージはデフォルトです。
例
version: 2.1
jobs:
build:
machine:
image: windows-server-2019-nvidia:stable
macos
CircleCI は macOS 上でのジョブ実行をサポートしています。macOS アプリケーションや iOS アプリ、 tvOS アプリ、さらには watchOS アプリのビルド、テスト、デプロイが可能です。 macOS 仮想マシン上でジョブを実行するには、ジョブ設定の最上位に macos
キーを追加し、使いたい Xcode のバージョンを指定します。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
xcode | ○ | 文字列型 | 仮想マシンにインストールする Xcode のバージョン。全リストは、 iOS のテストのサポートされている Xcode のバージョンでご確認ください。 |
例: macOS 仮想マシンを Xcode バージョン 12.5.1 で使用する場合
jobs:
build:
macos:
xcode: "12.5.1"
branches
– 廃止予定
このキーは廃止されます。 ワークフローのフィルタリング機能を使用して、どのジョブがどのブランチに対して実行されるかを制御することができます。
resource_class
resource_class
機能を使用すると、CPU と RAM のリソース量をジョブごとに構成できます。 実行環境では下記表のリソースクラスがご利用いただけます。
CircleCI では、すべてのお客様がシステムを安定した状態で利用できるよう、リソース クラスごとに同時処理数のソフト制限を設けています。 Performance プランまたは Custom プランを使用していて、特定のリソース クラスで待機時間が発生している場合は、このソフト制限に達している可能性があります。 CircleCI サポート にお客様のアカウントの制限値引き上げを依頼してください。
注: リソースクラスを指定しない場合、CircleCI は変更される可能性のあるデフォルト値を使用します。 デフォルト値にするよりもリソースクラスを指定することをお勧めします。
注: Java、Erlang など、CPU 数に関する情報を /proc
ディレクトリから入手する言語では、CircleCI のリソースクラス機能を使用するときに、低速化を防ぐために追加の設定が必要になることがあります。 この問題は使用する CPU コアを 32 個要求したときに発生するもので、1 コアをリクエストしたときよりも実行速度が低下します。 該当する言語を使用しているユーザーは、問題が起こらないよう CPU コア数を決まった範囲に固定するなどして対処してください。
注: 割り当てられているメモリ量を確認するには、grep hierarchical_memory_limit /sys/fs/cgroup/memory/memory.stat
を実行して cgroup メモリ階層制限をチェックしてください。
CircleCI Server をオンプレミスでホスティングしている場合は、利用可能なリソース クラスについてシステム管理者に問い合わせてください。
セルフホストランナー
resource_class
を使って セルフホストランナー インスタンスを設定します。
例えば下記のようにします。
jobs:
job_name:
machine: true
resource_class: <my-namespace>/<my-runner>
Docker 実行環境
クラス | vCPU | RAM |
---|---|---|
small | 1 | 2 GB |
medium | 2 | 4 GB |
medium+ | 3 | 6 GB |
large | 4 | 8 GB |
xlarge | 8 | 16 GB |
2xlarge(2) | 16 | 32 GB |
2xlarge+(2) | 20 | 40 GB |
例
jobs:
build:
docker:
- image: buildpack-deps:trusty
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
resource_class: xlarge
steps:
... // other config
Linux VM 実行環境
クラス | vCPU | RAM | ディスクサイズ |
---|---|---|---|
medium | 2 | 7.5 GB | 100 GB |
large | 4 | 15 GB | 100 GB |
xlarge | 8 | 32 GB | 100 GB |
2xlarge | 16 | 64 GB | 100 GB |
例
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 実行環境
クラス | vCPU | RAM |
---|---|---|
medium | 4 @ 2.7 GHz | 8 GB |
macos.x86.medium.gen2 | 4 @ 3.2 GHz | 8 GB |
large | 8 @ 2.7 GHz | 16 GB |
macos.x86.metal.gen1 | 12 @ 3.2 GHz | 32 GB |
注: macos.x86.metal.gen1
リソースは、最低 24 時間の利用が必要です。 このリソースクラスの詳細については、 macOS の専有ホストを参照して下さい。
注: large
リソースクラスは、年間契約のお客様のみご利用いただけます。 年間契約プランの詳細については、 サポートチケットをオープンしお問い合わせください。
例
jobs:
build:
macos:
xcode: "12.5.1"
resource_class: large
steps:
... // その他の設定
Windows 実行環境
クラス | vCPU | RAM | ディスクサイズ |
---|---|---|---|
medium (デフォルト) | 4 | 15GB | 200 GB |
large | 8 | 30GB | 200 GB |
xlarge | 16 | 60GB | 200 GB |
2xlarge | 32 | 128GB | 200 GB |
例
GPU 実行環境 (Linux)
クラス | vCPU | RAM | GPU | GPU モデル | GPU メモリ (GiB) | ディスクサイズ (GiB) |
---|---|---|---|---|---|---|
gpu.nvidia.small | 4 | 15 | 1 | NVIDIA Tesla P4 | 8 | 300 |
gpu.nvidia.medium | 8 | 30 | 1 | NVIDIA Tesla T4 | 16 | 300 |
gpu.nvidia.large | 8 | 30 | 1 | NVIDIA Tesla V100 | 16 | 300 |
注: このリソースは、サポートチームによる確認が必要です。 ご利用の際は、 サポート チケットをオープンしてください。
例
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)
クラス | vCPU | RAM | GPU | GPU モデル | GPU メモリ (GiB) | ディスクサイズ (GiB) |
---|---|---|---|---|---|---|
windows.gpu.nvidia.medium | 16 | 60 | 1 | NVIDIA Tesla T4 | 16 | 200 |
注: このリソースは、サポートチームによる確認が必要です。 ご利用の際は、 サポートチケットをオープンしてください。
例
version: 2.1
orbs:
win: circleci/windows@4.1.1
jobs:
build:
executor: win/gpu-nvidia
steps:
- checkout
- run: '&"C:\Program Files\NVIDIA Corporation\NVSMI\nvidia-smi.exe"'
(2) このリソースは、サポート チームによる確認が必要となります。 ご利用の際は、 サポート チケットをオープンしてください。
Arm 実行環境 (LinuxVM)
クラス | vCPU | RAM | ディスクサイズ |
---|---|---|---|
arm.medium (デフォルト) | 2 | 8 GB | 100 GB |
arm.large | 4 | 16 GB | 100 GB |
arm.xlarge | 8 | 32 GB | 100 GB |
arm.2xlarge | 16 | 64 GB | 100 GB |
steps
ジョブにおける steps
の設定は、キーと値のペアを 1 つずつ列挙する形で行います。キーはステップのタイプを表し、 値は設定内容を記述するマップか文字列(ステップのタイプによって異なる)のどちらかになります。 下記はマップを記述する場合の例です。
jobs:
build:
working_directory: ~/canary-python
environment:
FOO: bar
steps:
- run:
name: Running tests
command: make test
ここでは run
がステップのタイプとなります。 name
属性は CircleCI 上での表示に使われるものです。 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
あらゆるコマンドラインプログラムを呼び出すのに使います。設定値を表すマップを記述するか、簡略化した表記方法では、command
や name
として扱われる文字列を記述します。 run コマンドはデフォルトでは非ログインシェルで実行されます。そのため、いわゆる dotfiles をコマンド内で明示的に指定するといった工夫が必要になります。
run
ステップは、廃止予定の deploy
ステップに代わるものです。 ジョブの並列実行が 1 つの場合、廃止予定の deploy
ステップは、 run
ステップに直接スワップアウトできます。 並列実行が 2 以上の場合は、 deploy
から run
への移行を参照してください。キー | 必須 | タイプ | 説明 |
---|---|---|---|
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 | × | 文字列型 | このステップを有効または無効にする条件。 値は always 、on_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
によるディレクトリ作成が失敗し、ゼロ以外の終了ステータスを返したときは、コマンドの実行は中断され、ステップ全体としては失敗として扱われることになります。 それとは反対の挙動にしたいときは、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
)の返り値で決まるためです。
make test
が失敗したとしても、パイプの残りの部分が実行されることに注意してください。
このような動作に不都合があるときは、コマンドで set +o pipefail
を指定するか、shell
全体を(最初の例のように)書き換えてください。
通常はデフォルトのオプション(-eo pipefail
)を使うことを推奨しています。こうすることで、途中のコマンドでエラーがあっても気付くことができ、ジョブが失敗したときのデバッグも容易になります。 CircleCI 上では 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
この例では、command
と name
には run
の文字列値が割り当てられたのと同等となり、run
におけるコンフィグマップの残りにはデフォルト値が設定されます。
when
属性
デフォルトでは、CircleCI は config.yml
で定義された順序通り、ステップが失敗するまで(ゼロ以外の終了コードを返すまで)ジョブステップを 1 つずつ実行します。 コマンドが失敗すると、それ以降のジョブステップは実行されません。
when
属性を追加することで、このデフォルトのジョブステップの挙動を変えることができます。ジョブのステータスに応じてステップを続行するか、スキップするかを選択することも可能になります。
デフォルト値である on_success
は、それまでのステップが全て成功している(終了コード 0 を返した)ときのみ処理を続けます。
always
はそれまでのステップの終了ステータスにかかわらず処理を続けます。 前のステップが成功したか否かに関係なく処理を続けたいタスクがあるときに都合の良い設定です。 例えば、ログやコードカバレッジのデータをどこかのサーバーにアップロードするようなジョブステップに利用できます。
on_fail
は、それまでのステップの 1 つが失敗した (0 以外の終了コードを返した) 場合にのみ、そのステップが実行されることを意味します。 デバッグを支援するなんらかの診断データを保存したいとき、あるいはメールやチャットなどで失敗に関する通知をしたいときなどに on_fail
が使えます。
注: 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: Testing application
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: Upload Failed Tests
command: curl --data fail_tests.log http://example.com/error_logs
when: on_fail
when
ステップ (version: 2.1 が必須)
when
キーや unless
キーを使うことで条件付きのステップを作ることができます。 when
キーの下に、condition
サブキーと steps
サブキーを記述します。 when
ステップの用途として考えられるのは、事前に Workflows を実行して確認した(コンパイルの時点で決定される)条件に基づいて実行するために、コマンドとジョブの設定をカスタマイズする、といったものです。 詳細は「コンフィグを再利用する」の 「条件付きステップ」を参照してください。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
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
) にソース コードをチェックアウトするために使用する特別なステップです。 コードのチェックアウトを簡便にすることを目的にしたヘルパー関数である、というのが特殊としている理由です。 HTTPS 経由で git を実行する場合はこのステップは使えません。ssh 経由でチェックアウトするのと同じ設定を行う必要があります。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
path | × | 文字列型 | チェックアウト ディレクトリ。 ジョブの working_directory からの相対パスとして解釈されます (デフォルトは . ) |
path
が既に存在する場合、次のように動作します。
- Ubuntu 16.04、Docker v18.09.3、Docker Compose v1.23.1
- Git リポジトリ以外 - ステップは失敗します。
単純に checkout
する場合は、ステップタイプは属性なしで文字列を記述するだけです。
- checkout
注: CircleCI は、サブモジュールをチェックアウトしません。 そのプロジェクトにサブモジュールが必要なときは、下記の例のように適切なコマンドを実行する run
ステップを追加してください。
- checkout
- run: git submodule sync
- run: git submodule update --init
このコマンドは、SSH 経由で GitHub や Bitbucket を操作するために必要な認証キーを自動的に挿入します。この詳細は、カスタム チェックアウト コマンドを実装する際に役に立つ インテグレーション ガイドで解説しています。
注: checkout
ステップは、自動ガベージコレクションをスキップするように Git を構成します。 restore_cache キーで .git
ディレクトリをキャッシュしていて、そのディレクトリ配下のデータ量を最小限にするのにガベージコレクションも実行したい場合は、先に run ステップで git gc
コマンドを実行しておく方法があります。
setup_remote_docker
Docker コマンド実行用のリモート Docker 環境を作成します。 詳細は Docker コマンドを実行するを参照してください。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
docker_layer_caching | × | ブール値 | True に設定すると、リモート Docker 環境で Docker レイヤーキャッシュ が有効になります (デフォルトは false )。 |
version | × | 文字列型 | 使用する Docker のバージョン文字列 (デフォルトは 17.09.0-ce )。 サポートされている Docker バージョンについては、 こちらを参照してください。 |
注:
setup_remote_docker
は、machine
Executor と互換性がありません。machine
Executor における Docker レイヤーキャッシングの方法について、詳細は「Docker レイヤーキャッシング」の「 Machine Executor」を参照してください。- 現在、プライベート クラウドまたはデータセンターにインストールされている CircleCI では、
version
キーがサポートされていません。 リモート環境にインストールされている Docker のバージョンについては、システム管理者に問い合わせてください。
save_cache
CircleCI のオブジェクトストレージにある、依存関係やソースコードのようなファイル、ディレクトリのキャッシュを生成し、保存します。 キャッシュはその後のジョブで 復元することができます。 詳細については、 依存関係のキャッシュを参照してください。
保存期間は、 CircleCI Web アプリの Plan > Usage Controls からカスタマイズ可能です。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
paths | ○ | リスト | キャッシュに追加するディレクトリのリスト。 |
key | ○ | 文字列型 | このキャッシュの一意の識別子。 |
name | × | 文字列型 | CircleCI の UI に表示されるステップのタイトル (デフォルトは「Saving Cache」)。 |
when | × | 文字列型 | このステップを有効または無効にする条件。 値は always 、on_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.json 、pom.xml 、project.clj など) の使用をお勧めします。 restore_cache と save_cache の間でこのファイルが変化しないのが重要なポイントです。ファイル内容が変化すると、restore_cache のタイミングで使われるファイルとは異なるキャッシュキーを元にしてキャッシュを保存するためです。 |
{{ epoch }} | UNIX エポックからの秒数で表される現在時刻。 |
{{ arch }} | OS と CPU の情報。 OS や CPU アーキテクチャに合わせてコンパイル済みバイナリをキャッシュするような場合に用います。darwin amd64 あるいは linux i386/32-bit のような文字列になります。 |
ステップの処理では、以上のようなテンプレートの部分は実行時に値が置き換えられ、その置換後の文字列がキー
の値として使われます。
テンプレートの例
myapp-{{ checksum "package-lock.json" }}
-package-lock.json
ファイルの内容が変わるたびにキャッシュが再生成されます。このプロジェクトのさまざまなブランチで同じキャッシュ キーが生成されます。myapp-{{ .Branch }}-{{ checksum "package-lock.json" }}
- 上の例と同じように、ファイルの内容が変わるたびにキャッシュが再生成されますが、各ブランチで個別のキャッシュが生成されます。myapp-{{ epoch }}
- ジョブを実行するごとに個別のキャッシュが生成されます。
キャッシュの key
にテンプレート値を埋め込む場合、キャッシュの保存に制限がかかることに注意してください。CircleCI のストレージにキャッシュをアップロードするのに通常より時間がかかります。 そのため、実際に変更があったときにのみ新しいキャッシュを生成し、ジョブ実行のたびに新たなキャッシュを作らないように key
を使うのがコツです。
v1-...
など) を付加すると便利です。 こうすれば、プレフィックスのバージョン番号を増やしていくだけで、キャッシュ全体を再生成できます。例
- 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 つの属性を指定する必要があります。 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
が復元されます。
key の詳しい書式については、 save_cache
ステップの key
セクションをご覧ください。
CircleCI が keys
のリストを処理するときは、最初にマッチした既存のキャッシュを復元します。 通常は、より特定度の高いキー (たとえば、package-lock.json
ファイルの正確なバージョンに対応するキー) を最初に記述し、より汎用的なキー (たとえば、プロジェクトの任意のキャッシュが対象となるキー) をその後に記述します。 キーに該当するキャッシュが存在しない場合は、警告が表示され、ステップがスキップされます。
元々のキャッシュの保存場所に復元されるため、restore_cache では path の指定は不要です。
例
- 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
- 廃止予定
現在のプロセスに関しては、 実行をご覧ください。 並列実行が 2 以上の場合は、 deploy
から run
への移行を参照してください。
deploy
から run
への移行
**注: **廃止予定の deploy
ステップが使われている設定ファイルは、 変更する 必要があります。ジョブに並列実行が使われているかいないかに関わらず、deploy
ステップの すべての インスタンスを削除する必要があります。
並列実行が 1 つの場合、deploy
キーと run
キーをスワップアウトします。 移行に必要な処理はこれだけです。
ジョブの 並列実行が 2 つ以上の場合、deploy
ステップは直接置き換えられません。 1 つのワークフローで、テストジョブとデプロイジョブの 2 つのジョブを別々に作成することを推奨します。 テストジョブではテストをが並列で実行され、デプロイジョブはテストジョブに依存します。 テストジョブの並列実行が 2 つ以上の場合、以前の deploy
ステップのコマンドが ‘run’ に置き換えられ 、並列実行は行われません。 以下のサンプルをご覧ください。
例
以下の例では 2 つ以上の並列実行を含む設定ファイルで、廃止予定の deploy
ステップを置き換えています。(このコードは廃止されるため、コピーしないでください)。
# Example of deprecated syntax, do not copy
version: 2.1
jobs:
deploy-step-job:
docker:
- image: cimg/base:stable
parallelism: 3
steps:
- checkout
- run:
name: "Say hello"
command: "echo Hello, World!"
- run:
name: "Write random data"
command: openssl rand -hex 4 > rand_${CIRCLE_NODE_INDEX}.txt
- run:
name: "Emulate doing things"
command: |
if [[ "$CIRCLE_NODE_INDEX" != "0" ]]; then
sleep 30
fi
- deploy: #deprecated deploy step, do not copy
command: |
echo "this is a deploy step which needs data from the rand"
cat rand_*.txt
workflows:
deploy-step-workflow:
jobs:
- deploy-step-job
完全に外部リソースに依存している場合 (たとえば、Docker コンテナがレジストリにプッシュされるなど)、上記の deploy
ステップをジョブとして抽出します。これにはdoing-things-job
を完了させる必要があります。 doing-things-job
では 並列実行を 3 つ使用し、deploy-step-job
では実際のデプロイを実行します。 以下のサンプルを参照してください。
version: 2.1
jobs:
doing-things-job:
docker:
- image: cimg/base:stable
parallelism: 3
steps:
- checkout
- run:
name: "Say hello"
command: "echo Hello, World!"
- run:
name: "Write random data"
command: openssl rand -hex 4 > rand_${CIRCLE_NODE_INDEX}.txt
- run:
name: "Emulate doing things"
command: |
if [[ "$CIRCLE_NODE_INDEX" != "0" ]]; then
sleep 30
fi
# create a new job with the deploy step in it
deploy-job:
docker:
- image: cimg/base:stable
steps:
- run: # change "deploy" to "run"
command: |
echo "this is a deploy step"
workflows:
deploy-step-workflow:
jobs:
- doing-things-job
# add your new job and make it depend on the
# "doing-things-job"
- deploy-job:
requires:
- doing-things-job
deploy-job
の doing-things-job
からファイルが必要な場合は、 ワークスペースを使います。 これにより、2 つのジョブでファイルを共用でき、 deploy-job
がファイルにアクセスできるようになります。 以下のサンプルを参照してください。
version: 2.1
jobs:
doing-things-job:
docker:
- image: cimg/base:stable
parallelism: 3
steps:
- checkout
- run:
name: "Say hello"
command: "echo Hello, World!"
- run:
name: "Write random data"
command: openssl rand -hex 4 > rand_${CIRCLE_NODE_INDEX}.txt
- run:
name: "Emulate doing things"
command: |
if [[ "$CIRCLE_NODE_INDEX" != "0" ]]; then
sleep 30
fi
# save the files your deploy step needs
- persist_to_workspace:
root: . # relative path to our working directory
paths: # file globs which will be persisted to the workspace
- rand_*
deploy-job:
docker:
- image: cimg/base:stable
steps:
# attach the files you persisted in the doing-things-job
- attach_workspace:
at: . # relative path to our working directory
- run:
command: |
echo "this is a deploy step"
workflows:
deploy-step-workflow:
jobs:
- doing-things-job
- deploy-job:
requires:
- doing-things-job
このサンプルでは “fan-in” ワークフロー (詳細は、 ワークフロー を参照)を効果的に使用しています。 廃止される deploy
ステップは、近い将来のある時点でサポートが終了する予定です。 お客様の設定の移行のために十分な時間をお取りする予定です。
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 または Cucumber JSON のテスト メタデータ ファイルが格納されたサブディレクトリを含むディレクトリ、またはシングル テストへのパス (絶対パス、または 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
値の使用
パイプライン値はすべてのパイプライン構成で使用でき、事前の宣言なしに利用できます。 利用可能なパイプライン値は次のとおりです。
変数 | タイプ | 値 |
---|---|---|
pipeline.id | 文字列型 | パイプラインを表す、 グローバルに一意のID。 |
pipeline.number | 整数型 | パイプラインを表す、プロジェクトで一意の整数の ID |
pipeline.project.git_url | 文字列型 | 現在のプロジェクトがホストされている URL 。 たとえば、https://github.com/circleci/circleci-docs |
pipeline.project.type | 文字列型 | 小文字の VCS プロバイダ名。 例: “github”、“bitbucket” |
pipeline.git.tag | 文字列型 | パイプラインをトリガーするためにプッシュされた git タグの名前。 タグでトリガーされたパイプラインでない場合は、文字列は空です。 |
pipeline.git.branch | 文字列型 | パイプラインをトリガーするためにプッシュされた git タグの名前。 |
pipeline.git.revision | 文字列型 | 現在ビルドしている長い git SHA(40文字) |
pipeline.git.base_revision | 文字列型 | 現在ビルドしているものより前のビルドの長い git SHA (40 文字) **注: ** 多くの場合、pipeline.git.base_revision は、現在実行しているパイプラインより前のパイプラインを実行する SHA ですが、いくつか注意事項があります。 ブランチの最初のビルドの場合、変数は表示されません。 また、ビルドが API からトリガーされた場合も変数は表示されません。 |
pipeline.in_setup | ブール値型 | パイプラインがセットアップ段階にある場合 ( セットアップ ワークフローの実行中など) は、有効です。 |
pipeline.trigger_source | 文字列型 | パイプラインをトリガーするソース、現在の値は webhook 、api 、scheduled_pipeline です。 |
pipeline.schedule.name | 文字列型 | パイプラインのスケジュール実行の場合はスケジュール名です。 他のソースがこのパイプラインをトリガーすると、値は空の文字列になります。 |
pipeline.schedule.id | 文字列型 | パイプラインのスケジュール実行の場合は当該スケジュールの一意の 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
steps:
- run: echo “Hello World”
workflows:
build-workflow:
jobs:
- build
注:
- IP アドレスの範囲機能をご利用いただくには、有料の Performance プランまたは Scale プランのご契約が必要です。
workflows
あらゆるジョブの自動化に用います。 各ワークフローは、キーとなるワークフロー名と、値となるマップで構成します。 名前は、その config.yml
内で一意である必要があります。 ワークフロー構成の最上位のキーは version
と jobs
です。 詳細については、 ワークフローを使ったジョブのスケジュール実行のページを参照してください。
version
(v2.1 の設定ファイルでは不要)
ワークフローの version
フィールドは、サポートの終了または互換性を損なう変更について注意を促すために記述します。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
version | 設定ファイルのバージョンが 2 の場合は Y | 文字列型 | 現在は 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
を指定した場合、一致するブランチではジョブは実行されません。only
とignore
のどちらも指定していない場合、全てのブランチでジョブを実行します。only
とignore
の両方を指定した場合、only
が使用され、ignore
は使われません。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
branches | ○ | マップ | 実行するブランチを定義するマップ。 |
only | ○ | 文字列、または文字列のリスト | 単一のブランチ名、またはブランチ名のリスト。 |
ignore | × | 文字列、または文字列のリスト | 単一のブランチ名、またはブランチ名のリスト。 |
jobs
ジョブでは、requires
、name
、context
、type
、filters
の各キーを使用できます。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
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
注 : hold
というジョブ名は、メインの設定に入れないようにしてください。
filters
ジョブのフィルタリングでは、branches
キーまたは tags
キーを使用できます。
注 : ワークフローではジョブレベルのブランチは無視されます。 ジョブレベルでブランチを指定していて後でワークフローを追加する場合は、ジョブレベルのブランチを削除し、代わりにそれを config.yml
のワークフローセクションで以下のように宣言する必要があります。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
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
を指定した場合、一致するブランチではジョブは実行されません。only
とignore
のいずれも指定していない場合、すべてのブランチでジョブが実行されます。only
とignore
の両方を指定した場合は、only
を処理してからignore
の処理に移ります。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
branches | × | マップ | 実行するブランチを定義するマップ。 |
only | × | 文字列、または文字列のリスト | 単一のブランチ名、またはブランチ名のリスト。 |
ignore | × | 文字列、または文字列のリスト | 単一のブランチ名、またはブランチ名のリスト。 |
tags
CircleCI は明示的にタグフィルターを指定しない限り、タグに対してワークフローは実行しません。 さらに、ジョブが (直接的または間接的に) 他のジョブを必要とする場合は、それらのジョブにタグフィルターを指定する必要があります。
tags では only
キーと ignore
キーが使えます。 スラッシュで囲むことで正規表現でタグに一致させたり、そのような文字列のリストでマップさせたりできます。 正規表現は、文字列全体に一致する必要があります。 CircleCI では軽量版と注釈付き版のどちらのタグにも対応しています。
only
の値にマッチするタグはすべてジョブを実行します。ignore
の値にマッチするタグはすべてジョブを実行しません。only
とignore
のどちらも指定していない場合、すべてのタグのジョブがスキップされます。only
とignore
の両方を指定した場合は、only
を処理してからignore
の処理に移ります。
キー | 必須 | タイプ | 説明 |
---|---|---|---|
tags | × | マップ | 実行するタグを定義するマップ。 |
only | × | 文字列、または文字列のリスト | 単一のタグ名、またはタグ名のリスト。 |
ignore | × | 文字列、または文字列のリスト | 単一のタグ名、またはタグ名のリスト。 |
詳細については、ワークフローに関するドキュメントの「 Git タグに対応するワークフローを実行する」を参照してください。
matrix
(version: 2.1 が必須)
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
上記のマトリックスは、パラメーター a
と b
の組み合わせのうち、{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-steps
と post-steps
(version: 2.1 が必須)
ワークフローでは、すべてのジョブ呼び出しは、オプションで 2つの特別な引数 pre-steps
と post-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"
ワークフローでの when
の使用
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:
...
この例では、POST
本体に以下が含まれた状態でパイプラインがトリガーされたときに、テストが明示的に呼び出されない限りは integration_tests
ワークフローは実行されないようにしています。
{
"parameters": {
"run_integration_tests": true
}
}
いくつかの例と概念的な情報については、 ワークフローに関するドキュメントを参照してください。
ロジックステートメント
一部のダイナミックコンフィグ機能では、ロジックステートメントを引数として使用できます。 ロジックステートメントとは、設定ファイルのコンパイル時 (ワークフローの実行前) に真偽の評価が行われるステートメントです。 ロジックステートメントには次のものがあります。
Type | Arguments | true if | Example |
---|---|---|---|
YAML literal | None | is truthy | true /42 /"a string" |
YAML alias | None | resolves to a truthy value | *my-alias |
Pipeline Value | None | resolves to a truthy value | << pipeline.git.branch >> |
Pipeline Parameter | None | resolves to a truthy value | << pipeline.parameters.my-parameter >> |
and | N logic statements | all arguments are truthy | and: [ true, true, false ] |
or | N logic statements | any argument is truthy | or: [ false, true, false ] |
not | 1 logic statement | the argument is not truthy | not: true |
equal | N values | all arguments evaluate to equal values | equal: [ 42, << pipeline.number >>] |
matches | pattern and value | value matches the pattern | matches: { pattern: "^feature-.+$", value: << pipeline.git.branch >> } |
次の論理値は偽とみなされます。
- false
- null
- 0
- NaN
- 空の文字列 (“”)
- 引数を持たないステートメント
上記以外の値はすべて真とみなされます。 ただし、空のリストを引数とするロジックステートメントはバリデーションエラーとなるので注意してください。
ロジックステートメントの真偽の評価は常に最上位レベルで行われ、必要に応じて強制することもできます。 また、最大 100 レベルの深さまで、引数の仕様に応じた任意の方法でネストできます。
matches
の pattern
には、 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: 12.5.1
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
関連項目
ドキュメントの改善にご協力ください
このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.