本頁面由 Cloud Translation API 翻譯而成。

連線至 Bitbucket Cloud 主機

本頁說明如何將 Bitbucket Cloud 主機連線至 Cloud Build。

事前準備

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

請確認原始碼位於 Bitbucket Cloud 存放區。
確認 Bitbucket Cloud 原始碼存放區有 Dockerfile 或 Cloud Build 設定檔。
安裝 Google Cloud CLI，即可使用 gcloud 指令。

必要 IAM 權限

為確保具備連線所需的權限，請要求管理員將 Cloud Build 連線管理員 (cloudbuild.connectionAdmin) IAM 角色授予您的使用者帳戶。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

管理員或許也能透過自訂角色或其他預先定義的角色，授予必要權限。

建立 Bitbucket Cloud 存取權杖

在 Bitbucket Cloud 中建立下列兩個存取權杖：

管理員存取權杖 - 用於連結及取消連結存放區。
讀取存取權杖 - 允許 Cloud Build 存取原始碼。

如要建立這些權杖，請按照下列步驟操作：

登入 Bitbucket Cloud。
按照 Bitbucket Cloud 的指示，建立連結至存放區、專案或工作區的存取權杖。

授予下列權限：
- 管理員存取權杖：
  - 存放區：讀取和管理員
  - 提取要求：讀取
  - Webhook：讀取和寫入
- 讀取存取權杖：
  - 存放區：讀取
注意： 部分權杖類型僅適用於 Bitbucket Premium。進一步瞭解 Bitbucket Cloud 中的權杖。
複製權杖，以供後續程序使用。

連線至 Bitbucket Cloud 主機

控制台

如要將 Cloud Build 連結至 Bitbucket Cloud 主機，請完成下列步驟：

在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面。

開啟「Repositories」(存放區) 頁面

畫面會顯示「Repositories」(存放區) 頁面。
在專案選取器中選取 Google Cloud 專案。
選取頁面頂端的「第 2 代」分頁標籤。
按一下「建立主機連線」，將新主機連結至 Cloud Build。
選取「Bitbucket」做為來源供應商。
在「設定連線」部分，輸入下列資訊：
1. 「Region」(區域)：選取連線的區域。
  
  注意： 您必須指定區域。您的連線無法在全球存在。
2. 名稱：輸入連線名稱。
3. 在「主機詳細資料」部分，選取「Bitbucket Cloud」做為主機類型。
4. 工作區：輸入 Bitbucket Cloud 存放區的工作區 ID。
5. 存取權杖：輸入先前建立的管理員存取權杖。
6. 讀取存取權杖：輸入先前建立的讀取存取權杖。
按一下「連線」。

新連線會顯示在「Repositories」(存放區) 頁面中。

gcloud

請完成下列步驟來儲存憑證：

執行下列指令，將存取權杖儲存在專案的 Secret Manager 中：Google Cloud
```
echo -n ADMIN_TOKEN | gcloud secrets create ADMIN_SECRET_NAME --data-file=-

echo -n READ_TOKEN | gcloud secrets create READ_SECRET_NAME --data-file=-
```
其中：
- ADMIN_TOKEN 是您的管理員存取權杖。
- ADMIN_SECRET_NAME 是您要在 Secret Manager 中為管理員存取權權杖密鑰指定的名稱。
- READ_TOKEN 是您的讀取存取權杖。
- READ_SECRET_NAME 是您要在 Secret Manager 中為讀取存取權杖密鑰命名的名稱。
執行下列指令，在 Secret Manager 中建立 Webhook 密鑰，其中 WEBHOOK_SECRET_NAME 是您要為 Webhook 密鑰指定的名稱：
```
echo -n ${ex.(random-uuid)} | gcloud secrets create WEBHOOK_SECRET_NAME --data-file=-
```

如果您的密鑰並非全都在同一個專案中，請執行下列指令，授予 Cloud Build 服務代理程式存取權：

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

gcloud secrets add-iam-policy-binding READ_SECRET_NAME \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_ACCOUNT}" \
    --role="roles/secretmanager.secretAccessor"

gcloud secrets add-iam-policy-binding WEBHOOK_SECRET_NAME \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_ACCOUNT}" \
    --role="roles/secretmanager.secretAccessor"

其中：

PROJECT_ID 是您的 Google Cloud 專案 ID。
ADMIN_SECRET_NAME 是管理員權杖密鑰的名稱。
READ_SECRET_NAME 是讀取權杖密鑰的名稱。
WEBHOOK_SECRET_NAME 是 Webhook 密鑰的名稱。

使用下列指令，將 Cloud Build 連結至 Bitbucket Cloud 主機：

gcloud builds connections create bitbucket-cloud CONNECTION_NAME \
    --workspace=WORKSPACE_ID \
    --project=PROJECT_ID \
    --region=REGION \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/ADMIN_SECRET_NAME/versions/latest \
    --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_SECRET_NAME/versions/latest \
    --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET_NAME/versions/1

其中：

CONNECTION_NAME 是您要為 Bitbucket Cloud 主機連線指定的名稱。
WORKSPACE_ID 是 Bitbucket Cloud 存放區的工作區 ID。
PROJECT_ID 是您的 Google Cloud 專案 ID。
REGION 是主機連線的區域。
ADMIN_SECRET_NAME 是管理員權杖密鑰的名稱。
READ_SECRET_NAME 是讀取存取權權杖密鑰的名稱。
WEBHOOK_SECRET_NAME 是 Webhook 密鑰的名稱。

Terraform

您可以使用 Terraform，將 Bitbucket Cloud 主機連至 Cloud Build。

在以下範例中，程式碼片段會執行下列操作：

設定 Terraform Google 供應商。
建立 Secret Manager 密鑰，用於儲存 Bitbucket 權杖。
將存取密鑰的必要權限授予 Cloud Build 服務代理。

建立 Bitbucket Cloud 連線。

// 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 and add the repository resource
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    bitbucket_cloud_config {
        workspace = "WORKSPACE_ID"
        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 是權杖的名稱，具有 webhook、repository、repository:admin 和 pullrequest 範圍存取權。
ADMIN_TOKEN_VALUE 是 ADMIN_TOKEN_NAME 的值。
READ_TOKEN_NAME 是具有 repository:read 範圍的權杖名稱。
READ_TOKEN_VALUE 是 READ_TOKEN_NAME 的值。
WEBHOOK_SECRET_NAME 是 Webhook 密鑰的名稱。
WEBHOOK_SECRET_VALUE 是 WEBHOOK_SECRET_NAME 的值。
REGION 是連線的地區。
CONNECTION_NAME 是連線名稱。
WORKSPACE_ID 是 Bitbucket Cloud 存放區的 Workspace ID。

輪替舊的或過期的 Bitbucket Cloud 存取權杖

如果 Bitbucket Cloud 存取權杖過期，Cloud Build 主機連線就會與 Bitbucket Cloud 存放區中斷連線。因此，在下列情況下，您會看到錯誤訊息：

嘗試連結 Bitbucket Cloud 存放區和 Cloud Build 連線時，會出現 Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection 訊息。
在「Triggers」(觸發條件) 頁面中，按一下「Run」(執行) 後，系統會開啟「Run trigger」(執行觸發條件) 頁面，並顯示 Failed to list branches. You can still enter one manually 訊息。

如要輪替連線的舊權杖或過期權杖，請按照下列步驟操作：

找出與主機連線相關聯的密鑰：
1. 執行下列指令：
```
gcloud builds connections describe CONNECTION_PATH --region=REGION
```
  其中：
  - CONNECTION_PATH 是 Cloud Build 中 Bitbucket Cloud 主機連線的路徑，格式為 projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME。
  - REGION 是連線的區域。
2. 在指令輸出中，找出使用者權杖欄位的值。readAuthorizerCredential.userTokenSecretVersion 顯示權杖的 Secret Manager 名稱，Read 並顯示權杖的 Secret Manager 名稱。authorizerCredential.userTokenSecretVersion Admin 這些名稱會以 Secret 形式儲存在 Secret Manager 中。
在 Bitbucket Cloud 中輪替每個存取權杖：
1. 前往連結至 Cloud Build 主機連線的 Bitbucket Cloud 存放區。
2. 請按照 Bitbucket 說明文件中的操作說明輪替存取權杖。輪替符記時，Bitbucket Cloud 會使用新憑證建立新符記，並使舊版符記失效。輪替後的權杖與原始權杖的權限和範圍相同。
3. 複製輪替後權杖的 ID。
為每個權杖建立新的密鑰版本：
1. 在 Google Cloud 控制台中開啟「Secret Manager」頁面：
  
  開啟 Secret Manager 頁面
2. 針對您輪替的每個符記，找出您在步驟 1 中識別的密碼名稱，然後按一下「動作」，再按一下「新增版本」。
  
  注意： 如果在「密鑰」視窗中找不到密鑰，請選取「區域性密鑰」分頁，並在「區域性密鑰」視窗中尋找密鑰。
3. 在「新增版本」視窗中，輸入輪替權杖的 ID，然後按一下「新增版本」。

詳情請參閱 Bitbucket Cloud 說明文件中的「存取權杖」和「提升 Bitbucket 安全性：推出存取權杖到期功能」。

連線至 Bitbucket Cloud 主機 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要 IAM 權限

建立 Bitbucket Cloud 存取權杖

連線至 Bitbucket Cloud 主機

控制台

gcloud

Terraform

輪替舊的或過期的 Bitbucket Cloud 存取權杖

後續步驟

連線至 Bitbucket Cloud 主機