从 Bitbucket Cloud 构建代码库

本页面介绍了如何使用网络钩子触发器在 Bitbucket Cloud 上构建。

准备工作

  • 启用 Cloud Build and Secret Manager API。

    启用 API

  • 如需使用此页面上的 gcloud 命令,请安装 Cloud SDK

设置

在创建网络钩子触发器以在 Bitbucket Cloud 中构建之前,您需要创建一个 SSH 密钥以对 Bitbucket Cloud 连接进行身份验证。如果您在不使用关联代码库的情况下创建触发器并访问外部源代码管理系统(例如 Bitbucket Cloud)中的代码,则需要在内嵌构建配置中检索 SSH 密钥。

本部分介绍如何在创建 Webhook 触发器之前创建和存储 SSH 密钥。

创建 SSH 密钥

为了访问 Bitbucket Cloud 上的代码,您需要在内嵌构建配置中检索 SSH 密钥。

如需创建 SSH 密钥,请执行以下操作:

  1. 打开一个终端窗口。

  2. 创建名为 working-dir 的新目录并导航至该目录:

    mkdir working-dir
    cd working-dir
    
  3. 创建一个新的 Bitbucket Cloud SSH 密钥,其中 bitbucket.org 是您的 Bitbucket Cloud 代码库的网址:

    ssh-keygen -t rsa -b 4096 -N '' -C bitbucket.org -f id_bitbucket
    

    该命令会在 working-dir/id_bitbucket 中创建一个新的 SSH 密钥,该 SSH 密钥没有密码。如果您的 SSH 密钥受密码保护,则 Cloud Build 无法使用它。

在 Bitbucket Cloud 上添加公共 SSH 访问密钥

为了确保其他系统对 Bitbucket Cloud 中管理的代码库执行的操作,您需要添加您在 Bitbucket Cloud 中的公共 SSH 访问密钥并授予密钥读取权限。要了解如何添加密钥,请参阅添加访问密钥

在 Secret Manager 中创建和存储凭据

当您创建 SSH 密钥时,您的本地环境中会创建一个 id_bitbucket 文件。由于此文件包含与身份验证关联的敏感信息,因此必须先在 Secret Manager 中存储此文件,然后才能使用它来调用构建。

除了创建 Webhook 触发器时使用的 Secret 之外,您还需要在 Secret Manager 中创建 Secret,以验证传入的 Webhook 事件并向 Cloud Build 授权。

如需在 Secret Manager 中创建和存储凭据,请执行以下操作:

  1. 转到 Cloud Console 中的 Secret Manager 页面:

    转到 Secret Manager 页面

  2. Secret Manager 页面上,点击创建密钥

  3. 创建 Secret 页面的名称下,输入 Secret 的名称。

  4. 密钥值字段中,输入密钥的名称或上传文件。

    如需上传 SSH 密钥文件,请点击上传以添加 working-dir/id_bitbucket 文件。

  5. 保持区域部分不变。

  6. 点击创建 Secret 按钮以创建 Secret。

创建 Secret 后,Google Cloud Console 将自动向您的 Cloud Build 服务帐号 ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com 授予 Secret Manager Secret Accessor 角色。如果您未在服务帐号上看到此角色,请完成向您的服务帐号授予 Secret Manager 角色中所述的步骤。

现在您已存储 SSH 密钥,接下来还可以通过运行以下命令从您的环境中删除 SSH 密钥:

rm id_bitbucket*

您现在可以创建 Webhook 触发器了。

创建 Webhook 触发器

控制台

如需使用 Google Cloud Console 创建一个从 Bitbucket Cloud 调用构建的 Webhook 触发器,请执行以下操作:

  1. 打开触发器页面

    打开“构建触发器”页面

  2. 从页面顶部选择您的项目,然后点击打开

  3. 点击创建触发器

  4. 输入以下触发器设置:

    • 名称:触发器的名称。
    • 说明(可选):触发器的说明。
    • 事件:选择 Webhook 事件以设置触发器启动构建来响应传入的 Webhook 事件。
    • Webhook 网址:使用 Webhook 网址对传入的 Webhook 事件进行身份验证。

      • Secret:您需要使用 Secret 对传入的 Webhook 事件进行身份验证。您可以创建新的 Secret,也可以使用现有 Secret。

        如需创建新的 Secret,请执行以下操作:

        1. 选择新建
        2. 点击创建 Secret

          您将看到创建 Webhook Secret 弹出框。

        3. Secret 名称字段中,输入 Secret 名称。

        4. 点击创建 Secret 以保存您的 Secret,系统将自动在 Secret Manager 中创建并存储该 Secret。

        如需使用现有 Secret,请执行以下操作:

        1. 选择使用现有 Secret (Use existing)。
        2. Secret 字段中,从下拉菜单选择要使用的 Secret 的名称,或者按照说明通过资源 ID 添加 Secret。
        3. Secret 版本字段中,从下拉菜单选择您的 Secret 版本。

        如果您使用现有 Secret,则可能需要手动向您的 Cloud Build 服务帐号 ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com 授予 Secret Manager Secret Accessor 角色。如需了解详情,请参阅向您的服务帐号授予 Secret Manager 角色

      创建或选择密钥后,您将看到 Webhook 网址预览。您的网址将包含由 Cloud Build 生成的 API 密钥和您的密钥。如果 Cloud Build 无法检索 API 密钥,您可以手动将 API 密钥添加到网址,或者了解如何获取 API 密钥(如果没有)。

      借助网址,您可以使用 POST 方法发出 HTTP 请求来调用 Webhook 事件。

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
      

      如需了解如何在 Bitbucket Cloud 中创建 Webhook 时使用网址,请参阅在 Bitbucket Cloud 中创建 Webhook

    • 来源(可选):要在 webhook 触发器运行时构建的代码库。保留此字段为空。在此示例中,构建配置是内嵌构建配置,因此不需要源。

    • 配置:在 Google Cloud Console 中创建内嵌构建配置。

      在以下示例中,内嵌构建配置使用 SSH 密钥验证与 Bitbucket Cloud 的连接,并访问指定的代码库。然后,内嵌构建配置签出调用 Webhook 的提交。

      steps:
      # first, setup SSH:
      # 1- save the SSH key from Secret Manager to a file
      # 2- add the host key to the known_hosts file
      - name: gcr.io/cloud-builders/git
        args:
          - '-c'
          - |
            echo "$$SSHKEY" > /root/.ssh/id_rsa
            chmod 400 /root/.ssh/id_rsa
            ssh-keyscan bitbucket.org > /root/.ssh/known_hosts
        entrypoint: bash
        secretEnv:
          - SSHKEY
        volumes:
          - name: ssh
            path: /root/.ssh
      # second, clone the repository
      - name: gcr.io/cloud-builders/git
        args:
          - clone
          - '-n'
          - 'git@bitbucket.org/BITBUCKET_REPO'
          - .
        volumes:
          - name: ssh
            path: /root/.ssh
      # third, checkout the specific commit that invoked this build
      - name: gcr.io/cloud-builders/git
        args:
          - checkout
          - $_TO_SHA
      availableSecrets:
        secretManager:
        - versionName: PATH_TO_SECRET_VERSION
          env: SSHKEY
      

      其中:

      • BITBUCKET_REPO 是您的 Bitbucket 代码库的路径。
      • PATH_TO_SECRET_VERSION 是存储在 Secret Manager 中的 Secret 版本的路径。这是包含 SSH 密钥的 Secret。例如 projects/project-id/secrets/secret-name/versions/1
      • SSHKEY 是本例中用于存储 Secret 路径的环境变量的名称。
    • 替代变量(可选):您可以使用此字段选择定义特定于触发器的替代变量

      在此示例中,假设您想要监控与提交 ID 关联的特定分支名称,然后在构建定义中切换到该分支名称。如需获取此数据,您可以使用载荷绑定创建替代变量,以保存分支名称。

      指定以下变量和值:

      变量名称 变量值
      _BRANCH $(body.push.changes[0].new.name)
      _TO_SHA $(body.push.changes[0].new.target.hash)

      如需查看与 Bitbucket Cloud 事件关联的载荷,请参阅事件载荷

    • 过滤条件(可选):您可以在触发器中创建一项规则,用于确定触发器是否会根据替代变量执行构建。

      如果您希望触发器在分支名称与 main 匹配时执行构建,则可以使用“==”运算符检查完全匹配。如果您想要按正则表达式进行匹配,则还可以使用“matches”关键字。

      指定以下内容作为过滤条件:

      • _BRANCH == refs/heads/main

      如需查看适用于 Webhook 触发器的更多过滤语法示例,请参阅使用 CEL 过滤构建事件

  5. 点击创建以创建构建触发器。

gcloud

如需创建从 Bitbucket Cloud 调用构建的 Webhook 触发器,请执行以下操作:

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --substitutions=''
       --filter=''
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --branch=BRANCH_NAME # --tag=TAG_NAME

其中:

  • TRIGGER_NAME 是触发器的名称。
  • PATH_TO_REPO 是要对其调用构建的代码库的路径。例如 https://www.github.com/owner/repo
  • PATH_TO_SECRET 是存储在 Secret Manager 中的 Secret 的路径。例如 projects/my-project/secrets/my-secret/versions/2
  • PATH_TO_INLINE_BUILD_CONFIG 是内嵌构建配置的路径。

  • 如果您想要将触发器设置为基于分支构建,则 BRANCH_NAME 是您的分支的名称。

  • 如果您想要将触发器设置为基于标记构建,则 TAG_NAME 是您的标记的名称。

在 Bitbucket Cloud 中创建 Webhook

为了让 Bitbucket Cloud 向 Cloud Build 发出请求,您需要按照创建和触发 Webhook 中的说明创建 Bitbucket Cloud 中的 Webhook。

现在,每当代码库的更新与您在 Webhook 中指定的触发器事件匹配时,Cloud Build Webhook 触发器都会自动调用构建。

后续步骤