连接到 Bitbucket 数据中心主机

本页面介绍了如何将 Bitbucket 数据中心主机连接到 Cloud Build。连接到 Bitbucket 数据中心主机可将 Bitbucket 数据中心代码库与 Cloud Build 集成。这样，您就可以配置构建触发器，以从 Bitbucket 数据中心构建代码库和在专用网络中从 Bitbucket 数据中心构建代码库。

准备工作

  • Enable the Cloud Build, Secret Manager, and Compute Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

必需的 IAM 权限

如需获得连接到 Bitbucket Data Center 主机所需的权限，请让您的管理员为您授予用户账号的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如果您的 Bitbucket 数据中心实例托管在专用网络中，请参阅在专用网络中从 Bitbucket 数据中心构建代码库，了解配置主机连接所需的其他 IAM 角色。

创建个人访问令牌

在为 Bitbucket 数据中心实例创建主机连接之前，请在 Bitbucket 数据中心中创建个人访问令牌，方法如下：

  1. 登录 Bitbucket 数据中心实例。

  2. 按照说明为您的用户账号创建 HTTP 访问令牌。

    1. 创建具有代码库管理员范围的访问令牌，用于与代码库建立连接和断开连接。

    2. 创建具有 repository read 范围的访问令牌，以确保 Cloud Build 代码库可以访问代码库中的源代码。

  3. 请妥善保存您的令牌值。您将使用它们连接到 Bitbucket 数据中心代码库。

连接到 Bitbucket 数据中心主机

控制台

如需使用 Google Cloud 控制台将 Bitbucket 数据中心主机连接到 Cloud Build，请执行以下操作：

  1. 在 Google Cloud 控制台中打开代码库页面：

    打开“代码库”页面

  2. 选择页面顶部的第 1 代标签页。

  3. 点击连接主机。

  4. 从下拉菜单中选择 Bitbucket 数据中心。

    您将看到连接主机面板。

    输入以下信息，将 Bitbucket 数据中心实例连接到 Cloud Build：

    1. 区域：选择连接的区域。

    2. 名称：输入连接的名称。

    3. 主机网址：您的 Bitbucket 数据中心实例的主机网址。例如 https://bbs.example-test.com:7990。

    4. Google Cloud API 密钥：输入用于对凭据进行身份验证的 API 密钥。

    5. CA 证书：您的自签名证书。您的证书大小不得超过 10 KB，并且应采用 PEM 格式（.pem、.cer 或 .crt）。如果您将此部分留空， Google Cloud 将使用一组默认证书中的证书。

    6. 用户名：您的 Bitbucket 数据中心账号用户名。此账号应拥有对您要与 Cloud Build 连接的代码库的管理员访问权限。

    7. 读取访问令牌：输入您的 Bitbucket 数据中心账号个人访问令牌，该令牌具有读取权限。

    8. 管理员访问令牌：输入您的 Bitbucket 数据中心账号个人访问令牌，该令牌具有项目和代码库的管理员权限。

    9. 在网络类型下，选择以下选项之一：

      1. 公共互联网：如果您的实例可通过公共互联网访问，请选择此选项。

      2. 专用网络：如果您的实例托管在专用网络上，请选择此选项。

        1. 项目：选择您的 Google Cloud 项目 ID。

        2. 网络：从下拉菜单中选择您的网络。如果您尚未创建网络，请参阅创建和管理 VPC 网络，了解如何创建网络。

        3. IP 范围：输入对等网络分配的范围内可分配给虚拟机的内部 IP 范围。

          您可以使用无类别域间路由 (CIDR) 路由表示法以 STARTING_IP/SUBNET_PREFIX_SIZE 格式指定范围。例如，192.0.2.0/24 的前缀长度为 24。IP 范围的前 24 位用作子网掩码 (192.0.2.0)，而可能的宿主地址范围为 192.0.2.0 到 192.0.2.255。

          前缀长度的值不得超过 /29。如果未指定范围值，系统会自动分配默认值 /24。如果未指定前缀长度值，系统会自动在对等互连的 VPC 网络中分配 IP 地址。如果未指定 IP 地址的值，系统会自动在对等互连的 VPC 网络中为 IP 地址分配一个范围。

  5. 点击连接主机。

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

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

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

gcloud

如需使用 gcloud 命令将 Bitbucket 数据中心主机连接到 Cloud Build，您必须在终端中运行 gcloud alpha builds enterprise-config bitbucket-data-center create 命令。与使用Google Cloud 控制台连接主机不同，您需要在运行以下命令之前手动将个人访问令牌和网络钩子 Secret 存储在 Secret Manager 中：

gcloud alpha builds enterprise-config bitbucket-data-center create
    --name=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 \
    --peered-network-ip-range=PEERED_NETWORK_IP_RANGE \
    --ssl-ca-file=SSL_CA_FILE

其中：

  • CONFIG_NAME 是 Bitbucket 数据中心配置的名称。
  • USERNAME 是 Bitbucket 数据中心用户名。
  • HOST_URI 是 Bitbucket 数据中心实例的主机 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 数据中心实例的 VPC 网络。如需了解详情，请参阅在专用网络中从 Bitbucket 数据中心构建代码库。

  • 可选：PEERED_NETWORK_IP_RANGE 是虚拟机可在对等互连网络的已分配范围内分配到的内部 IP 范围。

  • SSL_CA_FILE 是包含用于向 Bitbucket 数据中心发出请求的 SSL 证书的本地文件的路径。证书应采用 PEM 格式。

API

如需使用 API 将 Bitbucket 数据中心主机连接到 Cloud Build，请使用以下 JSON 模板。与使用 Google Cloud 控制台连接主机不同，您需要在调用 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",
    "peeredNetworkIpRange": "PEERED_NETWORK_IP_RANGE",
    "sslCa": "SSL_CERTIFICATE"
}

其中：

  • HOST_URI 是 Bitbucket 数据中心实例的主机 URI。
  • USERNAME 是 Bitbucket 数据中心用户名。
  • API_KEY 是 Google Cloud API 密钥。

  • ADMIN_ACCESS_TOKEN_SECRET_VERSION 是存储在 Secret Manager 中的管理员访问令牌的资源名称。您可能需要向 Cloud Build 服务代理 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com 授予 Secret Manager Secret Accessor 角色。如需了解详情，请参阅向服务账号授予 Secret Manager 角色。

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

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

  • 可选：PEERED_NETWORK 是本地 Bitbucket 数据中心实例要进行对等互连的 VPC 网络。

    您可以使用无类别域间路由 (CIDR) 路由表示法以 STARTING_IP/SUBNET_PREFIX_SIZE 格式指定范围。例如，192.0.2.0/24 的前缀长度为 24。IP 范围的前 24 位用作子网掩码 (192.0.2.0)，而可能的宿主地址范围为 192.0.2.0 到 192.0.2.225。

  • 可选：PEERED_NETWORK_IP_RANGE 是虚拟机可在对等互连网络的已分配范围内分配到的内部 IP 范围。

  • 可选：SSL_CERTIFICATE 是用于本地 Bitbucket 数据中心实例的 SSL 证书。

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

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

其中：

  • PROJECT_ID 是您的 Google Cloud 项目 ID。
  • REGION 是与您的 Bitbucket 数据中心配置关联的地区。
  • CONFIG_NAME 是 Bitbucket 数据中心配置的名称。

如果成功，响应正文将包含一个新创建的 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/REGION/operations/OPERATION_ID

其中：

  • PROJECT_NUMBER 是您的 Google Cloud 项目编号。
  • PROJECT_ID 是 Google Cloud 项目 ID。
  • REGION 是与您的 Bitbucket 数据中心配置关联的地区。
  • OPERATION_ID 是您的 Bitbucket 数据中心配置创建操作的 ID。

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

轮换旧的或过期的 Bitbucket 数据中心访问令牌

如果您的 Bitbucket 数据中心访问令牌过期，则 Cloud Build 主机连接会与 Bitbucket 数据中心代码库断开连接。因此，在以下情况下，您会看到错误：

  • 当您尝试关联 Bitbucket 数据中心代码库 Cloud Build 连接时，系统会显示 Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection 消息。

  • 在触发器页面上，当您点击运行时，系统会打开运行触发器页面并显示 Failed to list branches. You can still enter one manually 消息。

如需为连接轮换旧令牌或过期令牌，请执行以下操作：

  1. 查找与主机连接关联的密钥：

    1. 运行以下命令：

      gcloud builds connections describe CONNECTION_PATH --region=REGION

      其中：

      • CONNECTION_PATH 是 Cloud Build 中 Bitbucket 数据中心主机连接的路径，格式为 projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME。
      • REGION 是连接的区域。

    2. 在命令的输出中，查找用户令牌字段的值。readAuthorizerCredential.userTokenSecretVersion 显示 Read 令牌的 Secret Manager 名称，authorizerCredential.userTokenSecretVersion 显示 Admin 令牌的 Secret Manager 名称。这些名称以 Secret 形式存储在 Secret Manager 中。

  2. 在 Bitbucket 数据中心内轮换每个访问令牌：

    1. 前往已连接到 Cloud Build 主机连接的 Bitbucket 数据中心代码库。

    2. 按照 Bitbucket 文档中的说明轮换访问令牌。 轮替令牌时，Bitbucket Data Center 会使用新凭据创建新令牌，并使该令牌的先前版本失效。轮换后的令牌与原始令牌具有相同的权限和范围。

    3. 复制轮换后的令牌的 ID。

  3. 为每个令牌创建新的 Secret 版本：

    1. 在 Google Cloud 控制台中打开 Secret Manager 页面：

      打开 Secret Manager 页面

    2. 对于您轮换的每个令牌，找到您在第 1 步中确定的 Secret 名称，然后依次点击 Actions（操作）和 Add new version（添加新版本）。

    3. 在添加新版本窗口中，输入轮换后的令牌的 ID，然后点击添加新版本。

如需了解详情，请参阅 Bitbucket 数据中心文档中的访问令牌和增强 Bitbucket 中的安全性：为访问令牌引入过期时间。

后续步骤