Mengotomatiskan build sebagai respons terhadap peristiwa webhook

generasi ke-1 generasi ke-2

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 secara langsung, seperti Bitbucket.com, Bitbucket Server, atau GitLab, ke Cloud Build melalui peristiwa webhook.

Dengan pemicu webhook, Anda dapat menentukan file konfigurasi build inline daripada menentukan sumber saat membuat pemicu. Konfigurasi build inline memberi Anda kontrol atas operasi Git dan memungkinkan Anda menentukan 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 dan informasi autentikasi untuk Anda menggunakan Secret Manager. Pemicu repositori memungkinkan Anda memfilter peristiwa masuk dan memposting status build kembali ke penyedia sumber, dan juga 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 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 Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

  Aktifkan API

• Untuk menggunakan perintah gcloud 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 konsol Google Cloud :

1. Buka halaman Pemicu:

   Buka halaman Pemicu build

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

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 kumpulan pribadi, maka Cloud Build akan menggunakan kumpulan pribadi untuk menjalankan build Anda. Dalam hal ini, region yang Anda tentukan di pemicu harus cocok dengan region tempat Anda membuat pool pribadi.
     • Jika file konfigurasi build yang terkait dengan pemicu tidak menentukan kumpulan pribadi, Cloud Build akan menggunakan kumpulan default untuk menjalankan build Anda di region yang sama dengan pemicu.

   • Deskripsi (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 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 dibuat dan disimpan secara otomatis 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 drop-down atau ikuti petunjuk untuk menambahkan secret menurut ID resource.

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

        Jika menggunakan secret yang ada, Anda mungkin perlu memberikan peran Secret Manager Secret Accessor ke akun layanan Cloud Build Anda secara manual, 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, 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 kepada 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.

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

     • Pembuatan repositori: Pilih generasi ke-2.

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

     • Cabang atau Tag: Tentukan ekspresi reguler dengan cabang atau nilai tag yang akan dicocokkan. 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 otomatis memanggil build:

       Peringatan: Setiap pengguna dengan akses baca ke repositori dapat mengirimkan permintaan pull, yang dapat menjalankan build yang mencakup perubahan pada kode sumber dalam permintaan pull. Untuk menonaktifkan perilaku ini, sebaiknya gunakan persetujuan manual untuk membatasi pembuatan saat membuat permintaan pull di repositori publik. Anda juga dapat mempelajari lebih lanjut 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 dijalankan setelah pemilik atau kolaborator mengomentari /gcbrun pada permintaan pull.

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

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

   • Konfigurasi: Pilih file konfigurasi build yang ada 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.
       • Buildpacks: Gunakan buildpacks untuk konfigurasi Anda.

     • Lokasi: Tentukan lokasi untuk konfigurasi Anda.

       • Repositori: 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 build Anda.
       • Variabel lingkungan buildpack (opsional): Jika Anda memilih buildpacks sebagai jenis konfigurasi, klik Tambahkan variabel lingkungan paket untuk menentukan variabel lingkungan dan nilai buildpack. 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 secara inline. Klik Open 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 echo "hello world":

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

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

   • 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 wilayah 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 terkait 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 dibuat Cloud Build.
• BRANCH_NAME adalah nama cabang Anda jika Anda ingin menyetel pemicu untuk membangun di cabang. Jika Anda menetapkan parameter ini, Anda tidak dapat menentukan tag.
• TAG_NAME adalah nama tag Anda jika Anda ingin menyetel pemicu untuk membangun 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) Berikan 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 ke akun layanan Cloud Build Anda secara manual:

1. Buka halaman IAM di konsol Google Cloud :

   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 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 Google Cloud console:

   Buka halaman Credentials

2. Klik Buat kredensial.

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 Batasi kunci untuk menyelesaikan langkah-langkah tambahan guna mengamankan kunci Anda. Jika tidak, klik Tutup.

   Untuk mempelajari cara membatasi kunci Anda, lihat Menerapkan pembatasan 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.