连接到 Bitbucket 数据中心主机

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

准备工作

  • Enable the Cloud Build and Secret Manager 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 数据中心主机所需的权限，请让您的管理员为您授予用户账号的 Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

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

创建个人访问令牌

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

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

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

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

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

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

连接到 Bitbucket 数据中心主机

控制台

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

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

    打开“代码库”页面

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

  3. 在顶部栏的项目选择器中，选择您的 Google Cloud 项目。

  4. 点击创建主机连接，将新主机连接到 Cloud Build。

  5. 在左侧面板中，选择 Bitbucket 作为您的来源提供方。

  6. 在配置连接部分中，输入以下信息：

    1. 区域：为连接选择一个区域。您必须指定区域。您的连接无法全局存在。

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

  7. 在主机详细信息部分，选择或输入以下信息：

    1. Bitbucket 主机：选择 Bitbucket 数据中心作为主机。

    2. 主机网址：输入 Bitbucket 数据中心主机的网址。

  8. 在网络部分中，选择以下选项之一：

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

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

      1. CA 证书：您的自签名证书。点击浏览，从本地机器打开证书。

        您的证书大小不得超过 10 KB，并且应采用 PEM 格式（.pem、.cer 或 .crt）。如果您将此字段留空，Cloud Build 会使用一组默认证书中的证书。

      2. 在 Service Directory 服务部分中，选择服务的位置。您可以接受预先填充的项目 ID，也可以指定其他项目。

        1. 选择服务的项目。您可以接受预填充的项目，选择在其他项目中以进行浏览，也可以选择手动输入。

          如果您选择手动输入，请输入以下信息：

          • 项目：输入您的 Google Cloud项目 ID，或从下拉菜单中选择该 ID。

          • 区域：此字段会预先选择连接所在的区域。为服务指定的区域必须与关联的连接所对应的区域一致。

        2. 命名空间：选择服务的命名空间。

        3. 服务：选择命名空间中的服务名称。

  9. 在 HTTP 访问令牌部分中，输入以下信息：

    1. 管理员访问令牌：输入具有 repository admin 范围访问权限的令牌。此令牌用于与代码库建立连接和断开连接。

    2. 读取访问令牌：输入具有 repository read 范围访问权限的令牌。Cloud Build 触发器使用此令牌访问代码库中的源代码。

  10. 点击连接。

    点击关联按钮后，您的个人访问令牌会安全地存储在 Secret Manager 中。连接到 Bitbucket 数据中心主机后，Cloud Build 会代表您创建网络钩子密钥。您可以在 Secret Manager 页面上查看和管理 Secret。

gcloud

  1. 将令牌存储在 Secret Manager 中。

  2. 运行以下命令，在 Secret Manager 中创建网络钩子 Secret，其中 WEBHOOK_SECRET 是您要为网络钩子 Secret 指定的名称：

      cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create WEBHOOK_SECRET --data-file=-

  3. 如果您将密钥存储在不同于计划用于创建主机连接的 Google Cloud 项目中，请运行以下命令，以向您的项目授予对 Cloud Build 服务代理的访问权限：

    PN=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
    --role="roles/secretmanager.admin"

    其中：

    • PROJECT_ID 是 Google Cloud 项目 ID。

现在，您可以继续将 Bitbucket 数据中心主机连接到 Cloud Build。

  1. 运行以下命令以创建 Bitbucket 数据中心连接：

    gcloud builds connections create bitbucket-data-center CONNECTION_NAME \
    --host-uri=HOST_URI \
    --project=PROJECT_ID \
    --region=REGION \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/ADMIN_TOKEN/versions/SECRET_VERSION \
    --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
    --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION
 ```

Where:
    • CONNECTION_NAME 是 Cloud Build 中 Bitbucket 数据中心主机连接的名称。
    • HOST_URI 是 Bitbucket 数据中心实例的 URI。
    • PROJECT_ID 是您的 Google Cloud 项目 ID。
    • REGION 是连接的区域。
    • ADMIN_TOKEN 是具有 repository admin 范围的令牌的名称。
    • READ_TOKEN 是具有 repository read 范围的令牌的名称。
    • SECRET_VERSION 是相应 Secret 的版本。
    • WEBHOOK_SECRET 是您的 Webhook Secret。

Terraform

您可以使用 Terraform 将 Bitbucket 数据中心主机连接到 Cloud Build。

在以下示例中，相应代码段会执行以下操作：

  • 配置 Terraform Google 提供程序。
  • 创建 Secret Manager Secret 以存储 Bitbucket 令牌。
  • 向 Cloud Build 服务代理授予访问 Secret 的必要权限。

  • 创建 Bitbucket 数据中心连接。

    // Configure the Terraform Google provider
terraform {
  required_providers {
    google = {}
  }
}

provider "google" {
  project = "PROJECT_ID"
  region = "REGION"
}

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "admin-token-secret" {
    project = "PROJECT_ID"
    secret_id = "ADMIN_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "admin-token-secret-version" {
    secret = google_secret_manager_secret.admin-token-secret.id
    secret_data = "ADMIN_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "read-token-secret" {
    project = "PROJECT_ID"
    secret_id = "READ_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "read-token-secret-version" {
    secret = google_secret_manager_secret.read-token-secret.id
    secret_data = "READ_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
    secret = google_secret_manager_secret.webhook-secret-secret.id
    secret_data = "WEBHOOK_SECRET_VALUE"
}

data "google_iam_policy" "p4sa-secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy-pak" {
  project = google_secret_manager_secret.admin-token-secret.project
  secret_id = google_secret_manager_secret.admin-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-token-secret.project
  secret_id = google_secret_manager_secret.read-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-whs" {
  project = google_secret_manager_secret.webhook-secret-secret.project
  secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

// Create the connection resource
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    bitbucket_data_center_config {
        host_uri = "BITBUCKET_URI"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.admin-token-secret-version.id
        }
        read_authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.read-token-secret-version.id
        }
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pak,
        google_secret_manager_secret_iam_policy.policy-rpak,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

其中：

  • PROJECT_ID 是您的 Google Cloud 项目 ID。
  • PROJECT_NUMBER 是您的 Google Cloud 项目编号。
  • ADMIN_TOKEN_NAME 是具有 repository:admin 范围的令牌的名称。
  • ADMIN_TOKEN_VALUE 是 ADMIN_TOKEN_NAME 的值。
  • READ_TOKEN_NAME 是具有 repository:read 范围的令牌的名称。
  • READ_TOKEN_VALUE 是 READ_TOKEN_NAME 的值。
  • WEBHOOK_SECRET_NAME 是您的网络钩子 Secret 的名称。
  • WEBHOOK_SECRET_VALUE 是 WEBHOOK_SECRET_NAME 的值。
  • REGION 是连接的地区。
  • CONNECTION_NAME 是 Cloud Build 中 Bitbucket 数据中心主机连接的名称。
  • BITBUCKET_URI 是 Bitbucket 数据中心实例的 URI。

轮换旧的或过期的 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 中的安全性：为访问令牌引入过期时间。

后续步骤