Menghubungkan ke host GitHub Enterprise

Halaman ini menjelaskan cara menghubungkan host GitHub Enterprise ke Cloud Build.

Sebelum memulai

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

Izin IAM yang diperlukan

Untuk menghubungkan host GitHub Enterprise, berikan peran Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) ke akun pengguna Anda.

Untuk menambahkan peran yang diperlukan ke akun pengguna Anda, lihat Mengonfigurasi akses ke resource Cloud Build. Untuk mempelajari peran IAM yang terkait dengan Cloud Build lebih lanjut, lihat Peran dan izin IAM.

Untuk membuat koneksi menggunakan langkah-langkah penginstalan gcloud, berikan peran Admin Secret Manager (roles/secretmanager.admin) ke Agen Layanan Cloud Build dengan menjalankan perintah berikut di project Google Cloud Anda:

      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"

Jika instance GitHub Enterprise Anda dihosting di jaringan pribadi, lihat Membangun repositori dari GitHub Enterprise di jaringan pribadi untuk mempelajari peran IAM tambahan yang diperlukan sebelum koneksi host.

Menghubungkan ke host GitHub Enterprise

Konsol

Untuk menghubungkan host GitHub Enterprise Anda ke Cloud Build:

  1. Buka halaman Repositories di konsol Google Cloud.

    Buka halaman Repositori

    Anda akan melihat halaman Repositori.

  2. Di pemilih project di panel atas, pilih project Google Cloud Anda.

  3. Di bagian atas halaman, pilih tab Generasi ke-2.

  4. Klik Create host connection untuk menghubungkan host baru ke Cloud Build.

  5. Di panel kiri, pilih GitHub Enterprise sebagai penyedia sumber Anda.

  6. Di bagian Configure Connection, masukkan informasi berikut:

    1. Region: Pilih region untuk koneksi Anda.

    2. Nama: Masukkan nama untuk koneksi Anda.

  7. Di bagian Host details, masukkan informasi berikut:

    1. URL Host: Masukkan URL host untuk koneksi Anda. Misalnya, github.example.com

    2. Sertifikat CA: Klik Jelajahi untuk mengupload sertifikat yang ditandatangani sendiri.

    3. Di bagian Jenis koneksi, pilih salah satu opsi berikut:

      1. Internet publik: Pilih opsi ini jika instance Anda dapat diakses melalui internet publik.

      2. Akses jaringan pribadi: Pilih opsi ini jika instance Anda dihosting di jaringan pribadi.

      3. Di bagian Layanan Direktori Layanan, pilih lokasi untuk layanan Anda:

        • Dalam project your-project
        • Dalam project lain
        • Masukkan secara manual

        1. Jika Anda memilih Dalam project lain atau Masukkan secara manual, masukkan informasi berikut:

          • Project: Masukkan atau pilih project ID Google Cloud Anda dari menu drop-down.

          • Region: Kolom ini memilih region koneksi Anda secara otomatis. Region yang ditentukan untuk layanan Anda harus cocok dengan region yang terkait dengan koneksi Anda.

        2. Namespace: Pilih namespace layanan Anda.

        3. Layanan: Pilih nama layanan di namespace Anda.

  8. Klik Connect.

    Setelah mengklik tombol Connect, Anda akan diminta untuk membuat Aplikasi GitHub di host GitHub Enterprise dan menginstal aplikasi di akun pengguna atau organisasi. Token autentikasi dari host GitHub Enterprise Anda akan dibuat dan disimpan dalam project ini sebagai secret Secret Manager. Anda dapat mencabut akses dengan meng-uninstal atau menghapus aplikasi GitHub dari host Anda kapan saja.

    Cloud Build menyimpan data autentikasi Aplikasi GitHub yang dibuat sebagai secret di Secret Manager dalam project Anda. Data ini mencakup kunci pribadi dan secret webhook Anda. Kunci pribadi digunakan sebagai metode autentikasi untuk mengakses API Server Perusahaan. Rahasia webhook digunakan untuk memvalidasi peristiwa yang dikirim dari server ke Cloud Build. Akun Agen Layanan Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) digunakan untuk mengakses secret Anda. Untuk melihat secret, lihat Mencantumkan secret dan melihat detail secret.

    Setelah mengizinkan Aplikasi GitHub Cloud Build, Anda akan dialihkan ke halaman Repositori Cloud Build.

Anda kini telah berhasil membuat koneksi GitHub Enterprise.

gcloud

Untuk menghubungkan host GitHub Enterprise ke Cloud Build menggunakan perintah gcloud, selesaikan langkah-langkah berikut:

  1. Masukkan perintah berikut untuk membuat koneksi GitHub Enterprise:

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

    Dengan keterangan:

    • CONNECTION_NAME adalah nama koneksi Anda.
    • HOST_URI adalah URI instance GitHub Enterprise Anda. Contoh, https://mmy-ghe-server.net.
    • REGION adalah region untuk koneksi Anda.

    Jika instance GitHub Enterprise Anda berada di jaringan pribadi, tentukan resource Direktori Layanan Anda. Anda juga dapat menentukan sertifikat CA.

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

    Dengan keterangan:

    • PROJECT_ID adalah ID project Google Cloud Anda.
    • REGION adalah region untuk koneksi Anda.
    • NAMESPACE adalah namespace untuk layanan Anda.
    • SERVICE_NAME adalah nama layanan Anda di namespace.
    • SSL_CA_FILEPATH adalah jalur file ke sertifikat CA Anda.

    Setelah menjalankan perintah gcloud builds connections..., Anda akan menerima link untuk menginstal aplikasi GitHub Cloud Build.

  2. Ikuti link yang ditampilkan di langkah sebelumnya untuk membuat dan menginstal Aplikasi GitHub Cloud Build di server perusahaan Anda.

  3. Masukkan perintah berikut untuk memverifikasi koneksi Anda:

    gcloud builds connections describe CONNECTION_NAME --region=REGION

    Dengan keterangan:

    • CONNECTION_NAME adalah nama koneksi Anda.
    • REGION adalah region untuk koneksi Anda.

    Jika kolom installationState disetel ke COMPLETE, Anda telah berhasil menginstal koneksi. Jika tidak, kolom installationState akan menyediakan link untuk langkah tambahan yang diperlukan.

Anda kini telah berhasil membuat koneksi GitHub Enterprise.

Menghubungkan ke host GitHub Enterprise secara terprogram

Untuk menghubungkan host GitHub Enterprise secara terprogram ke Cloud Build, Anda harus menginstal aplikasi GitHub dengan menyelesaikan langkah-langkah berikut:

  1. Daftarkan aplikasi GitHub baru. Misalnya, Anda dapat mendaftarkan aplikasi GitHub baru di https://my-ghe-server.net/settings/apps/new.

  2. Lengkapi kolom di halaman:

    1. GitHub App Name: Masukkan nama untuk aplikasi Anda.
    2. URL Halaman beranda: Masukkan URL untuk Server GitHub Enterprise Anda.
    3. Hapus centang pada kotak Expire user authorization tokens.
    4. Di bagian Webhook, selesaikan langkah-langkah berikut:
      • Aktif: Centang kotak untuk mengaktifkan webook Anda.
      • URL webhook: Masukkan URL webhook Anda. Contoh, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. Region di URL webhook harus cocok dengan region koneksi Anda.
      • Webhook secret: Masukkan string yang dibuat secara acak dan catat.
    5. Di bagian Izin, tentukan izin berikut:
      • Izin repositori:
        • Pemeriksaan: Baca dan tulis
        • Konten: Baca dan tulis
        • Masalah: Hanya baca
        • Metadata Hanya baca
        • Status commit: Hanya baca
        • Permintaan pull: Hanya baca
    6. Di bagian Berlangganan peristiwa, centang kotak berikut:
      • Pemeriksaan berjalan
      • Suite pemeriksaan
      • Komentar commit
      • Komentar masalah
      • Permintaan pull
      • Komentar peninjauan permintaan pull
      • Push
      • Repositori
    7. Centang kotak Akun apa pun untuk mengizinkan aplikasi GitHub Anda diinstal oleh pengguna atau organisasi mana pun.

  3. Klik Create GitHub app untuk membuat aplikasi GitHub.

    Setelah mengklik Create GitHub app, Anda akan dialihkan ke halaman aplikasi. Catat ID Aplikasi dan slug Aplikasi Anda. Slug Aplikasi dapat ditemukan di segmen terakhir URL halaman. Misalnya, https://my-ghe-server.net/settings/apps/{app-slug}

  4. Di bagian Kunci pribadi, klik Buat kunci pribadi.

    Simpan file yang didownload di tempat yang aman.

  5. Di panel kiri, pilih Instal Aplikasi.

    Pilih pengguna atau organisasi tempat Anda ingin menginstal aplikasi. Setelah aplikasi diinstal, catat ID penginstalan. ID penginstalan dapat ditemukan di segmen terakhir URL halaman. Misalnya, https://my-ghe-server.net/settings/installations/{installation-id}.

Setelah menginstal aplikasi GitHub, selesaikan langkah-langkah berikut untuk menghubungkan host GitHub Enterprise secara terprogram menggunakan Terraform atau gcloud.

Terraform

Setelah menginstal aplikasi GitHub, Anda dapat menghubungkan host GitHub Enterprise ke Cloud Build menggunakan penyedia Terraform Google.

Dalam contoh berikut, cuplikan kode melakukan hal berikut:

  • Mengonfigurasi penyedia Google Terraform
  • Membuat secret untuk menyimpan kunci pribadi dan secret webhook Aplikasi GitHub
  • Memberikan izin yang diperlukan kepada Agen Layanan Cloud Build untuk mengakses secret

  • Membuat koneksi 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 {
        auto {}
    }
}

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 {
        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" "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
    ]
}

Dengan keterangan:

  • PROJECT_ID adalah ID project Google Cloud Anda.
  • PRIVATE_KEY_SECRET adalah secret yang berisi kunci pribadi Aplikasi GitHub Anda.
  • WEBHOOK_SECRET adalah nama rahasia yang berisi nilai rahasia webhook Aplikasi GitHub Anda.
  • WEBHOOK_SECRET_VALUE adalah nilai secret webhook Aplikasi GitHub Anda.
  • REGION adalah region untuk koneksi Anda.
  • CONNECTION_NAME adalah nama koneksi GitHub Anda.
  • URI adalah URI koneksi Anda. Contoh, https://my-github-enterprise-server.net.
  • APP_ID adalah ID Aplikasi GitHub Anda.
  • APP_SLUG adalah slug aplikasi. Contoh, https://github.com/settings/apps/{app-slug}.
  • INSTALLATION_ID adalah ID penginstalan aplikasi GitHub Anda. ID penginstalan Anda dapat ditemukan di URL Aplikasi GitHub Cloud Build, https://github.com/settings/installations/{installation-id}.

Anda kini telah berhasil membuat koneksi GitHub Enterprise.

gcloud

Setelah menginstal aplikasi GitHub, selesaikan langkah-langkah berikut untuk menghubungkan host GitHub Enterprise secara terprogram menggunakan gcloud:

  1. Simpan secret Anda di 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

    Dengan keterangan:

    • WEBHOOK_SECRET adalah string yang Anda buat untuk secret webhook.
    • PRIVATE_KEY_FILE adalah jalur file ke kunci pribadi yang Anda buat.

  2. Berikan akses ke Agen Layanan Cloud Build untuk mengakses secret Anda:

    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"

    Dengan keterangan:

    • PROJECT_ID adalah ID project Google Cloud Anda.
    • CLOUD_BUILD_SERVICE_AGENT adalah akun Per-Project Per-Produk Anda.

  3. Buat koneksi GitHub Enterprise Anda:

    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

    Dengan keterangan:

    • CONNECTION_NAME adalah nama koneksi Anda.
    • HOST_URI adalah URI instance GitHub Enterprise Anda. Contoh, https://mmy-ghe-server.net.
    • APP_ID adalah ID Aplikasi GitHub Anda.
    • APP_SLUG adalah slug aplikasi. Contoh, https://my-ghe-server.net/settings/apps/app-slug.
    • PROJECT_ID adalah ID project Google Cloud Anda.
    • INSTALLATION_ID adalah ID penginstalan aplikasi GitHub Anda. Misalnya, https://my-ghe-server.net/settings/installations/installation-id
    • REGION adalah region untuk koneksi Anda.

    Jika instance GitHub Enterprise Anda berada di jaringan pribadi, tentukan resource Direktori Layanan Anda. Anda juga dapat menentukan sertifikat CA.

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

    Dengan keterangan:

    • PROJECT_ID adalah ID project Google Cloud Anda.
    • REGION adalah region untuk koneksi Anda.
    • NAMESPACE adalah namespace layanan Anda.
    • SERVICE_NAME adalah nama layanan Anda di namespace.
    • SSL_CA_FILEPATH adalah jalur file ke sertifikat CA Anda.

Anda kini telah berhasil membuat koneksi GitHub Enterprise.

Langkah berikutnya