sumber variabel lingkungan dan cara menggunakannya - Alibaba Cloud DevOps

Variabel lingkungan merupakan cara umum untuk menyesuaikan pipeline dan dapat digunakan di tahap apa pun. Topik ini menjelaskan jenis-jenis variabel lingkungan—bawaan, kustom, dan kelompok variabel umum—serta cara menggunakannya.

Sumber variabel lingkungan

Variabel bawaan

Pipeline Alibaba Cloud DevOps menyediakan variabel bawaan yang terkait dengan informasi dasar dan sumber kode. Anda dapat menggunakan variabel ini untuk menyesuaikan alur kerja Anda.

Modul	Parameter	Deskripsi
Informasi dasar	PIPELINE_ID	ID pipeline.
	BUILD_NUMBER	Nomor eksekusi pipeline, dimulai dari 1 dan bertambah setiap kali dijalankan.
	PIPELINE_NAME	Nama pipeline. Contoh: `Frontend Project Release`.
	BUILD_REMARK	Catatan untuk eksekusi pipeline.
	BUILD_EXECUTOR	Pengguna yang memicu pipeline. Contoh: `John Doe`.
	BUILD_MESSAGE	Informasi pemicu pipeline. Contoh: `Manually triggered by John Doe from the web console`.
	PROJECT_DIR	Direktori kerja untuk menjalankan perintah. Contoh: `/root/workspace/1084-abc_docker-08191_b0wE`.
	DATETIME	Waktu saat ini. Contoh: `2017-06-22-23-26-33`.
	TIMESTAMP	Timestamp saat ini. Contoh: `1581581273232`.
Sumber kode (tunggal)	CI_SOURCE_NAME	Nama sumber kode.
	CI_COMMIT_REF_NAME	Nama branch atau tag sumber kode, yang dipilih saat menjalankan pipeline. Contoh: `master` atau `V1.0`.
	CI_COMMIT_TITLE	Pesan commit terakhir.
	CI_COMMIT_SHA	ID commit lengkap dari commit terakhir. Contoh: `2bfb63d779e3648c91950f82d374a25784cdabaf`.
	CI_COMMIT_ID	ID commit pendek 8 karakter dari commit terakhir (untuk Git). Nomor revisi dari commit terakhir (untuk SVN).
Sumber kode (multiple)	CI_SOURCE_NAME_n	Nama sumber kode ke-n.
	CI_COMMIT_REF_NAME_n	Nama branch atau tag sumber kode ke-n, yang dipilih saat menjalankan pipeline. Contoh: `master` atau `V1.0`.
	CI_COMMIT_TITLE_n	Pesan commit terakhir untuk sumber kode ke-n.
	CI_COMMIT_SHA_n	ID commit lengkap dari commit terakhir untuk sumber kode ke-n. Contoh: `2bfb63d779e3648c91950f82d374a25784cdabaf`.
	CI_COMMIT_ID_n	ID commit pendek 8 karakter dari commit terakhir untuk sumber kode ke-n.
Sumber artefak	CI_SOURCE_NAME	Nama sumber artefak.
	CI_SOURCE_URL	URL sumber artefak. Contoh: `https://packages.aliyun.com/generic/flow_generic_repo/artifacts?artifactName=Artifacts_2778530&version=2024-01-05-16-28-23`.
	CI_VERSION_NAME	Nama versi sumber artefak, yang dipilih saat menjalankan pipeline. Contoh: `2024-01-05-16-28-23`.

Untuk mengakses informasi dari sumber kode atau artefak tertentu ketika terdapat beberapa sumber, tambahkan sufiks numerik pada nama variabel.

Sebagai contoh, sebuah pipeline dapat memiliki sumber kode Git (sumber 1), sumber artefak (sumber 2), dan sumber kode SVN (sumber 3). Setelah pipeline dijalankan, Anda dapat melihat nilai aktual semua variabel di detail eksekusi. Sufiks numerik membedakan variabel untuk berbagai sumber, seperti CI_COMMIT_REF_NAME_1 dan CI_COMMIT_REF_NAME_2.

Nilai variabel CI_COMMIT_REF_NAME bergantung pada branch atau tag spesifik yang Anda pilih saat memicu pipeline. Jika Anda memicu pipeline secara manual dan memilih branch master, nilai CI_COMMIT_REF_NAME adalah master. Jika Anda memilih tag V1.0, nilainya adalah V1.0. Pemilihan saat runtime ini memungkinkan Anda menjalankan pipeline pada branch atau tag berbeda, dan nilai variabel akan berubah sesuai.

Ketika Anda memicu eksekusi pipeline, Anda dapat memilih branch atau tag tertentu di kotak dialog eksekusi. Nilai yang dipilih menjadi nilai runtime variabel CI_COMMIT_REF_NAME.

Penting

Perhatikan batasan dan skenario khusus berikut saat menggunakan variabel bawaan:

Ambiguitas variabel multi-sumber — Ketika pipeline memiliki beberapa sumber kode, jangan gunakan variabel tanpa indeks seperti CI_COMMIT_REF_NAME secara langsung. Meskipun sistem secara default merujuk ke sumber pertama, hasilnya tidak dapat diprediksi. Selalu gunakan variabel berindeks dengan sufiks numerik, seperti CI_COMMIT_REF_NAME_1 atau CI_COMMIT_REF_NAME_2, untuk merujuk sumber kode tertentu.
Prasyarat variabel Git — Variabel bawaan terkait Git seperti CI_COMMIT_TITLE, CI_COMMIT_SHA, dan CI_COMMIT_ID hanya diisi setelah langkah checkout kode dijalankan dalam pipeline. Jika tidak ada kode yang di-checkout, variabel ini kosong.
Batasan pemrosesan variabel — Alibaba Cloud DevOps Flow tidak mendukung operasi string langsung seperti ekstraksi substring atau pencocokan ekspresi reguler pada variabel bawaan (misalnya, CI_COMMIT_ID). Untuk memproses nilai variabel bawaan, tetapkan ke variabel kustom dalam skrip shell lalu lakukan operasi pada variabel kustom tersebut:
```
# Tetapkan variabel bawaan ke variabel kustom untuk diproses
MY_SHORT_SHA=$(echo $CI_COMMIT_SHA | cut -c1-8)
echo "MY_SHORT_SHA=$MY_SHORT_SHA" >> "$FLOW_ENV"
```
Cakupan CI_WORKSPACE — Variabel CI_WORKSPACE hanya berlaku dalam lingkungan build saat ini. Dalam skenario deployment host (ECS), variabel ini mungkin kosong atau mengarah ke jalur yang tidak diharapkan. Jangan mengandalkan CI_WORKSPACE untuk menemukan file di instance ECS. Gunakan jalur mutlak atau konfigurasikan variabel kustom dengan jalur direktori target sebagai gantinya.
Variabel bawaan yang tidak tersedia — Variabel bawaan tidak mencakup nama proyek repositori saat ini atau URL Git lengkap. Untuk mendapatkan informasi ini, konfigurasikan variabel kustom secara manual atau susun URL dengan menggabungkan domain Codeup dan jalur repositori.

Variabel kustom

Selain variabel bawaan, Alibaba Cloud DevOps Flow mendukung variabel kustom. Setiap variabel kustom memiliki cakupan terbatas pada pipeline tempat didefinisikan. Untuk membuat variabel kustom, pilih pipeline, klik Edit, lalu buka tab Variables and Cache. Alibaba Cloud DevOps Flow mendukung tipe variabel string dan enumerasi.

Tab ini berisi area konfigurasi untuk variabel string dan variabel yang dipilih saat runtime.

Variabel string

Di tab Variables and Cache, pada bagian String Variables, klik New Variable.
Masukkan Variable Name dan Default Value. Anda juga dapat mengonfigurasi private mode dan runtime settings.
1. Variable Name: Nama tidak boleh mengandung tanda hubung (-).
2. private mode: Saat diaktifkan, mode ini menyembunyikan nilai sehingga tidak muncul di log eksekusi. Gunakan untuk informasi sensitif seperti username dan password.
3. runtime settings: Mengontrol apakah nilai variabel wajib diisi saat runtime. Saat diaktifkan, Anda harus memberikan nilai setiap kali menjalankan pipeline.
Anda dapat menambahkan lebih banyak variabel atau menghapus yang sudah ada.
Klik Add lalu simpan pipeline. Kini Anda dapat menggunakan variabel tersebut sebagaimana dijelaskan dalam Use environment variables.

Variabel yang dipilih saat runtime

Di tab Variables and Cache, pada bagian Runtime-Selected Variables, klik New Variable.
Masukkan Variable Name dan definisikan Options.
1. Klik Add Option untuk menambahkan beberapa pilihan nilai variabel.
2. Aktifkan Default Value pada suatu opsi agar menjadi pilihan default.
Klik Add lalu simpan pipeline. Kini Anda dapat menggunakan variabel tersebut sebagaimana dijelaskan dalam Use environment variables.

Saat menjalankan pipeline, Anda akan diminta memilih nilai untuk variabel ini.

Praktik terbaik untuk variabel kustom

Hindari konflik penamaan — Nama variabel kustom tidak boleh bertentangan dengan kata cadangan sistem atau parameter bawaan seperti image, tag, atau version. Konflik dapat menyebabkan error tak terduga pada langkah pembuatan image atau deployment. Nama variabel harus dimulai dengan huruf, hanya berisi huruf, angka, dan garis bawah, serta panjangnya antara 1 hingga 64 karakter.
Penanganan karakter khusus dalam nilai variabel — Ketika nilai variabel seperti password mengandung karakter khusus seperti @, penggabungan langsung nilai tersebut dalam URL menyebabkan error format. Encode karakter khusus tersebut dalam URL (misalnya, ganti @ dengan %40), atau gunakan variabel private mode agar sistem menangani otentikasi secara otomatis.
Izin akses sumber kode dinamis — Pipeline tidak melakukan otentikasi otomatis dengan identitas pelaksana saat mengakses repositori kode yang dikonfigurasi secara dinamis. Untuk mengakses repositori pribadi, konfigurasikan username Git dan token akses sebagai variabel pribadi, atau tambahkan repositori sebagai sumber pipeline untuk mewarisi izin akses.
Escape referensi variabel dalam file YAML — Dalam skenario seperti kubectl apply, sintaks ${} dalam file YAML mungkin salah ditafsirkan sebagai referensi variabel pipeline. Untuk mencegah hal ini, aktifkan opsi Variable Validation untuk menonaktifkan parsing variabel otomatis, atau gunakan sintaks escape $${} untuk mempertahankan string asli. Misalnya, tulis $${2} alih-alih ${2}.

Kelompok variabel umum

Kelompok variabel umum adalah kumpulan variabel lingkungan yang dikelola secara terpusat oleh organisasi Anda. Anda dapat mengaitkan pipeline dengan kelompok tersebut untuk menggunakan variabelnya.

Di tab Variables and Cache, pada bagian Common Variable Group, klik Associate Variable Group. Pilih kelompok variabel dari daftar drop-down lalu klik OK untuk mengaitkannya dengan pipeline.
Di bagian ini, Anda dapat melihat detail kelompok variabel yang dikaitkan atau memutus kaitannya. Setelah menyimpan pipeline, Anda dapat menggunakan variabel tersebut sebagaimana dijelaskan dalam Use environment variables.

Gunakan variabel lingkungan

Setelah mendefinisikan variabel, Anda dapat mereferensikannya di mana saja dalam pipeline menggunakan sintaks ${XXX}. Sistem menyelesaikan variabel dengan urutan prioritas berikut:

Variabel output langkah > Variabel input runtime pipeline > Variabel pipeline > Variabel kelompok variabel umum.
Jika Anda mengaitkan pipeline dengan beberapa kelompok variabel umum yang berisi variabel dengan nama sama, nilai dari kelompok yang paling baru dikaitkan akan diutamakan.

Bagian berikut memberikan contoh kasus penggunaan umum variabel lingkungan, termasuk eksekusi perintah, deployment host, argumen pembuatan image, file konfigurasi, dan pengiriman data.

Gunakan variabel dalam perintah

Anda dapat menggunakan variabel untuk mengubah parameter dalam file konfigurasi. Misalnya, mengubah nilai parameter key dalam file a.conf dari 123 menjadi nilai variabel lingkungan bernama abc.

Dalam langkah skrip shell, gunakan perintah sed untuk mengganti nilai parameter dengan nilai variabel lingkungan.

$ cat a.conf
key=123
$ sed -i "s/key=123/key=${abc}/g" a.conf
$ cat a.conf
key=abc_value

高的 (7)

Di Variables and Cache pipeline, atur nilai default variabel abc menjadi abc_value.

Variabel dalam deployment host

Anda dapat mereferensikan variabel lingkungan secara langsung dalam skrip deployment Anda menggunakan sintaks ${XXX} untuk mengontrol logika deployment host. Setelah pipeline dijalankan, Anda dapat memeriksa log langkah deployment host untuk memverifikasi bahwa sistem telah meneruskan nilai variabel dengan benar.

Variabel sebagai argumen pembuatan image

Jika Anda perlu menggunakan variabel lingkungan pipeline sebagai argumen selama pembuatan image, konfigurasikan sebagai berikut.

Dalam langkah pembuatan image, gunakan lingkungan kontainer tertentu. Di argumen build, tambahkan argumen kustom dan tetapkan variabel lingkungan ke dalamnya menggunakan format ${XXX}. Sistem meneruskan argumen ke perintah build menggunakan flag --build-arg.

Di Build Parameters langkah pembuatan image, tambahkan argumen kustom seperti abc=${abc}. Argumen ini diteruskan ke perintah Docker build sebagai --build-arg.

横向多个 (2)

Dalam Dockerfile Anda, referensikan argumen tersebut menggunakan ARG argName.

FROM <base-image>
ARG argName
RUN echo $argName

Gunakan variabel dalam file konfigurasi

Jika Anda perlu memodifikasi parameter dalam file konfigurasi menggunakan variabel lingkungan, ikuti langkah-langkah berikut. Misalnya, mengganti parameter username dalam file a.conf dengan variabel pipeline:

Dalam file a.conf, ubah baris menjadi username = ${abc}.
Dalam variabel lingkungan pipeline, konfigurasikan variabel abc dan atur nilai default-nya menjadi my_name_is_hanmeimei.
Tambahkan pekerjaan ke pipeline. Dari bagian Utilities, tambahkan langkah Replace EnvVar in File. Masukkan jalur file konfigurasi di bidang Source File Path. Target File Path bersifat opsional. Jika Anda menentukan jalur target, langkah ini membuat file baru. Jika tidak, file asli akan dimodifikasi.

Dalam contoh ini, Source File Path diatur ke a.conf, dan Target File Path diatur ke b.conf.

Periksa hasilnya. Langkah ini mengganti placeholder username di a.conf dengan nilai variabel dalam file baru b.conf, yang kini berisi my_name_is_hanmeimei. Catatan: Langkah-langkah hanya berbagi ruang kerja jika berada dalam pekerjaan yang sama.

Pengiriman variabel

Variabel lingkungan yang didefinisikan di halaman konfigurasi pipeline bersifat statis. Namun, Anda mungkin perlu menghasilkan variabel lingkungan dari output langkah yang sedang berjalan dan meneruskannya ke langkah atau pekerjaan berikutnya. Anda dapat melakukannya dengan dua cara:

Kirim variabel dalam satu pekerjaan: Langkah 1 menghasilkan variabel lingkungan kustom, dan Langkah 2 menggunakannya.
Kirim variabel antar pekerjaan: Pekerjaan 1 menghasilkan variabel lingkungan, dan Pekerjaan 2 menggunakannya.

Penting: Anda harus menggunakan sintaks berbeda untuk lingkungan build yang berbeda. Sintaks untuk menyuntikkan variabel lingkungan adalah: di lingkungan default, gunakan echo 'USER_abc=123' > .env (nama variabel harus diawali dengan USER_); di lingkungan kontainer tertentu atau lingkungan VM default, gunakan echo "yaojia_Test=myParam" >> "$FLOW_ENV".

高的 (28)

Di Pekerjaan 1, Anda dapat menambahkan langkah dengan membuka Add Step > Utilities > Set Variables untuk mempromosikan variabel lingkungan ke tingkat pipeline.

Lingkungan Kontainer atau VM

Kirim variabel dalam satu pekerjaan

Dalam skenario ini, Anda berbagi variabel lingkungan dalam satu pekerjaan. Misalnya, Langkah 1 menghasilkan variabel yaojia_Test=myParam, dan Langkah 2 mereferensikannya menggunakan ${yaojia_Test}.

Dalam langkah sebelumnya, Anda dapat menyuntikkan variabel lingkungan dengan menjalankan perintah echo "yaojia_Test=myParam" >> "$FLOW_ENV", yang menambahkan variabel ke file $FLOW_ENV.

# Log eksekusi Langkah 2
echo $yaojia_Test
myParam
# [Success]

Kirim variabel antar pekerjaan

Dalam skenario ini, Anda berbagi variabel lingkungan antar beberapa pekerjaan dalam pipeline. Misalnya, Pekerjaan 1 menghasilkan variabel yaojia_Test=myParam, dan Pekerjaan 2 mereferensikannya menggunakan ${yaojia_Test}.

Dalam langkah di Pekerjaan 1, suntikkan variabel lingkungan dengan menambahkannya ke file $FLOW_ENV.
Di Pekerjaan 1, tambahkan langkah lain dengan memilih untuk mempromosikan variabel lingkungan ke tingkat pipeline.
Di Pekerjaan 2, Anda kemudian dapat menggunakan ${yaojia_Test} untuk mereferensikan variabel tersebut.

Setelah Pekerjaan 1 menyuntikkan dan mempromosikan variabel, Pekerjaan 2 dapat mereferensikannya menggunakan ${yaojia_Test}.

# Log eksekusi Pekerjaan 2
echo $yaojia_Test
myParam
# [Success]

Catatan penggunaan untuk lingkungan kontainer atau VM

Gunakan mode append untuk mencegah penimpaan — Saat menulis variabel ke $FLOW_ENV, gunakan operator append (>>). Jangan gunakan operator overwrite (>), karena akan menggantikan semua variabel yang ditulis sebelumnya.

# Benar: mode append mempertahankan variabel yang ada
echo "VAR_A=value1" >> "$FLOW_ENV"
echo "VAR_B=value2" >> "$FLOW_ENV"

# Salah: mode overwrite — VAR_A hilang
echo "VAR_A=value1" > "$FLOW_ENV"
echo "VAR_B=value2" > "$FLOW_ENV"

Batasan pembacaan dalam langkah yang sama — Setelah menulis variabel ke $FLOW_ENV menggunakan echo, Anda tidak dapat langsung membaca variabel tersebut dalam langkah yang sama dengan mereferensikan $KEY. Variabel hanya dimuat ke konteks runtime setelah langkah saat ini selesai. Untuk memverifikasi nilai variabel, bacalah di langkah berikutnya.
Solusi sementara untuk deployment Kubernetes — Jika variabel yang didefinisikan dalam langkah skrip shell tidak tersedia atau mengembalikan nilai default di langkah deployment Kubernetes, tambahkan langkah Set Variables (buka Add Step > Utilities > Set Variables) setelah langkah shell. Dalam langkah ini, tetapkan variabel secara eksplisit ke nama variabel baru yang dapat direferensikan oleh langkah Kubernetes.
Ekstraksi nomor versi secara dinamis — Untuk mengekstraksi nomor versi dari artefak build seperti pom.xml dan meneruskannya ke langkah pembuatan image Docker downstream:
```
# Ekstraksi versi dari pom.xml
VERSION=$(grep -m1 '<version>' pom.xml | sed 's/.*<version>$.*$<\/version>.*/\1/')
echo "IMAGE_VERSION=$VERSION" >> "$FLOW_ENV"
```
Pemecahan masalah pengaturan variabel — Jika variabel tidak berlaku atau menyebabkan error di lingkungan kontainer, verifikasi hal berikut:
- Anda telah menambahkan langkah Set Variables untuk mempromosikan variabel ke tingkat pipeline.
- Sintaks sesuai dengan lingkungan target. Gunakan echo "KEY=VALUE" >> "$FLOW_ENV" untuk lingkungan kontainer atau VM. Jangan gunakan echo 'USER_KEY=VALUE' > .env, yang hanya berlaku untuk lingkungan default.

FAQ

Bagaimana cara menggunakan variabel lingkungan untuk deployment multi-lingkungan atau memilih target build secara dinamis?

Deployment multi-lingkungan — Buat pipeline terpisah untuk tahapan berbeda seperti development, testing, dan production. Di setiap pipeline, konfigurasikan variabel kustom dengan nilai spesifik untuk lingkungan target, seperti identifier lingkungan atau jalur file konfigurasi. Pendekatan ini memungkinkan deployment berbeda tanpa memodifikasi skrip build Anda.
Pemilihan target build dinamis — Alibaba Cloud DevOps Flow tidak mendukung pemilihan target build spesifik (seperti file JAR atau modul layanan tertentu) dari UI pipeline. Sebagai solusi sementara, definisikan variabel yang dipilih saat runtime untuk menentukan jalur direktori target layanan. Referensikan variabel ini dalam perintah build Anda untuk memilih target build secara dinamis, dan konfigurasikan jalur unggah artefak agar hanya mencakup direktori yang sesuai dengan nilai variabel yang dipilih.