替换变量值

在构建配置文件中使用 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：构建执行期间使用的构建配置文件的路径；否则，如果构建是在触发器上以内嵌方式配置的，或构建使用 Dockerfile 或 Buildpack，则为空字符串。
• $SERVICE_ACCOUNT_EMAIL：您用于 build。这是默认服务账号或用户指定的服务 。
• $SERVICE_ACCOUNT：服务账号的资源名称，格式为 projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

注意：$COMMIT_SHA 和 $REVISION_ID 均表示与您的构建关联的提交 ID。支持这两种替代变量。

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_]+）。这样做可以防止与内置替代变量产生冲突。要使用 使用以 $ 开头的表达式时，必须使用 $$. Thus:
  • $FOO is invalid since it is not a built-in substitution.
  • $$FOO 求值结果为字面量字符串 $FOO。
• 参数数量的上限为 200 个。参数键的长度上限为 100 个字节，参数值的长度上限为 4000 个字节。

您可以使用以下两种方式之一来指定变量：$_FOO 或 ${_FOO}：

• $_FOO 和 ${_FOO} 计算结果均为 _FOO 的值。但是，${} 允许替代变量在两侧都没有空格的情况下也能够起作用，这意味着允许使用 ${_FOO}BAR 等替代变量。
• $$ allows you to include a literal $ in the template. Thus:
  • $_FOO evaluates to the value of _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 级别。如需自动将所有替换项映射到将在整个 build 中可用的环境变量，请在 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"
      }
    

    此外，您还可以将替换项作为环境变量在整个 build 中提供，然后在一步中忽略它们。在构建级别将 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 中手动运行构建。