Mengkustomisasi alur kerja Anda dengan variabel lingkungan

Selesai

Dalam unit ini, Anda mempelajari cara mengonfigurasi dan mengelola perilaku khusus lingkungan menggunakan variabel, konteks, dan skrip kustom dalam alur kerja GitHub Actions.

Untuk menerapkan proses ini, Anda akan mempelajari cara:

• Gunakan variabel lingkungan default dan kustom.
• Mengakses informasi kontekstual dalam alur kerja.
• Atur variabel lingkungan pada cakupan alur kerja yang berbeda.
• Gunakan skrip kustom dengan kata kunci eksekusi.
• Terapkan perlindungan lingkungan untuk penyebaran.

Variabel dan konteks lingkungan default

Dalam alur kerja GitHub Actions, beberapa variabel lingkungan default tersedia untuk Anda gunakan, tetapi hanya dalam runner yang menjalankan pekerjaan. Variabel default ini peka huruf besar/kecil, dan mengacu pada nilai konfigurasi untuk sistem dan untuk pengguna saat ini. Sebaiknya Anda menggunakan variabel lingkungan default ini untuk mereferensikan filesystem daripada menggunakan jalur file yang dikodekan secara permanen. Untuk menggunakan variabel lingkungan default, tentukan $ diikuti dengan nama variabel lingkungan.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Selain variabel lingkungan default, Anda dapat menggunakan variabel yang ditentukan sebagai konteks. Konteks dan variabel default serupa karena keduanya menyediakan akses ke informasi lingkungan, tetapi keduanya memiliki beberapa perbedaan penting. Meskipun variabel lingkungan default hanya dapat digunakan dalam runner, Anda dapat menggunakan variabel konteks kapan saja dalam alur kerja. Misalnya, variabel konteks memungkinkan Anda menjalankan pernyataan if untuk mengevaluasi ekspresi sebelum runner dijalankan.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Contoh ini menggunakan konteks github.ref untuk memeriksa cabang yang memicu alur kerja. Jika cabang adalah main, runner dijalankan untuk mencetak "Menyebarkan ke server produksi di cabang $GITHUB_REF." Variabel lingkungan default $GITHUB_REF digunakan oleh runner untuk merujuk pada cabang. Perhatikan bahwa variabel lingkungan default semuanya huruf besar saat variabel konteks semuanya huruf kecil.

Informasi kontekstual tersedia dalam alur kerja

Gunakan konteks untuk mengakses informasi tentang eksekusi alur kerja, variabel, lingkungan runner, pekerjaan, dan langkah-langkah. Setiap konteks adalah objek yang berisi properti yang dapat menjadi objek atau string lain. Konteks yang tersedia meliputi github, env, vars, job, jobs, steps, runner, secrets, strategy, matrix, needs, dan inputs.

Tabel berikut ini mencantumkan konteks dan deskripsi alur kerja:

Konteks	Deskripsi
github	Informasi tentang alur kerja yang dijalankan. Untuk informasi selengkapnya, lihat github konteks.
env	Berisi variabel yang Anda tetapkan dalam alur kerja, pekerjaan, atau langkah. Untuk informasi selengkapnya, lihat env konteks.
vars	Berisi variabel yang Anda tetapkan di tingkat repositori, organisasi, atau lingkungan. Untuk informasi selengkapnya, lihat vars konteks.
job	Informasi tentang pekerjaan yang sedang berjalan. Untuk informasi selengkapnya, lihat job konteks.
jobs	Untuk alur kerja yang dapat digunakan kembali saja, berisi keluaran pekerjaan dari alur kerja tersebut. Untuk informasi selengkapnya, lihat jobs konteks.
steps	Informasi tentang langkah-langkah yang dilakukan dalam pekerjaan saat ini. Untuk informasi selengkapnya, lihat steps konteks.
runner	Informasi tentang pelari yang menjalankan pekerjaan saat ini. Untuk informasi selengkapnya, lihat runner konteks.
secrets	Berisi nama dan nilai rahasia yang tersedia untuk alur kerja yang dijalankan. Untuk informasi selengkapnya, lihat secrets konteks.
strategy	Informasi tentang strategi eksekusi matriks untuk pekerjaan saat ini. Untuk informasi selengkapnya, lihat strategy konteks.
matrix	Berisi properti matriks yang ditentukan dalam alur kerja yang berlaku untuk pekerjaan saat ini. Untuk informasi selengkapnya, lihat matrix konteks.
needs	Berisi hasil dari semua pekerjaan yang didefinisikan sebagai dependensi dari pekerjaan saat ini. Untuk informasi selengkapnya, lihat needs konteks.
inputs	Berisi input alur kerja yang dapat digunakan kembali atau dipicu secara manual. Untuk informasi selengkapnya, lihat inputs konteks.

Konteks yang berbeda tersedia pada waktu yang berbeda dalam pelaksanaan alur kerja. Misalnya, Anda hanya dapat menggunakan secrets konteks di tempat tertentu dalam pekerjaan. Selain itu, Anda dapat menggunakan beberapa fungsi, seperti fungsi hashFiles, hanya di tempat-tempat tertentu.

Tabel berikut ini mencantumkan batasan untuk setiap konteks dan fungsi khusus dalam alur kerja. Konteks yang tercantum hanya tersedia untuk kunci alur kerja yang ditunjukkan. Anda tidak dapat menggunakannya di tempat lain. Anda dapat menggunakan fungsi di mana saja kecuali tercantum dalam tabel berikut.

Kunci alur kerja	Konteks	Fungsi khusus
run-name	github inputs vars	Tidak ada
concurrency	github inputs vars	Tidak ada
env	github,secrets,inputs,vars	Tidak ada
jobs.<job_id>.concurrency	github, needsstrategy, matrix, inputs, vars	Tidak ada
jobs.<job_id>.container	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.container.credentials	github, , needsstrategy, matrix, env, vars, , secrets,inputs	Tidak ada
jobs.<job_id>.container.env.<env_id>	, github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs	Tidak ada
jobs.<job_id>.container.image	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.continue-on-error	github, needsstrategy, vars, matrix, inputs	Tidak ada
jobs.<job_id>.defaults.run	github, needsstrategy, matrix, env, vars, inputs	Tidak ada
jobs.<job_id>.env	github, needsstrategy, matrix, vars, secrets, inputs	Tidak ada
jobs.<job_id>.environment	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.environment.url	, github, needs, strategy, matrix, job, runner, env, vars, steps, inputs	Tidak ada
jobs.<job_id>.if	github,needs,vars,inputs	always,canceled,success,failure
jobs.<job_id>.name	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.outputs.<output_id>	github needs strategy matrix job runner env vars secrets steps inputs	Tidak ada
jobs.<job_id>.runs-on	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.secrets.<secrets_id>	github, needsstrategy, matrix, secrets, inputs, vars	Tidak ada
jobs.<job_id>.services	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.services.<service_id>.credentials	github, , needsstrategy, matrix, env, vars, , secrets,inputs	Tidak ada
jobs.<job_id>.services.<service_id>.env.<env_id>	, github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs	Tidak ada
jobs.<job_id>.steps.continue-on-error	github needs strategy matrix job runner env vars secrets steps inputs	hashFiles
jobs.<job_id>.steps.env	github needs strategy matrix job runner env vars secrets steps inputs	hashFiles
jobs.<job_id>.steps.if	, github, needs, strategy, matrix, job, runner, env, vars, steps, inputs	always canceled success failure hashFiles
jobs.<job_id>.steps.name	github needs strategy matrix job runner env vars secrets steps inputs	hashFiles
jobs.<job_id>.steps.run	github needs strategy matrix job runner env vars secrets steps inputs	hashFiles
jobs.<job_id>.steps.timeout-minutes	github needs strategy matrix job runner env vars secrets steps inputs	hashFiles
jobs.<job_id>.steps.with	github, , needs, strategymatrix, job, runner, env, vars, secrets, , stepsinputs	hashFiles
jobs.<job_id>.steps.working-directory	github, , needs, strategymatrix, job, runner, env, vars, secrets, , stepsinputs	hashFiles
jobs.<job_id>.strategy	github, kebutuhan, vars, inputs,	Tidak ada
jobs.<job_id>.timeout-minutes	github, needsstrategy, matrix, vars, inputs	Tidak ada
jobs.<job_id>.with.<with_id>	github, needsstrategy, matrix, inputs, vars	Tidak ada
on.workflow_call.inputs.<inputs_id>.default	github inputs vars	Tidak ada
on.workflow_call.outputs.<output_id>.value	github, pekerjaan, vars, inputs	Tidak ada

Variabel lingkungan kustom

Serupa dengan menggunakan variabel lingkungan default, Anda dapat menggunakan variabel lingkungan kustom dalam file alur kerja Anda. Untuk membuat variabel kustom, Anda perlu menentukannya dalam file alur kerja menggunakan konteks env. Jika Anda ingin menggunakan nilai variabel lingkungan di dalam runner, Anda dapat menggunakan metode normal sistem operasi runner untuk membaca variabel lingkungan.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Mengatur variabel lingkungan kustom dalam alur kerja

Anda dapat menentukan variabel lingkungan yang tercakup ke seluruh alur kerja dengan menggunakan env di tingkat atas file alur kerja. Cakupan konten pekerjaan dalam alur kerja dengan menggunakan jobs.<job_id>.env. Anda dapat mencakup variabel lingkungan pada langkah tertentu dalam pekerjaan dengan menggunakan jobs.<job_id>.steps[*].env.

Berikut adalah contoh yang memperlihatkan ketiga skenario dalam file alur kerja:

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Menggunakan konteks default dalam alur kerja

Platform GitHub menetapkan variabel lingkungan default. Variabel tersebut tidak ditentukan dalam alur kerja, tetapi Anda dapat menggunakan variabel lingkungan default dalam alur kerja dalam konteks yang sesuai. Sebagian besar variabel ini, selain CI, dimulai dengan GITHUB_* atau RUNNER_*. Dua jenis terakhir tidak dapat ditimpa. Selain itu, variabel default ini memiliki properti konteks yang sesuai dan bernama serupa. Misalnya, RUNNER_* rangkaian variabel default memiliki properti konteks yang cocok dari runner.*.

Berikut adalah contoh cara mengakses variabel default dalam alur kerja dengan menerapkan metode ini:

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Untuk informasi selengkapnya, lihat Variabel lingkungan default.

Meneruskan variabel lingkungan kustom ke alur kerja

Anda dapat meneruskan variabel lingkungan kustom dari satu langkah pekerjaan alur kerja ke langkah berikutnya dalam pekerjaan. Hasilkan nilai dalam satu langkah pekerjaan, dan tetapkan nilai ke variabel lingkungan yang sudah ada atau baru. Selanjutnya, Anda menulis pasangan variabel/nilai ke file lingkungan GITHUB_ENV. Anda dapat menggunakan file environment dalam sebuah aksi atau dari perintah shell dalam tugas alur kerja dengan menggunakan kata kunci run.

Langkah yang membuat atau memperbarui variabel lingkungan tidak memiliki akses ke nilai baru, tetapi semua langkah berikutnya dalam pekerjaan memiliki akses.

Berikut adalah sebuah contoh:

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

Menambahkan perlindungan lingkungan

Anda dapat menambahkan aturan perlindungan untuk lingkungan yang ditentukan untuk repositori GitHub Anda.

Untuk menambahkan lingkungan di repositori Anda:

1. Pilih pengaturan.

   

2. Di panel kiri, pilih Lingkungan.

   

3. Pilih tombol Lingkungan baru untuk menambahkan dan mengonfigurasi lingkungan dan menambahkan perlindungan.

   

Tentang lingkungan

Gunakan lingkungan untuk menjelaskan target penyebaran umum seperti produksi, penahapan, atau pengembangan. Saat alur kerja GitHub Actions disebarkan ke lingkungan, lingkungan muncul di halaman utama repositori. Anda dapat menggunakan lingkungan untuk memerlukan persetujuan agar pekerjaan dapat dilanjutkan, membatasi cabang yang dapat memicu alur kerja, mengatur penyebaran dengan menggunakan aturan perlindungan penyebaran khusus, atau membatasi akses ke rahasia.

Setiap pekerjaan dalam alur kerja dapat mereferensikan satu lingkungan. Aturan perlindungan apa pun yang Anda tetapkan untuk lingkungan harus dipatuhi sebelum pekerjaan yang mereferensikan lingkungan dikirimkan ke runner. Pekerjaan dapat mengakses rahasia lingkungan hanya setelah pekerjaan dikirim ke runner.

Ketika alur kerja mengacu pada lingkungan, lingkungan tersebut muncul di deployment repositori.

Aturan perlindungan lingkungan

Aturan perlindungan penyebaran lingkungan memerlukan kondisi tertentu dipenuhi sebelum tugas yang mereferensikan lingkungan berlanjut. Anda dapat menggunakan aturan perlindungan penyebaran untuk memerlukan persetujuan manual, menunda pekerjaan, atau membatasi lingkungan ke cabang tertentu. Anda juga dapat membuat dan menerapkan aturan perlindungan kustom yang didukung oleh GitHub Apps untuk menggunakan sistem mitra untuk mengontrol penyebaran yang mereferensikan lingkungan yang dikonfigurasi di GitHub.

Berikut adalah penjelasan tentang aturan perlindungan ini:

• Aturan perlindungan peninjau yang diperlukan. Gunakan aturan ini untuk mengharuskan orang atau tim tertentu menyetujui pekerjaan alur kerja yang mereferensikan lingkungan. Anda dapat mencantumkan hingga enam pengguna atau tim sebagai peninjau. Peninjau harus memiliki setidaknya izin Baca ke repositori. Hanya satu peninjau wajib yang perlu menyetujui pekerjaan untuk dapat melanjutkan.

  Anda juga dapat mencegah peninjauan mandiri untuk penyebaran ke lingkungan yang dilindungi. Jika Anda mengaktifkan pengaturan ini, pengguna yang memulai penyebaran tidak dapat menyetujui pekerjaan penyebaran, meskipun mereka adalah peninjau yang diperlukan. Dengan mengaktifkan tinjauan mandiri, ia memastikan bahwa lebih dari satu orang meninjau penyebaran ke lingkungan yang dilindungi.

  Untuk informasi selengkapnya tentang meninjau pekerjaan yang mereferensikan lingkungan dengan peninjau yang diperlukan, lihat Meninjau penyebaran.

• Aturan proyeksi pengatur waktu tunggu. Anda dapat menggunakan aturan perlindungan pengatur waktu tunggu untuk menunda sebuah pekerjaan selama waktu tertentu setelah pekerjaan dipicu, sebelum penyebaran lingkungan berlanjut. Waktu (dalam menit) harus berupa bilangan bulat antara 1 dan 43.200 (30 hari). Waktu tunggu tidak dihitung dalam waktu yang dapat ditagih.

• Aturan perlindungan cabang dan tag. Anda dapat menggunakan aturan perlindungan untuk cabang dan tag penyebaran guna membatasi cabang dan tag mana yang digunakan untuk menyebarkan ke lingkungan sistem. Anda memiliki beberapa opsi untuk aturan perlindungan cabang penyebaran dan tag untuk lingkungan.

  • Tanpa pembatasan berarti tidak ada pembatasan pada cabang atau tag mana yang dapat disebarkan ke lingkungan.
  • Hanya cabang yang dilindungi memungkinkan cabang dengan aturan perlindungan yang diaktifkan untuk mengakses lingkungan. Jika tidak ada aturan perlindungan cabang yang didefinisikan untuk cabang apa pun di repositori, maka semua cabang dapat disebarkan. Pengaturan Cabang dan tag yang dipilih memastikan Hanya cabang dan tag yang cocok dengan pola nama yang Anda tentukan yang dapat disebarkan ke lingkungan.
  • Jika Anda menentukan releases/* sebagai cabang penyebaran atau aturan tag, hanya cabang atau tag dengan nama yang dimulai dengan releases/ yang dapat disebarkan ke lingkungan. (Karakter wildcard tidak cocok dengan /. Untuk mencocokkan cabang atau tag yang dimulai dengan release/ dan mengandung satu garis miring tunggal, gunakan release/*/*.) Jika Anda menambahkan main sebagai aturan cabang, cabang bernama main dapat juga dikerahkan ke lingkungan.

• Aturan perlindungan penyebaran kustom. Anda dapat membuat aturan perlindungan kustom untuk menyaring penyebaran agar menggunakan layanan mitra. Misalnya, Anda dapat menggunakan sistem pengamatan, sistem manajemen perubahan, sistem kualitas kode, atau konfigurasi manual lainnya yang Anda gunakan untuk menilai kesiapan dan memberikan persetujuan otomatis untuk penyebaran ke GitHub.

  Setelah membuat aturan perlindungan penyebaran kustom dan menginstalnya di repositori, Anda dapat mengaktifkan aturan perlindungan penyebaran kustom untuk lingkungan apa pun di repositori.

  

Nota

Jika Anda memiliki paket GitHub Free, GitHub Pro, atau GitHub Team, aturan proyeksi penyebaran lingkungan hanya tersedia untuk repositori publik; kecuali untuk aturan perlindungan cabang dan tag. Untuk pengguna yang memiliki paket GitHub Pro atau GitHub Team, aturan perlindungan cabang dan tag juga tersedia untuk repositori privat.

Skrip di alur kerja Anda

Dalam contoh cuplikan alur kerja sebelumnya, run kata kunci digunakan untuk mencetak string teks. Karena kata kunci run memberi tahu pekerjaan untuk menjalankan perintah pada runner, Anda menggunakan kata kunci run untuk menjalankan tindakan atau skrip.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

Dalam contoh ini, Anda menggunakan npm untuk menginstal bats paket pengujian perangkat lunak dengan menggunakan run kata kunci. Anda juga dapat menjalankan skrip sebagai tindakan. Anda dapat menyimpan skrip di repositori, sering dilakukan di direktori .github/scripts/, lalu menyediakan jalur dan jenis shell menggunakan kata kunci run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash