Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

連線至 Bitbucket Cloud 主機

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

事前準備

如果尚未啟用 Cloud Build、Secret Manager 和 Compute Engine API，請啟用這些 API。
啟用 API 時所需的角色
如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API

確認原始碼位於 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」做為來源供應商。
在「設定連線」部分，輸入下列資訊：
- 區域：選取連線的區域。
  
  注意： 您必須指定區域。您的連線無法在全球範圍內存在。
- 名稱：輸入連線名稱。
在「主機詳細資料」部分，輸入下列資訊：
- 選取「Bitbucket Cloud」做為主機類型。
- 工作區：輸入 Bitbucket Cloud 存放區的工作區 ID。
選用：如要管理用於加密 Bitbucket Cloud 存放區存取權杖的加密金鑰，請前往「Encryption」(加密) 部分，然後選擇 Cloud Key Management Service 金鑰。詳情請參閱「為 Secret Manager 啟用客戶管理的加密金鑰」。
在「存取權權杖」部分，輸入下列內容：
- 管理員存取權杖：輸入先前建立的管理員存取權杖。
- 讀取存取權杖：輸入先前建立的讀取存取權杖。
按一下「連線」。

新連線會顯示在「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 是網路鉤子密鑰的名稱。

使用下列指令，將 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 provider。
建立 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 存取權杖

輪替存取權杖，讓 Cloud Build 主機連線維持與 Bitbucket Cloud 存放區的連線。如果 Bitbucket Cloud 存取權杖過期，Cloud Build 主機連線就會與 Bitbucket Cloud 存放區中斷連線。發生這種情況時，您必須輪替過期的權杖，才能停用連線或連結存放區。此外，在下列情況下，您也會看到錯誤訊息：

連線的「連線詳細資料」頁面會顯示錯誤訊息 Connection is disconnected due to an invalid or expired access token。
如果嘗試將存放區連結至權杖過期的連線，系統會顯示「Invalid access token」(存取權杖無效) 訊息。按一下「查看連線」，即可前往連線的「連線詳細資料」頁面，查看過期的權杖。

Cloud Build 可讓您輸入新的權杖值，並將這些權杖儲存在 Secret Manager 的最新密鑰版本中，藉此輪替存取權杖。如要輪替存取權杖，請按照下列步驟操作：

在 Bitbucket Cloud 中輪替每個存取權杖：
1. 前往連結至 Cloud Build 主機連線的 Bitbucket Cloud 存放區。
2. 請按照 Bitbucket 說明文件中的指示輪替存取權杖。輪替權杖時，Bitbucket Cloud 會使用新憑證建立新權杖，並使舊版權杖失效。輪替後的權杖與原始權杖的權限和範圍相同。
3. 複製輪替權杖的 ID。
在 Cloud Build 中更新存取權杖：
1. 前往連線的「連線詳細資料」頁面。
2. 選取「更新存取權杖」。
3. 在「權杖輪替」選單中，於「API 存取權杖」和「讀取存取權杖」欄位輸入新權杖。
4. (選用)：如要讓連線一律使用最新版權杖密鑰，請選取「將連線更新為一律使用最新版本」。如果連線使用特定密鑰版本號碼，取消選取這個選項可能會有所幫助。
5. 選取「更新」即可儲存變更。
  
  Cloud Build 會將新存取權杖儲存至 Secret Manager，做為最新版本的密鑰。

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

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

事前準備

必要 IAM 權限

建立 Bitbucket Cloud 存取權杖

連線至 Bitbucket Cloud 主機

控制台

gcloud

Terraform

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

後續步驟

連線至 Bitbucket Cloud 主機