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

1+ year ago2 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI 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(40文字)

pipeline.git.base_revision

GitHub, Bitbucket

文字列

現在ビルドしているものより前のビルドの長い git SHA (40 文字) 注: 多くの場合、pipeline.git.base_revision は、現在実行しているパイプラインより前のパイプラインを実行する SHA ですが、いくつか注意事項があります。 ブランチの最初のビルドの場合、変数は表示されません。 また、ビルドが API からトリガーされた場合も変数は表示されません。

pipeline.trigger_source

GitHub, Bitbucket

文字列

パイプラインをトリガーするソース、現在の値は webhookapischeduled_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-tagworkingdir) が設定ファイルの一番上で定義され、後続の 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 キーを渡します。

注: この POSTparameters キーを渡すリクエストは、シークレットではありませんのでご注意ください。

下の例では、上記の設定ファイルの例で説明したパラメーターを使用して、パイプラインをトリガーしています (注: パイプラインをトリガーするコマンドを実行したときに、設定ファイルでパラメータが宣言されていない場合、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)`というエラーが表示されます)。

  1. プロジェクトのフィルタリング機能を使ってプロジェクトを選択します。

  2. ブランチのフィルタリング機能を使って新しいパイプラインを実行するブランチを選択します。

  3. Trigger Pipeline ボタンをクリックします (ページの右上隅)。

  4. Add Parameters ドロップダウンを使って、パラメーターのタイプ、名前、値を指定します。

  5. 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` 句もあり、条件の真偽を逆に指定できます。