再利用可能な設定ファイル リファレンス ガイド
ここでは、再利用可能なコマンド、ジョブ、Executor、Orb を利用する方法について説明します。 また、パラメーター化された再利用可能な要素を作成するためのパラメーターの使用方法についても取り上げます。
-
パラメーター
宣言の使用 - 再利用可能なコマンドのオーサリング
- 再利用可能な Executor のオーサリング
- パラメーター化されたジョブのオーサリング
- 条件付きステップの定義
- インライン Orb の作成
- 関連項目
再利用可能な設定ファイルに関する注意事項
-
(任意)
circleci config process
コマンドにアクセスできるように、CircleCI CLI をインストールします 。 このコマンドを使用すると、再利用可能なキーを含む展開後の設定ファイルを確認できます。 インストール方法と詳しい使い方については、ドキュメント「CircleCI のローカル CLI の使用」を参照してください。 -
CircleCI 設定ファイルの要素を再利用するには、
version: 2.1
の.circleci/config.yml
ファイルを使用する必要があります。 -
コマンド、ジョブ、Executor、パラメーターの名前はアルファベットで始める必要があります。 名前に含めることができるのは小文字 (
a
~z
)、数字 (0
~9
)、アンダースコア (_
)、ハイフン (-
) だけです。
パラメーター
宣言の使用
パラメーターは、ジョブ、コマンド、または Executor の下で名前で宣言します。 parameters
キーの直下に置かれた子キーは、マップ内のキー セットです。 パイプライン パラメーターは、プロジェクト設定ファイルの最上部で定義します。 パイプライン パラメーターの詳細については、パイプラインの値とパラメーターに関するガイドを参照してください。
次の例では、greeting
という名前のコマンドを宣言し、to
という名前のパラメーターを使用しています。 to
パラメーターは、”Hello” とユーザーにエコーバックするステップで使用しています。
version: 2.1
commands: # パラメーターを使用する再利用可能なコマンド
greeting:
parameters:
to:
default: "world"
type: string
steps:
- run: echo "Hello <<parameters.to>>"
jobs:
my-job:
docker:
- image: cimg/base:stable
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
steps:
- greeting:
to: "My-Name"
workflows:
my-workflow:
jobs:
- my-job
パラメーターの構文
パラメーターは、以下のキーを直下の子キーとして持つことができます。
キー名 | 説明 | デフォルト値 |
---|---|---|
description | オプションのキー。 Orb のドキュメントを生成するために使用します。 | N/A |
type | 必須. 詳細については、以下の「パラメーター型」セクションを参照してください。 | N/A |
default | パラメーターのデフォルト値。 このキーがない場合は、パラメーターが必須であることを意味します。 | N/A |
パラメーターの型
このセクションでは、パラメーターの型と使用方法について説明します。
Orb では以下のパラメーター型がサポートされます。
文字列型
ブール値型
整数型
列挙型
Executor 型
ステップ型
- 環境変数名型
パイプライン パラメーターでは以下のパラメーター型がサポートされます。
文字列型
ブール値型
整数型
列挙型
文字列型
基本的な文字列型パラメーターは以下のように記述します。
version: 2.1
commands:
copy-markdown:
parameters:
destination:
description: destination directory
type: string
default: docs
steps:
- run: cp *.md << parameters.destination >>
引用符で囲まれていないと他の型 (ブール値、数値など) を表してしまう文字列、および YAML で特別な意味を持つ文字 (特にコロン) を含む文字列は、引用符で囲む必要があります。 それ以外の場合は、引用符は任意です。 when
節の評価時に、空文字列は false 値として扱われます。 その他の文字列はすべて true 値として扱われます。 なお、YAML でブール値として解釈される文字列値を引用符なしで使用すると、型エラーが発生します。
ブール値型
ブール値型パラメーターは、条件文で使用すると便利です。
version: 2.1
commands:
npm-install:
parameters:
clean:
description: Perform a clean install
type: boolean
default: false
steps:
- when:
condition: << parameters.clean >>
steps:
- run: npm clean-install
- when:
condition:
not: << parameters.clean >>
steps:
- run: npm install
ブール値型パラメーターの評価は、YAML 1.1 で指定されている値に基づいています。
- true と評価されるもの:
y
、yes
、true
、on
- false と評価されるもの:
n
、no
、false
、off
注: ブール値は true のときに ‘1’ を、false のときに ‘0’ を返す場合があります。
上記の値は、語頭のみ大文字、またはすべて大文字で表記しても有効です。
整数型
整数値を渡すには、パラメーター型 integer
を使用します。 以下の例では、integer
型を使用して、ジョブで parallelism
の値を指定しています。
version: 2.1
jobs:
build:
parameters:
p:
type: integer
default: 1
parallelism: << parameters.p >>
machine: true
steps:
- checkout
workflows:
workflow:
jobs:
- build:
p: 2
列挙型
enum
型パラメーターには、任意の値のリストを指定できます。 enum
型パラメーターは、特定の文字列値のセットに含まれる値だけを使用するように制限したい場合に使用します。 以下の例では、enum
型パラメーターを使用して、バイナリのターゲット オペレーティング システムを宣言しています。
version: 2.1
commands:
list-files:
parameters:
os:
default: "linux"
description: The target Operating System for the heroku binary. Must be one of "linux", "darwin", "win32".
type: enum
enum: ["linux", "darwin", "win32"]
以下の enum
型の宣言は、デフォルト値が列挙リスト内に宣言されていないため、無効です。
version: 2.1
commands:
list-files:
parameters:
os:
type: enum
default: "windows" # カンマ区切り列挙リストに含まれていないデフォルト値の宣言は無効です。
enum: ["darwin", "linux"]
Executor 型
executor
パラメーター型を使用すると、ジョブの呼び出し元が実行する Executor を決定できるようになります。
version: 2.1
executors:
xenial:
parameters:
some-value:
type: string
default: foo
environment:
SOME_VAR: << parameters.some-value >>
docker:
- image: ubuntu:xenial
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
bionic:
docker:
- image: ubuntu:bionic
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
jobs:
test:
parameters:
e:
type: executor
executor: << parameters.e >>
steps:
- run: some-tests
workflows:
workflow:
jobs:
- test:
e: bionic
- test:
e:
name: xenial
some-value: foobar
ステップ型
ステップ型パラメーターは、ジョブまたはコマンドに、定義済みのステップとユーザー定義のステップを混在させる必要がある場合に使用します。 コマンドまたはジョブの呼び出しに渡すステップは、パラメーターとして渡す場合、提供されるステップが 1 つだけでも必ずシーケンスとして定義します。
version: 2.1
commands:
run-tests:
parameters:
after-deps:
description: "Steps that will be executed after dependencies are installed, but before tests are run"
type: steps
default: []
steps:
- run: make deps
- steps: << parameters.after-deps >>
- run: make test
以下の例では、パラメーターとして渡すステップに対し、ジョブの steps
で steps
宣言の値を指定しています。
version: 2.1
commands:
run-tests:
parameters:
after-deps:
description: "Steps that will be executed after dependencies are installed, but before tests are run"
type: steps
default: []
steps:
- run: make deps
- steps: << parameters.after-deps >>
- run: make test
jobs:
build:
machine: true
steps:
- run-tests:
after-deps:
- run: echo "The dependencies are installed"
- run: echo "And now I'm going to run the tests"
上記は以下のとおり解決されます。
version: 2.1
steps:
- run: make deps
- run: echo "The dependencies are installed"
- run: echo "And now I'm going to run the tests"
- run: make test
環境変数名型
環境変数名 (env_var_name
) 型パラメーターは文字列で、POSIX_NAME 正規表現 (スペースや特殊文字の使用不可など) に適合している必要があります。 env_var_name
は、渡された文字列を環境変数名として使用できるかどうかのチェックを CircleCI で実施できるという点で便利なパラメーター型です。 環境変数の詳細については、「環境変数の使用」を参照してください。
以下の例は、再利用可能な build
ジョブで AWS S3 にデプロイする場合の env_var_name
パラメーター型の使用方法を示しています。 この例では、AWS_ACCESS_KEY
および AWS_SECRET_KEY
環境変数に access-key
および secret-key
パラメーターを指定して使用しています。 したがって、s3cmd
を実行するデプロイ ジョブがある場合、必要な認証を使用しつつもカスタム バケットにデプロイする再利用可能コマンドを作成することが可能です。
パラメーターを使わない config.yml
ファイルは次のとおりです。
version: 2.1
jobs:
build:
docker:
- image: ubuntu:latest
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
steps:
- run:
command: |
s3cmd --access_key ${FOO_BAR} \
--secret_key ${BIN_BAZ} \
ls s3://some/where
workflows:
workflow:
jobs:
- build
次に、パラメーターを使って書き換えた config.yml
ファイルを示します。
version: 2.1
jobs:
build:
parameters:
access-key:
type: env_var_name
default: AWS_ACCESS_KEY
secret-key:
type: env_var_name
default: AWS_SECRET_KEY
command:
type: string
docker:
- image: ubuntu:latest
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
steps:
- run: |
s3cmd --access_key ${<< parameters.access-key >>} \\
--secret_key ${<< parameters.secret-key >>} \\
<< parameters.command >>
workflows:
workflow:
jobs:
- build:
access-key: FOO_BAR
secret-key: BIN_BAZ
command: ls s3://some/where
再利用可能なコマンドのオーサリング
コマンドは、config.yml
ファイルの commands
キーの下で宣言します。 以下の例では、文字列型パラメーター to
を受け取る sayhello
というコマンドを定義しています。
version: 2.1
commands:
sayhello:
description: "A very simple command for demonstration purposes"
parameters:
to:
type: string
default: "World"
steps:
- run: echo Hello << parameters.to >>
commands
キー
コマンドは、ジョブ内で実行される一連のステップのシーケンスをマップとして定義します。 これにより、1 つのコマンド定義を複数のジョブで再利用することができます。
キー | 必須 | 種類 | 説明 |
---|---|---|---|
steps | ○ | シーケンス | コマンドの呼び出し元のジョブ内で実行する一連のステップ。 |
parameters | × | マップ | パラメーター キーのマップ。 詳細については「パラメーターの構文」セクションを参照してください。 |
description | × | 文字列 | コマンドの目的を記述する文字列。 ドキュメントの生成に使用します。 |
再利用可能なコマンドの呼び出し
再利用可能なコマンドは、ジョブ内のステップとして、特定のパラメーターを使用して呼び出します。 コマンドを使用すると、そのコマンドのステップが、コマンドが呼び出される場所に挿入されます。 コマンドは、ジョブ内の steps
の下に置かれたシーケンスの一部としてのみ使用できます。
次の例では、上述の sayhello
コマンドを使用しています。 myjob
ジョブ内でこのコマンドを呼び出し、to
パラメーターの値を渡します。
version: 2.1
commands:
sayhello:
description: "A very simple command for demonstration purposes"
parameters:
to:
type: string
default: "World"
steps:
- run: echo Hello << parameters.to >>
jobs:
myjob:
docker:
- image: "cimg/base:stable"
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
steps:
- sayhello: # "sayhello" コマンドを呼び出します。
to: "Lev"
コマンド内での他のコマンドの呼び出し
コマンドは、実行のスコープ内で他のコマンドを使用することができます。 たとえば、Orb 内で宣言されているコマンドは、その Orb 内で他のコマンドを使用可能です。 また、インポートした他の Orb で定義されているコマンド (some-orb/some-command
など) も使用できます。
特別なキー
CircleCI では、すべての circleci.com ユーザーが利用できる特別なキーが複数提供されており、CircleCI Server でデフォルトで使用できます。 その一部をご紹介します。
checkout
setup_remote_docker
persist_to_workspace
注: 特別なキーはカスタム コマンドでオーバーライドできます。
コマンドの使用例
以下に、aws-s3
Orb の、sync
というコマンドを定義する部分を例として示します。
version: 2.1
# Aws-s3 orb
commands:
sync:
description: "A simple encapsulation of doing an s3 sync"
parameters:
from:
type: string
to:
type: string
overwrite:
default: false
type: boolean
steps:
- run:
name: Deploy to S3
command: aws s3 sync << parameters.from >> << parameters.to >><<# parameters.overwrite >> --delete<</ parameters.overwrite >>"
この sync
コマンドをバージョン 2.1 の .circleci/config.yml
ファイルで呼び出すには、次の例のようにします。
version: 2.1
orbs:
aws-s3: circleci/aws-s3@1.0.0
jobs:
deploy2s3:
docker:
- image: circleci/<language>:<version TAG>
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
steps:
- aws-s3/sync:
from: .
to: "s3://mybucket_uri"
overwrite: true
workflows:
build-test-deploy:
jobs:
- deploy2s3
build
ジョブは以下のように定義します。
version: 2.1
orbs:
aws-cli: circleci/aws-cli@0.1.2
aws-s3: circleci/aws-s3@1.0.0
jobs:
build:
executor: aws-cli/default
steps:
- checkout
- run: mkdir bucket && echo "lorum ipsum" > bucket/build_asset.txt
- aws-s3/sync:
from: bucket
to: "s3://my-s3-bucket-name/prefix"
overwrite: true
- aws-s3/copy:
from: bucket/build_asset.txt
to: "s3://my-s3-bucket-name"
arguments: --dryrun
再利用可能な Executor のオーサリング
Executor はジョブ内のステップを実行するための環境を定義します。 CircleCI の設定で job
を宣言する際に、実行環境のタイプ (docker
、machine
、macos
など) を定義します。 また、 挿入する環境変数、使用するシェル、使用する resource_class
のサイズなどの環境パラメーターも定義します。
jobs
の外側で宣言された Executor は、その宣言のスコープ内のすべてのジョブで使用できます。 そのため、1 つの Executor 定義を複数のジョブで再利用できます。
Executor 定義では、以下のキーを 1 つ以上指定します。
-
docker
、machine
、macos
environment
working_directory
shell
resource_class
次の例では、ジョブ my-job
を実行するための my-executor
を定義しています。
version: 2.1
executors:
my-executor:
docker:
- image: cimg/ruby:2.5.1-browsers
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
jobs:
my-job:
executor: my-executor
steps:
- run: echo outside the executor
executors
キー
Executor は、ジョブのステップが実行される環境を定義します。 1 つの Executor 定義を複数のジョブで 再利用することができます。
キー | 必須 | 種類 | 説明 |
---|---|---|---|
docker | ○ (1) | リスト |
docker Executor を指定するオプション |
resource_class | × | 文字列 | ジョブ内の各コンテナに割り当てる CPU と RAM の量 (docker Executor でのみ使用可能)。 注: この機能にアクセスするには有償アカウントが必要です。 有料のコンテナベース プランをお使いの場合は、サポート チケットをオープンして機能の利用をリクエストしてください。 |
machine | ○ (1) | マップ |
machine Executor を指定するオプション |
macos | ○ (1) | マップ |
macOS Executor を指定するオプション |
shell | × | 文字列 | すべてのステップで実行コマンドに使用するシェル。 各ステップで shell を使用してオーバーライドできます。 |
working_directory | × | 文字列 | ステップを実行するディレクトリ |
environment | × | マップ | 環境変数の名前と値のマップです。 |
例
version: 2.1
executors:
my-executor:
docker:
- image: cimg/ruby:2.5.1-browsers
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
jobs:
my-job:
executor: my-executor
steps:
- run: echo outside the executor
再利用可能な Executor の呼び出し
以下の例では、executor
の下で name
キーの値として my-executor
を渡しています。 この方法は主に、Executor の呼び出しにパラメーターを渡す場合に使用されます。
version: 2.1
executors:
my-executor:
docker:
- image: cimg/ruby:2.5.1-browsers
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
jobs:
my-job:
executor:
name: my-executor
steps:
- run: echo outside the executor
Orb では、Orb 内のすべてのコマンドが使用する Executor を定義することも可能です。 これにより、Orb のオーサーにより定義された実行環境内で、その Orb のコマンドを実行できます。
config.yml
で宣言した Executor をマトリックス ジョブで使用する例
次の例では、Node イメージを指定した Docker Executor を、node-docker
として宣言しています。 image 文字列のタグ部分は、version
パラメーターを使用してパラメーター化しています。 version
パラメーターは、test
ジョブにも設定しています。 こうすることで、ワークフローでこのジョブが呼び出されるときに、ジョブを通じてこのパラメーターを Executor に渡すことができます。
matrix-tests
ワークフローで test
ジョブが呼び出されると、このジョブはマトリックス ジョブにより複数回同時実行されます。 その際、実行ごとに異なるパラメーターのセットが使用されます。 これにより、Node アプリケーションを多数のバージョンの Node.js でテストしています。
version: 2.1
executors:
node-docker: # 再利用可能な Executor を宣言します。
parameters:
version:
description: "version tag"
default: "lts"
type: string
docker:
- image: cimg/node:<<parameters.version>>
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
jobs:
test:
parameters:
version:
description: "version tag"
default: "lts"
type: string
executor:
name: node-docker
version: <<parameters.version>>
steps:
- checkout
- run: echo "how are ya?"
workflows:
matrix-tests:
jobs:
- test:
matrix:
parameters:
version:
- 13.11.0
- 12.16.0
- 10.19.0
Orb で定義されている Executor の使用
他の Orb の Executor を参照することもできます。 Orb のユーザーは、その Orb の Executor を呼び出すことができます。 たとえば、foo-orb
で bar
Executor を定義します。
version: 2.1
# foo-orb の yaml
executors:
bar:
machine: true
environment:
RUN_TESTS: foobar
baz-orb
でも bar
Executor を定義できます。
version: 2.1
# baz-orb の yaml
executors:
bar:
docker:
- image: cimg/base:stable
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
どちらの Executor も設定ファイルでは、以下のように使用できます。
version: 2.1
# config.yml
orbs:
foo-orb: somenamespace/foo@1
baz-orb: someothernamespace/baz@3.3.1
jobs:
some-job:
executor: foo-orb/bar # プレフィックス付き Executor
some-other-job:
executor: baz-orb/bar # プレフィックス付き Executor
注: foo-orb/bar
と baz-orb/bar
は、異なる Executor です。 どちらも、それぞれの Orb に相対的なローカル名 bar
を持ちますが、独立した Executor であり、異なる Orb で定義されています。
Executor 呼び出し時のキーのオーバーライド
job
での Executor の呼び出し時には、ジョブ自体に含まれるキーは、呼び出された Executor のキーをオーバーライドします。 たとえば、ジョブで docker
スタンザが宣言されている場合は、 Executor で指定した Docker ではなく、その Docker がジョブ全体で使用されます。
注: environment
変数のマップは付加的です。 executors
と job
で同じ environment
変数を定義している場合は、ジョブの値が使用されます。 詳細については、環境変数の使用に関するページを参照してください。
version: 2.1
executors:
node:
docker:
- image: cimg/node:lts
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
ENV: ci
jobs:
build:
docker:
- image: cimg/base:stable
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
# The test executor below will be overwritten by the more explicit "docker" executor. Any env vars will be added.
executor: node
steps:
- run: echo "Node will not be installed."
上記の設定は以下のとおり解決されます。
version: 2.1
jobs:
build:
docker:
- image: cimg/base:stable
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
ENV: ci # From executor.
steps:
- run: echo "Node will not be installed."
パラメーター化されたジョブのオーサリング
必要なパラメーターをサブキーとしてジョブに渡すことで、config.yml
の ワークフロー定義内で、同じジョブを複数回呼び出すことができます。 使用されている構文の詳細については、上記のパラメーターに関するセクションを参照してください。
config.yml
でパラメーター化されたジョブを定義して呼び出す例を次に示します。
version: 2.1
jobs:
sayhello: # パラメーター化されたジョブを定義します。
description: A job that does very little other than demonstrate what a parameterized job looks like
parameters:
saywhat:
description: "To whom shall we say hello?"
default: "World"
type: string
machine: true
steps:
- run: echo "Hello << parameters.saywhat >>"
workflows:
build:
jobs:
- sayhello:# パラメーター化されたジョブを呼び出します。
saywhat: Everyone
注: 複数のワークフローでパラメーターを使用して同じジョブを複数回呼び出すと、ビルド名が変更されます (例: sayhello-1
、sayhello-2
など)。 ビルド名に数字が追加されないようにするには、name
キーを利用します。 重複する場合は、ジョブ名に数字が追加されます。 以下に例を示します。
workflows:
build:
jobs:
- sayhello:
name: build-sayhello
saywhat: Everyone
deploy:
jobs:
- sayhello:
name: deploy-sayhello
saywhat: All
Orb 内で定義されているジョブ
Orb 内で宣言されているジョブは、その Orb 内のコマンドまたはグローバルコマンドを使用できます。 ただし、ジョブ宣言のスコープ外のコマンドを呼び出すことはできません。
hello-orb
version: 2.1
jobs:
sayhello:
parameters:
saywhat:
description: "To whom shall we say hello?"
default: "World"
type: string
machine: true
steps:
- say:
saywhat: "<< parameters.saywhat >>"
commands:
saywhat:
parameters:
saywhat:
type: string
steps:
- run: echo "<< parameters.saywhat >>"
hello-orb を利用する設定ファイル
# config.yml
version: 2.1
orbs:
hello-orb: somenamespace/hello-orb@volatile
workflows:
build:
jobs:
- hello-orb/sayhello:
saywhat: Everyone
Executor でのパラメーターの使用
Executor でパラメーターを使用するには、その Executor の下でパラメーターを定義します。 Executor を呼び出すときは、executor:
宣言の下で、キーのマップ (各キーに渡すパラメーターの値を指定したもの) としてパラメーターのキーを渡します。
Executor 内のパラメーターには、string
型、enum
型、boolean
型を使用できます。 デフォルト値は、オプションの default
キーを使用して指定できます。
パラメーター化された Executor を使用したビルドの設定例
version: 2.1
executors:
python:
parameters:
tag:
type: string
default: latest
myspecialvar:
type: string
docker:
- image: cimg/python:<< parameters.tag >>
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
environment:
MYPRECIOUS: << parameters.myspecialvar >>
jobs:
build:
executor:
name: python
tag: "2.7"
myspecialvar: "myspecialvalue"
上記は以下のとおり解決されます。
version: 2.1
jobs:
build:
steps: []
docker:
- image: cimg/python:2.7
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # コンテキスト/プロジェクト UI 環境変数の参照
environment:
MYPRECIOUS: "myspecialvalue"
パラメーターのスコープ
パラメーターは、パラメーターを定義したジョブまたはコマンド内でのみ有効です。 ジョブまたはコマンドから呼び出し元のコマンドにパラメーターを渡す場合は、明示的に渡す必要があります。
version: 2.1
jobs:
sayhello:
parameters:
saywhat:
description: "To whom shall we say hello?"
default: "World"
type: string
machine: true
steps:
- say:
# コマンド "say" の "saywhat" パラメーターには
# デフォルト値が定義されていないため
# 手動で渡す必要があります。
saywhat: << parameters.saywhat >>
commands:
say:
parameters:
saywhat:
type: string
steps:
- run: echo "<< parameters.saywhat >>"
workflows:
build:
jobs:
- sayhello:
saywhat: Everyone
同じジョブの複数回の呼び出し
1 つの設定ファイルで、同じジョブを複数回呼び出すことができます。 ビルドのインジェストにおける設定ファイルの処理時に、ジョブに名前が付けられていなければ、CircleCI で自動的に名前が生成されます。 name
キーを使用して、重複するジョブに明示的に名前を付けることもできます。
注: 繰り返しジョブがワークフロー内の別のジョブのアップストリームになければならない場合は、その繰り返しジョブに明示的に名前を付ける必要があります。 たとえば、ワークフロー内でジョブ呼び出しの requires
キーの下で使用するジョブには、明示的に名前を付ける必要があります。
version: 2.1
workflows:
build:
jobs:
- loadsay
# このジョブには、ダウンストリームの依存関係がないため、明示的な名前は必要ありません。
- sayhello:
saywhat: Everyone
requires:
- loadsay
# saygoodbye がジョブ依存関係としてこのジョブを要求しているため、このジョブには明示的な名前が必要です。
- sayhello:
name: SayHelloChad
saywhat: Chad
# 明示的に定義した "sayhello" を使用します。
- saygoodbye:
requires:
- SayHelloChad
事前ステップと事後ステップの使用
すべてのジョブ呼び出しは、オプションで 2つの特別な引数、pre-steps
と post-steps
を受け取ることができます。 pre-steps
の下のステップは、ジョブ内の他のすべてのステップよりも前に実行されます。 post-steps
の下のステップは、他のすべてのステップよりも後に実行されます。
事前ステップと事後ステップを使用すると、特定のジョブ内で、そのジョブを変更せずにいくつかのステップを実行できます。 これは、たとえば、ジョブの実行前にカスタムのセットアップ ステップを実行したいときに便利です。
事前ステップと事後ステップの定義
以下の例では、build
ワークフローの bar
ジョブ内で、事前ステップと事後ステップを定義しています。
# config.yml
version: 2.1
jobs:
bar:
machine: true
steps:
- checkout
- run:
command: echo "building"
- run:
command: echo "testing"
workflows:
build:
jobs:
- bar:
pre-steps:
- run:
command: echo "install custom dependency"
post-steps:
- run:
command: echo "upload artifact to s3"
注: ジョブ内の pre-steps
キーと post-steps
キーは、バージョン 2.1 以上の設定ファイルで使用可能です。
条件付きステップの定義
条件付きステップは、設定ファイルのコンパイル時に条件が満たされた場合にのみ、ワークフロー実行前に実行されます。 そのため、たとえば条件を使用して環境変数をチェックすることはできません。 環境変数は、実行環境のシェルでステップが実行されるまで挿入されないからです。
条件付きステップは、通常のステップがパラメーター値を入力として使用できる箇所ならどこにでも配置することができます。
たとえば、myorb/foo: { dostuff: true }
として呼び出された場合には一連のステップを実行するが、myorb/foo: { dostuff: false }
として呼び出された場合は実行しないといったコマンドを Orb で定義できます。
さらに、Orb のオーサーであれば、ジョブまたはコマンドの steps
キーで条件付きステップを定義することもできます。
# config.yml 内
version: 2.1
jobs:
myjob:
parameters:
preinstall-foo:
type: boolean
default: false
machine: true
steps:
- run: echo "preinstall is << parameters.preinstall-foo >>"
- when:
condition: << parameters.preinstall-foo >>
steps:
- run: echo "preinstall"
- unless:
condition: << parameters.preinstall-foo >>
steps:
- run: echo "don't preinstall"
workflows:
workflow:
jobs:
- myjob:
preinstall-foo: false
- myjob:
preinstall-foo: true
- myjob # 空の文字列は false
注: 条件付きステップは、バージョン 2.1 以上の設定ファイルで使用可能です。
when
ステップ
when
キーの下に、condition
サブキーと steps
サブキーを記述します。 steps
サブキーは、条件が true 値であると評価された場合にのみ実行されます。
キー | 必須 | 種類 | 説明 |
---|---|---|---|
condition | ○ | ロジック | ロジック ステートメント |
steps | ○ | シーケンス | 条件が true 値のときに実行するステップのリスト |
unless
ステップ
unless
キーの下に、condition
サブキーと steps
サブキーを記述します。 steps
サブキーは、条件が false 値であると評価された場合にのみ実行されます。
キー | 必須 | 種類 | 説明 |
---|---|---|---|
condition | ○ | ロジック | ロジック ステートメント |
steps | ○ | シーケンス | 条件が false 値のときに実行するステップのリスト |
インライン Orb の作成
再利用可能な設定ファイル要素を設定ファイル内で直接定義する場合、それらの要素をインライン Orb 内にラップすることもできます。 インライン Orb は、開発に役立つほか、ローカル設定ファイル内で名前を共有する要素の名前空間を作成するときにも便利です。
インライン Orb を記述するには、設定ファイル内の Orb 宣言セクションにその Orb のキーを置き、その下に Orb エレメントを置きます。 たとえば、ある Orb を別の Orb 内にインポートして使用する (インライン Orb) 場合の設定ファイルは以下のようになります。 ここでは、インライン Orb my-orb
に node
Orb をインポートしています。
version: 2.1
orbs:
my-orb:
orbs:
node: circleci/node@3.0
commands:
my_command:
steps:
- run: echo "Run my tests"
jobs:
my_job:
executor: node/default # Node Orb の Executor
steps:
- checkout
- my_command
- store_test_results:
path: test-results
workflows:
main:
jobs:
- my-orb/my_job
関連項目
- CircleCI で使用できる設定例は、「サンプルの設定例」でご覧いただけます。
- 設定ファイル内で CircleCI Orb を使用するための詳しいレシピは、「設定クックブック」で紹介しています。
- CircleCI 設定ファイルで使用できるデータベースの設定例については、「データベースの設定例」を参照してください。
ドキュメントの改善にご協力ください
このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか?
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

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