Menghubungkan ke host GitHub Enterprise

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

Sebelum memulai

Aktifkan API Cloud Build and Secret Manager.
Mengaktifkan API

Pastikan Anda memiliki GitHub Enterprise versi terbaru.
Pastikan Anda memetakan domain kustom ke host GitHub Enterprise dan memiliki sertifikat SSL yang valid untuk host.

Catatan: Jika host GitHub Enterprise Anda berjalan di instance Compute Engine, Anda dapat membuat Load Balancer HTTP Eksternal, dan menggunakan sertifikat SSL yang dikelola Google untuk instance Anda.
Jika instance GitHub Enterprise Anda dihosting di jaringan pribadi, lihat Membuat repositori dari GitHub Enterprise di jaringan pribadi sebelum menyelesaikan petunjuk di halaman ini.

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 lebih lanjut peran IAM yang terkait dengan Cloud Build, lihat Peran dan izin IAM.

Untuk membuat koneksi menggunakan langkah-langkah penginstalan gcloud, berikan peran Admin Secret Manager (roles/secretmanager.admin) kepada 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 Membuat 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 ke Cloud Build:

Buka halaman Repositories di Konsol Google Cloud.

Buka halaman Repositori

Anda akan melihat halaman Repositories.
Pada pemilih project di panel atas, pilih project Google Cloud Anda.
Di bagian atas halaman, pilih tab generasi ke-2.
Klik Create host connection untuk menghubungkan host baru ke Cloud Build.
Di panel kiri, pilih GitHub Enterprise sebagai penyedia sumber.
Di bagian Configure Connection, masukkan informasi berikut:
1. Region: Pilih region untuk koneksi Anda.
  
  Catatan: Anda harus menentukan wilayah. Koneksi Anda tidak dapat ada secara global.
2. Nama: Masukkan nama untuk koneksi Anda.
Di bagian Detail host, 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.
  
  Catatan: Ukuran sertifikat Anda tidak boleh melebihi 10 KB dan harus dalam format PEM (.pem, .cer, atau .crt). Jika bagian ini dibiarkan kosong, kumpulan sertifikat default akan digunakan.
3. Di bawah 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 In another project atau Enter manually, masukkan informasi berikut:
      - Project: Masukkan atau pilih ID project Google Cloud Anda dari menu drop-down.
      - Region: Kolom ini memilih region koneksi Anda terlebih dahulu. Region yang ditetapkan 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.
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 akan dibuat dan disimpan dalam project ini sebagai rahasia 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 rahasia di Secret Manager pada project Anda. Data ini mencakup kunci pribadi dan rahasia webhook Anda. Kunci pribadi digunakan sebagai metode autentikasi untuk mengakses API Server Enterprise. 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 Anda, lihat Mencantumkan rahasia dan melihat detail rahasia.

Setelah memberi otorisasi pada Aplikasi GitHub Cloud Build, Anda akan dialihkan ke halaman Repositori Cloud Build.

Anda berhasil membuat koneksi GitHub Enterprise.

gcloud

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

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 berada di jaringan pribadi, tentukan resource Direktori Layanan. Anda juga dapat menentukan sertifikat CA Anda.
```
--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 dalam namespace Anda.
- SSL_CA_FILEPATH adalah jalur file ke sertifikat CA Anda.
Setelah menjalankan perintah gcloud builds connections..., Anda akan menerima link untuk menginstal aplikasi Cloud Build GitHub.
Ikuti link yang ditampilkan di langkah sebelumnya untuk membuat dan menginstal Aplikasi GitHub Cloud Build di server perusahaan Anda.
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 ditetapkan ke COMPLETE, berarti Anda berhasil menginstal koneksi. Jika tidak, kolom installationState akan menyediakan link untuk langkah tambahan yang diperlukan.

Anda berhasil membuat koneksi GitHub Enterprise.

Menghubungkan ke host GitHub Enterprise secara terprogram

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

Daftarkan aplikasi GitHub baru. Misalnya, Anda dapat mendaftarkan aplikasi GitHub baru di https://my-ghe-server.net/settings/apps/new.
Lengkapi kolom pada halaman:
1. GitHub App Name: Masukkan nama untuk aplikasi Anda.
2. URL halaman beranda: Masukkan URL untuk Server GitHub Enterprise Anda.
3. Hapus centang kotak Berakhir token otorisasi pengguna.
4. Di bagian Webhook, selesaikan langkah-langkah berikut:
  - Aktif: Centang kotak untuk mengaktifkan buku catatan.
  - 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.
  - Rahasia webhook: Masukkan string yang dibuat secara acak dan catat.
5. Di bagian Izin, tentukan izin berikut:
  - Izin repositori:
    - Pemeriksaan: Baca dan tulis
    - Daftar isi: 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:
  - Check run
  - Rangkaian pemeriksaan
  - Commit komentar
  - Komentar masalah
  - Permintaan pull
  - Mengambil komentar permintaan peninjauan
  - Dorongan
  - Repositori
7. Centang kotak Any account agar aplikasi GitHub Anda dapat diinstal oleh pengguna atau organisasi mana pun.
Klik Create GitHub app untuk membuat aplikasi GitHub.

Setelah mengklik Create GitHub app, Anda akan diarahkan 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}
Di bagian Kunci pribadi, klik Buat kunci pribadi.

Simpan file yang didownload di tempat yang aman.
Di panel kiri, pilih Install App.

Pilih pengguna atau organisasi tempat Anda ingin menginstal aplikasi. Setelah aplikasi diinstal, catat ID penginstalannya. 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 Anda secara terprogram menggunakan Terraform atau gcloud.

Terraform

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

Dalam contoh berikut, cuplikan kode melakukan hal berikut:

Mengonfigurasi penyedia Google Terraform
Membuat rahasia untuk menyimpan kunci pribadi dan rahasia webhook Aplikasi GitHub.
Memberikan izin yang diperlukan kepada Cloud Build Service Agent 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 {
        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
    ]
}

Dengan keterangan:

PROJECT_ID adalah ID project Google Cloud Anda.
PRIVATE_KEY_SECRET adalah rahasia 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 rahasia 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 siput aplikasi. Contoh, https://github.com/settings/apps/{app-slug}.
INSTALLATION_ID adalah ID penginstalan aplikasi GitHub Anda. ID penginstalan dapat ditemukan di URL Aplikasi GitHub Cloud Build Anda, https://github.com/settings/installations/{installation-id}.

Anda berhasil membuat koneksi GitHub Enterprise.

gcloud

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

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 rahasia webhook.
PRIVATE_KEY_FILE adalah jalur file ke kunci pribadi yang Anda buat.

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 Produk Per Project Anda.

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 siput 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 berada di jaringan pribadi, tentukan resource Direktori Layanan. Anda juga dapat menentukan sertifikat CA Anda.
```
  --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 dalam namespace Anda.
- SSL_CA_FILEPATH adalah jalur file ke sertifikat CA Anda.

Anda berhasil membuat koneksi GitHub Enterprise.

Langkah berikutnya

Pelajari cara menghubungkan repositori ke GitHub Enterprise.
Pelajari cara melakukan blue/green deployment di Compute Engine.