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

連結至 Bitbucket Data Center 主機

本頁說明如何將 Bitbucket Data Center 主機連線至 Cloud Build。連線至 Bitbucket Data Center 主機後，即可將 Bitbucket Data Center 存放區與 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

在 Bitbucket 資料中心存放區中準備好原始碼。
在 Bitbucket Data Center 來源存放區中，擁有 Dockerfile 或 Cloud Build 設定檔。
如果尚未安裝 Bitbucket Data Center 執行個體，請參閱 Bitbucket Data Center 安裝指南瞭解操作說明。

必要 IAM 權限

如要取得連線至 Bitbucket Data Center 主機所需的權限，請要求管理員在您的使用者帳戶中授予下列 IAM 角色：

Cloud Build 編輯器 (roles/cloudbuild.builds.editor)
整合擁有者 (roles/cloudbuild.integrations.owner)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如果 Bitbucket 資料中心執行個體託管於私人網路，請參閱「在私人網路中從 Bitbucket 資料中心建構存放區」，瞭解設定主機連線所需的其他 IAM 角色。

建立個人存取權杖

為 Bitbucket Data Center 執行個體建立主機連線前，請在 Bitbucket Data Center 中建立個人存取權杖，方法如下：

登入 Bitbucket Data Center 執行個體。
按照操作說明為使用者帳戶建立 HTTP 存取權杖。
1. 建立具備存放區管理員範圍的存取權杖，用於連結及取消連結存放區。
2. 建立具備「repository read」範圍的存取權杖，確保 Cloud Build 存放區可以存取存放區中的原始碼。
請妥善保存符記值。您會使用這些密鑰連線至 Bitbucket Data Center 存放區。

連線至 Bitbucket Data Center 主機

控制台

如要使用 Google Cloud 控制台將 Bitbucket Data Center 主機連結至 Cloud Build，請按照下列步驟操作：

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

開啟「Repositories」(存放區) 頁面
選取頁面頂端的「第 1 代」分頁標籤。
按一下「連結主機」。
從下拉式選單中選取「Bitbucket Data Center」。

系統會顯示「連結主機」面板。

輸入下列資訊，將 Bitbucket Data Center 執行個體連結至 Cloud Build：
1. 「Region」(區域)：選取連線的區域。
2. 名稱：輸入連線名稱。
3. 主機網址：Bitbucket Data Center 執行個體的主機網址。例如：https://bbs.example-test.com:7990。
4. Google Cloud API 金鑰：輸入用於驗證憑證的 API 金鑰。
5. CA 憑證：自行簽署的憑證。憑證大小不得超過 10 KB，且應為 PEM 格式 (.pem、.cer 或 .crt)。如果將這個部分留空， Google Cloud 會使用預設憑證集中的憑證。
6. 使用者名稱：Bitbucket Data Center 帳戶的使用者名稱。這個帳戶應具備您要連結至 Cloud Build 的存放區管理員存取權。
7. 讀取存取權杖：輸入具有讀取權限的 Bitbucket Data Center 帳戶個人存取權杖。
8. 管理員存取權杖：輸入 Bitbucket Data Center 帳戶的個人存取權杖，並對專案和存放區具備管理員權限。
9. 在「網路類型」下方，選取下列任一選項：
  1. 公開網際網路：如果可透過公開網際網路存取執行個體，請選取這個選項。
  2. 私人網路：如果執行個體是託管在私人網路上，請選取這個選項。
    1. 「Project」(專案)：選取 Google Cloud 專案 ID。
    2. 網路：從下拉式選單中選取網路。如果尚未建立網路，請參閱「建立及管理虛擬私有雲網路」，瞭解如何建立網路。
    3. IP 範圍：輸入 VM 可在對等互連網路的已分配範圍內指派的內部 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。如果未指定前置字元長度，系統會自動在對等互連的虛擬私有雲網路中指派 IP 位址。如果未指定 IP 位址的值，系統會自動在對等互連的 VPC 網路中指派 IP 位址範圍。
      
      注意： 只有在指定網路後，才能指定 IP 範圍。如果您已指定「網路」，「IP 範圍」為選填。
按一下「連結主機」。

如果 Bitbucket Data Center 執行個體位於對等互連的網路上，主機連線作業可能需要幾分鐘才能完成。

系統會將您重新導向至「Connect Repository」(連結存放區) 面板。

建立主機連線後，系統會將個人存取權杖和 webhook 密鑰安全地儲存在 Secret Manager 中。您可以在「Secret Manager」頁面查看及管理密鑰。

gcloud

如要使用 gcloud 指令將 Bitbucket Data Center 主機連線至 Cloud Build，請在終端機中執行 gcloud alpha builds enterprise-config bitbucket-data-center create 指令。與使用Google Cloud 控制台連結主機不同，您需要先在 Secret Manager 中手動儲存個人存取權杖和 Webhook 密鑰，才能執行下列指令：

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 Data Center 設定的名稱。
USERNAME 是你的 Bitbucket Data Center 使用者名稱。
HOST_URI 是 Bitbucket Data Center 執行個體的主機 URI。
ADMIN_ACCESS_TOKEN_SECRET_VERSION 是儲存在 Secret Manager 中的管理員存取權杖資源名稱。儲存在 Secret Manager 中的密鑰應採用 projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER} 格式。您可以將 latest 指定為版本，使用密碼的最新版本。這適用於儲存在 Secret Manager 中的每個資源。

READ_ACCESS_TOKEN_SECRET_VERSION 是儲存在 Secret Manager 中的讀取存取權杖資源名稱。
WEBHOOK_SECRET_SECRET_VERSION 是儲存在 Secret Manager 中的 Webhook 密鑰資源名稱。
API_KEY 是 Google Cloud API 金鑰。
選用：PEERED_NETWORK 是要連線的虛擬私有雲網路，適用於內部部署的 Bitbucket Data Center 執行個體。詳情請參閱「在私有網路中從 Bitbucket Data Center 建構存放區」。
選用：PEERED_NETWORK_IP_RANGE 是 VM 可在對等互連網路的已分配範圍內指派的內部 IP 範圍。

注意： 只有在設定 --peered-network 旗標時，才能指定 --peered-network-ip-range 旗標。如果已設定 --peered-network 旗標，--peered-network-ip-range 旗標為選用。
SSL_CA_FILE 是本機檔案的路徑，其中包含您要用於向 Bitbucket Data Center 發出要求的 SSL 憑證。憑證應採用 PEM 格式。

API

如要使用 API 將 Bitbucket Data Center 主機連線至 Cloud Build，請使用下列 JSON 範本。與使用 Google Cloud 控制台連線主機不同，您需要先在 Secret Manager 中手動儲存個人存取權杖和 Webhook 密鑰，才能呼叫 API：

{
    "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 Data Center 執行個體的主機 URI。
USERNAME 是你的 Bitbucket Data Center 使用者名稱。
API_KEY 是 Google Cloud API 金鑰。
ADMIN_ACCESS_TOKEN_SECRET_VERSION 是儲存在 Secret Manager 中的管理員存取權杖資源名稱。您可能需要將 Secret Manager Secret 存取者角色授予 Cloud Build 服務代理程式 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com。詳情請參閱「將 Secret Manager 角色授予服務帳戶」一文。

注意： 儲存在 Secret Manager 中的密碼資源名稱預期格式為 projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}。您可以將 latest 指定為版本，使用密碼的最新版本。這適用於 Secret Manager 中儲存的每項資源。
READ_ACCESS_TOKEN_SECRET_VERSION 是儲存在 Secret Manager 中的讀取存取權杖資源名稱。
WEBHOOK_SECRET_SECRET_VERSION 是儲存在 Secret Manager 中的 Webhook 密鑰資源名稱。
選用：PEERED_NETWORK 是要與內部部署 Bitbucket Data Center 執行個體對等互連的 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。

注意： 前置字元長度的值不得超過 /29。如未指定範圍值，系統會自動指派預設值 /24。如未指定前置字串長度值，系統會自動在對等互連的虛擬私有雲網路中指派 IP 位址。
選用：PEERED_NETWORK_IP_RANGE 是 VM 可在對等互連網路的已分配範圍內指派的內部 IP 範圍。

注意： 只有在設定 peeredNetwork 旗標時，才能指定 peeredNetworkIpRange 旗標。如果已設定 peeredNetwork 旗標，peeredNetworkIpRange 旗標為選用。
選用：SSL_CERTIFICATE 是用於內部部署 Bitbucket Data Center 執行個體的 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 Data Center 設定相關聯的區域。
CONFIG_NAME 是 Bitbucket Data Center 設定的名稱。

如果成功，回應主體即會包含新建立的 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 Data Center 設定相關聯的區域。
OPERATION_ID 是 Bitbucket Data Center 設定建立作業的 ID。

您可能需要持續執行 GetOperation API 指令，直到回應包含 done: true 為止，這表示作業已完成。如果成功建立 Bitbucket Data Center 設定，您可以在 response.value 欄位中看到設定。否則，請參閱 error 欄位，查看詳細錯誤報告。

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

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

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

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

後續步驟

瞭解如何連結 Bitbucket Data Center 存放區。
瞭解如何在 Compute Engine 上執行藍綠部署。