替换变量值

在构建配置文件中使用 substitutions 以在构建时替代特定变量。

对于那些直到构建时才知道值的变量,或者使用不同的变量值重用现有构建请求,替代变量很有用。

Cloud Build 提供内置替代变量,您也可以定义自己的替代变量。在构建的 stepsimages 中使用 substitutions 可在构建时解析它们的值。

本页面介绍了如何使用默认替代变量或者定义自己的 substitutions

使用默认替代变量

Cloud Build 为所有构建提供以下默认替代变量:

  • $PROJECT_ID:您的 Cloud 项目的 ID
  • $BUILD_ID:您的构建的 ID

Cloud Build 为触发器调用的构建提供以下默认替代变量:

  • $COMMIT_SHA:与您的构建关联的提交 ID
  • $REVISION_ID:与您的构建关联的提交 ID。
  • $SHORT_SHACOMMIT_SHA 的前七个字符
  • $REPO_NAME:代码库的名称
  • $BRANCH_NAME:您的分支名称
  • $TAG_NAME:您的标记名称

Cloud Build 提供适用于拉取请求且特定于 GitHub 的以下默认替代变量:

  • $_HEAD_BRANCH:拉取请求的标头分支
  • $_BASE_BRANCH:拉入请求的基本分支
  • $_HEAD_REPO_URL:拉取请求的标头代码库网址
  • $_PR_NUMBER:拉取请求编号

如果默认替代变量不可用(例如无源构建或使用存储源的构建),则会使用空字符串替换出现的缺失变量。

使用 gcloud builds submit 启动构建时,您可以使用 --substitutions 参数指定通常来自触发构建的变量。具体来说,您可以手动提供以下变量的值:

  • $COMMIT_SHA
  • $REVISION_ID
  • $SHORT_SHA
  • $REPO_NAME
  • $BRANCH_NAME
  • $TAG_NAME

例如,以下命令使用 TAG_NAME 替代变量:

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

以下示例使用默认替代变量 $BUILD_ID$PROJECT_ID$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=$PROJECT_ID'
  - '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=$PROJECT_ID",
        "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
  • 参数数量的上限为 100 个。参数键的长度上限为 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:
    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 时,如果您的触发器包含替代变量,则在运行构建或调用触发器后,您将收到错误。

定义替代变量时,您并非只能使用静态字符串。您还可以访问调用触发器的事件载荷。这些载荷可作为载荷绑定使用。您还可以对替代变量应用 bash 样式的字符串操作,并将生成的字符串存储为新的替代变量。如需了解详情,请参阅在替代变量中使用 bash 样式的字符串操作和载荷绑定

后续步骤