substitutions
は、ビルド時に特定の変数を置き換える場合にビルド構成ファイルの中で使用します。
置換はビルド時まで値が不明な変数を設定する場合や、既存のビルド リクエストを別の変数値で再利用する場合に役立ちます。
Cloud Build には組み込みの置換が用意されていますが、独自の置換を定義することもできます。ビルド時に値を解決するには、ビルドの steps
と images
に substitutions
を使用します。
このページでは、デフォルトの置換を使用する方法や独自の substitutions
を定義する方法について説明します。
デフォルトの置換の使用
Cloud Build では、すべてのビルドを対象に次のデフォルトの置換が用意されています。
$PROJECT_ID
: Cloud プロジェクトの ID$BUILD_ID
: ビルドの ID$PROJECT_NUMBER
: プロジェクトの番号$LOCATION
: ビルドに関連付けられたリージョン
Cloud Build では、トリガーによって呼び出されるビルドを対象に次のデフォルトの置換が用意されています。
$TRIGGER_NAME
: トリガーに関連付けられた名前$COMMIT_SHA
: ビルドに関連付けられた commit ID$REVISION_ID
: ビルドに関連付けられた commit ID$SHORT_SHA
:COMMIT_SHA
の最初の 7 文字$REPO_NAME
: リポジトリの名前$BRANCH_NAME
: ブランチの名前$TAG_NAME
: タグの名前$REF_NAME
: ブランチまたはタグの名前$TRIGGER_BUILD_CONFIG_PATH
: ビルドの実行中に使用されるビルド構成ファイルへのパス。それ以外の場合は、ビルドがインラインでトリガーに構成された場合、Dockerfile
またはBuildpack
を使用する場合は空の文字列。
Cloud Build では、pull リクエスト トリガーに使用する GitHub 固有のデフォルトの置換を以下のように用意しています。
$_HEAD_BRANCH
: pull リクエストのヘッドブランチ$_BASE_BRANCH
: pull リクエストのベースブランチ$_HEAD_REPO_URL
: pull リクエストのヘッド リポジトリの URL$_PR_NUMBER
: pull リクエストの数
デフォルトの置換が利用できない場合は(ソースがないビルドや、ストレージ ソースを使用しているビルドなど)、置換されなかった不明な変数が空の文字列に置き換えられます。
gcloud builds submit
を使用してビルドを開始するとき、--substitutions
引数を使用して、トリガーされたビルドから通常取得する変数を指定できます。具体的には、次の値を手動で指定できます。
$TRIGGER_NAME
$COMMIT_SHA
$REVISION_ID
$SHORT_SHA
$REPO_NAME
$BRANCH_NAME
$TAG_NAME
$REF_NAME
$TRIGGER_BUILD_CONFIG_PATH
たとえば、次のコマンドでは TAG_NAME
置換を使用しています。
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=TAG_NAME="test"
次の例では、デフォルトの置換 $BUILD_ID
、$PROJECT_ID
、$PROJECT_NUMBER
、$REVISION_ID
を使用しています。
YAML
steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
args: ['bash', './myscript.sh']
env:
- 'BUILD=$BUILD_ID'
- 'PROJECT_ID=$PROJECT_ID'
- 'PROJECT_NUMBER=$PROJECT_NUMBER'
- 'REV=$REVISION_ID'
# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.']
# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/my-image'
JSON
{
"steps": [{
"name": "ubuntu",
"args": [
"bash",
"./myscript.sh"
],
"env": [
"BUILD=$BUILD_ID",
"PROJECT_ID=$PROJECT_ID",
"PROJECT_NUMBER=$PROJECT_NUMBER",
"REV=$REVISION_ID"
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
}],
"images": [
"gcr.io/$PROJECT_ID/my-image"
]
}
次の例に、docker
ビルドステップを使用してイメージを作成し、デフォルトの $PROJECT_ID
置換を使用して Container Registry にイメージを push するビルド リクエストを示します。
この例では、
- ビルド リクエストのビルドステップは 1 つで、
gcr.io/cloud-builders
のdocker
ビルドステップを使用して Docker イメージをビルドします。- ステップ内の
args
フィールドはdocker
コマンドに渡す引数を指定します。この場合は、build -t gcr.io/my-project/cb-demo-img .
が呼び出されます($PROJECT_ID
がプロジェクト ID に置き換えられた後)。
- ステップ内の
images
フィールドにはイメージの名前が含まれます。ビルドが成功すると、ビルドされたイメージは Container Registry に push されます。イメージがビルドによって正常に作成されていない場合、ビルドは失敗します。
YAML
steps:
- name: gcr.io/cloud-builders/docker
args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
}],
"images": [
"gcr.io/$PROJECT_ID/cb-demo-img"
]
}
ユーザー定義の置換の使用
独自の置換を定義することもできます。ユーザー定義の置換は、次のルールに従う必要があります。
- 置換はアンダースコア(
_
)で始まり、大文字と数字のみを使用する必要があります(正規表現_[A-Z0-9_]+
に従います)。こうすると、組み込み置換と競合しなくなります。$
で始まる式を使用するには、$$
を使用する必要があります。つまり、$FOO
は組み込み置換ではないため、無効です。$$FOO
はリテラル文字列$FOO
と評価されます。
- パラメータの数は 100 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。
変数は、$_FOO
または ${_FOO}
のいずれかで指定できます。
$_FOO
と${_FOO}
はどちらも_FOO
の値に評価されます。ただし、${}
を使用すると、スペースで囲わずに置換を実行できます。これにより、${_FOO}BAR
のような置換が可能になります。$$
では、テンプレートにリテラル$
を含めることができます。つまり、$_FOO
は_FOO
の値と評価されます。$$_FOO
はリテラル文字列$_FOO
と評価されます。$$$_FOO
は、_FOO
の値が後に続くリテラル文字$
と評価されます。
置換を使用するには、gcloud
コマンドで --substitutions
引数を使用するか、構成ファイルで置換を指定します。
次の例に、_NODE_VERSION_1
と _NODE_VERSION_2
という 2 つのユーザー定義の置換があるビルド構成を示します。
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_1}',
'-t',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
'.']
- name: 'gcr.io/cloud-builders/docker'
args: ['build',
'--build-arg',
'node_version=${_NODE_VERSION_2}',
'-t',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
'.']
substitutions:
_NODE_VERSION_1: v6.9.1 # default value
_NODE_VERSION_2: v6.9.2 # default value
images: [
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]
JSON
{
"steps": [{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_1}",
"-t",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
"."
]
}, {
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"--build-arg",
"node_version=${_NODE_VERSION_2}",
"-t",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
"."
]
}],
"substitutions": {
"_NODE_VERSION_1": "v6.9.1"
"_NODE_VERSION_1": "v6.9.2"
},
"images": [
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
"gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
]
}
ビルド構成ファイルで指定した置換値をオーバーライドするには、gcloud builds submit
コマンドの --substitutions
フラグを使用します。置換は、配列やシーケンスではなく、値への変数のマッピングであることに注意してください。$PROJECT_ID
と $BUILD_ID
以外のデフォルトの置換変数値をオーバーライドできます。次のコマンドは、上記のビルド構成ファイルで指定されている _NODE_VERSION_1
のデフォルト値をオーバーライドします。
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .
デフォルトでは、置換変数や置換がない場合、ビルドでエラーが返されます。ただし、ALLOW_LOOSE
オプションを設定すると、このチェックをスキップできます。
次のスニペットは「hello world」を出力し、未使用の置換を定義します。
ALLOW_LOOSE
置換オプションが設定されているため、置換が欠落していてもビルドは成功します。
YAML
steps:
- name: 'ubuntu'
args: ['echo', 'hello world']
substitutions:
_SUB_VALUE: unused
options:
substitution_option: 'ALLOW_LOOSE'
JSON
{
"steps": [
{
"name": "ubuntu",
"args": [
"echo",
"hello world"
]
}
],
"substitutions": {
"_SUB_VALUE": "unused"
},
"options": {
"substitution_option": "ALLOW_LOOSE"
}
}
ビルドがトリガーによって呼び出される場合は、デフォルトで ALLOW_LOOSE
オプションが設定されます。この場合、置換変数または置換が欠落しているとビルドはエラーを返しません。トリガーによって呼び出されたビルドの ALLOW_LOOSE
オプションをオーバーライドすることはできません。
ALLOW_LOOSE
オプションを指定しなければ、置換マッピングまたはビルド リクエストに一致しないキーがある場合にエラーが発生します。たとえば、ビルド リクエストに $_FOO
が含まれていて、置換マッピングで _FOO
が定義されていない場合、ビルドを実行した後またはトリガーが起動した後にトリガーに置換変数が含まれていれば、にエラーが発生します。
以下の置換変数には、ALLOW_LOOSE
オプションを設定しなくても、常にデフォルトの空の文字列値が含まれます。
$REPO_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA
置換変数を定義するときは、静的な文字列に制限されません。また、トリガーを呼び出したイベント ペイロードにアクセスすることもできます。これらはペイロード バインディングとして使用できます。また、置換変数に bash パラメータの拡張を適用し、結果の文字列を新しい置換変数として保存することもできます。詳しくは、ペイロード バインディングと bash パラメータの拡張を置換で使用するをご覧ください。
動的置換
ビルド構成ファイルで dynamic_substitutions
オプションを true
に設定すると、ユーザー定義の置換内の別の変数の値を参照できます。トリガーによってビルドが呼び出された場合、dynamic_substitutions
フィールドは常に true
に設定され、ビルド構成ファイルで指定する必要はありません。ビルドを手動で呼び出す場合、ビルドの実行時に bash パラメータの拡張が解釈されるようにするには、dynamic_substitutions
フィールドを true
に設定する必要があります。
次のビルド構成ファイルは、変数 ${PROJECT_ID}
を参照する置換変数 ${_IMAGE_NAME}
を示しています。dynamic_substitutions
フィールドは true
に設定されているため、参照はビルドを手動で呼び出すときに適用されます。
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
_IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
dynamic_substitutions: true
JSON
{
"steps": [
{
"name": "gcr.io/cloud-builders/docker",
"args": [
"build",
"-t",
"${_IMAGE_NAME}",
"."
]
}
],
"substitutions": {
"_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image"
},
"options": {
"dynamic_substitutions": true
}
}
詳細については、bash パラメータの拡張を適用するをご覧ください。
次のステップ
- ペイロード バインディングと bash パラメータの拡張を置換で使用する方法を学習する。
- 基本的なビルド構成ファイルを作成する方法を学習する。
- ビルドトリガーを作成および管理する方法を学習する。
- Cloud Build でビルドを手動で実行する方法を学習する。