在构建配置文件中使用 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
:与您的构建关联的提交 ID$REVISION_ID
:与您的构建关联的提交 ID$SHORT_SHA
:COMMIT_SHA
的前七个字符$REPO_NAME
:代码库的名称$REPO_FULL_NAME
:代码库的完整名称,包括用户或组织$BRANCH_NAME
:您的分支名称$TAG_NAME
:您的标记名称$REF_NAME
:您的分支或标记的名称$TRIGGER_BUILD_CONFIG_PATH
:构建执行期间使用的 build 配置文件的路径;否则,如果构建在触发器上以内嵌方式配置或使用Dockerfile
或Buildpack
,则为空字符串。$SERVICE_ACCOUNT_EMAIL
:您用于构建的服务帐号的电子邮件地址。此服务帐号可以是默认服务帐号,也可以是用户指定的服务帐号。$SERVICE_ACCOUNT
:服务帐号的资源名称,格式为projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL
Cloud Build 提供以下特定于 GitHub 的默认替代变量,用于拉取请求触发器:
$_HEAD_BRANCH
:拉取请求的标头分支$_BASE_BRANCH
:拉入请求的基本分支$_HEAD_REPO_URL
:拉取请求的标头代码库网址$_PR_NUMBER
:拉取请求编号
如果默认替代变量不可用(例如无源构建或使用存储源的构建),则会使用空字符串替换出现的缺失变量。
使用 gcloud builds submit
启动构建时,您可以使用 --substitutions
参数指定通常来自触发构建的变量。具体来说,您可以手动提供以下变量的值:
$TRIGGER_NAME
$COMMIT_SHA
$REVISION_ID
$SHORT_SHA
$REPO_NAME
$REPO_FULL_NAME
$BRANCH_NAME
$TAG_NAME
$REF_NAME
$TRIGGER_BUILD_CONFIG_PATH
$SERVICE_ACCOUNT_EMAIL
$SERVICE_ACCOUNT
例如,以下命令使用 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:
在此示例中:
- 构建请求有一个构建步骤,该步骤使用
gcr.io/cloud-builders
中的docker
构建步骤来构建 Docker 映像。- 该步骤中的
args
字段指定传递给docker
命令的参数,在此示例中,系统将调用build -t gcr.io/my-project/cb-demo-img .
(使用您的项目 ID 替换$PROJECT_ID
后)。
- 该步骤中的
images
字段包含映像的名称。如果构建成功,则生成的映像将推送到 Container Registry。如果构建未成功创建映像,则构建将失败。
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
。
- 参数的数量上限为 200 个。参数键的长度上限为 100 个字节,参数值的长度上限为 4000 个字节。
您可以使用以下两种方式之一来指定变量:$_FOO
或 ${_FOO}
:
$_FOO
和${_FOO}
计算结果均为_FOO
的值。但是,${}
允许替代变量在两侧都没有空格的情况下也能够起作用,这意味着允许使用${_FOO}BAR
等替代变量。$$
允许您在模板中包含文字$
。因此:$_FOO
计算结果为_FOO
。$$_FOO
计算结果为文字字符串$_FOO
。$$$_FOO
计算结果为文字字符串$
,后跟_FOO
的值。
如需使用替代变量,请在 gcloud
命令中使用 --substitutions
参数,或在配置文件中指定替代变量。
以下示例演示了一个构建配置,其中包含两个用户定义的替代变量,分别名为 _NODE_VERSION_1
和 _NODE_VERSION_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:
substitutionOption: '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
$REPO_FULL_NAME
$BRANCH_NAME
$TAG_NAME
$COMMIT_SHA
$SHORT_SHA
定义替代变量时,您并非只能使用静态字符串。您还可以访问调用触发器的事件载荷。这些载荷可作为载荷绑定使用。您还可以对替代变量应用 bash 参数扩展,并将生成的字符串存储为新的替代变量。如需了解详情,请参阅在替代中使用载荷绑定和 bash 参数扩展。
动态替代
您可以通过将构建配置文件中的 dynamicSubstitutions
选项设置为 true
来引用用户定义的替代变量中另一个变量的值。如果由触发器调用您的构建,则 dynamicSubstitutions
字段始终设置为 true
,无需在构建配置文件中指定。如果是手动调用您的构建,则必须将 dynamicSubstitutions
字段设置为 true
,以便在运行构建时解读 bash 参数扩展。
以下构建配置文件显示了引用变量 ${PROJECT_ID}
的替代变量 ${_IMAGE_NAME}
。dynamicSubstitutions
字段设置为 true
,因此将在手动调用构建时应用引用:
YAML
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
_IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
dynamicSubstitutions: 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 参数扩展。
将替代变量映射到环境变量
脚本不直接支持替换,但支持环境变量。您可以将替换项映射到环境变量,可以一次性自动映射到环境变量,也可以通过自行定义每个环境变量来手动映射。
自动替换映射
在 build 级别。如需自动将所有替代变量映射到在整个构建过程中都会使用的环境变量,请在构建级别将
automapSubstitutions
设置为true
选项。例如,以下构建配置文件显示了用户定义的替代变量$_USER
和映射到环境变量的默认替代变量$PROJECT_ID
:YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" options: automapSubstitutions: true substitutions: _USER: "Google Cloud"
JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'" } ], "options": { "automap_substitutions": true }, "substitutions": { "_USER": "Google Cloud" } }
在步骤级别。如需自动映射所有替代变量,并在一个步骤中将它们作为环境变量提供,请在该步骤中将
automapSubstitutions
字段设置为true
。在以下示例中,只有第二步将正确显示替换内容,因为它是唯一启用了自动替换映射的步骤:YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: true substitutions: _USER: "Google Cloud"
JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": true } ], }, "substitutions": { "_USER": "Google Cloud" }
此外,您可以将替代变量作为环境变量在整个构建中使用,然后在一个步骤中忽略它们。在构建级别将
automapSubstitutions
设置为true
,然后在要忽略替代步骤的步骤中将同一字段设置为false
。在以下示例中,即使在构建级别启用了映射替换,也不会在第二步输出项目 ID,因为在该步骤中将automapSubstitutions
设置为false
:YAML
steps: - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Hello $_USER" - name: 'ubuntu' script: | #!/usr/bin/env bash echo "Your project ID is $PROJECT_ID" automapSubstitutions: false options: automapSubstitutions: true substitutions: _USER: "Google Cloud"
JSON
{ "steps": [ { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Hello $_USER'" }, { "name": "ubuntu", "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'", "automap_substitutions": false } ], "options": { "automap_substitutions": true }, }, "substitutions": { "_USER": "Google Cloud" }
手动替换映射
您可以手动将替换内容映射到环境变量。每个环境变量都是使用 env
字段在步骤级别定义的,并且变量的作用域仅限于定义它们的步骤。此字段采用键和值列表。
以下示例展示了如何将替代项 $PROJECT_ID
映射到环境变量 BAR
:
YAML
steps:
- name: 'ubuntu'
env:
- 'BAR=$PROJECT_ID'
script: 'echo $BAR'
JSON
{
"steps": [
{
"name": "ubuntu",
"env": [
"BAR=$PROJECT_ID"
],
"script": "echo $BAR"
}
]
}
后续步骤
- 了解如何在替代变量中使用载荷绑定和 bash 参数扩展。
- 了解如何创建基本构建配置文件。
- 了解如何创建和管理构建触发器。
- 了解如何在 Cloud Build 中手动运行构建。