GitHub Enterprise ホストに接続する

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

始める前に

  • Cloud Build and Secret Manager API を有効にします。

    API を有効にする

必要な IAM 権限

GitHub Enterprise ホストを接続するには、Cloud Build 接続管理者（roles/cloudbuild.connectionAdmin）ロールをユーザー アカウントに付与します。

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

gcloud インストール手順を使用して接続を作成するには、Google Cloud プロジェクトで次のコマンドを実行して、Secret Manager 管理者のロール（roles/secretmanager.admin）を Cloud Build サービス エージェントに付与します。

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

GitHub Enterprise インスタンスがプライベート ネットワークでホストされている場合は、ホストに接続する前に、必要な追加の IAM ロールについて、プライベート ネットワークで GitHub Enterprise からリポジトリをビルドするをご覧ください。

GitHub Enterprise ホストに接続する

コンソール

GitHub Enterprise ホストを Cloud Build に接続するには:

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

    [リポジトリ] ページを開く

    [リポジトリ] ページが表示されます。

  2. 上部のバーにあるプロジェクト セレクタで、Google Cloud プロジェクトを選択します。

  3. ページ上部にある [第 2 世代] タブを選択します。

  4. [ホスト接続を作成] をクリックして、新しいホストを Cloud Build に接続します。

  5. 左側のパネルで、ソース プロバイダとして [GitHub Enterprise] を選択します。

  6. [接続の構成] セクションで、次の情報を入力します。

    1. [リージョン]: 接続のリージョンを選択します。

    2. 名前: 接続の名前を入力します。

  7. [Host details] セクションに、次の情報を入力します。

    1. Host URL: 接続のホスト URL を入力します。例: github.example.com

    2. CA 証明書: [参照] をクリックして、自己署名証明書をアップロードします。

    3. [接続タイプ] で、次のいずれかのオプションを選択します。

      1. 公共のインターネット: インスタンスに公共のインターネット経由でアクセスできる場合は、このオプションを選択します。

      2. プライベート ネットワーク アクセス: インスタンスがプライベート ネットワークにホストされている場合は、このオプションを選択します。

      3. [Service Directory サービス] で、サービスのロケーションを選択します。

        • プロジェクト your-project 内
        • 別のプロジェクト内
        • 手動で入力

        1. [別のプロジェクト内] か [手動で入力] を選択した場合は、次の情報を入力します。

          • プロジェクト: プルダウン メニューから Google Cloud プロジェクト ID を入力または選択します。

          • リージョン: このフィールドは、接続のリージョンを事前に選択します。サービス用に指定されるリージョンは、接続に関連付けられたリージョンと一致する必要があります。

        2. 名前空間: サービスの名前空間を選択します。

        3. サービス: 名前空間内のサービス名を選択します。

  8. [Connect] をクリックします。

    [接続] ボタンをクリックした後、GitHub Enterprise ホストで GitHub アプリを作成し、ユーザー アカウントまたは組織にそのアプリをインストールするよう求められます。GitHub Enterprise ホストから認証トークンが作成され、Secret Manager のシークレットとしてこのプロジェクトに保存されます。ホストから GitHub アプリをアンインストールまたは削除すれば、いつでもアクセス権を取り消すことができます。

    Cloud Build は、作成された GitHub アプリの認証データを、Secret Manager にプロジェクトの Secret Manager に保存します。このデータには、秘密鍵と Webhook シークレットが含まれます。秘密鍵は、Enterprise Server の API にアクセスするための認証方法として使用されます。Webhook シークレットは、サーバーから Cloud Build に送信されるイベントを検証するために使用されます。Cloud Build サービス エージェント アカウント（service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com）が、シークレットへのアクセスに使用されます。シークレットを表示するには、シークレットを一覧表示し、シークレットの詳細を確認するをご覧ください。

    Cloud Build GitHub アプリを承認すると、Cloud Build の [リポジトリ] ページにリダイレクトされます。

これで、GitHub Enterprise 接続が正常に作成されました。

gcloud

gcloud コマンドを使用して GitHub Enterprise ホストを Cloud Build に接続するには、次の手順を行います。

  1. 次のコマンドを入力して、GitHub Enterprise 接続を作成します。

    gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI --region=REGION

    ここで

    • CONNECTION_NAME は接続の名前です。
    • HOST_URI は、GitHub Enterprise インスタンスの URI です。例: https://mmy-ghe-server.net
    • REGION は、接続のリージョンです。

    GitHub Enterprise インスタンスがプライベート ネットワークにある場合は、Service Directory リソースを指定します。CA 証明書を指定することもできます。

    --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
--ssl-ca-file=SSL_CA_FILEPATH

    ここで

    • PROJECT_ID はユーザーの Google Cloud プロジェクト ID です。
    • REGION は、接続のリージョンです。
    • NAMESPACE は、サービスの名前空間です。
    • SERVICE_NAME は、名前空間内のサービスの名前です。
    • SSL_CA_FILEPATH は、CA 証明書へのファイルパスです。

    gcloud builds connections... コマンドを実行すると、Cloud Build GitHub アプリをインストールするためのリンクが得られます。

  2. 前のステップで返されたリンクをクリックして、Cloud Build GitHub アプリを作成しエンタープライズ サーバーにインストールします。

  3. 次のコマンドを入力して接続を確認します。

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    ここで

    • CONNECTION_NAME は接続の名前です。
    • REGION は、接続のリージョンです。

    installationState フィールドが COMPLETE に設定されていれば、接続は正常にインストールされています。そうでない場合、installationState フィールドには、必要な追加手順へのリンクが表示されます。

これで、GitHub Enterprise 接続が正常に作成されました。

GitHub Enterprise ホストにプログラムで接続する

GitHub Enterprise ホストを Cloud Build にプログラムで接続するには、次の手順で GitHub アプリをインストールする必要があります。

  1. 新しい GitHub アプリを登録します。たとえば、新しい GitHub アプリは、https://my-ghe-server.net/settings/apps/new で登録できます。

  2. ページの各フィールドに値を入力します。

    1. GitHub アプリ名: アプリの名前を入力します。
    2. ホームページの URL: GitHub Enterprise Server の URL を入力します。
    3. [Expire user authorization tokens] チェックボックスをオフにします。
    4. [Webhook] セクションで、次の操作を行います。
      • 有効: チェックボックスをオンにすると、webbook が有効になります。
      • Webhook URL: Webhook URL を入力します。例: https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhookWebhook URL のリージョンは、接続のリージョンと一致している必要があります。
      • Webhook シークレット: ランダムに生成された文字列を入力し、メモしておきます。
    5. [権限] セクションで、次の権限を指定します。
      • Repository permissions:
        • Checks: 読み取りと書き込み
        • Contents: 読み取りと書き込み
        • Issues: 読み取り専用
        • メタデータ: 読み取り専用
        • commit ステータス: 読み取り専用
        • pull リクエスト: 読み取り専用
    6. [イベントに登録] セクションで、次のチェックボックスをオンにします。
      • チェックの実行
      • チェック スイート
      • commit コメント
      • 問題のコメント
      • pull リクエスト
      • pull リクエスト レビュー コメント
      • push
      • リポジトリ
    7. ユーザーや組織が GitHub アプリをインストールできるようにするには、[Any account] のチェックボックスをオンにします。

  3. [GitHub アプリを作成] をクリックして、GitHub アプリを作成します。

    [GitHub アプリを作成] をクリックすると、アプリのページにリダイレクトされます。アプリ ID とアプリスラッグをメモします。アプリスラッグは、ページの URL の最後のセグメントで確認できます。例: https://my-ghe-server.net/settings/apps/{app-slug}

  4. [秘密鍵] セクションで、[秘密鍵を生成] をクリックします。

    ダウンロードしたファイルを安全な場所に保存します。

  5. 左側のペインで [アプリをインストール] を選択します。

    アプリをインストールするユーザーまたは組織を選択します。アプリをインストールしたら、インストール ID をメモします。インストール ID は、ページの URL の最後のセグメントにあります。例: https://my-ghe-server.net/settings/installations/{installation-id}。

GitHub アプリをインストールしたら、次の手順を実行して、Terraform または gcloud を使用して GitHub Enterprise ホストをプログラムで接続します。

Terraform

GitHub アプリをインストールしたら、Google Terraform プロバイダを使用して GitHub Enterprise ホストを Cloud Build に接続できます。

次の例では、コード スニペットによって次のことが行われます。

  • Terraform の Google プロバイダを構成する
  • GitHub アプリの秘密鍵と Webhook シークレットを保存するためのシークレットを作成する
  • Cloud Build サービス エージェントにシークレットへのアクセスに必要な権限を付与します。

  • GitHub Enterprise 接続を作成する

    // Configure the terraform google provider
terraform {
  required_providers {
    google = {}
  }
}

// create Secrets and grant permissions to the Service Agent
resource "google_secret_manager_secret" "private-key-secret" {
    project = "PROJECT_ID"
    secret_id = "PRIVATE_KEY_SECRET"

    replication {
        automatic = true
    }
}

resource "google_secret_manager_secret_version" "private-key-secret-version" {
    secret = google_secret_manager_secret.private-key-secret.id
    secret_data = file("private-key.pem")
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET"

    replication {
        automatic = true
    }
}

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" "serviceagent-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-pk" {
  project = google_secret_manager_secret.private-key-secret.project
  secret_id = google_secret_manager_secret.private-key-secret.secret_id
  policy_data = data.google_iam_policy.serviceagent-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.serviceagent-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"

    github_enterprise_config {
        host_uri = "URI"
        private_key_secret_version = google_secret_manager_secret_version.private-key-secret-version.id
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
        app_id = "APP_ID"
        app_slug = "APP_SLUG"
        app_installation_id = INSTALLATION_ID
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pk,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

ここで

  • PROJECT_ID はユーザーの Google Cloud プロジェクト ID です。
  • PRIVATE_KEY_SECRET は、GitHub アプリの秘密鍵を含むシークレットです。
  • WEBHOOK_SECRET は、GitHub アプリの Webhook シークレット値を含むシークレット名です。
  • WEBHOOK_SECRET_VALUE は、GitHub アプリの Webhook シークレットの値です。
  • REGION は、接続のリージョンです。
  • CONNECTION_NAME は GitHub 接続の名前です。
  • URI は、接続の URI です。例: https://my-github-enterprise-server.net
  • APP_ID は GitHub アプリの ID です。
  • APP_SLUG は、アプリスラッグです。例: https://github.com/settings/apps/{app-slug}
  • INSTALLATION_ID は、GitHub アプリのインストール ID です。インストール ID は、Cloud Build GitHub アプリの URL https://github.com/settings/installations/{installation-id} にあります。

これで、GitHub Enterprise 接続が正常に作成されました。

gcloud

GitHub アプリをインストールしたら、次の手順に沿って gcloud を使用して、GitHub Enterprise ホストをプログラムで接続します。

  1. シークレットを Secret Manager に保存します。

    echo -n WEBHOOK_SECRET | gcloud secrets create mygheapp-webhook-secret --data-file=-
# creating secret from the downloaded private key:
gcloud secrets create mygheapp-private-key --data-file=PRIVATE_KEY_FILE

    ここで

    • WEBHOOK_SECRET は、Webhook シークレット用に作成した文字列です。
    • PRIVATE_KEY_FILE は、生成した秘密鍵へのファイルパスです。

  2. Cloud Build サービス エージェントにシークレットへのアクセス権を付与します。

    PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud secrets add-iam-policy-binding mygheapp-webhook-secret \
  --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"
gcloud secrets add-iam-policy-binding mygheapp-private-key \
  --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
  --role="roles/secretmanager.secretAccessor"

    ここで

    • PROJECT_ID はユーザーの Google Cloud プロジェクト ID です。
    • CLOUD_BUILD_SERVICE_AGENT は、プロダクトごとのプロジェクトごとのアカウントです。

  3. GitHub Enterprise 接続を作成します。

    gcloud builds connections create github-enterprise CONNECTION_NAME \
  --host-uri=HOST_URI \
  --app-id=APP_ID \
  --app-slug=APP_SLUG \
  --private-key-secret-version=projects/PROJECT_ID/secrets/mygheapp-private-key/versions/1 \
  --webhook-secret-secret-version=projects/PROJECT_ID/secrets/mygheapp-webhook-secret/versions/1 \
  --app-installation-id=INSTALLATION_ID \
  --region=REGION

    ここで

    • CONNECTION_NAME は接続の名前です。
    • HOST_URI は、GitHub Enterprise インスタンスの URI です。例: https://mmy-ghe-server.net
    • APP_ID は GitHub アプリの ID です。
    • APP_SLUG は、アプリスラッグです。例: https://my-ghe-server.net/settings/apps/app-slug
    • PROJECT_ID はユーザーの Google Cloud プロジェクト ID です。
    • INSTALLATION_ID は、GitHub アプリのインストール ID です。例: https://my-ghe-server.net/settings/installations/installation-id
    • REGION は、接続のリージョンです。

    GitHub Enterprise インスタンスがプライベート ネットワークにある場合は、Service Directory リソースを指定します。CA 証明書を指定することもできます。

      --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
  --ssl-ca-file=SSL_CA_FILEPATH

    ここで

    • PROJECT_ID はユーザーの Google Cloud プロジェクト ID です。
    • REGION は、接続のリージョンです。
    • NAMESPACE は、サービスの名前空間です。
    • SERVICE_NAME は、名前空間内のサービスの名前です。
    • SSL_CA_FILEPATH は、CA 証明書へのファイルパスです。

これで、GitHub Enterprise 接続が正常に作成されました。

次のステップ