💡 ULASAN & REFERENSI • DIPERBARUI: 26 October 2026 • REDAKSI AZWINN

GitLab API v4 CI/CD Variables: Panduan Endpoint & Kelola

GitLab API v4 menyediakan endpoint khusus untuk mengelola CI/CD variables secara programatik pada level project, group, dan instance. Fitur ini memungkinkan pengembang dan DevOps engineer untuk membuat, membaca, memperbarui, serta menghapus variabel environment tanpa harus mengakses antarmuka web GitLab secara manual, sangat berguna untuk otomatisasi pipeline dan infrastruktur.

Untuk mengakses endpoint ini, Anda memerlukan Personal Access Token (PAT), Project Access Token, atau CI_JOB_TOKEN dengan hak akses yang memadai (biasanya level Maintainer atau Owner). Seluruh permintaan API wajib menyertakan token tersebut di dalam header HTTP dengan kunci PRIVATE-TOKEN.

Daftar Endpoint Utama GitLab API v4 CI/CD Variables

Tabel berikut merangkum endpoint HTTP yang paling sering digunakan untuk mengelola variabel CI/CD pada level project dalam GitLab API v4:

Metode Endpoint URL Deskripsi Fungsi
GET /projects/:id/variables Menampilkan daftar semua variabel CI/CD dalam suatu project.
GET /projects/:id/variables/:key Menampilkan detail dari variabel tertentu berdasarkan kuncinya.
POST /projects/:id/variables Membuat variabel CI/CD baru di dalam project.
PUT /projects/:id/variables/:key Memperbarui nilai atau konfigurasi variabel yang sudah ada.
DELETE /projects/:id/variables/:key Menghapus variabel CI/CD dari project.

Parameter Permintaan (Request Parameters)

Saat melakukan operasi pembuatan (POST) atau pembaruan (PUT) variabel pada project, terdapat beberapa parameter standar yang wajib atau opsional disertakan dalam payload:

  • key (string, wajib): Nama variabel (contoh: DATABASE_URL).
  • value (string, wajib): Nilai dari variabel tersebut.
  • variable_type (string, opsional): Jenis variabel, bernilai env_var (default) atau file.
  • protected (boolean, opsional): Jika true, variabel hanya terekspos pada branch yang dilindungi (protected branches). Default: false.
  • masked (boolean, opsional): Jika true, nilai variabel akan disembunyikan di log pipeline. Default: false.
  • environment_scope (string, opsional): Batasan environment (contoh: production, *). Default: *.

Contoh Implementasi Menggunakan cURL

Berikut adalah contoh praktis penggunaan perintah cURL untuk berinteraksi langsung dengan GitLab API v4 dalam mengelola variabel project.

1. Mengambil Daftar Variabel

curl --header "PRIVATE-TOKEN: " "https://gitlab.com/api/v4/projects/12345678/variables"

2. Menambah Variabel Baru

curl --request POST --header "PRIVATE-TOKEN: " \
     --data "key=API_KEY&value=secret123&masked=true&protected=true" \
     "https://gitlab.com/api/v4/projects/12345678/variables"

3. Menghapus Variabel

curl --request DELETE --header "PRIVATE-TOKEN: " \
     "https://gitlab.com/api/v4/projects/12345678/variables/API_KEY"

Manajemen Variabel Level Group dan Instance

Selain level project, GitLab API v4 juga mendukung pengelolaan variabel pada level group dan instance (admin). Struktur URL untuk level group menggunakan endpoint /groups/:id/variables, sedangkan untuk instance menggunakan /admin/ci/variables. Parameter yang digunakan umumnya serupa dengan level project, namun membutuhkan hak akses administrator untuk level instance.

Troubleshooting dan Tips Lapangan

Kesalahan 404 Not Found: Pastikan ID project atau nama kunci (key) variabel sudah benar. Perhatikan bahwa pencarian kunci yang mengandung karakter khusus mungkin memerlukan URL encoding (misalnya garis miring / diganti dengan %2F).

Kesalahan 401 Unauthorized: Token akses yang digunakan mungkin sudah kedaluwarsa atau tidak memiliki cakupan (scope) api yang diperlukan untuk membaca dan menulis data konfigurasi.

🔍 Orang Lain Juga Mencari Ini