Cloud Build gagal dengan kesalahan SUBSTITUTIONVARIABLENOT_DEFINED untuk template CI dan skrip validasi substitusi yang menjalankan pipeline tetap

Diterbitkan: 2025-11-29

Cloud Build telah menjadi alat penting dalam integrasi berkelanjutan dan alur kerja penerapan di banyak pengembang dan organisasi. Integrasinya yang erat dengan produk Google Cloud Platform (GCP) lainnya dan alur kerja yang dapat dibuat skrip menjadikannya favorit bagi tim yang menginginkan pipeline CI/CD yang dapat disesuaikan dan diskalakan. Namun, seperti banyak alat canggih lainnya, Cloud Build juga memiliki keunikannya—terutama dalam hal variabel dan parameterisasi. Salah satu masalah frustasi yang dialami oleh banyak pengembang baru-baru ini adalah kesalahanSUBSTITUTION_VARIABLE_NOT_DEFINED. Masalah yang sulit dipahami ini dapat menghentikan seluruh proses pipa, sehingga memengaruhi kecepatan pengembangan dan meningkatkan waktu pemecahan masalah.

TL;DR

Jika pipeline Cloud Build Anda gagal dengan errorSUBSTITUTION_VARIABLE_NOT_DEFINED, kemungkinan besar ini berarti variabel substitusi yang diperlukan tidak ada di pemicu build atau file konfigurasi Anda. Hal ini biasa terjadi saat menggunakan templat CI yang dibagikan ke seluruh repositori. Skrip validasi variabel khusus memperbaikinya dengan memeriksa semua variabel yang diperlukan saat runtime, memberikan masukan yang lebih jelas dan mencegah kesalahan build. Solusi ini juga meningkatkan ketahanan pipeline secara keseluruhan dan meminimalkan upaya proses debug manual.

Memahami Kesalahan SUBSTITUTION_VARIABLE_NOT_DEFINED

ErrorSUBSTITUTION_VARIABLE_NOT_DEFINEDdikeluarkan oleh Cloud Build saat proses build mereferensikan variabel substitusi yang belum ditentukan dalam konteks build tersebut. Variabel substitusi ini memungkinkan Anda menyesuaikan langkah-langkah build dan template tanpa melakukan hardcoding nilai langsung ke pipeline YAML, sehingga meningkatkan kegunaan kembali dan kejelasan.

Misalnya, template Cloud Build umum mungkin menyertakan langkah-langkah build seperti berikut:

tangga:
- nama: 'gcr.io/cloud-builders/docker'
  argumen: ['build', '-t', '${_IMAGE_NAME}', '.']

Di sini, ${_IMAGE_NAME} adalah variabel substitusi yang ditentukan pengguna. Jika variabel ini tidak disediakan pada saat build dipicu, mungkin melalui konfigurasi pemicu atau baris perintah, Cloud Build akan langsung gagal dengan errorSUBSTITUTION_VARIABLE_NOT_DEFINED.

Akar Penyebab dalam Implementasi Templat CI

Masalah ini menjadi sangat merepotkan ketika tim menggunakan templat bersama, atau ketika repositori berbeda mendukung logika CI yang sama melalui konfigurasi YAML terpusat. Seringkali, setiap repositori atau pemicu build mungkin perlu mendefinisikan variabel yang berbeda, namun menegakkan konsistensi menjadi suatu tantangan. Banyak tim menganggap variabel substitusi bersifat opsional atau memiliki fallback default, hanya untuk menemui kesalahan ini ketika variabel tersebut tidak ada dalam konteks build yang mengharapkannya.

Situasi di mana kesalahan ini mungkin muncul:

Ketika nilai default dilupakan dalam pengaturan pemicu
Ketika templat baru ditambahkan tetapi tidak semua variabel yang diperlukan didokumentasikan atau diterapkan
Ketika pengembang mengkloning templat di seluruh lingkungan (misalnya, pementasan, produksi) tetapi menghilangkan definisi variabel tertentu

Perbaikan Pragmatis: Skrip Validasi Substitusi

Untuk mengatasi masalah ini dan mencegah gangguan di masa depan, beberapa tim memperkenalkan mekanisme pra-validasi—skrip validasitertanam yang berjalan di awal pipeline untuk memeriksa variabel substitusi yang diperlukan sebelum langkah penting apa pun dijalankan.

Skrip memindai lingkungan saat ini dan berupaya menegaskan keberadaan (dan terkadang jenis atau pola) semua variabel penting. Jika ada yang hilang, ia menghentikan eksekusi lebih awal dan memberikan daftar variabel mana yang tidak ada yang dapat dibaca manusia.

Berikut adalah contoh sederhana dari skrip yang ditulis dalam bash:

#!/bin/bash
mengatur -e

DIPERLUKAN_VARS=(
  "_IMAGE_NAME"
  "_SERVICE_NAME"
)

untuk VAR dalam "${REQUIRED_VARS[@]}"
Mengerjakan
  jika [[ -z "${!VAR}" ]]; Kemudian
    echo "ERROR: Variabel substitusi yang diperlukan ${VAR} tidak ditentukan."
    keluar 1
  fi
Selesai

echo "Semua variabel substitusi yang diperlukan ada."

Dengan menempatkan langkah ini di bagian atas alur pembangunan, tim dapat mendeteksi kesalahan lebih awal, mengurangi siklus komputasi yang terbuang, dan memberikan masukan yang lebih berguna kepada pengembang lain.

Integrasi ke dalam Alur Kerja Cloud Build

Dalam alur kerja praktis, skrip shell validasi dapat disertakan sebagai perintah inline atau diimpor dari file skrip bersama di lokasi yang aman, seperti bucket GCS berversi. Ini biasanya merupakan langkah pertama dalam file cloudbuild.yaml:

tangga:
- nama: 'gcr.io/cloud-builders/bash'
  titik masuk: 'bash'
  argumen: ['-c', './validate_vars.sh']

Ini memberi tim kemampuan untuk:

Versi logika validasi CI mereka
Pertahankan satu sumber kebenaran untuk variabel yang diharapkan
Mengurangi siklus debug berisik yang melibatkan pengeditan pemicu coba-coba

Pengalaman Pengembang yang Ditingkatkan

Pengenalan skrip validasi ini mempunyai dampak langsung:

Lebih sedikit kegagalan saluran pipakarena variabel yang hilang tanpa diketahui.
Pesan kesalahan yang lebih jelasyang menunjuk langsung ke masalah, bukan log yang tidak jelas.
Orientasi yang lebih cepatbagi pengembang baru yang menggunakan kembali alur kerja CI yang ada tanpa memerlukan pengetahuan suku yang lengkap tentang variabel yang diharapkan.

Seiring waktu, beberapa tim memperluas validator untuk mengizinkan variabelopsionaldan mengatur fallback, sehingga memberikan lebih banyak fleksibilitas pada template bersama. Yang lain memasangkannya dengan validasi skema YAML untuk menghubungkan seluruh pipeline cloudbuild.yaml saat runtime.

Mencegah Kesalahan pada Proyek Baru

Agar proyek mendatang bebas dari masalah ini, disarankan untuk mengikuti praktik terbaik berikut:

Dokumentasikan semua variabel substitusi yang diperlukandalam panduan README atau CI untuk repo.
Gunakan skrip validasidi setiap templat baru yang ditambahkan ke alur kerja CI/CD Anda.
Tentukan konvensi penamaan yang jelas(misalnya, variabel yang dimulai dengan _ menyiratkan substitusi khusus yang diperlukan).
Tetapkan nilai defaultdalam build jika sesuai atau berikan logika variabel opsional melalui skrip.

Pikiran Terakhir

Meskipun kesalahanSUBSTITUTION_VARIABLE_NOT_DEFINEDsekilas tampak tidak berbahaya, kesalahan ini mewakili masalah yang lebih luas dalam kebersihan CI/CD dan manajemen konfigurasi. Memperlakukan validasi variabel sebagai komponen kelas satu dari pipeline Anda memastikan praktik otomatisasi yang lebih kuat, lebih sedikit build yang rusak, dan developer yang lebih bahagia. Dengan memperkenalkan skrip validasi sederhana, banyak tim dapat menyederhanakan alur kerja saluran mereka dan secara signifikan mengurangi waktu henti dan upaya debugging.

FAQ: Variabel dan Validasi Substitusi Cloud Build

T: Apa yang dimaksud dengan variabel substitusi di Cloud Build?
Variabel substitusi adalah placeholder di file cloudbuild.yaml Anda yang diganti dengan nilai sebenarnya saat build dipicu. Variabel-variabel ini digunakan untuk menyesuaikan build untuk lingkungan atau konfigurasi yang berbeda.
T: Mengapa saya melihat kesalahan SUBSTITUTION_VARIABLE_NOT_DEFINED?
Kesalahan ini biasanya terjadi ketika variabel yang direferensikan dalam file YAML tidak melewati pemicu atau lingkungan build, sehingga tidak ditentukan saat runtime.
T: Bagaimana cara menyediakan variabel substitusi saat memicu build?
Anda dapat meneruskan variabel substitusi melalui Google Cloud Console saat menyiapkan pemicu, atau melalui gcloud CLI menggunakan tanda --substitutions .
T: Dapatkah saya menetapkan nilai default untuk variabel substitusi?
Cloud Build tidak mendukung nilai default secara langsung di YAML, tetapi Anda dapat membuat skrip logika untuk menangani variabel yang tidak ditentukan dan menetapkan fallback secara terprogram dalam skrip bash atau Python.
T: Apa cara terbaik untuk menerapkan kehadiran variabel di beberapa proyek?
Gunakan skrip validasi bersama di awal semua templat cloudbuild.yaml untuk menegakkan konsistensi dan memvalidasi input sebelum melanjutkan pekerjaan build.