Menggunakan binding payload dan ekspansi parameter bash dalam substitusi

Halaman ini menjelaskan cara menggunakan binding payload dan menerapkan ekspansi parameter bash ke variabel penggantian yang terkait dengan pemicu build Anda. Jika Anda tidak terbiasa dengan cara menggunakan variabel penggantian dalam konfigurasi build, lihat Mengganti nilai variabel.

Cloud Build memungkinkan Anda menyimpan bagian payload peristiwa pemicu sebagai variabel penggantian. Payload peristiwa adalah isi peristiwa yang memanggil pemicu. Variabel yang terkait dengan payload disebut sebagai binding dan tersedia untuk build yang dipanggil oleh peristiwa push dan pull. Dengan binding, Anda dapat mengakses data tambahan yang terkait dengan build, seperti bahasa yang terkait dengan kode sumber dan penulis permintaan pull.

Cloud Build juga memungkinkan pengguna menerapkan perluasan parameter bash ke nilai variabel penggantian. Perluasan parameter bash memungkinkan Anda mengakali string yang terkait dengan variabel yang ada. Anda dapat memanipulasi string dengan menggunakan huruf besar atau mengganti substring.

Anda dapat menggunakan binding payload dan menerapkan perluasan parameter bash saat menentukan atau memperbarui pemicu build di konsol Google Cloud dan di file konfigurasi Cloud Build. Selain itu, Anda dapat menerapkan perluasan parameter bash saat menjalankan build manual.

Binding payload

Anda dapat menyimpan bagian payload peristiwa pemicu sebagai nilai variabel penggantian. Binding payload tersedia sebagai nilai variabel untuk build yang dipanggil oleh peristiwa push dan pull, dan dapat digunakan untuk mengakses payload JSON saat kode sumber Anda berada di repositori GitHub atau Cloud Source Repositories. Untuk mempelajari payload peristiwa GitHub lebih lanjut, lihat Payload peristiwa webhook. Untuk mempelajari payload peristiwa untuk Cloud Source Repositories lebih lanjut, lihat Notifikasi untuk Cloud Source Repositories.

Anda dapat mengakses informasi dari payload peristiwa menggunakan awalan yang ditetapkan, yang mewakili root payload peristiwa. Dimulai dengan awalan, Anda dapat menggunakan sintaksis JSONPath untuk mengakses payload dan mengambil data darinya. Awalan payload berikut tersedia bergantung pada jenis peristiwa Anda:

Awalan Sumber Deskripsi
push GitHub Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa push
pull_request GitHub Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa permintaan pull
issue_comment GitHub Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa komentar masalah yang terkait dengan permintaan pull
csr Cloud Source Repositories Memungkinkan Anda mengakses kolom dalam payload JSON untuk peristiwa push

Untuk peristiwa apa pun yang terkait dengan aplikasi GitHub, nilai variabel bawaan is_collaborator dan perm_level juga tersedia. Status pengguna diperiksa untuk peristiwa push dan pull berdasarkan nilai variabel push.pusher.name, pull_request.pull_request.user.login, dan issue_comment.comment.user.login. Tabel berikut menunjukkan cara menyertakannya sebagai nilai variabel untuk pemicu saat kode sumber Anda berada di GitHub:

Nama Variabel Nilai Variabel Deskripsi Variabel
_PERM_LEVEL $(perm_level) Mendapatkan tingkat izin pengguna
_IS_COLLABORATOR $(is_collaborator) Output true jika pengguna adalah kolaborator

Anda dapat menggunakan nilai variabel is_collaborator dan perm_level untuk peristiwa push, peristiwa permintaan pull, dan peristiwa permintaan pull yang dibatasi oleh komentar. Anda tidak perlu mendahului nilai variabel ini dengan awalan.

Membuat penggantian menggunakan binding payload

Untuk membuat variabel penggantian yang menggunakan binding payload:

  1. Buka halaman Pemicu.

  2. Jika Anda belum membuat pemicu build, klik Create trigger. Atau, pilih pemicu yang ada.

  3. Di bagian Substitution variables, klik Add variable.

  4. Tambahkan nama untuk Variabel Anda dengan mengikuti konvensi yang diuraikan di bawah ini:

    • Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mengikuti ekspresi reguler [A-Z0-9_]+). Hal ini mencegah konflik dengan penggantian bawaan.

    • Jumlah parameter dibatasi hingga 100 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

    Untuk mempelajari lebih lanjut cara menentukan dan menggunakan penggantian yang ditentukan pengguna, lihat Menggunakan penggantian yang ditentukan pengguna.

  5. Tambahkan nilai untuk variabel Anda, menggunakan awalan yang didukung.

    Jika kode sumber Anda ada di GitHub, Anda dapat merujuk ke informasi dalam payload peristiwa dalam variabel penggantian menggunakan binding payload. Untuk mengakses payload JSON peristiwa push, gunakan awalan push atau body. Dalam contoh berikut, awalan push dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

    Nama Variabel Nilai Variabel Deskripsi Variabel
    _PUSH_NAME $(push.repository.name) Mendapatkan nama repositori yang terkait dengan peristiwa push
    _COMMITS $(push.commits) Mendapatkan array objek commit yang menjelaskan setiap commit yang didorong
    _OWNER $(push.repository.owner.name) Mendapatkan nama pemilik repositori
    _URL $(push.repository.html_url) Mendapatkan URL untuk repositori GitHub Anda
    _LANGUAGE $(push.repository.language) Mendapatkan bahasa kode sumber Anda yang disertakan dalam push

    Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan push, lihat PushEvent.

    Untuk mengakses payload JSON peristiwa permintaan pull, gunakan awalan pull_request atau body. Dalam contoh berikut, awalan pull_request dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

    Nama Variabel Nilai Variabel Deskripsi Variabel
    _PULL_REQUEST_ID $(pull_request.pull_request.id) Mendapatkan ID permintaan pull
    _PULL_REQUEST_TITLE $(pull_request.pull_request.title) Mendapatkan judul permintaan pull
    _PULL_REQUEST_BODY $(pull_request.pull_request.body) Mendapatkan isi permintaan pull
    _USERNAME $(pull_request.pull_request.user.login) Mendapatkan nama pengguna pengirim permintaan pull
    _MERGE_TIME $(pull_request.pull_request.merged_at) Mendapatkan waktu permintaan pull digabungkan

    Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan pull_request, lihat PullRequestEvent.

    Untuk mengakses payload JSON peristiwa commit, gunakan awalan commit. Dalam contoh berikut, awalan commit dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

    Nama Variabel Nilai Variabel Deskripsi Variabel
    _COMMIT_URL $(commit.url) Mendapatkan URL yang terkait dengan commit
    _COMMIT_USER $(commit.author.login) Mendapatkan nama pengguna penulis commit
    _COMMIT_MESSAGE $(commit.commit.message) Mendapatkan pesan commit yang terkait dengan commit
    _COMMIT_DATE $(commit.commit.committer.date) Mendapatkan tanggal yang terkait dengan commit
    _COMMIT_ADDITIONS $(commit.files['*'].additions) Mendapatkan jumlah penambahan yang terkait dengan file dalam commit

    Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan commit, lihat Mendapatkan commit.

    Jika Anda mengaktifkan Kontrol komentar untuk pemicu yang dipanggil oleh permintaan pull, peristiwa yang memanggil pemicu adalah IssueCommentEvent dan awalan terkaitnya adalah issue_comment. Dalam contoh berikut, awalan issue_comment dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda:

    Nama Variabel Nilai Variabel Deskripsi Variabel
    _PULL_REQUEST_ID $(issue_comment.issue.id) Mendapatkan ID permintaan pull
    _PULL_REQUEST_TITLE $(issue_comment.issue.title) Mendapatkan judul permintaan pull
    _STATE $(issue_comment.state) Mendapatkan status permintaan pull (yaitu terbuka, tertutup, dll.)
    _LABELS $(issue_comment.issue.labels) Mendapatkan daftar label yang terkait dengan permintaan pull
    _LABELS_URL $(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url) Mendapatkan URL yang terkait dengan label yang cocok dengan deskripsi

    Untuk mengetahui daftar kolom yang dapat Anda akses menggunakan awalan issue_comment, lihat IssueCommentEvent.

    Jika kode sumber Anda berada di Cloud Source Repositories, Anda dapat merujuk ke informasi dalam payload peristiwa dalam variabel penggantian menggunakan binding payload. Untuk mengakses payload JSON dari peristiwa push, gunakan awalan csr atau body. Dalam contoh berikut, awalan csr dalam nilai variabel digunakan sebagai titik entri untuk mengakses informasi dari payload JSON build Anda.

    Nama Variabel Nilai Variabel Deskripsi Variabel
    _REPO_NAME $(csr.name) Mendapatkan nama repositori Anda
    _REPO_URL $(csr.url) Mendapatkan URL repositori Anda
    _CREATED_REPO $(csr.createRepoEvent) Menunjukkan apakah pengguna membuat repositori
    _REF_EVENT_NAME $(csr.refUpdateEvent.refUpdates['*'].refName) Nama ref (misalnya, "refs/heads/primary-branch")

    Untuk melihat kolom tambahan yang dapat Anda akses di Cloud Source Repositories, lihat Data notifikasi.

Ekspansi parameter bash

Anda dapat menerapkan ekspansi parameter bash ke variabel default dan variabel yang ditentukan pengguna. Contoh operasi yang didukung meliputi penggantian substring, pemotongan string, dan kapitalisasi. Misalnya, Anda mungkin ingin mengganti substring dalam variabel default dan menggunakan variabel tersebut sebagai tag gambar.

Ekspansi parameter bash yang dapat Anda tentukan untuk variabel penggantian adalah sebagai berikut:

Ekspansi bash Deskripsi
${var} Memperluas nilai string yang disimpan di var
${var^} Mengubah huruf pertama dalam string menjadi huruf kapital
${var^^} Mengapitalisasi semua karakter dalam string
${var,} Mengubah karakter pertama dalam string menjadi huruf kecil
${var,,} Mengubah semua karakter dalam string menjadi huruf kecil
${var:position} Menghapus karakter position pertama dari string
${var:position:length} Memotong string mulai dari nilai numerik yang ditentukan di position dan menyertakan hingga nilai numerik yang ditentukan di length
${var/substring/replacement} Mengganti instance paling kiri dari nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement
${var//substring/replacement} Mengganti semua instance nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement
${var/#substring/replacement} Mengganti instance pertama nilai yang ditentukan dalam substring dengan nilai yang ditentukan dalam replacement hanya jika substring adalah awalan var
${var/%substring/replacement} Mengganti instance terakhir nilai yang ditentukan di substring dengan nilai yang ditentukan di replacement hanya jika substring adalah akhiran dari var
${#var} Mengambil panjang string
${var:-default} Mengevaluasi var ke default kecuali jika var sudah ditentukan

Anda juga dapat menentukan pola yang akan dicocokkan untuk perluasan parameter bash berikut:

Ekspansi bash Deskripsi
${var#pattern} Menghapus karakter dari sisi kiri string hingga dan termasuk instance paling kiri dari pattern yang ditentukan
${var##pattern} Menghapus karakter dari sisi kiri string hingga dan termasuk instance paling kanan dari pattern yang ditentukan
${var%pattern} Menghapus karakter dari sisi kanan string hingga dan termasuk instance pertama pattern yang ditentukan
${var%%pattern} Menghapus karakter dari sisi kanan string hingga dan termasuk instance paling kiri dari pattern yang ditentukan

Pola yang dapat Anda tentukan meliputi:

Pola Deskripsi
* Mencocokkan nol karakter atau lebih alfanumerik
? Mencocokkan satu karakter alfanumerik
[ccc] Mencocokkan satu karakter apa pun di ccc termasuk rentang antara a-z atau 0-9
[^c] Mencocokkan karakter alfanumerik apa pun yang tidak ada di c, termasuk rentang karakter dengan lo <= c <= hi
c Mencocokkan karakter alfanumerik apa pun c
\c Mencocokkan karakter c apa pun, termasuk karakter non-alfanumerik seperti *, ?, atau \

Menerapkan ekspansi parameter bash

Untuk menerapkan ekspansi parameter bash ke variabel penggantian bawaan atau buatan pengguna:

  1. Buka halaman Pemicu.

  2. Jika Anda belum membuat pemicu build, klik Create trigger. Atau, pilih pemicu yang ada.

  3. Di bagian Substitution variables, klik Add variable.

  4. Tambahkan nama untuk Variabel Anda dengan mengikuti konvensi yang diuraikan di bawah ini:

    • Substitusi harus dimulai dengan garis bawah (_) dan hanya menggunakan huruf besar dan angka (mengikuti ekspresi reguler [A-Z0-9_]+). Hal ini mencegah konflik dengan penggantian bawaan.

    • Jumlah parameter dibatasi hingga 100 parameter. Panjang kunci parameter dibatasi hingga 100 byte dan panjang nilai parameter dibatasi hingga 4.000 byte.

    Untuk mempelajari lebih lanjut cara menentukan dan menggunakan penggantian yang ditentukan pengguna, lihat Menggunakan penggantian yang ditentukan pengguna.

  5. Tambahkan nilai untuk variabel Anda, dengan menerapkan ekspansi parameter bash yang didukung ke variabel penggantian bawaan atau variabel penggantian buatan pengguna lainnya.

    Dalam contoh berikut, variabel penggantian bawaan $BRANCH_NAME memiliki nilai default Feature_Secret_Project_#v2. Tabel berikut menunjukkan contoh perluasan parameter bash yang dapat Anda terapkan ke $BRANCH_NAME:

    Nama Variabel Ekspansi bash Nilai Variabel Deskripsi
    _BRANCH_LOWERCASE ${$BRANCH_NAME,,} feature_secret_project_#v2 mengubah semua karakter dalam string menjadi huruf kecil
    _BRANCH_NO_SUFFIX ${_BRANCH_LOWERCASE%_\#v2} feature_secret_project menghapus semua karakter dari sisi kanan string yang cocok dengan pola yang ditentukan
    _BRANCH_NO_PREFIX ${_BRANCH_NO_SUFFIX#*_} secret_project menghapus semua karakter hingga garis bawah pertama
    _BRANCH_FOR_IMAGE_NAME ${_BRANCH_NO_PREFIX//_/-} secret-project mengganti semua garis bawah dengan tanda hubung
    _IMAGE_NAME my-app-${_BRANCH_FOR_IMAGE_NAME}-prod my-app-secret-project-prod membuat nama untuk gambar menggunakan variabel _BRANCH_FOR_IMAGE_NAME yang ditentukan di atas

    Misalnya, _IMAGE_NAME ditentukan dalam pemicu Anda sebagai nilai yang ditentukan dalam tabel di atas, my-app-secret-project-prod. Nilai ini sekarang akan menggantikan definisi _IMAGE_NAME apa pun dalam file konfigurasi build Anda. Dalam contoh berikut, nilai variabel yang ditentukan untuk _IMAGE_NAME (my-app-secret-project-prod) akan menggantikan nilai default _IMAGE_NAME (test-image) saat pemicu build dipanggil.

    YAML

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: ['build',
              '-t',
              'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
              '.']
     substitutions:
         _IMAGE_NAME: test-image #default value
     images: [
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
     ]
     options:
         dynamicSubstitutions: true
    

    JSON

     {
       'steps': [
         {
           'name': 'gcr.io/cloud-builders/docker',
           'args': [
             'build',
             '-t',
             'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
             '.'
           ]
         }
       ],
       'substitutions': {
         '_IMAGE_NAME': 'test-image' #default value
       },
       'images': [
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
       ],
       "options": {
         "dynamic_substitutions": true
       }
     }
    

Kolom dynamicSubstitutions, yang ditetapkan ke true dalam contoh di atas, memungkinkan ekspansi parameter bash ditafsirkan. Jika build Anda dipanggil oleh pemicu, kolom dynamicSubstitutions selalu ditetapkan ke true dan tidak perlu ditentukan dalam file konfigurasi build Anda. Jika build dipanggil secara manual, Anda harus menetapkan kolom dynamicSubstitutions ke true agar ekspansi parameter bash ditafsirkan saat menjalankan build.

Menggunakan ekspansi parameter bash dengan binding payload

Anda dapat menerapkan ekspansi parameter bash ke variabel yang terkait dengan binding payload dengan membuat variabel baru untuk mereferensikan variabel yang berisi binding atau menggabungkan binding dengan ekspansi parameter bash. Tabel berikut mencantumkan contoh cara Anda dapat menggunakan ekspansi parameter bash dengan binding payload:

Nama Variabel Nilai Variabel Deskripsi Variabel
_URL $(push.repository.html_url) Mendapatkan URL repositori
_URL_CAPITAL ${_URL^^} Menggunakan ekspansi parameter bash untuk menulis semua karakter dalam URL dalam huruf besar
_APP_NAME my-app-${_URL_CAPITAL} Menambahkan awalan ke URL repositori yang diawali dengan huruf besar
APP_NAME_ID my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7} Membuat nama aplikasi yang menyertakan URL repositori dan tujuh karakter pertama ID payload

Langkah selanjutnya