Menghubungkan ke repositori GitHub

Halaman ini menjelaskan cara menghubungkan repositori GitHub ke Cloud Build. Untuk mempelajari repositori Cloud Build lebih lanjut, lihat Repositori Cloud Build.

Sebelum memulai

  • Aktifkan Cloud Build dan Secret Manager API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Aktifkan API

  • Siapkan kode sumber Anda di repositori GitHub.
  • Memiliki file konfigurasi Cloud Build Dockerfile atau di repositori sumber GitHub Anda.
  • Jika Anda menghubungkan repositori ke Cloud Build untuk pertama kalinya, pastikan Anda memiliki izin tingkat admin di repositori. Untuk mempelajari lebih lanjut izin repositori GitHub, lihat Tingkat izin repositori untuk organisasi.

  • Untuk menggunakan perintah gcloud di halaman ini, instal Google Cloud CLI.

Menghubungkan ke host GitHub

Konsol

Untuk menghubungkan repositori GitHub Anda ke Cloud Build:

  1. Buka halaman Repositori di Google Cloud konsol.

    Buka halaman Repositori

    Anda akan melihat halaman Repositories.

  2. Di pemilih project di panel atas, pilih Google Cloud project 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 sebagai penyedia sumber Anda.

  6. Di bagian Configure Connection, masukkan informasi berikut:

    • Region: Pilih region untuk koneksi Anda.

    • Name: Masukkan nama untuk koneksi Anda.

  7. Opsional: Jika Anda ingin mengelola kunci enkripsi yang digunakan untuk mengenkripsi token akses untuk repositori GitHub Anda, buka bagian Encryption dan pilih kunci Cloud Key Management Service. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan kunci enkripsi yang dikelola pelanggan untuk Secret Manager.

  8. Klik Hubungkan.

    Setelah mengklik tombol Connect, Anda akan diminta untuk memberi otorisasi ke Aplikasi GitHub Cloud Build agar dapat mengakses akun GitHub Anda. Anda dapat mencabut akses ke aplikasi dengan meng-uninstal atau menghapus Aplikasi dari host Anda kapan saja.

    Cloud Build meminta otorisasi akun pengguna GitHub Anda dan menyimpan token otorisasi yang dihasilkan sebagai secret di Secret Manager dalam project Anda. Token otorisasi digunakan untuk memvalidasi akses akun pengguna Anda untuk penginstalan Aplikasi GitHub Cloud Build dan ke repositori yang ditautkan. Akun Agen Layanan Cloud Build (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) digunakan untuk mengakses secret Anda. Untuk melihat secret Anda, lihat Mencantumkan secret dan melihat detail secret.

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

gcloud

Untuk menghubungkan host GitHub menggunakan gcloud, selesaikan langkah-langkah berikut:

  1. Masukkan perintah berikut untuk memulai koneksi ke repositori GitHub Anda:

     gcloud builds connections create github CONNECTION_NAME --region=REGION

    Dengan:

    • CONNECTION_NAME adalah nama untuk koneksi Anda sebagaimana yang akan muncul di Cloud Build.

    • REGION adalah region untuk pemicu Anda.

    Setelah menjalankan perintah gcloud builds connections, Anda akan melihat link untuk mengizinkan Aplikasi GitHub Cloud Build.

  2. Login ke akun github.com Anda.

  3. Ikuti link untuk memberi otorisasi pada Aplikasi GitHub Cloud Build.

    Setelah mengizinkan aplikasi, Cloud Build menyimpan token autentikasi sebagai secret di Secret Manager dalam project Google CloudAnda. Anda dapat melihat secret di halaman Secret Manager.

  4. Instal Aplikasi GitHub Cloud Build di akun Anda atau di akun organisasi yang Anda miliki.

    Izinkan penginstalan menggunakan akun GitHub Anda dan pilih izin repositori saat diminta.

  5. Verifikasi penginstalan koneksi GitHub Anda dengan menjalankan perintah berikut:

     gcloud builds connections describe CONNECTION_NAME --region=REGION

    Dengan:

    • CONNECTION_NAME adalah nama koneksi host GitHub Anda di Cloud Build.
    • REGION adalah region untuk pemicu Anda.

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

Menghubungkan ke host GitHub secara terprogram

Untuk menyiapkan koneksi terprogram secara aman, ikuti Google Cloud's praktik terbaik keamanan:

  • Workload Identity Federation (WIF): Jika Anda menjalankan skrip deployment atau konfigurasi Terraform melalui pipeline CI/CD (seperti GitHub Actions atau GitLab CI), konfigurasi Workload Identity Federation dan manfaatkan kredensial dengan masa berlaku singkat menggunakan peran IAM untuk mengautentikasi pipeline ke Google Cloud. Hal ini menghilangkan kebutuhan untuk mengelola dan mengekspos kunci akun layanan yang berlaku lama.
  • Prinsip Hak Istimewa Terendah: Pilih hanya cakupan dan izin minimal yang diperlukan untuk token autentikasi Anda.
  • Token Akses Pribadi dengan Izin Terperinci: Sebaiknya gunakan Token Akses Pribadi (PAT) dengan izin terperinci dengan tanggal habis masa berlaku yang singkat, bukan Token Akses Pribadi klasik.

  • Gunakan akun robot: Untuk mengurangi risiko gangguan pipeline saat karyawan mengubah peran atau keluar dari organisasi Anda, gunakan akun robot atau akun layanan GitHub khusus, bukan akun pribadi karyawan.

Terraform

Anda dapat menghubungkan host GitHub ke Cloud Build menggunakan penyedia Google Terraform dengan menyelesaikan langkah-langkah berikut:

  1. Instal Aplikasi GitHub Cloud Build di akun GitHub Anda atau di organisasi yang Anda miliki.

  2. Buat token akses pribadi di GitHub. Sebaiknya buat token ini menggunakan akun robot GitHub khusus:

    • Sebaiknya buat Personal Access Token (PAT) terperinci:

      • Tetapkan tanggal habis masa berlaku yang singkat. Token tanpa tanggal habis masa berlaku tidak disarankan.
      • Pilih izin minimal yang diperlukan untuk penyiapan Anda.

    • Jika Anda harus menggunakan Token Akses Pribadi lama/klasik sebagai pengganti (yang kurang aman karena memberikan cakupan repositori yang luas), pilih cakupan OAuth berikut saat diminta di GitHub:

    • repo untuk memberikan akses penuh ke repositori publik dan pribadi.

    • read:user untuk memberikan akses guna membaca data profil pengguna.

    • read:org untuk akses hanya baca ke keanggotaan organisasi dan project (jika aplikasi Anda diinstal di organisasi).

  3. Setelah membuat token, simpan di lokasi yang aman. Anda akan menggunakan token ini pada langkah-langkah berikutnya.

Dalam contoh berikut, cuplikan kode melakukan hal berikut:

  • Mengonfigurasi penyedia Google Terraform. Jika menjalankan konfigurasi dari pipeline deployment, konfigurasi penyedia untuk menggunakan Workload Identity Federation dengan kredensial berjangka pendek.

  • Membuat secret untuk menyatakan Token Akses Pribadi (PAT) GitHub dan memberikan izin kepada Agen Layanan Cloud Build untuk mengakses secret tersebut.

  • Membuat koneksi GitHub.

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

// Create a secret containing the personal access token and grant permissions to the Service Agent
resource "google_secret_manager_secret" "github_token_secret" {
    project = PROJECT_ID
    secret_id = SECRET_ID

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "github_token_secret_version" {
    secret = google_secret_manager_secret.github_token_secret.id
    secret_data = GITHUB_PAT
}

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" {
  project = google_secret_manager_secret.github_token_secret.project
  secret_id = google_secret_manager_secret.github_token_secret.secret_id
  policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
}

// Create the GitHub connection
resource "google_cloudbuildv2_connection" "my_connection" {
    project = PROJECT_ID
    location = REGION
    name = CONNECTION_NAME

    github_config {
        app_installation_id = INSTALLATION_ID
        authorizer_credential {
            oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
        }
    }
    depends_on = [google_secret_manager_secret_iam_policy.policy]
}

Dengan:

  • PROJECT_NUMBER adalah nomor project Google Cloud Anda.
  • SECRET_ID adalah ID token atau secret Anda di Secret Manager.
  • GITHUB_PAT adalah token akses dari token akses pribadi di GitHub.
  • PROJECT_ID adalah Google Cloud project ID Anda.
  • REGION adalah region untuk koneksi Anda.
  • CONNECTION_NAME adalah nama untuk koneksi Anda seperti yang akan muncul di Cloud Build.
  • INSTALLATION_ID adalah ID penginstalan aplikasi GitHub Cloud Build Anda. ID penginstalan Anda dapat ditemukan di URL Aplikasi GitHub Cloud Build Anda. Di URL berikut, https://github.com/settings/installations/1234567, ID penginstalan adalah nilai numerik 1234567.

gcloud

Untuk menghubungkan host GitHub menggunakan token dan ID penginstalan yang ada yang diperoleh dari koneksi sebelumnya, selesaikan langkah-langkah berikut:

  1. Instal Aplikasi GitHub Cloud Build di akun GitHub Anda atau di organisasi yang Anda miliki.

  2. Buat token akses pribadi di GitHub. Sebaiknya buat token ini menggunakan akun robot GitHub khusus:

    • Sebaiknya buat Personal Access Token (PAT) terperinci:

      • Tetapkan tanggal habis masa berlaku yang singkat. Token tanpa tanggal habis masa berlaku tidak disarankan.
      • Pilih izin minimal yang diperlukan untuk penyiapan Anda.

    • Jika Anda harus menggunakan Token Akses Pribadi lama/klasik sebagai pengganti (yang kurang aman karena memberikan cakupan repositori yang luas), pilih cakupan OAuth berikut saat diminta di GitHub:

    • repo untuk memberikan akses penuh ke repositori publik dan pribadi.

    • read:user untuk memberikan akses guna membaca data profil pengguna.

    • read:org untuk akses hanya baca ke keanggotaan organisasi dan project (jika aplikasi Anda diinstal di organisasi).

    Setelah membuat token, simpan di lokasi yang aman. Anda akan menggunakan token ini pada langkah-langkah berikutnya.

  3. Simpan token Anda di Secret Manager di Google Cloud project Anda dengan menjalankan perintah berikut:

        echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-

    Dengan:

    • TOKEN adalah token akses pribadi Anda.
    • SECRET_NAME adalah nama yang ingin Anda berikan ke secret di Secret Manager.

  4. Beri akses ke Agen Layanan Cloud Build pada secret, dengan SECRET_NAME adalah nama secret Anda seperti yang disimpan di Secret Manager:

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

  5. Buat koneksi GitHub Anda:

      gcloud builds connections create github CONNECTION_NAME \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/1  \
    --app-installation-id=INSTALLATION_ID --region=REGION

    Dengan:

    • CONNECTION_NAME adalah nama koneksi host GitHub Anda di Cloud Build.
    • PROJECT_ID adalah Google Cloud project ID Anda.
    • SECRET_NAME adalah nama secret Anda seperti yang disimpan di Secret Manager.
    • INSTALLATION_ID adalah ID penginstalan aplikasi GitHub Anda. ID penginstalan Anda dapat ditemukan di URL Aplikasi GitHub Cloud Build Anda. Pada URL berikut, https://github.com/settings/installations/1234567, ID penginstalan adalah nilai numerik 1234567.
    • REGION adalah region untuk koneksi Anda.

Menghubungkan repositori GitHub

Konsol

Untuk menghubungkan repositori GitHub ke koneksi host, selesaikan langkah-langkah berikut:

  1. Buka halaman Repositori di Google Cloud konsol.

    Buka halaman Repositori

    Anda akan melihat halaman Repositories.

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

  3. Klik Link Repositories untuk menautkan repositori dari koneksi Anda.

    Anda akan melihat panel Connect Repositories.

  4. Di panel Connect Repositories, masukkan informasi berikut:

    1. Koneksi: Pilih koneksi dari menu drop-down.

    2. Repositori: Pilih repositori yang akan ditautkan ke koneksi Anda.

    3. Nama Repositori: Masukkan nama untuk repositori Anda.

      1. Dibuat: Pilih opsi ini agar Cloud Build otomatis membuat nama repositori untuk Anda bagi repositori yang dipilih.

      2. Manual: Pilih opsi ini untuk menentukan nama secara manual bagi repositori yang Anda pilih.

        Jika memilih Manual, Anda dapat mengubah nama repositori yang dipilih di bagian Nama repositori.

  5. Klik Link untuk menautkan repositori ke koneksi Anda.

gcloud

Untuk menambahkan repositori GitHub ke koneksi Anda, masukkan perintah berikut:

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

Dengan:

  • REPO_NAME adalah nama repositori Anda.
  • REPO_URI adalah link ke repositori GitHub Anda. Contoh, https://github.com/cloud-build/test-repo.git.
  • CONNECTION_NAME adalah nama yang diberikan ke koneksi host GitHub Enterprise yang dibuat di Cloud Build dari Menghubungkan ke host GitHub.
  • REGION adalah region untuk koneksi Anda.

Terraform

Untuk menambahkan repositori GitHub ke koneksi Anda, tambahkan cuplikan kode berikut ke konfigurasi Terraform Anda:

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

Dengan:

  • PROJECT_ID adalah Google Cloud project ID Anda.
  • REPO_NAME adalah nama repositori GitHub Anda.
  • REGION adalah region untuk koneksi Anda.
  • URI adalah URI host repositori Anda. Contoh, https://github.com/myuser/myrepo.git.

Langkah berikutnya