在替代变量中使用载荷绑定和 bash 参数扩展

本页介绍如何使用载荷绑定和将 bash 参数扩展应用于与构建触发器关联的替代变量。如果您不熟悉如何在构建配置中使用替代变量,请参阅替换变量值

Cloud Build 可让您将触发器的事件载荷的一部分存储为替代变量。事件载荷是调用触发器的事件的正文。与载荷关联的变量称为绑定,可用于由推送和拉取事件调用的构建。通过绑定,您可以访问与构建相关的其他数据,例如与源代码关联的语言以及拉取请求的作者。

此外,Cloud Build 还可让用户将 bash 参数扩展应用于替代变量值。Bash 参数扩展允许您处理与现有变量关联的字符串。您可以通过使用大写字母或替换子字符串来处理字符串。

在 Google Cloud Console 中以及 Cloud Build 配置文件中定义或更新构建触发器时,您可以使用载荷绑定和应用 bash 参数扩展。此外,您可以在运行手动构建时应用 bash 参数扩展。

载荷绑定

您可以将触发器的事件载荷的一部分存储为替代变量值。载荷绑定可用作推送和拉取事件调用的构建的变量值,如果您的源代码位于 GitHub 代码库或 Cloud Source Repositories 中,则可以使用载荷绑定来访问 JSON 载荷。如需详细了解 GitHub 事件载荷,请参阅 Webhook 事件载荷。如需详细了解 Cloud Source Repositories 的事件载荷,请参阅 Cloud Source Repositories 通知

您可以使用指定的前缀来访问来自事件载荷的信息,该前缀表示事件载荷的根。从前缀开始,您可以使用 JSONPath 语法访问载荷并从中拉取数据。根据您的事件类型,可用的载荷前缀如下:

前缀 说明
push GitHub 可让您访问推送事件的 JSON 载荷中的字段
pull_request GitHub 可让您访问拉取请求事件的 JSON 载荷中的字段
issue_comment GitHub 可让您访问与拉取请求关联的问题评论事件的 JSON 载荷中的字段
csr Cloud Source Repositories 可让您访问推送事件的 JSON 载荷中的字段

对于与 GitHub 应用关联的任何事件,还可以使用内置变量 值 is_collaboratorperm_level。系统会通过变量值 push.pusher.namepull_request.pull_request.user.loginissue_comment.comment.user.login 检查推送和拉取事件的用户状态。下表显示了当源代码位于 GitHub 中时如何将下列值添加为触发器的变量值:

变量名称 变量值 变量说明
_PERM_LEVEL $(perm_level) 获取用户的权限级别
_IS_COLLABORATOR $(is_collaborator) 如果用户是协作者,则输出 true

您可以将变量值 is_collaboratorperm_level 用于推送事件、拉取请求事件以及受控于评论的拉取请求事件。您不需要这些变量值前面添加前缀。

创建使用载荷绑定的替代变量

如需创建使用载荷绑定的替代变量,请执行以下操作:

  1. 打开触发器页面。

  2. 如果尚未创建构建触发器,请点击创建触发器。否则,请选择现有的触发器。

  3. 替代变量下,点击添加变量

  4. 按照以下所述惯例为变量 添加一个名称:

    • 替代变量必须以下划线 (_) 开头,并且只能使用大写字母和数字(遵循正则表达式格式 [A-Z0-9_]+)。这样做可以防止与内置替代变量产生冲突。

    • 参数数量的上限为 100 个。参数键的长度上限为 100 个字节,参数值的长度上限为 4000 个字节。

    如需详细了解如何定义和使用用户定义的替代变量,请参阅使用用户定义的替代变量

  5. 使用受支持的前缀为变量添加

    如果您的源代码位于 GitHub 中,您可以在使用载荷绑定的替代变量中引用事件载荷中的信息。如需访问推送事件的 JSON 载荷,请使用前缀 pushbody。在以下示例中,变量值中的 push 前缀用作入口点来访问构建的 JSON 载荷中的信息:

    变量名称 变量值 变量说明
    _PUSH_NAME $(push.repository.name) 获取与推送事件关联的代码库的名称
    _COMMITS $(push.commits) 获取描述每个推送提交的提交对象数组
    _OWNER $(push.repository.owner.name) 获取代码库所有者的名称
    _URL $(push.repository.html_url) 获取 GitHub 代码库的网址
    _LANGUAGE $(push.repository.language) 获取推送中包含的源代码语言

    如需查看您可以使用 push 前缀访问的字段列表,请参阅 PushEvent

    如需访问拉取请求事件的 JSON 载荷,请使用前缀 pull_requestbody。在以下示例中,变量值中的 pull_request 前缀用作入口点来访问构建的 JSON 载荷中的信息:

    变量名称 变量值 变量说明
    _PULL_REQUEST_ID $(pull_request.pull_request.id) 获取拉取请求的 ID
    _PULL_REQUEST_TITLE $(pull_request.pull_request.title) 获取拉取请求的标题
    _PULL_REQUEST_BODY $(pull_request.pull_request.body) 获取拉取请求的正文
    _USERNAME $(pull_request.pull_request.user.login) 获取拉取请求的发送者的用户名
    _MERGE_TIME $(pull_request.pull_request.merged_at) 获取拉取请求的合并时间

    如需查看您可以使用 pull_request 前缀访问的字段列表,请参阅 PullRequestEvent

    如需访问提交事件的 JSON 载荷,请使用前缀 commit。在以下示例中,变量值中的 commit 前缀用作入口点来访问构建的 JSON 载荷中的信息:

    变量名称 变量值 变量说明
    _COMMIT_URL $(commit.url) 获取与提交内容关联的网址
    _COMMIT_USER $(commit.author.login) 获取提交内容作者的用户名
    _COMMIT_MESSAGE $(commit.commit.message) 获取与提交内容相关的提交消息
    _COMMIT_DATE $(commit.commit.committer.date) 获取与提交内容关联的日期
    _COMMIT_ADDITIONS $(commit.files['*'].additions) 获取与提交内容中文件相关联的附加项的数量

    如需查看可使用 commit 前缀访问的字段列表,请参阅获取提交内容

    如果您为拉取请求调用的触发器启用评论控制,则调用该触发器的事件为 IssueCommentEvent 且关联的前缀是 issue_comment。在以下示例中,变量值中的 issue_comment 前缀用作入口点来访问构建的 JSON 载荷中的信息:

    变量名称 变量值 变量说明
    _PULL_REQUEST_ID $(issue_comment.issue.id) 获取拉取请求的 ID
    _PULL_REQUEST_TITLE $(issue_comment.issue.title) 获取拉取请求的标题
    _STATE $(issue_comment.state) 获取拉取请求的状态(例如打开、关闭等)
    _LABELS $(issue_comment.issue.labels) 获取与拉取请求关联的标签列表
    _LABELS_URL $(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url) 获取与匹配说明的标签关联的网址

    如需查看您可以使用 issue_comment 前缀访问的字段列表,请参阅 IssueCommentEvent

    如果您的源代码位于 Cloud Source Repositories 中,则可以在使用载荷绑定的替代变量中引用事件载荷中的信息。如需访问推送事件中的 JSON 载荷,请使用前缀 csrbody。在以下示例中,变量值中的 csr 前缀用作入口点来访问构建的 JSON 载荷中的信息:

    变量名称 变量值 变量说明
    _REPO_NAME $(csr.name) 获取代码库的名称
    _REPO_URL $(csr.url) 获取代码库的网址
    _CREATED_REPO $(csr.createRepoEvent) 指示用户是否创建了代码库
    _REF_EVENT_NAME $(csr.refUpdateEvent.refUpdates['*'].refName) 参考的名称(例如“ref/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} 只有当 substringvar 的前缀时,才将 substring 中指定的值的第一个实例替换为 replacement 中指定的值
${var/%substring/replacement} 只有当 substringvar 的后缀时,才将 substring 中指定的值的最后一个实例替换为 replacement 中指定的值
${#var} 检索字符串的长度
${var:-default} 除非已定义 var,否则将 var 评估为 default

您还可以指定匹配以下 bash 参数扩展的模式:

Bash 展开 说明
${var#pattern} 移除字符串左侧的字符,直到包含指定的 pattern 最左侧的实例
${var##pattern} 移除字符串左侧的字符,直到包含指定的 pattern 最右侧的实例
${var%pattern} 移除字符串右侧的字符,直到包含指定的 pattern 的第一个实例
${var%%pattern} 移除字符串左侧的字符,直到包含指定的 pattern 最右侧的实例

您可以指定的模式包括:

格式 说明
* 匹配零个或更多个字母数字字符
? 匹配任何单个字母数字字符
[ccc] 匹配 ccc 中的任何单个字符,包括 a-z0-9 之间的范围
[^c] 匹配c 中的任何字母数字字符,包括 lo <= c <= hi 的字符范围
c 匹配任何字母数字字符 c
\c 匹配任何字符 c,包括非字母数字字符,例如 *?\

应用 bash 参数扩展

如需将 bash 参数扩展应用于内置或用户定义的替代变量,请执行以下操作:

  1. 打开触发器页面。

  2. 如果尚未创建构建触发器,请点击创建触发器。否则,请选择现有的触发器。

  3. 替代变量下,点击添加变量

  4. 按照以下所述惯例为变量 添加一个名称:

    • 替代变量必须以下划线 (_) 开头,并且只能使用大写字母和数字(遵循正则表达式格式 [A-Z0-9_]+)。这样做可以防止与内置替代变量产生冲突。

    • 参数数量的上限为 100 个。参数键的长度上限为 100 个字节,参数值的长度上限为 4000 个字节。

    如需详细了解如何定义和使用用户定义的替代变量,请参阅使用用户定义的替代变量

  5. 为变量添加一个,并将受支持的 bash 参数扩展应用于内置替代变量或其他用户定义的替代变量。

    在以下示例中,内置替代变量 $BRANCH_NAME 的默认值为 feature_secret_project_#v2。下表展示了可应用于 $BRANCH_NAME 的 bash 参数扩展的示例:

    变量名称 Bash 扩展 变量值 说明
    _BRANCH_NO_SUFFIX ${$BRANCH_NAME%_\#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:
         dynamic_substitutions: 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
       }
     }
    

在上述示例中设置为 truedynamic_substitutions 字段允许解读 bash 参数扩展。如果由触发器调用您的构建,则 dynamic_substitutions 字段始终设置为 true,无需在构建配置文件中指定。如果是手动调用您的构建,则必须将 dynamic_substitutions 字段设置为 true,以便在运行构建时解读 bash 参数扩展。

将 bash 参数扩展与载荷绑定结合使用

您可以将 bash 参数扩展应用于与载荷绑定关联的变量,方法是创建新变量来引用包含您的绑定的变量,或将绑定与 bash 参数扩展捆绑在一起。下表列出了如何将 bash 参数扩展与载荷绑定结合使用的示例:

变量名称 变量值 变量说明
_URL $(push.repository.html_url) 获取代码库的网址
_URL_CAPITAL ${_URL^^} 使用 bash 参数扩展将网址中的所有字符都设为大写
_APP_NAME my-app-${_URL_CAPITAL} 向代码库的大写网址添加前缀
APP_NAME_ID my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7} 创建一个应用名称,其中包含代码库网址和载荷 ID 的前七个字符

后续步骤