このページでは、ペイロード バインディングの使い方と、ビルドトリガーに関連付けられた置換変数に bash パラメータの拡張を適用する方法について説明します。ビルド構成で置換変数を使用する方法については、変数値の置換をご覧ください。
Cloud Build を使用すると、トリガーのイベント ペイロードの一部を置換変数として保存できます。イベント ペイロードは、トリガーを呼び出すイベントの本文です。ペイロードに関連付けられた変数はバインディングと呼ばれ、push イベントと pull イベントの両方によって呼び出されるビルドで使用できます。バインディングを使用すると、ソースコードに関連付けられた言語や pull リクエストの作成者など、ビルドに関連する追加データにアクセスできます。
また Cloud Build では、bash パラメータの拡張を置換変数の値に適用できます。bash パラメータの拡張では、既存の変数に関連付けられた文字列を操作できます。大文字への変換や部分文字列の置換により、文字列を操作できます。
Google Cloud Console と Cloud Build 構成ファイルでビルドトリガーを定義または更新する場合、ペイロード バインディングを使用して bash パラメータの拡張を適用できます。また、手動ビルドの実行時に bash パラメータの拡張を適用できます。
ペイロード バインディング
トリガーのイベント ペイロードの一部を置換変数値として保存できます。ペイロード バインディングは、push イベントと pull イベントによって呼び出されるビルドの変数値として使用でき、ソースコードが GitHub リポジトリまたは Cloud Source Repositories にある場合、JSON ペイロードにアクセスするために使用できます。GitHub イベント ペイロードの詳細については、Webhook イベント ペイロードをご覧ください。Cloud Source Repositories のイベント ペイロードの詳細については、Cloud Source Repositories の通知をご覧ください。
イベント ペイロードの情報にアクセスするには、イベント ペイロードのルートを表す接頭辞を指定します。接頭辞から始めて、JSONPath 構文を使用して、ペイロードにアクセスし、そこからデータを pull できます。イベントタイプに応じて、次のペイロードの接頭辞を使用できます。
接頭辞 | ソース | 説明 |
---|---|---|
push |
GitHub | push イベントの JSON ペイロード内のフィールドへのアクセスを可能にする |
pull_request |
GitHub | pull リクエス トイベントの JSON ペイロード内のフィールドへのアクセスを可能にする |
issue_comment |
GitHub | pull リクエストに関連する問題のコメント イベントの JSON ペイロード内のフィールドへのアクセスを可能にする |
csr |
Cloud Source Repositories | push イベントの JSON ペイロード内のフィールドへのアクセスを可能にする |
GitHub アプリに関連付けられているイベントについては、組み込み変数の値 is_collaborator
と perm_level
も使用できます。push および pull イベントのユーザーのステータスは、変数値 push.pusher.name
、pull_request.pull_request.user.login
、issue_comment.comment.user.login
によってチェックされます。次の表は、ソースコードが GitHub にある場合に、これらをトリガーの変数値として含める方法を示しています。
変数の名前 | 変数の値 | 変数の説明 |
---|---|---|
_PERM_LEVEL |
$(perm_level) |
ユーザーの権限レベルを取得する |
_IS_COLLABORATOR |
$(is_collaborator) |
ユーザーが共同編集者の場合、true を出力する |
変数値 is_collaborator
と perm_level
は、push イベント、pull リクエスト イベント、コメントによってゲートされる pull リクエスト イベントに使用できます。これらの変数値の前に接頭辞を付ける必要はありません。
ペイロード バインディングを使用した置換の作成
ペイロード バインディングを使用する置換変数を作成するには:
[トリガー] ページを開きます。
ビルドトリガーを作成していない場合は、[トリガーを作成] をクリックします。それ以外の場合は、既存のトリガーを選択します。
[代入変数] で [変数を追加] をクリックします。
以下の規則に従って、変数の名前を追加します。
置換はアンダースコア(
_
)で始まり、大文字と数字のみを使用する必要があります(正規表現[A-Z0-9_]+
に従います)。こうすると、組み込み置換と競合しなくなります。パラメータの数は 100 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。
ユーザー定義の置換を定義して使用する方法の詳細については、ユーザー定義の置換の使用をご覧ください。
サポートされている接頭辞を使用して、変数の値を追加します。
ソースコードが GitHub にある場合は、ペイロード バインディングを使用して置換変数内でイベント ペイロードの情報を参照できます。push イベントの JSON ペイロードにアクセスするには、接頭辞
push
またはbody
を使用します。次の例では、変数値のpush
接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。変数の名前 変数の値 変数の説明 _PUSH_NAME
$(push.repository.name)
push イベントに関連付けられたリポジトリの名前を取得する _COMMITS
$(push.commits)
push された各 commit を表す commit オブジェクトの配列を取得する _OWNER
$(push.repository.owner.name)
リポジトリ オーナーの名前を取得する _URL
$(push.repository.html_url)
GitHub リポジトリの URL を取得する _LANGUAGE
$(push.repository.language)
push に含まれるソースコードの言語を取得する push
接頭辞を使用してアクセスできるフィールドのリストについては、PushEvent
をご覧ください。pull リクエスト イベントの JSON ペイロードにアクセスするには、接頭辞
pull_request
またはbody
を使用します。次の例では、変数値のpull_request
接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。変数の名前 変数の値 変数の説明 _PULL_REQUEST_ID
$(pull_request.pull_request.id)
pull リクエストの ID を取得する _PULL_REQUEST_TITLE
$(pull_request.pull_request.title)
pull リクエストのタイトルを取得する _PULL_REQUEST_BODY
$(pull_request.pull_request.body)
pull リクエストの本文を取得する _USERNAME
$(pull_request.pull_request.user.login)
pull リクエストの送信者のユーザー名を取得する _MERGE_TIME
$(pull_request.pull_request.merged_at)
pull リクエストがマージされた時刻を取得する pull_request
接頭辞を使用してアクセスできるフィールドのリストについては、PullRequestEvent
をご覧ください。commit イベントの JSON ペイロードにアクセスするには、接頭辞
commit
を使用します。次の例では、変数値のcommit
接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。変数の名前 変数の値 変数の説明 _COMMIT_URL
$(commit.url)
commit に関連付けられている URL を取得します。 _COMMIT_USER
$(commit.author.login)
commit の作成者のユーザー名を取得します。 _COMMIT_MESSAGE
$(commit.commit.message)
commit に関連付けられている commit メッセージを取得します。 _COMMIT_DATE
$(commit.commit.committer.date)
commit に関連付けられている日付を取得します。 _COMMIT_ADDITIONS
$(commit.files['*'].additions)
commit 内のファイルに関連付けられている追加の数を取得します。 commit
接頭辞を使用してアクセスできるフィールドのリストについては、commit の取得をご覧ください。pull リクエストによって呼び出されるトリガーのコメント制御を有効にすると、トリガーを呼び出すイベントは
IssueCommentEvent
になり、関連付けられた接頭辞はissue_comment
になります。次の例では、変数値のissue_comment
接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。変数の名前 変数の値 変数の説明 _PULL_REQUEST_ID
$(issue_comment.issue.id)
pull リクエストの ID を取得する _PULL_REQUEST_TITLE
$(issue_comment.issue.title)
pull リクエストのタイトルを取得する _STATE
$(issue_comment.state)
pull リクエストの状態(オープン、クローズなど)を取得する _LABELS
$(issue_comment.issue.labels)
pull リクエストに関連付けられたラベルのリストを取得する _LABELS_URL
$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)
説明に一致するラベルに関連付けられた URL を取得する issue_comment
接頭辞を使用してアクセスできるフィールドのリストについては、IssueCommentEvent
をご覧ください。ソースコードが Cloud Source Repositories にある場合は、ペイロード バインディングを使用して置換変数内でイベント ペイロードの情報を参照できます。push イベントの JSON ペイロードにアクセスするには、接頭辞
csr
またはbody
を使用します。次の例では、変数値のcsr
接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。変数の名前 変数の値 変数の説明 _REPO_NAME
$(csr.name)
リポジトリの名前を取得します _REPO_URL
$(csr.url)
リポジトリの URL を取得します _CREATED_REPO
$(csr.createRepoEvent)
ユーザーがリポジトリを作成したかどうかを示します _REF_EVENT_NAME
$(csr.refUpdateEvent.refUpdates['*'].refName)
参照の名前(refs/heads/primary-branch など) Cloud Source Repositories でアクセスできるその他のフィールドについては、通知データをご覧ください。
bash パラメータの拡張
デフォルト変数とユーザー定義変数に bash パラメータの拡張を適用できます。サポートされている操作には、部分文字列の置換、文字列のスライス、大文字への変換などがあります。たとえば、デフォルト変数の部分文字列を置き換えて、その変数をイメージタグとして使用できます。
置換変数に指定できる bash パラメータの拡張は次のとおりです。
bash の拡張 | 説明 |
---|---|
${var} |
var に保存されている文字列値を展開します。 |
${var^} |
文字列の最初の文字を大文字にする |
${var^^} |
文字列内のすべての文字を大文字にする |
${var,} |
文字列の最初の文字を小文字にする |
${var,,} |
文字列内のすべての文字を小文字にする |
${var:position} |
文字列の最初の position 文字を削除する |
${var:position:length} |
position で指定された数値で始まる文字列をスライスし、length で指定された数値まで含める |
${var/substring/replacement} |
substring で指定された値の左端のインスタンスを replacement で指定された値に置き換える |
${var//substring/replacement} |
substring で指定された値のすべてのインスタンスを replacement に指定された値に置き換える |
${var/#substring/replacement} |
substring が var の接頭辞の場合にのみ、substring で指定された値の最初のインスタンスを replacement で指定された値に置き換える |
${var/%substring/replacement} |
substring が var の接尾辞の場合にのみ、substring で指定された値の最初のインスタンスを replacement で指定された値に置き換える |
${#var} |
文字列の長さを取得する |
${var:-default} |
var が定義されている場合を除き、var を default と評価する |
次の bash パラメータの拡張に一致するパターンを指定することもできます。
bash の拡張 | 説明 |
---|---|
${var#pattern} |
指定された pattern の左端のインスタンス(このインスタンスも含む)まで、文字列の左側から文字を削除する |
${var##pattern} |
指定された pattern の右端のインスタンス(このインスタンスも含む)まで、文字列の左側から文字を削除する |
${var%pattern} |
指定された pattern の最初のインスタンス(このインスタンスも含む)まで、文字列の右側から文字を削除する |
${var%%pattern} |
指定された pattern の左端のインスタンス(このインスタンスも含む)まで文字列の右側から文字を削除する |
指定できるパターンには次のものがあります。
パターン | 説明 |
---|---|
* |
ゼロ個以上の英数字と一致します |
? |
任意の 1 個の英数字と一致します |
[ccc] |
ccc 内の任意の 1 文字と一致します(a-z または 0-9 の間の範囲を含む) |
[^c] |
c にない英数字文字に一致します(lo <= c <= hi の範囲を含む) |
c |
任意の英数字(c )と一致します |
\c |
* 、? 、\ などの英数字以外の文字を含む任意の文字(c )と一致します |
bash パラメータの拡張を適用する
組み込みまたはユーザー定義の置換変数に bash パラメータの拡張を適用するには:
[トリガー] ページを開きます。
ビルドトリガーを作成していない場合は、[トリガーを作成] をクリックします。それ以外の場合は、既存のトリガーを選択します。
[代入変数] で [変数を追加] をクリックします。
以下の規則に従って、変数の名前を追加します。
置換はアンダースコア(
_
)で始まり、大文字と数字のみを使用する必要があります(正規表現[A-Z0-9_]+
に従います)。こうすると、組み込み置換と競合しなくなります。パラメータの数は 100 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。
ユーザー定義の置換を定義して使用する方法の詳細については、ユーザー定義の置換の使用をご覧ください。
変数の値を追加して、サポートされている bash パラメータの拡張を組み込み置換変数または別のユーザー定義の置換変数に適用します。
次の例では、組み込み置換変数
$BRANCH_NAME
にデフォルト値のFeature_Secret_Project_#v2
が設定されています。次の表は、$BRANCH_NAME
に適用できる bash パラメータの拡張の例を示しています。変数の名前 bash の拡張 変数の値 説明 _BRANCH_LOWERCASE
${$BRANCH_NAME,,}
feature_secret_project_#v2
文字列内のすべての文字を小文字にする _BRANCH_NO_SUFFIX
${_BRANCH_LOWERCASE%_\#v2}
feature_secret_project
指定したパターンと一致する文字列の右側にあるすべての文字を削除する _BRANCH_NO_PREFIX
${_BRANCH_NO_SUFFIX#*_}
secret_project
最初のアンダースコアまでのすべての文字を削除する _BRANCH_FOR_IMAGE_NAME
${_BRANCH_NO_PREFIX//_/-}
secret-project
すべてのアンダースコアをダッシュに置き換える _IMAGE_NAME
my-app-${_BRANCH_FOR_IMAGE_NAME}-prod
my-app-secret-project-prod
上記で定義した _BRANCH_FOR_IMAGE_NAME
変数を使用してイメージの名前を作成する_IMAGE_NAME
は、上記の表my-app-secret-project-prod
で指定された値としてトリガーで定義されています。この値は、ビルド構成ファイル内の_IMAGE_NAME
の定義をすべてオーバーライドします。次の例では、_IMAGE_NAME
(my-app-secret-project-prod
)に指定された変数値が、ビルドトリガーが呼び出されたときに_IMAGE_NAME
(test-image
)のデフォルト値を置き換えます。YAML
steps: - name: 'gcr.io/cloud-builders/docker' args: ['build', '-t', 'gcr.io/$PROJECT_ID/${_IMAGE_NAME}', '.'] substitutions: _IMAGE_NAME: test-image #default value images: [ 'gcr.io/$PROJECT_ID/${_IMAGE_NAME}' ] options: dynamicSubstitutions: true
JSON
{ 'steps': [ { 'name': 'gcr.io/cloud-builders/docker', 'args': [ 'build', '-t', 'gcr.io/$PROJECT_ID/${_IMAGE_NAME}', '.' ] } ], 'substitutions': { '_IMAGE_NAME': 'test-image' #default value }, 'images': [ 'gcr.io/$PROJECT_ID/${_IMAGE_NAME}' ], "options": { "dynamic_substitutions": true } }
上記の例で dynamicSubstitutions
フィールドを true
に設定すると、bash パラメータの拡張を解釈できます。トリガーによってビルドが呼び出された場合、dynamicSubstitutions
フィールドは常に true
に設定され、ビルド構成ファイルで指定する必要はありません。ビルドを手動で呼び出す場合、ビルドの実行時に bash パラメータの拡張が解釈されるようにするには、dynamicSubstitutions
フィールドを true
に設定する必要があります。
ペイロード バインディングで bash パラメータの拡張を使用する
バインディングを含む変数を参照する新しい変数を作成するか、バインディングを bash パラメータの拡張とともに文字列化することで、ペイロード バインディングに関連付けられた変数に bash パラメータの拡張を適用できます。次の表は、ペイロード バインディングで bash パラメータの拡張をどのように使用できるかの例を示しています。
変数の名前 | 変数の値 | 変数の説明 |
---|---|---|
_URL |
$(push.repository.html_url) |
リポジトリの URL を取得する |
_URL_CAPITAL |
${_URL^^} |
bash パラメータの拡張を使用して URL 内のすべての文字を大文字にする |
_APP_NAME |
my-app-${_URL_CAPITAL} |
リポジトリの大文字に変換された URL に接頭辞を追加する |
APP_NAME_ID |
my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7} |
リポジトリ URL とペイロード ID の最初の 7 文字を含むアプリケーション名を作成する |
次のステップ
- 変数値を置換する方法を学習する。
- 基本的なビルド構成ファイルを作成する方法を学習する。
- ビルドトリガーを作成および管理する方法を学習する。
- 手動でビルドを実行する方法を学習する。