Mengotomatiskan build sebagai respons terhadap peristiwa webhook

Cloud Build memungkinkan Anda menentukan pemicu webhook untuk mengautentikasi dan menerima peristiwa webhook yang masuk. Peristiwa ini, yang dikirim ke URL kustom, memungkinkan Anda menghubungkan sistem eksternal dan platform pengelolaan kode sumber, seperti Bitbucket.com, Bitbucket Server, atau GitLab, langsung ke Cloud Build.

Dengan pemicu webhook, Anda dapat menentukan konfigurasi build inline, bukan repositori sumber. Konfigurasi inline ini memberi Anda kontrol atas operasi Git dan alur kerja build. Untuk mengotomatiskan build pada peristiwa repositori, Anda dapat menggunakan pemicu repositori Cloud Build, yang terintegrasi langsung dengan penyedia seperti GitHub dan GitLab.

Dengan pemicu webhook, Anda dapat menentukan file konfigurasi build inline, bukan menentukan sumber saat membuat pemicu. Konfigurasi build inline memberi Anda kontrol atas operasi Git dan memungkinkan Anda menentukan sisa build.

Halaman ini menguraikan cara membuat pemicu webhook untuk mengotomatiskan build sebagai respons terhadap peristiwa webhook.

Sebelum memulai

  • Aktifkan Cloud Build API dan Secret Manager API, jika belum diaktifkan.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

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

  • Jika pemicu webhook Anda menggunakan repositori Cloud Build sebagai sumber, pastikan Anda memahami repositori Cloud Build.

Membuat pemicu webhook

Konsol

Untuk membuat pemicu webhook menggunakan konsol Google Cloud :

  1. Buka halaman Pemicu:

    Buka halaman pemicu build

  2. Pilih project Anda dari bagian atas halaman, lalu klik Open.

  3. Klik Create trigger.

  4. Masukkan setelan pemicu berikut:

    • Nama: Nama untuk pemicu Anda.

    • Region: Pilih region untuk pemicu Anda.

      • Jika file konfigurasi build yang terkait dengan pemicu menentukan pool pribadi, Cloud Build akan menggunakan pool pribadi untuk menjalankan build Anda. Dalam hal ini, region yang Anda tentukan dalam pemicu harus cocok dengan region tempat Anda membuat pool pribadi.
      • Jika file konfigurasi build yang terkait dengan pemicu tidak menentukan pool pribadi, Cloud Build akan menggunakan pool default untuk menjalankan build Anda di region yang sama dengan pemicu Anda.

    • Description (Opsional): Deskripsi untuk pemicu Anda.

    • Peristiwa: Pilih Peristiwa webhook untuk menyiapkan pemicu agar memulai build sebagai respons terhadap peristiwa webhook yang masuk.

    • URL Webhook: Gunakan URL webhook untuk mengautentikasi peristiwa webhook yang masuk. Anda memerlukan rahasia untuk mengautentikasi peristiwa webhook masuk. Anda dapat membuat secret baru atau menggunakan secret yang sudah ada. Rahasia ini terpisah dari rahasia yang terkait dengan kunci SSH Anda.

      Untuk membuat secret:

      1. Pilih Use a new secret (generated by Cloud Build).

      2. Klik Buat Secret.

        Anda akan melihat dialog Create a webhook secret.

      3. Di kolom Secret name, masukkan nama untuk secret Anda.

      4. Klik Create secret untuk menyimpan secret Anda, yang akan otomatis dibuat dan disimpan untuk Anda di Secret Manager.

      Untuk menggunakan secret yang ada:

      1. Pilih Use an existing secret or create your own.
      2. Di kolom Secret, pilih nama secret yang ingin Anda gunakan dari menu drop-down atau ikuti petunjuk untuk menambahkan secret berdasarkan ID resource.

      3. Di kolom Secret version, pilih versi secret Anda dari menu drop-down.

        Jika menggunakan secret yang ada, Anda mungkin perlu memberikan peran Secret Manager Secret Accessor secara manual ke akun layanan Cloud Build, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Untuk mempelajari lebih lanjut, lihat Memberikan peran Secret Manager ke akun layanan Anda.

        Setelah membuat atau memilih rahasia, Anda akan melihat Pratinjau URL webhook. URL Anda akan berisi kunci API yang dibuat oleh Cloud Build dan secret Anda. Jika Cloud Build tidak dapat mengambil kunci API, Anda dapat menambahkan kunci API secara manual ke URL atau mempelajari cara mendapatkan kunci API jika Anda belum memilikinya.

        Anda dapat menggunakan URL untuk memanggil peristiwa webhook dengan membuat permintaan HTTP menggunakan metode POST.

        Setelah menyelesaikan langkah-langkah ini, peran Secret Manager Secret Accessor akan otomatis diberikan ke agen layanan Cloud Build Anda, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. Jika Anda tidak melihat peran ini ditambahkan secara otomatis ke agen layanan, selesaikan langkah-langkah berikut yang diuraikan dalam Memberikan peran Secret Manager ke akun layanan Anda.

    • Source (opsional): Jika Anda menentukan konfigurasi build inline, Anda tidak perlu menentukan sumber. Jika tidak, lakukan hal berikut:

      • Repository generation: Pilih 2nd generation.

      • Repository: Dari daftar repositori yang tersedia, pilih repositori yang ingin Anda bangun. Region repositori Anda harus cocok dengan region pemicu Anda.

      • Branch atau Tag: Tentukan ekspresi reguler dengan cabang atau nilai tag agar sesuai. Untuk mengetahui informasi mengenai sintaksis ekspresi reguler yang dapat diterima, lihat sintaksis RE2.

      • Kontrol komentar: Jika Anda memilih Permintaan pull sebagai Peristiwa, pilih salah satu opsi berikut untuk mengontrol apakah pemicu akan otomatis memanggil build:

        • Wajib kecuali untuk pemilik dan kolaborator: Saat permintaan pull dibuat atau diperbarui oleh pemilik atau kolaborator repositori, build akan dijalankan secara otomatis. Jika kontributor eksternal memulai tindakan, build hanya akan dijalankan setelah pemilik atau kolaborator mengomentari /gcbrun pada permintaan pull.

        • Required: Saat permintaan pull dibuat atau diperbarui oleh kontributor mana pun, build hanya dijalankan setelah pemilik atau kolaborator memberikan komentar /gcbrun pada permintaan pull. Build dijalankan setiap kali perubahan pada permintaan pull dibuat.

        • Tidak diperlukan: Saat permintaan pull dibuat atau diperbarui oleh kontributor mana pun, build akan dijalankan secara otomatis.

    • Configuration: Pilih file konfigurasi build yang terletak di repositori jarak jauh Anda atau buat file konfigurasi build inline untuk digunakan dalam build Anda. Jika Anda tidak menentukan repositori sumber, Anda harus memilih file konfigurasi build Inline sebagai opsi konfigurasi:

      • Type: Pilih jenis konfigurasi yang akan digunakan untuk build Anda.

        • File konfigurasi Cloud Build (yaml atau json): Gunakan file konfigurasi build untuk konfigurasi Anda.
        • Dockerfile: Gunakan Dockerfile untuk konfigurasi Anda.
        • Buildpack: Gunakan buildpack untuk konfigurasi Anda.

      • Lokasi: Tentukan lokasi untuk konfigurasi Anda.

        • Repository: Jika file konfigurasi Anda berada di repositori jarak jauh, berikan lokasi file konfigurasi build, direktori Dockerfile, atau direktori buildpack. Jika jenis konfigurasi build Anda adalah Dockerfile atau buildpack, Anda harus memberikan nama untuk image yang dihasilkan dan secara opsional, waktu tunggu untuk build Anda. Setelah memberikan nama image Dockerfile atau buildpack, Anda akan melihat pratinjau perintah docker build atau pack yang akan dijalankan oleh build Anda.
        • Variabel lingkungan buildpack (opsional): Jika Anda memilih buildpacks sebagai jenis konfigurasi, klik Tambahkan variabel lingkungan paket untuk menentukan variabel dan nilai lingkungan buildpack Anda. Untuk mempelajari lebih lanjut variabel lingkungan buildpack, lihat Variabel lingkungan.

        • Inline: Jika Anda memilih Cloud Build configuration file (yaml or json) sebagai opsi konfigurasi, Anda dapat menentukan konfigurasi build secara inline. Klik Open Editor untuk menulis file konfigurasi build di konsolGoogle Cloud menggunakan sintaksis YAML atau JSON. Klik Done untuk menyimpan konfigurasi build Anda.

      Dalam contoh berikut, log file konfigurasi build inline menampilkan "Halo Dunia":

       steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']

    • Substitutions (opsional): Jika Anda memilih file konfigurasi build sebagai opsi konfigurasi build atau membuat file konfigurasi build inline, Anda dapat memilih untuk menentukan variabel substitusi khusus pemicu menggunakan kolom ini. Anda juga dapat memperoleh data menggunakan binding payload saat menentukan nilai variabel substitusi.

    • Filter (opsional): Anda dapat membuat aturan dalam pemicu yang menentukan apakah pemicu akan menjalankan build berdasarkan variabel substitusi atau tidak.

  5. Klik Create untuk membuat pemicu build Anda.

gcloud

Untuk membuat pemicu webhook:

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

Dengan:

  • TRIGGER_CONFIG_PATH Adalah jalur ke file konfigurasi pemicu. Jika Anda menggunakan file konfigurasi pemicu, kolom name, description, region, secret, service-account, subscription-filter, dan substitution harus tetap tidak ditentukan. Untuk mengetahui informasi selengkapnya, lihat BuildTrigger dalam dokumentasi referensi Cloud Build.
  • TRIGGER_NAME adalah nama pemicu Anda.
  • DESCRIPTION (Opsional) adalah deskripsi untuk pemicu Anda.
  • REGION adalah region untuk pemicu Anda. Nilai ini harus berupa region selain "global".
  • SECRET_NAME adalah nama secret Anda seperti yang disimpan di Secret Manager.
  • SECRET_VERSION adalah versi yang terkait dengan secret Anda seperti yang disimpan di Secret Manager.
  • SERVICE_ACCOUNT adalah akun layanan yang digunakan untuk menjalankan semua operasi yang dikontrol pengguna yang terkait dengan pemicu build Anda. Jika Anda tidak menentukan akun layanan, Cloud Build akan menggunakan akun layanan Cloud Build default.
  • PROJECT_ID adalah project ID Google Cloud Anda.
  • CONNECTION_NAME adalah nama koneksi host Anda.
  • REPO_NAME adalah nama repositori Anda.
  • PATH_TO_BUILD_CONFIG adalah jalur ke file konfigurasi build. Gunakan parameter ini jika pemicu Anda merujuk ke file konfigurasi build di repositori Cloud Build. Jika Anda menetapkan parameter ini, Anda tidak dapat menentukan inline-config atau menggunakan parameter untuk Dockerfile.
  • PATH_TO_INLINE_BUILD_CONFIG adalah jalur ke konfigurasi build inline. Gunakan parameter ini jika pemicu mengacu pada file konfigurasi build lokal. Jika menetapkan parameter ini, Anda tidak dapat menentukan build-config atau menggunakan parameter untuk Dockerfile.
  • DOCKERFILE adalah jalur ke Dockerfile. Gunakan parameter ini jika pemicu Anda merujuk ke Dockerfile. Jika menetapkan parameter Dockerfile, Anda tidak dapat menentukan build-config atau inline-config.
  • DOCKERFILE_DIR adalah direktori Dockerfile.
  • DOCKERFILE_IMAGE adalah nama image Docker yang di-build oleh Cloud Build.
  • BRANCH_NAME adalah nama cabang Anda jika Anda ingin menetapkan pemicu untuk di-build di cabang. Jika menetapkan parameter ini, Anda tidak dapat menentukan tag.
  • TAG_NAME adalah nama tag jika Anda ingin menetapkan pemicu untuk mem-build pada tag. Jika Anda menetapkan parameter ini, Anda tidak dapat menentukan branch.
  • SUBSTITUTION (Opsional) adalah parameter yang akan diganti dalam spesifikasi build. Contoh, _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'.
  • FILTER (Opsional) adalah ekspresi filter CEL untuk pemicu, seperti '_SUB_ONE == "prod"'.
  • (Opsional) Jika --require-approval ada dalam perintah, Cloud Build memerlukan persetujuan manual untuk build yang dipicu.

Memanggil peristiwa webhook

Gunakan perintah berikut untuk memanggil peristiwa webhook:

curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

(Opsional) Memberikan peran Secret Manager ke akun layanan Anda

Saat Anda mengonfigurasi secret selama pembuatan pemicu webhook, dalam sebagian besar kasus, Cloud Build akan otomatis memberikan peran Secret Manager Secret Accessor ke akun layanan yang memerlukan peran tersebut. Namun, jika menggunakan secret yang sudah ada, Anda mungkin juga perlu memberikan peran Secret Manager Secret Accessor secara manual ke akun layanan Cloud Build:

  1. Buka halaman IAM di konsol Google Cloud :

    Buka halaman IAM

  2. Opsional: Untuk melihat akun yang disediakan Google, pilih kotak centang Sertakan pemberian peran yang disediakan Google.

  3. Catat akun layanan build yang ingin Anda beri peran.

  4. Buka halaman Secret Manager di konsol Google Cloud :

    Buka halaman Secret Manager

  5. Klik nama secret Anda.

    Anda akan melihat halaman Secret details.

    1. Klik tab Permissions.

    2. Klik Grant access.

      Anda akan melihat panel Berikan akses.

    3. Di bagian Add Principals, tambahkan email yang terkait dengan akun layanan build.

    4. Di bagian Assign roles, pilih Secret Manager > Secret Manager Secret Accessor.

    5. Klik Simpan.

(Opsional) Mendapatkan kunci API

Untuk mengautentikasi peristiwa webhook masuk, Anda memerlukan kunci API. Kunci API ini adalah bagian dari secret yang Anda pilih saat mengonfigurasi pemicu webhook. Jika Anda belum memiliki kunci API, atau Cloud Build tidak dapat mengambilnya saat mengonfigurasi secret di konsol Google Cloud , Anda dapat membuat kunci API secara manual:

Untuk mendapatkan kunci API:

  1. Buka halaman Credentials di konsol Google Cloud :

    Buka halaman Credentials

  2. Klik Buat kredensial.

  3. Klik kunci API.

    Anda akan melihat dialog dengan kunci API yang telah dibuat. Catat kunci API Anda.

  4. Jika Anda ingin membatasi kunci untuk aplikasi produk, klik Restrict key untuk menyelesaikan langkah-langkah tambahan guna mengamankan kunci Anda. Jika tidak, klik Close.

    Untuk mempelajari cara membatasi kunci, lihat Menerapkan pembatasan kunci API.

Langkah berikutnya