パイプラインの値とパラメーター

3 months ago2 min read

クラウド

Server v4.x

Server v3.x

このページの内容

はじめに

パイプラインの値とパラメーターを使用すると、再利用可能なパイプラインを設定できます。

パイプライン値: 設定ファイル全体で使用できるメタデータ。
パイプラインパラメーター: 型指定されたパイプライン変数。設定ファイルの一番上にある parameters キーで宣言します。 parameters は、API からパイプラインの新規実行をトリガーする際にパイプラインに渡すことができます。

パイプライン値

パイプライン値は、すべてのパイプライン設定で事前に宣言することなく使用できます。

値や定義済みの環境変数の全リストは、プロジェクトの値と変数に関するガイドを参照して下さい。

変数	VCS	タイプ	値
`pipeline.id`	GitHub, Bitbucket	文字列	パイプラインを表す、グローバルに一意のID。
`pipeline.number`	GitHub, Bitbucket	整数	パイプラインを表す、プロジェクトで一意の整数の ID.
`pipeline.project.git_url`	GitHub, Bitbucket	文字列	現在のプロジェクトがホストされている URL 。例: `https://github.com/circleci/circleci-docs`
`pipeline.project.type`	GitHub, Bitbucket	文字列	小文字の VCS プロバイダ名。例: “github”、“bitbucket”
`pipeline.git.tag`	GitHub, Bitbucket	文字列	パイプラインをトリガーするためにプッシュされた git タグの名前。タグでトリガーされたパイプラインでない場合は、文字列は空です。
`pipeline.git.branch`	GitHub, Bitbucket	文字列	パイプラインをトリガーするためにプッシュされた git タグの名前。
`pipeline.git.revision`	GitHub, Bitbucket	文字列	現在ビルドしている長い git SHA（４０文字）
`pipeline.git.base_revision`	GitHub, Bitbucket	文字列	現在ビルドしているものより前のビルドの長い git SHA (40 文字) 注: 多くの場合、`pipeline.git.base_revision` は、現在実行しているパイプラインより前のパイプラインを実行する SHA ですが、いくつか注意事項があります。ブランチの最初のビルドの場合、変数は表示されません。また、ビルドが API からトリガーされた場合も変数は表示されません。
`pipeline.in_setup`	GitHub, Bitbucket	ブール値	パイプラインがセットアップ段階にある場合 (セットアップワークフローの実行中など) は、有効です。
`pipeline.trigger_source`	GitHub, Bitbucket	文字列	パイプラインをトリガーするソース、現在の値は `webhook`、`api`、`scheduled_pipeline` です。
`pipeline.schedule.name`	GitHub, Bitbucket	文字列	パイプラインのスケジュール実行の場合はスケジュール名です。他のソースがこのパイプラインをトリガーすると、値は空の文字列になります。
`pipeline.schedule.id`	GitHub, Bitbucket	文字列	パイプラインのスケジュール実行の場合は当該スケジュールの一意の ID です。他のソースがこのパイプラインをトリガーすると、値は空の文字列になります。
`pipeline.trigger_parameters.circleci.trigger_id`	GitLab		イベントを受信したトリガーの ID
`pipeline.trigger_parameters.circleci.config_source_id`	GitLab		設定ソースの ID
`pipeline.trigger_parameters.circleci.trigger_type`	GitLab		GitLab
`pipeline.trigger_parameters.circleci.event_time`	GitLab		CircleCI のイベント受信のタイムスタンプ
`pipeline.trigger_parameters.circleci.event_type`	GitLab		push、pull request、manual など
`pipeline.trigger_parameters.circleci.project_id`	GitLab		CircleCI のプロジェクト ID
`pipeline.trigger_parameters.circleci.actor_id`	GitLab		CircleCI のユーザー ID
`pipeline.trigger_parameters.gitlab.type`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.project_id`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.ref`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.checkout_sha`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.user_id`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.user_name`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.user_username`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.user_avatar`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.repo_name`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.repo_url`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.web_url`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.commit_sha`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.commit_title`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.commit_message`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.commit_timestamp`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.commit_author_name`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.commit_author_email`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.total_commits_count`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.branch`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.default_branch`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.x_gitlab_event_id`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。
`pipeline.trigger_parameters.gitlab.is_fork_merge_request`	GitLab		GitLab のドキュメントの Webhook と Webhook events を参照して下さい。

使用例:

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/node:17.0
    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>`が設定されます。文字列を空にする必要がある場合は、シェルコマンドで変数を設定するをご覧ください。

設定ファイルにおけるパイプラインパラメーター

パイプラインパラメーターは、.circleci/config.yml の一番上で parameters キーを使って宣言します。パイプラインパラメーターは値で参照され、pipeline.parameters のスコープ内で設定ファイル内の変数として使用できます。

パイプラインパラメーターでは以下のタイプのデータをサポートしています。

文字列
boolean
integer
enum

詳細については「パラメーターの構文」セクションを参照してください。

以下の例では、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 >>
    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 キーを渡すリクエストは、シークレットではありませんのでご注意ください。

下の例では、上記の設定ファイルの例で説明したパラメーターを使用して、パイプラインをトリガーしています (注: パイプラインをトリガーするコマンドを実行したときに、設定ファイルでパラメータが宣言されていない場合、Project not found などのエラー応答メッセージが表示されます)。

curl -u ${CIRCLE_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 アプリからパイプラインをトリガーする時に、設定ファイルで宣言していないパラメーターを渡すと、そのパイプラインは失敗し、`Unexpected argument(s)`というエラーが表示されます)。

プロジェクトのフィルタリング機能を使ってプロジェクトを選択します。
ブランチのフィルタリング機能を使って新しいパイプラインを実行するブランチを選択します。
Trigger Pipeline ボタンをクリックします (ページの右上隅)。
Add Parameters ドロップダウンを使って、パラメーターのタイプ、名前、値を指定します。
Trigger Pipeline をクリックします。

Web アプリでスケジュールされたパイプラインを設定する際にも、パラメーターを呼び出すことができます。パラメータは、メニューの「Project Settingsプロジェクト設定」[トリガー]内のトリガーフォームの一部です。スケジュールされたパイプラインの一部として設定されたパラメータは、設定ファイルにも宣言する必要があります。そうでない場合、パイプラインは「Unexpected argument(s)」というエラーで失敗します。

構成処理のステージ

設定プロセスは次の段階を経て進みます。

パイプラインパラメーターが解決され、型チェックされる
パイプラインパラメーターが Orb ステートメントに置き換えられる
Orb がインポートされる

残りの設定プロセスが進み、要素パラメーターが解決され、型チェックされ、置き換えられます。

パイプラインパラメーターのスコープ

パイプラインパラメーターは、それらが宣言されている .circleci/config.yml 内でのみ扱うことができます。 .circleci/config.yml でローカルに宣言された Orb を含め、Orb ではパイプラインパラメーターを使用できません。これは、パイプラインのスコープを Orb 内で使用するとカプセル化が崩れ、Orb と呼び出し側の設定ファイルの間に強い依存関係が生まれ、決定論的動作が損なわれ脆弱性が攻撃される領域が作られてしまう可能性があるためです。

要素パラメーターのスコープ

要素パラメーターは字句スコープをとるため、ジョブ、コマンド、Executor などで定義されている要素の範囲内に収まります。下の例のように、パラメーターを持つ要素がパラメーターを持つ別の要素を呼び出す場合、内側の要素は呼び出し元の要素のスコープを継承しません。

version: 2.1

commands:
  print:
    parameters:
      message:
        type: string
    steps:
      - run: echo << parameters.message >>

jobs:
  daily-message:
    machine: true
    parameters:
      message:
        type: string
    steps:
      - print:
          message: Printing << parameters.message >>

workflows:
  my-workflow:
    jobs:
      - daily-message:
         message: echo << parameters.message >>

cat-file ジョブから print コマンドを呼び出しても、file パラメーターのスコープは print コマンド内には及びません。これにより、すべてのパラメーターが常に有効な値にバインドされ、使用可能なパラメーターが常に認識されます。これを実行すると、Arguments referenced without declared parameters: message というパイプラインエラーが発生します。

パイプライン値のスコープ

パイプライン値、つまり CircleCI が提供するパイプライン内で使用できる値 (例: << pipeline.number >> ) は、常にスコープ内で有効です。

パイプラインパラメーターのスコープ

設定ファイル内で定義されているパイプラインパラメーターは常にスコープ内で有効ですが、2 つの例外があります。

パイプラインパラメーターは、他のパイプラインパラメーターの定義の範囲内では有効でないため、相互に依存させることはできません。
データ漏えいを防ぐために、パイプラインパラメーターは Orb 本体、Orb のインラインの範囲内では有効ではありません。

条件付きワークフロー

ワークフロー宣言の下でロジックステートメントと一緒に when clause 句（または逆の unless 句）を使用すると、そのワークフローを実行するかどうかを判断できます。 when や unless のロジックステートメントにより値の真偽を評価します。

この設定の最も一般的な活用方法は、値としてパイプラインパラメーターを使用し、API トリガーでそのパラメーターを渡して、実行するワークフローを決定できるようにすることです。以下の設定例では、パイプラインパラメーター 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:
  mytestjob:
    steps:
      - checkout
      - ... # job steps

上記の例では、以下のように 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.