パイプラインの値とパラメーター
パイプラインの値とパラメーターを使用すると、再利用可能なパイプラインを設定できます。
- パイプライン値: 設定ファイル全体で使用できるメタデータ。
- パイプラインパラメーター: 型指定されたパイプライン変数。 設定ファイルの一番上にある
parameters
キーで宣言します。parameters
は、API からパイプラインの新規実行をトリガーする際にパイプラインに渡すことができます。
パイプライン値
パイプライン値は、あらゆるパイプライン設定で、事前に宣言することなく使用できます。
値や定義済みの環境変数の全リストは、 プロジェクトの値と変数に関するガイドを参照して下さい。
変数 | タイプ | 値 |
---|---|---|
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 です。 他のソースがこのパイプラインをトリガーすると、値は空の文字列になります。 |
使用例:
jobs:
build:
docker:
- image: cimg/node:17.0
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
CIRCLE_COMPARE_URL: << pipeline.project.git_url >>/compare/<< pipeline.git.base_revision >>..<<pipeline.git.revision>>
working_directory: ~/main
steps:
- run: echo "This is pipeline ID << pipeline.id >>"
- run: echo $CIRCLE_COMPARE_URL
上記の方法で environment
キーの値を設定する際にパイプラインの変数が空の場合、変数は <nil>
が設定されます。 文字列を空にする必要がある場合は、 シェルコマンドで変数を設定するをご覧ください。 {class=”alert alert-info” }
設定ファイルにおけるパイプラインパラメーター
パイプラインパラメーターは、.circleci/config.yml
の一番上で parameters
キーを使って宣言します。
パイプラインパラメーターでは以下のタイプのデータをサポートしています。
- 文字列
- ブール値
- 整数
- 列挙型
詳細については「 パラメーターの構文」セクションを参照してください。
パイプラインパラメーターは値で参照され、pipeline.parameters
のスコープ内で設定ファイル内の変数として使用できます。
以下の例では、2 つのパイプラインパラメーター (image-tag
、workingdir
) が設定ファイルの一番上で定義され、後続の build
ジョブで参照されています。
version: 2.1
parameters:
image-tag:
type: string
default: "current"
workingdir:
type: string
default: "~/main"
jobs:
build:
docker:
- image: cimg/node:<< pipeline.parameters.image-tag >>
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
IMAGETAG: << pipeline.parameters.image-tag >>
working_directory: << pipeline.parameters.workingdir >>
steps:
- run: echo "Image tag used was ${IMAGETAG}"
- run: echo "$(pwd) == << pipeline.parameters.workingdir >>"
API からパイプラインをトリガーするときにパラメーターを渡す
パイプラインをトリガーする API v2 エンドポイントを使用すると、特定のパラメーターの値でパイプラインをトリガーすることができます。 これを実行するには、POST
本体の JSON パケット内で parameters
キーを渡します。
注: この POST
で parameters
キーを渡すリクエストは、シークレットではありませんのでご注意ください。
下の例では、上記の設定ファイルの例で説明したパラメーターを使用して、パイプラインをトリガーしています (注: API からパイプラインをトリガーするときにパラメーターを渡すには、設定ファイルでパラメーターを宣言している必要があります)。
curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
"parameters": {
"workingdir": "./myspecialdir",
"image-tag": "4.8.2"
}
}' https://circleci.com/api/v2/project/:project_slug/pipeline
CiecleCI Web アプリを使ってパイプラインをトリガーするときにパラメーターを渡す
CLI や API の使用に加えて、CircleCI Web アプリからパラメーターを使ってパイプラインをトリガーすることもできます。 以下の設定を行います。
- Web アプリでダッシュボードを表示します。
- プロジェクトのフィルタリング機能を使ってプロジェクトを選択します。
- ブランチのフィルタリング機能を使って新しいパイプラインを実行するブランチを選択します。
- Trigger Pipeline ボタンをクリックします (ページの右上隅)。
- Add Parameters ドロップダウンを使って、パラメーターのタイプ、名前、値を指定します。
- Trigger Pipeline をクリックします。
注: Web アプリからパイプラインをトリガーする時に、設定ファイルで宣言していないパラメーターを渡すと、そのパイプラインは失敗し、 Unexpected argument(s)
というエラーが表示されます。
パイプラインパラメーターのスコープ
パイプラインパラメーターは、それらが宣言されている .circleci/config.yml
内でのみ扱うことができます。 config.yml でローカルに宣言された Orb を含め、Orb ではパイプラインパラメーターを使用できません。 これは、パイプラインのスコープを Orb 内で使用するとカプセル化が崩れ、Orb と呼び出し側の設定ファイルの間に強い依存関係が生まれ、決定論的動作が損なわれ、脆弱性が攻撃される領域が作られてしまう可能性があるためです。
設定プロセスの段階とパラメーターのスコープ
プロセスの段階
設定プロセスは次の段階を経て進みます。
- パイプラインパラメーターが解決され、型チェックされる
- パイプライン パラメーターが Orb ステートメントに置き換えられる
- Orb がインポートされる
残りの設定プロセスが進み、要素パラメーターが解決され、型チェックされ、置き換えられます。
要素パラメーターのスコープ
要素パラメーターは字句スコープをとるため、ジョブ、コマンド、Executor などで定義されている要素の範囲内に収まります。 下の例のように、パラメーターを持つ要素がパラメーターを持つ別の要素を呼び出す場合、内側の要素は呼び出し元の要素のスコープを継承しません。
version: 2.1
commands:
print:
parameters:
message:
type: string
steps:
- run: echo << parameters.message >>
jobs:
cat-file:
parameters:
file:
type: string
steps:
- print:
message: Printing << parameters.file >>
- run: cat << parameters.file >>
workflows:
my-workflow:
jobs:
- cat-file:
file: test.txt
cat-file ジョブから print
コマンドを呼び出しても、file パラメーターのスコープは print コマンド内には及びません。 これにより、すべてのパラメーターが常に有効な値にバインドされ、使用可能なパラメーターが常に認識されます。
パイプライン値のスコープ
パイプライン値、つまり CircleCI が提供するパイプライン内で使用できる値 (例: << pipeline.number >>
) は、常にスコープ内で有効です。
パイプラインパラメーターのスコープ
設定ファイル内で定義されているパイプラインパラメーターは常にスコープ内で有効ですが、2 つの例外があります。
- パイプラインパラメーターは、他のパイプラインパラメーターの定義の範囲内では有効でないため、相互に依存させることはできません。
- データ漏えいを防ぐために、パイプラインパラメーターは Orb 本体、Orb のインラインの範囲内では有効ではありません。
条件付きワークフロー
ワークフロー宣言の下で ロジックステートメントと一緒に when 句(または逆の
unless 句)を使用すると、そのワークフローを実行するかどうかを判断できます。 when
や unless
のロジックステートメントにより値の真偽を評価します。
この設定の最も一般的な活用方法は、値としてパイプラインパラメーターを使用し、API トリガーでそのパラメーターを渡して、実行するワークフローを決定できるようにすることです。
以下の設定例では、パイプラインパラメーター run_integration_tests
を使用して integration_tests
ワークフローの実行を制御しています。
version: 2.1
parameters:
run_integration_tests:
type: boolean
default: false
workflows:
version: 2
integration_tests:
when: << pipeline.parameters.run_integration_tests >>
jobs:
- mytestjob
jobs:
...
この例では、下のように POST
本体でパイプラインをトリガーする際にパラメーターを明示的に指定しなければ、integration_tests
ワークフローはトリガーされません。
{
"parameters": {
"run_integration_tests": true
}
}
when
キーは、パイプライン パラメーターだけでなくすべての真偽値を受け入れますが、この機能が強化されるまでは、パイプライン パラメーターを使用する方法が主流となるでしょう。 また、when
句の逆の unless
句もあり、条件の真偽を逆に指定できます。
ドキュメントの改善にご協力ください
このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.