Bitbucket Server ホストに接続する

このページでは、Bitbucket Server ホストを Cloud Build に接続する方法について説明します。

準備

Cloud Build, Secret Manager, and Compute Engine API を有効にします。
API を有効にする

Bitbucket Server インスタンスをまだインストールしていない場合、インストールの手順については、Bitbucket Server インストールガイドをご覧ください。

設定

Bitbucket Server ホストを接続する前に、Bitbucket Server からの受信イベントを認証して受け入れるための API キーを取得する必要があります。さらに、Webhook を作成してリポジトリデータを取得するには、Google Cloud プロジェクトで IAM 権限を付与して、Bitbucket Server に個人用のアクセストークンを作成する必要があります。

API キーの取得

ホストを接続して受信 Webhook イベントを認証するには、API キーが必要です。

API キーを取得するには:

Google Cloud Console の認証情報ページを開きます。

[認証情報] ページを開く
[認証情報を作成] をクリックします。
[API キー] をクリックします。

作成した API キーとともにダイアログが表示されます。API キーをメモします。
プロダクトアプリケーションのキーを制限する場合は、[キーを制限] をクリックして、キーを保護する追加の手順を行います。制限しない場合は、[閉じる] をクリックします。

キーを制限する方法については、API キーの制限を適用するをご覧ください。

必要な IAM 権限

GitHub Enterprise ホストに接続するには、Cloud Build 編集者（roles/cloudbuild.builds.editor）ロールとCloud Build 統合オーナー（cloudbuild.integrations.owner）ロールをユーザーアカウントに付与します。

必要なロールをユーザーアカウントに追加するには、Cloud Build リソースへのアクセスの構成をご覧ください。Cloud Build に関係する IAM ロールについて詳しくは、IAM ロールと権限をご覧ください。

個人用アクセストークンの作成

次のタスクを実行するには、Bitbucket Server に、個人用のアクセストークンを 2 つ作成する必要があります。

Webhook の作成: 管理者アクセス権を持つ個人用のアクセストークンを作成します。
リポジトリデータの取得: 読み取りアクセス権を持つ個人用のアクセストークンを作成します。必要に応じて、読み取りアクセスと書き込みアクセスの両方を持つトークンを作成できます。

これらの個人用のアクセストークンは、必要最小限の権限です。追加の権限は、必要に応じて、Bitbucket Server に構成します。たとえば、Bitbucket Server アカウントを選択して、Bitbucket Server インスタンス上のリポジトリのサブセットにのみアクセスし、Cloud Build で利用できる対象を細かく制御できます。

個人用のアクセストークンを作成したら、トークン値を安全に保存して Bitbucket Server リポジトリに接続します。

Bitbucket Server ホストへの接続

コンソール

Google Cloud コンソールを使用して Bitbucket Server ホストを Cloud Build に接続するには:

Google Cloud コンソールで [リポジトリ] ページを開きます。

[リポジトリ] ページを開く
ページの上部で、[第 1 世代] タブを選択します。
[ホストに接続] をクリックします。
プルダウンメニューから [Bitbucket Server] を選択します。

[リポジトリを接続] パネルが表示されます。

次の情報を入力して、Bitbucket Server インスタンスを Cloud Build に接続します。
- [リージョン]: 接続のリージョンを選択します。
- [名前]: 接続の名前を入力します。
1. Host URL: Bitbucket Server インスタンスのホスト URL。例: https://bbs.example-test.com:7990
2. Google Cloud API キー: 認証情報の認証に使用される API キー。
3. CA 証明書: 自己署名証明書。証明書のサイズは 10 KB 以下の PEM 形式（.pem、.cer、または .crt）にする必要があります。このセクションを空白のままにすると、デフォルトの証明書のセットが使用されます。
4. ユーザー名: Bitbucket Server アカウントのユーザー名。このアカウントには、Cloud Build に接続するリポジトリに対する管理者権限が必要です。
5. 読み取りアクセストークン: 読み取り権限を持つ Bitbucket Server アカウントの個人用アクセストークン。
6. 管理者アクセストークン: プロジェクトとサーバーリポジトリに対する管理者権限を持つ Bitbucket Server アカウントの個人アクセストークン。
7. [ネットワークの種類] で、次のいずれかのオプションを選択します。
  1. 公共のインターネット: インスタンスに公共のインターネット経由でアクセスできる場合は、このオプションを選択します。
  2. プライベートネットワーク: インスタンスがプライベートネットワークでホストされている場合は、このオプションを選択します。
    1. プロジェクト: Google Cloud プロジェクト ID を選択します。
    2. ネットワーク: プルダウンメニューからネットワークを選択します。ネットワークを作成していない場合は、VPC ネットワークを作成して管理するでネットワークの作成方法を確認してください。
    3. IP 範囲: ピアリングされたネットワークの割り当て範囲内で VM を割り当てることができる内部 IP 範囲を入力します。
      
      STARTING_IP/SUBNET_PREFIX_SIZE 形式のクラスレスドメイン間ルーティング（CIDR）ルーティング表記を使用して範囲を指定できます。たとえば、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 アドレスに値が指定されていない場合、IP アドレスにはピアリングされる VPC ネットワーク内の範囲が自動的に割り当てられます。
      
      注: [ネットワーク] を指定した場合、[IP 範囲] のみを指定できます。[ネットワーク] を指定した場合、[IP 範囲] は省略できます。
[ホストに接続] をクリックします。

Bitbucket Server インスタンスがピアリングされたネットワーク上にある場合、ホストの接続に数分かかることがあります。

[リポジトリを接続] パネルにリダイレクトされます。

ホスト接続を作成すると、個人用のアクセストークンと Webhook シークレットは、Secret Manager に安全に保存されます。シークレットは、Secret Manager ページで確認および管理できます。

gcloud

gcloud コマンドを使用して Bitbucket Server ホストを Cloud Build に接続するには、ターミナルで「gcloud alpha builds enterprise-config bitbucketserver create」コマンドを実行する必要があります。Google Cloud Console を使用してホストを接続する場合とは異なり、個人用のアクセストークンと Webhook シークレットを Secret Manager に手動で保存した後、次のコマンドを実行する必要があります。

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 インスタンスに接続する VPC ネットワークです。詳細については、プライベートネットワークに Bitbucket Server からリポジトリをビルドするをご覧ください。
（省略可）PEERED_NETWORK_IP_RANGE は、ピアリングされたネットワークの割り当て範囲内で VM を割り当てることができる内部 IP 範囲です。

注: --peered-network-ip-range フラグは、--peered-network フラグが設定されている場合にのみ指定できます。--peered-network フラグが設定されている場合、--peered-network-ip-range フラグは省略可能です。
SSL_CA_FILE は、Bitbucket Server へのリクエストに使用する SSL 証明書を含むローカルファイルへのパスです。証明書は PEM 形式にする必要があります。

API

API を使用して Bitbucket Server ホストを Cloud Build に接続するには、次の JSON テンプレートを使用します。Google Cloud コンソールを使用してホストを接続する場合とは異なり、API を呼び出す前に、個人用のアクセストークンと Webhook シークレットを Secret Manager に手動で保存する必要があります。

  {
      "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 に保存された管理者アクセストークンのリソース名です。Cloud Build サービスアカウント（service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com）に、Secret Manager のロールを付与する必要がある場合があります。詳しくは、サービスアカウントに 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 Server インスタンスにピアリングする VPC ネットワークです。

STARTING_IP/SUBNET_PREFIX_SIZE 形式のクラスレスドメイン間ルーティング（CIDR）ルーティング表記を使用して範囲を指定できます。たとえば、192.0.2.0/24 の接頭辞長は 24 文字です。IP 範囲の最初の 24 ビットがサブネットマスク（192.0.2.0）として使用され、可能なホストアドレスの範囲は 192.0.2.0～192.0.2.225 です。

注: 接頭辞長の値は /29 以下にしてください。範囲に値が指定されていない場合は、デフォルト値の /24 が自動的に割り当てられます。接頭辞長に値が指定されていない場合、ピアリングされた VPC ネットワーク内で IP アドレスが自動的に割り当てられます。
（省略可）PEERED_NETWORK_IP_RANGE は、ピアリングされたネットワークの割り当て範囲内で VM を割り当てることができる内部 IP 範囲です。

注: --peeredNetworkIpRange フラグは、peeredNetwork フラグが設定されている場合にのみ指定できます。peeredNetwork フラグが設定されている場合、peeredNetworkIpRange フラグは省略可能です。
[省略可] 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 のインスタンスが含まれます。