从 Bitbucket Server 构建代码库

借助 Cloud Build,您可以创建触发器,以便通过 Bitbucket Server 上托管的代码库进行构建,从而让您能够执行构建来响应与 Bitbucket Server 代码库关联的提交请求或拉取请求等事件。

本页面介绍了如何在 Bitbucket Server 实例上启用触发器功能,以及如何在实例托管在本地环境中从 Bitbucket Server 构建代码库。

准备工作

  • 启用 Cloud Build, Secret Manager, and Compute Engine API。

    启用 API

  • 如果您尚未安装 Bitbucket Server 实例,请参阅 Bitbucket Server 安装指南了解相关说明。
  • [可选] 如果您的 Bitbucket Server 实例托管在本地环境中,请启用 Service Networking API 以对等互连 Virtual Private Cloud 网络。

设置

创建 Bitbucket Server 触发器之前,您必须获取 API 密钥以对 Bitbucket Server 的传入事件进行身份验证和接受。此外,您必须在 Google Cloud 项目中授予 IAM 权限,以便在 Bitbucket Server 中创建触发器和创建个人访问令牌,用于创建网络钩子和检索代码库数据。

本部分讨论在创建 Bitbucket Server 触发器之前需要完成的步骤。

获取 API 密钥

如需连接主机代码库并对传入的网络钩子事件进行身份验证,您需要一个 API 密钥。

要获取 API 密钥,请执行以下操作:

  1. 在 Google Cloud Console 中打开凭据页面:

    打开“凭据”页面

  2. 点击创建凭据

  3. 点击 API 密钥

    您会看到一个对话框,其中含有已创建的 API 密钥。记下您的 API 密钥。

  4. 如果您要对产品应用的密钥进行限制,请点击限制密钥,以完成保护密钥的其他步骤。否则,请点击关闭

    如需了解如何限制密钥,请参阅应用 API 密钥限制

必需的 IAM 权限

如需连接 Bitbucket Server 主机,请向您的用户帐号授予 Cloud Build Editor (roles/cloudbuild.builds.editor) 角色和 Cloud Build Integrations Owner (cloudbuild.integrations.owner) 角色。

如需向您的用户帐号添加所需的角色,请参阅配置对 Cloud Build 资源的访问权限。如需详细了解与 Cloud Build 关联的 IAM 角色,请参阅 IAM 角色和权限

创建个人访问令牌

您必须在 Bitbucket Server 中创建两个个人访问令牌以执行以下任务:

这些个人访问令牌是所需的最低权限。您可以根据需要在 Bitbucket Server 中配置其他权限。例如,您可以选择 Bitbucket Server 帐号以仅访问 Bitbucket Server 实例上的部分代码库,以便更精细地控制在 Cloud Build 中可用的内容。

创建个人访问令牌后,请安全地保存令牌值。稍后您将使用这些令牌连接到 Bitbucket Server 代码库。

从 Bitbucket Server 调用触发器

本部分介绍如何将您的 Bitbucket Server 代码库关联到 Cloud Build,以及如何创建触发器以自动在关联的代码库上调用构建。如果要在本地环境中使用 Bitbucket Server 触发器,请参阅从 Bitbucket Server 在本地环境中构建代码库,以了解更多说明。

连接到 Bitbucket Server 主机

控制台

如需使用 Google Cloud Console 将 Bitbucket Server 主机连接到 Cloud Build,请执行以下操作:

  1. 在 Google Cloud Console 中打开管理代码库页面:

    打开“管理代码库”页面

  2. 点击连接主机

    您将看到连接主机面板。

    输入以下信息,将您的 Bitbucket Server 实例关联到 Cloud Build:

    • 主机网址:您的 Bitbucket Server 实例的主机网址。例如 https://bbs.example-test.com:7990
    • Google Cloud API 密钥:用于对凭据进行身份验证的 API 密钥。
    • [可选] CA 证书:您的自签名证书。您的证书大小不得超过 10 kB,并且应采用 PEM 格式(.pem.cer.crt)。如果此部分留空,则将使用一组默认证书

    • 用户名:您的 Bitbucket Server 帐号的用户名。 此帐号应拥有对您要与 Cloud Build 连接的代码库的管理员访问权限。

    • 读取访问令牌:您的 Bitbucket Server 帐号个人访问令牌,具有读取权限。

    • 管理员访问令牌:您的 Bitbucket Server 帐号个人访问令牌,具有项目和代码库的管理员权限。

    • [可选] 网络项目:您的本地网络上的网络项目 ID。

    • [可选] 网络名称:您的本地网络上的网络名称。

  3. 点击连接主机

    如果您的 Bitbucket Server 实例位于对等网络上,则连接主机可能需要几分钟才能完成。

    系统会将您重定向到连接代码库面板。

    创建主机连接后,您的个人访问令牌和网络钩子 Secret 将安全地存储在 Secret Manager 中。您可以在 Secret Manager 页面上查看和管理 Secret。

gcloud

如需使用 gcloud 命令将 Bitbucket Server 主机连接到 Cloud Build,您必须在终端中运行 gcloud alpha builds enterprise-config bitbucketserver create 命令。与使用 Google Cloud Console 连接主机不同,您需要在运行以下命令之前在 Secret Manager 中手动存储个人访问令牌和网络钩子密钥:

gcloud alpha builds enterprise-config bitbucketserver create
    --name=BITBUCKET_SERVER_CONFIG_NAME \
    --user-name=USERNAME \
    --host-uri=HOST_URI \
    --admin-access-token-secret-version=ADMIN_ACCESS_TOKEN_SECRET_VERSION \
    --read-access-token-secret-version=READ_ACCESS_TOKEN_SECRET_VERSION \
    --webhook-secret-secret-version=WEBHOOK_SECRET_SECRET_VERSION \
    --api-key=API_KEY \
    --peered-network=PEERED_NETWORK \
    --ssl-ca-file=SSL_CA_FILE

其中:

  • BITBUCKET_SERVER_CONFIG_NAME 是您的 Bitbucket Server 配置的名称。
  • USERNAME 是 Bitbucket Server 的用户名。
  • HOST_URI 是 Bitbucket Server 实例的主机 URI。
  • ADMIN_ACCESS_TOKEN_SECRET_VERSION 是存储在 Secret Manager 中的管理员访问令牌的资源名称。注意:存储在 Secret Manager 中的 Secret 的预期格式为 projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}。您可以将 latest 指定为版本,以使用最新版本的 Secret。这适用于存储在 Secret Manager 中的每个资源。
  • READ_ACCESS_TOKEN_SECRET_VERSION 是存储在 Secret Manager 中的读取访问令牌的资源名称。
  • WEBHOOK_SECRET_SECRET_VERSION 是存储在 Secret Manager 中的网络钩子 Secret 的资源名称。
  • API_KEY 是 Google Cloud API 密钥。
  • [可选] PEERED_NETWORK 是本地 Bitbucket Server 实例要连接的 VPC 网络。
  • SSL_CA_FILE 是包含用于向 Bitbucket Server 发出请求的 SSL 证书的本地文件的路径。证书应采用 PEM 格式。

API

如需使用 API 将您的 Bitbucket Server 主机关联到 Cloud Build,请使用以下 JSON 模板。与使用 Google Cloud Console 连接主机不同,您需要在调用 API 之前手动将个人访问令牌和网络钩子密钥存储在 Secret Manager 中:

  {
      "hostUri": HOST_URI,
      "username": USERNAME,
      "apiKey": API_KEY,
      "secrets": {
        "adminAccessTokenVersionName": ADMIN_ACCESS_TOKEN_SECRET_VERSION,
        "readAccessTokenVersionName": READ_ACCESS_TOKEN_SECRET_VERSION,
        "webhookSecretVersionName": WEBHOOK_SECRET_SECRET_VERSION,
      },
      "peeredNetwork": PEERED_NETWORK,
      "sslCa": SSL_CERTIFICATE
  }

其中:

  • HOST_URI 是 Bitbucket Server 实例的主机 URI。
  • USERNAME 是 Bitbucket Server 的用户名。
  • API_KEY 是 Google Cloud API 密钥。
  • ADMIN_ACCESS_TOKEN_SECRET_VERSION 是存储在 Secret Manager 中的管理员访问令牌的资源名称。您可能需要将 Secret Manager 角色授予您的 Cloud Build 服务帐号 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com。如需了解详情,请参阅向您的服务帐号授予 Secret Manager 角色

  • READ_ACCESS_TOKEN_SECRET_VERSION 是存储在 Secret Manager 中的读取访问令牌的资源名称。

  • WEBHOOK_SECRET_SECRET_VERSION 是存储在 Secret Manager 中的网络钩子 Secret 的资源名称。

  • [可选] PEERED_NETWORK 是本地 Bitbucket Server 实例要进行对等连接的 VPC 网络。

  • [可选] SSL_CERTIFICATE 是用于本地 Bitbucket Server 实例的 SSL 证书。

在终端中输入以下 curl 命令:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/bitbucketServerConfigs/?bitbucketServerConfigId=BITBUCKET_SERVER_CONFIG_NAME -d @config.json

其中:

  • PROJECT_NUMBER 是您的 Cloud 项目编号。
  • PROJECT_ID 是您的 Cloud 项目 ID。
  • BITBUCKET_SERVER_CONFIG_NAME 是您的 Bitbucket Server 配置的名称。

如果成功,响应正文将包含一个新创建的 Operation 实例。

在终端中输入以下 curl 命令:

  curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/operations/OPERATION_ID

其中:

  • PROJECT_NUMBER 是您的 Cloud 项目编号。
  • PROJECT_ID 是您的 Cloud 项目 ID。
  • OPERATION_ID 是您的 Bitbucket Server 配置创建操作的 ID。

您可能需要继续运行 GetOperation API 命令,直到响应包含 done: true(表示操作已完成)。如果 Bitbucket Server 配置已成功创建,您可以在 response.value 字段中看到该配置。否则,请查看 error 字段以获取详细的错误报告。

关联到 Bitbucket Server 代码库

控制台

如需使用 Google Cloud Console 将 Bitbucket Server 代码库连接到 Cloud Build,请执行以下操作:

  1. 打开 Google Cloud Console 中的触发器页面。

    打开“触发器”页面

  2. 点击关联代码库

    您将看到连接代码库面板。

  3. 选择来源下,选择 Bitbucket Server

  4. 选择代码库下,选择要关联到 Cloud Build 的 Bitbucket Server 代码库。

  5. 点击关联以关联您的代码库。

    连接代码库后,Cloud Build 会在 Bitbucket Server 实例的代码库中配置网络钩子。然后,当您更改代码库时,代码库会发送网络钩子以调用相应的 Bitbucket Server 触发器。一个代码库也可以通过多个主机连接多次连接。如需了解如何管理网络钩子,请参阅管理网络钩子

    如需找到网络钩子,您需要获取网络钩子 ID。您可以在 BitbucketServerConfig 中找到每个已连接代码库的网络钩子 ID。输入以下命令以检索网络钩子 ID,其中 CONFIG_NAME 是 Bitbucket Server 配置的名称:

    gcloud alpha builds enterprise-config bitbucketserver describe --config=CONFIG_NAME
    
  6. 点击完成。(可选)点击创建触发器以创建触发器。

API

如需使用 API 将您的 Bitbucket Server 代码库关联到 Cloud Build,请使用以下 JSON 模板。

  {
    "parent": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/BITBUCKET_SERVER_CONFIG_NAME",
    "requests": {
      "parent": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/BITBUCKET_SERVER_CONFIG_NAME",
      "bitbucketServerConnectedRepository": {
        "parent": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/BITBUCKET_SERVER_CONFIG_NAME",
        "repo": {
           "projectKey": "PROJECT_KEY",
           "repoSlug": "REPO_SLUG"
         }
       }
    }
  }

其中:

  • PROJECT_NUMBER 是您的 Cloud 项目的项目编号。
  • BITBUCKET_SERVER_CONFIG_NAME 是您的 Bitbucket Server 配置的名称。
  • PROJECT_KEY 是 Bitbucket Server 项目的密钥。 如果要连接个人代码库,您的项目密钥应在用户名前面包含波浪号 (~) 符号。例如 ~${USERNAME}。主机代码库的完整网址可能类似于 https://${HOST_URI}/projects/~${USER_NAME}/repos/${REPO_SLUG}
  • REPO_SLUG 是 Bitbucket Server 代码库的 slug

在终端中输入以下 curl 命令:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/bitbucketServerConfigs/BITBUCKET_SERVER_CONFIG_NAME/connectedRepositories:batchCreate -d @requests.json

其中:

  • PROJECT_NUMBER 是您的 Cloud 项目编号。
  • PROJECT_ID 是您的 Cloud 项目 ID。
  • BITBUCKET_SERVER_CONFIG_NAME 是您的 Bitbucket Server 配置的名称。

如果成功,响应正文将包含一个新创建的 Operation 实例。

在终端中输入以下 curl 命令:

  curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/operations/OPERATION_ID

其中:

  • PROJECT_NUMBER 是您的 Cloud 项目编号。
  • PROJECT_ID 是您的 Cloud 项目 ID。
  • OPERATION_ID 是您的 Bitbucket Server 配置创建操作的 ID。

您可能需要继续运行 GetOperation API 命令,直到响应包含 done: true(表示操作已完成)。如果 Bitbucket Server 代码库连接成功,您可以在 response.bitbucketServerConnectedRepositories 字段中看到连接的代码库。否则,请查看 error 字段以获取详细的错误报告。

创建 Bitbucket Server 触发器

控制台

如需使用 Google Cloud Console 创建 Bitbucket Server 触发器,请执行以下操作:

  1. 打开触发器页面

    打开“触发器”页面

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

  3. 点击创建触发器

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

    • 名称:触发器的名称。

    • 区域:选择触发器的区域

    • 说明(可选):触发器的说明。

    • 事件:选择用于调用触发器的代码库事件。

      • 推送到分支:设置触发器,以便基于对特定分支的提交启动构建。

      • 推送新标记:将触发器设置为以基于包含特定标记的提交启动构建。

      • 拉取请求(不支持 Cloud Source Repositories):设置触发器,以便基于针对拉取请求进行的提交启动构建。

    • 来源:选择要在 Bitbucket Server 触发器运行时构建的代码库。

    • 修订版本:选择要在 Bitbucket Server 触发器运行时构建的分支或标记。

    • 分支:设置一个触发器以构建此分支。

    • 标记:设置一个触发器以构建此标记。

    • 配置:选择位于您的代码库中的构建配置文件,或在触发器上以内嵌方式配置构建。

    • 类型:选择要用于构建的配置类型。

      • Cloud Build 配置文件(yaml 或 json):为您的配置使用构建配置文件。
      • Dockerfile:为您的配置使用 Dockerfile
    • 位置:为您的配置指定位置。

      • 代码库:如果您的配置文件位于代码库中,请提供构建配置文件的位置或 Dockerfile 目录,并为生成的映像提供名称。如果您的配置是 Dockerfile,则还可以选择提供构建的超时时间。提供了 Dockerfile 和映像名称后,您会看到构建将执行的 docker build 命令的预览。

      • 内嵌:如果您选择了 Cloud Build 配置文件(yaml 或 json)作为配置选项,则可以指定内嵌构建配置。点击打开编辑器,使用 YAML 或 JSON 语法在 Google Cloud Console 中编写构建配置文件。点击完成以保存您的构建配置。

  5. 点击创建以创建 Bitbucket Server 触发器。

gcloud

如需使用 gcloud 命令创建 Bitbucket Server 触发器,您需要在终端中运行以下 gcloud alpha builds triggers create bitbucketserver 命令:

gcloud alpha builds triggers create bitbucketserver
    --name=TRIGGER_NAME \
    --project-key=PROJECT_KEY \
    --repo-slug=REPO_SLUG \
    --bitbucket-server-config-resource=projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/ID \
    --branch-pattern=BRANCH_NAME \ # --tag-pattern=TAG_NAME
    --build-config=BUILD_CONFIG

其中:

  • TRIGGER_NAME 是触发器的名称。
  • PROJECT_KEY 是 Bitbucket Server 项目的密钥。
  • REPO_SLUG 是 Bitbucket Server 代码库的 slug
  • PROJECT_NUMBER 是您的 Cloud 项目的项目编号。
  • ID 是您的 BitbucketServerConfig 的 ID。
  • 如果您要设置您的触发器来构建特定分支,则 BRANCH_NAME 是您的分支的正则表达式。
  • 如果您要设置您的触发器来构建特定标记,则 TAG_NAME 是您的标记的正则表达式。
  • BUILD_CONFIG 是构建配置文件的路径。

API

如需使用 API 创建 Bitbucket Server 触发器,请使用以下 JSON 模板。

    {
      "filename": "cloudbuild.yaml",
      "name": "curl-trigger",
      "description": "curl trigger",
      "bitbucket_server_trigger_config": {
          "repo_slug": REPO_SLUG
          "project_key": PROJECT_KEY
          "push": {
             "branch": BRANCH_NAME # "tag": TAG_NAME
          }
     "bitbucket_server_config_resource": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/ID"
      }
  }

其中:

  • PROJECT_KEY 是 Bitbucket Server 项目的密钥。
  • REPO_SLUG 是 Bitbucket Server 代码库的 slug
  • PROJECT_NUMBER 是您的 Cloud 项目的项目编号。
  • ID 是您的 BitbucketServerConfig 的 ID。
  • 如果您要设置您的触发器来构建特定分支,则 BRANCH_NAME 是您的分支的正则表达式。
  • 如果您要设置您的触发器来构建特定标记,则 TAG_NAME 是您的标记的正则表达式。

在终端中输入以下 curl 命令:

curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/triggers -d @trigger.json

其中:

  • PROJECT_NUMBER 是您的 Cloud 项目编号。
  • PROJECT_ID 是您的 Cloud 项目 ID。

从 Bitbucket Server 在本地环境中构建代码库

如果您的 Bitbucket Server 实例托管在本地环境中,并且无法通过公共互联网连接进行访问,则需要在 VPC 网络和服务提供方网络之间创建专用连接。您还需要在本地环境中构建专用池

如需创建 Bitbucket Server 触发器以在本地环境中构建,请执行以下操作:

  1. 通过完成以下步骤,在您的 VPC 网络与服务提供方网络之间创建专用连接:

    1. 启用 Service Networking API
    2. 创建新的 VPC 网络选择现有的 VPC 网络

    3. 在 VPC 网络中分配已命名的 IP 范围。如需将 VPC 网络与 Cloud Build 搭配使用,前缀长度必须为 /23 或更低,例如 /22/21 等。

    4. 在 VPC 网络与 Google Cloud 之间建立 VPC 网络专用连接。如需了解详情,请参阅创建专用连接

    5. 如果您已为 Bitbucket Server 实例配置了 DNS,则需要手动将您的 DNS 区域与服务提供商对等互连。如需了解详情,请参阅与服务提供方共享专用 DNS 区域

    6. [可选] 如果您不想通过 Cloud 项目创建专用连接,可以设置一个共享 VPC,并让您的 Cloud 项目使用该网络(如果您的项目属于某个组织)。您仍需要将共享 VPC 与 Service Networking API 对等互连。

  2. 使用专用池运行构建。如果您尚未创建专用池,请参阅创建新的专用池

  3. 创建 Bitbucket Server 触发器以构建托管在 Bitbucket Server 实例上的代码库。

您的 Bitbucket Server 触发器现在会根据您的配置自动调用 Bitbucket Server 实例上的 build。如需了解如何使用专用工作器池运行构建,请参阅在专用池中运行构建

后续步骤