Mengotomatiskan build sebagai respons terhadap peristiwa webhook

1st gen 2nd gen

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

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 bagian build lainnya.

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

Catatan: Jika Anda membuat pemicu yang mengotomatiskan build pada peristiwa repositori, sebaiknya gunakan pemicu repositori Cloud Build. Pemicu repositori yang menggunakan repositori Cloud Build (generasi ke-2) dapat dikonfigurasi secara terprogram dan terintegrasi dengan penyedia sumber, termasuk dukungan untuk GitHub dan GitLab. Repositori Cloud Build (generasi ke-2) juga mengelola token autentikasi dan informasi atas nama Anda menggunakan Secret Manager. Pemicu repositori memungkinkan Anda memfilter peristiwa masuk dan memposting status build kembali ke penyedia sumber, serta dapat dikonfigurasi untuk bekerja dengan jaringan pribadi. Untuk mempelajari lebih lanjut, lihat halaman Ringkasan repositori.

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

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

  Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru yang tersedia dengan menjalankan gcloud components update.

• 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 Google Cloud konsol:

1. Buka halaman Pemicu:

   Buka halaman Pemicu build

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

3. Klik Buat pemicu.

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.

   • Deskripsi (Opsional): Deskripsi untuk pemicu Anda.

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

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

     Untuk membuat secret:

     1. Pilih Gunakan secret baru (dibuat oleh Cloud Build).

     2. Klik Buat Secret.

        Anda akan melihat dialog Buat secret webhook.

     3. Di kolom Nama secret, masukkan nama untuk secret Anda.

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

     Untuk menggunakan secret yang ada:

     1. Pilih Gunakan secret yang ada atau buat secret Anda sendiri.
     2. Di kolom Secret, pilih nama secret yang ingin Anda gunakan dari menu dropdown atau ikuti petunjuk untuk menambahkan secret berdasarkan ID resource.

     3. Di kolom Versi secret, pilih versi secret Anda dari menu dropdown.

        Jika menggunakan secret yang ada, Anda mungkin perlu memberikan peran Secret Manager Secret Accessor secara manual ke akun layanan Cloud Build Anda, 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 secret, 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, 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 otomatis ditambahkan ke agen layanan Anda, selesaikan langkah-langkah berikut yang diuraikan dalam Memberikan peran Secret Manager ke akun layanan Anda.

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

     • Generasi repositori: Pilih Generasi ke-2.

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

     • Cabang atau Tag: Tentukan ekspresi reguler dengan nilai cabang atau tag agar sesuai. Untuk mengetahui informasi mengenai sintaksis regular expression 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:

       Peringatan: Pengguna mana pun yang memiliki akses baca ke repositori dapat mengirimkan permintaan pull, yang mungkin menjalankan build yang menyertakan perubahan pada kode sumber dalam permintaan pull. Untuk menonaktifkan perilaku ini, sebaiknya gunakan persetujuan manual untuk mengontrol build saat membuat permintaan pull di repositori publik. Anda juga dapat mempelajari lebih lanjut tentang hak istimewa waktu build pemicu.

       • 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.

       • Wajib: Saat permintaan pull dibuat atau diperbarui oleh kontributor mana pun, build hanya akan dijalankan setelah pemilik atau kolaborator mengomentari /gcbrun pada permintaan pull. Build dijalankan setiap kali perubahan dilakukan pada permintaan pull.

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

   • Konfigurasi: 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:

     • Jenis: 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.

       • Repositori: Jika file konfigurasi Anda berada di repositori jarak jauh, berikan lokasi file konfigurasi build, Dockerfile direktori, 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 File konfigurasi Cloud Build (yaml atau json) sebagai opsi konfigurasi, Anda dapat menentukan konfigurasi build inline. Klik Buka Editor untuk menulis file konfigurasi build di Google Cloud konsol menggunakan sintaksis YAML atau JSON. Klik Selesai untuk menyimpan konfigurasi build Anda.

         Catatan: Dukungan konfigurasi build inline tidak tersedia untuk Dockerfile atau buildpack.

     Dalam contoh berikut, file konfigurasi build inline mencatat gema "hello world":

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

   • Substitusi (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 Anda.

5. Klik Buat untuk membuat pemicu build.

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 Google Cloud project ID 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 merujuk ke file konfigurasi build lokal. Jika Anda 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 Anda menetapkan parameter Dockerfile, Anda tidak dapat menentukan build-config atau inline-config.
• DOCKERFILE_DIR adalah direktori Dockerfile.
• DOCKERFILE_IMAGE adalah nama image Docker yang dibangun Cloud Build.
• BRANCH_NAME adalah nama cabang Anda jika Anda ingin menetapkan pemicu untuk membangun cabang. Jika Anda menetapkan parameter ini, Anda tidak dapat menentukan tag.
• TAG_NAME adalah nama tag Anda jika Anda ingin menetapkan pemicu untuk membangun tag. Jika Anda menetapkan parameter ini, Anda tidak dapat menentukan branch.
• SUBSTITUTION (Opsional) adalah parameter yang akan diganti dalam spesifikasi build. Misalnya, _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 akan 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 Anda menggunakan secret yang ada, Anda mungkin juga perlu memberikan peran Secret Manager Secret Accessor secara manual ke akun layanan Cloud Build Anda:

1. Buka halaman IAM di Google Cloud konsol:

   Buka halaman IAM

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

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

4. Buka halaman Secret Manager di Google Cloud konsol:

   Buka halaman Secret Manager

5. Klik nama secret Anda.

   Anda akan melihat halaman Detail secret.

   1. Klik tab Permissions.

   2. Klik Grant access.

      Anda akan melihat panel Grant access.

   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 Google Cloud konsol, Anda dapat membuat kunci API secara manual:

Cara mendapatkan kunci API:

1. Buka halaman Credentials di Google Cloud konsol:

   Buka halaman Credentials

2. Klik Create credentials.

3. Klik API Key.

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

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

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

Langkah berikutnya

• Pelajari cara membuat dan mengelola pemicu.
• Pelajari cara membangun repositori yang dihosting di Bitbucket Server.
• Pelajari cara memulai build secara manual.
• Pelajari cara melihat hasil build.
• Pelajari cara memecahkan masalah error build.