本頁說明如何將 Bitbucket Server 主機連線至 Cloud Build。
事前準備
-
Enable the Cloud Build, Secret Manager, and Compute Engine APIs.
- 如未安裝 Bitbucket Server 執行個體，請參閱 Bitbucket Server 安裝指南的操作說明。
設定
連線 Bitbucket Server 主機前，您必須先取得 API 金鑰，以便驗證及接受來自 Bitbucket Server 的傳入事件。此外，您必須在 Google Cloud 專案中授予 IAM 權限，才能在 Bitbucket Server 中建立個人存取權杖，進而建立 Webhook 及擷取存放區資料。
取得 API 金鑰
如要連結主機並驗證連入的 Webhook 事件，需要使用 API 金鑰。
取得 API 金鑰的方法如下：
在 Google Cloud 控制台中開啟「憑證」頁面：
按一下 [Create credentials] (建立憑證)。
點選「API 金鑰」。
畫面上會顯示一個對話方塊，其中包含您建立的 API 金鑰。記下 API 金鑰。
如要限制金鑰用於產品應用程式，請按一下「限制金鑰」，完成額外步驟來保護金鑰安全。否則請按一下「關閉」。
如要瞭解如何限制金鑰，請參閱「套用 API 金鑰限制」。
必要 IAM 權限
如要連結 Bitbucket Server 主機，請將「Cloud Build 編輯者」(roles/cloudbuild.builds.editor) 和「Cloud Build Integrations Owner」(cloudbuild.integrations.owner) 角色授予使用者帳戶。
如要將必要角色新增至使用者帳戶，請參閱設定 Cloud Build 資源的存取權。如要進一步瞭解與 Cloud Build 相關聯的 IAM 角色，請參閱「IAM 角色和權限」。
建立個人存取權杖
您必須在 Bitbucket Server 中建立兩組個人存取權杖，才能執行下列工作：
- 建立 Webhook：建立具備管理員存取權的個人存取權杖。
- 擷取存放區資料：建立具有「讀取」存取權的個人存取權杖。您可以選擇建立同時具有「讀取」和「寫入」權限的權杖。
這些個人存取權杖是必要的最低權限。您可能需要視需要在 Bitbucket Server 中設定其他權限。舉例來說，您可以選取 Bitbucket Server 帳戶，只存取 Bitbucket Server 執行個體上的部分存放區，以便更精細地控管 Cloud Build 中可用的項目。
建立個人存取權杖後，請妥善儲存權杖值，以便連線至 Bitbucket Server 存放區。
連線至 Bitbucket Server 主機
主控台
如要使用 Google Cloud 控制台將 Bitbucket Server 主機連結至 Cloud Build，請按照下列步驟操作：
在 Google Cloud 控制台中開啟「Repositories」(存放區) 頁面：
選取頁面頂端的「第 1 代」分頁標籤。
按一下「連結主機」。
從下拉式選單中選取「Bitbucket Server」。
系統會顯示「連線主機」面板。
輸入下列資訊，將 Bitbucket Server 執行個體連結至 Cloud Build：
「區域」：選取連線的區域。
名稱：輸入連線名稱。
主機網址：Bitbucket Server 執行個體的主機網址。例如：
https://bbs.example-test.com:7990。Google Cloud API 金鑰：用於驗證憑證的 API 金鑰。
CA 憑證：自行簽署的憑證。憑證大小不得超過 10 KB，且應採用 PEM 格式 (
.pem、.cer或.crt)。如果這個部分留空，系統會改用預設憑證集。使用者名稱：您的 Bitbucket Server 帳戶使用者名稱。這個帳戶應具備您要連結至 Cloud Build 的存放區管理員存取權。
讀取存取權杖：您的 Bitbucket Server 帳戶個人存取權杖，具有讀取權限。
管理員存取權杖：您的 Bitbucket Server 帳戶個人存取權杖， 具備專案和存放區的管理員權限。
在「網路類型」下方，選取下列任一選項：
公開網際網路：如果執行個體可透過公開網際網路存取，請選取這個選項。
私人網路：如果執行個體是託管在私人網路上，請選取這個選項。
專案：選取 Google Cloud 專案 ID。
網路：從下拉式選單中選取網路。如果您尚未建立網路，請參閱「建立及管理虛擬私有雲網路」，瞭解如何建立網路。
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。如果未指定前置字元長度，系統會自動在對等互連的 VPC 網路中指派 IP 位址。如果未指定 IP 位址的值，系統會自動在對等互連的 VPC 網路中，為 IP 位址指派一個範圍。
按一下「連結主機」。
如果 Bitbucket Server 執行個體位於對等互連的網路上，主機連線作業可能需要幾分鐘才能完成。
系統會將您重新導向至「Connect Repository」(連結存放區) 面板。
建立主機連線後，系統會將個人存取權杖和 webhook 密鑰安全地儲存在 Secret Manager 中。您可以在「Secret Manager」頁面查看及管理密鑰。
gcloud
如要使用 gcloud 指令將 Bitbucket Server 主機連結至 Cloud Build，請在終端機中執行 gcloud alpha builds enterprise-config bitbucketserver create 指令。與使用Google Cloud 控制台連結主機不同，您需要先在 Secret Manager 中手動儲存個人存取權杖和 Webhook 密鑰，才能執行下列指令：
gcloud alpha builds enterprise-config bitbucketserver create
--name=BITBUCKET_SERVER_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
其中：
- BITBUCKET_SERVER_CONFIG_NAME 是 Bitbucket Server 設定的名稱。
- USERNAME 是您的 Bitbucket Server 使用者名稱。
- HOST_URI 是 Bitbucket Server 執行個體的主機 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 Server 執行個體。詳情請參閱「在私人網路中透過 Bitbucket Server 建構存放區」。
[選用] PEERED_NETWORK_IP_RANGE 是 VM 可在對等互連網路的已分配範圍內指派的內部 IP 範圍。
SSL_CA_FILE 是本機檔案的路徑，其中包含您要用於 Bitbucket Server 要求的 SSL 憑證。憑證應採用 PEM 格式。
API
如要使用 API 將 Bitbucket Server 主機連結至 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 Server 執行個體的主機 URI。
- USERNAME 是您的 Bitbucket Server 使用者名稱。
- 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 角色授予服務帳戶」一文。READ_ACCESS_TOKEN_SECRET_VERSION 是儲存在 Secret Manager 中的讀取存取權杖資源名稱。
WEBHOOK_SECRET_SECRET_VERSION 是儲存在 Secret Manager 中的 Webhook 密鑰資源名稱。
[選用] PEERED_NETWORK 是要與內部部署 Bitbucket Server 執行個體對等互連的虛擬私有雲網路。
您可以使用無類別跨網域路由 (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 是 VM 可在對等互連網路的已分配範圍內指派的內部 IP 範圍。
[選用] SSL_CERTIFICATE 是用於 Bitbucket Server 內部部署執行個體的 SSL 憑證。
在終端機中輸入下列 curl 指令：
curl -X POST -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/bitbucketServerConfigs/?bitbucketServerConfigId=BITBUCKET_SERVER_CONFIG_NAME -d @config.json
其中：
- PROJECT_NUMBER 是您的 Cloud 專案編號。
- PROJECT_ID 是您的 Cloud 專案 ID。
- REGION 是與 Bitbucket Server 設定相關聯的區域。
- BITBUCKET_SERVER_CONFIG_NAME 是 Bitbucket Server 設定的名稱。
如果成功，回應主體即會包含新建立的 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 是您的 Cloud 專案編號。
- PROJECT_ID 是您的 Cloud 專案 ID。
- REGION 是與 Bitbucket Server 設定相關聯的區域。
- OPERATION_ID 是 Bitbucket Server 設定建立作業的 ID。
您可能需要持續執行 GetOperation API 指令，直到回應包含 done: true 為止，這表示作業已完成。如果成功建立 Bitbucket Server 設定，您可以在 response.value 欄位中看到該設定。否則，請參閱 error 欄位，查看詳細錯誤報告。