Cara Menjalankan GitHub Actions Secara Lokal dengan Act

Daniel Costa

Daniel Costa

16 April 2025

Cara Menjalankan GitHub Actions Secara Lokal dengan Act

GitHub Actions telah merevolusi cara pengembang mengotomatiskan alur kerja dalam repositori mereka. Dari pipeline integrasi berkelanjutan dan penyebaran berkelanjutan (CI/CD) hingga mengotomatiskan pelabelan masalah dan generasi catatan rilis, Actions memberikan cara yang kuat dan terintegrasi untuk mengelola siklus hidup pengembangan perangkat lunak langsung dalam GitHub.

Namun, mengembangkan dan menguji alur kerja ini terkadang bisa terasa merepotkan. Siklus tradisional melibatkan:

  1. Melakukan perubahan pada file alur kerja Anda (biasanya terletak di .github/workflows/).
  2. Melakukan commit terhadap perubahan ini.
  3. Mendorongnya ke repositori GitHub Anda.
  4. Menunggu runner GitHub untuk mengambil pekerjaan dan mengeksekusinya.
  5. Menganalisis log di situs web GitHub untuk melihat apakah perubahan Anda berhasil atau jika mereka menyebabkan kesalahan.

Proses ini, terutama bagian menunggu dan beralih konteks antara editor lokal Anda dan UI GitHub, dapat secara signifikan memperlambat pengembangan, terutama saat melakukan iterasi pada alur kerja yang kompleks atau memecahkan masalah yang rumit. Bagaimana jika Anda bisa menguji Actions Anda sebelum mendorongnya?

Inilah tepatnya di mana act masuk. Seperti yang disarankan oleh tagline-nya, "Berpikir secara global, act secara lokal". act adalah alat baris perintah open-source yang dirancang untuk menjalankan alur kerja GitHub Actions Anda secara lokal menggunakan kontainer Docker. Ini mensimulasikan lingkungan yang disediakan oleh GitHub Actions, memungkinkan Anda untuk menguji dan melakukan iterasi pada alur kerja Anda dengan cepat tanpa perlu melakukan commit dan push setiap perubahan kecil.

💡
Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengapa Menjalankan GitHub Actions Secara Lokal dengan act?

Manfaat mengintegrasikan act ke dalam alur kerja pengembangan Anda sangat besar:

  1. Umpan Balik Cepat: Ini adalah keuntungan utama. Alih-alih siklus commit-push-tunggu-debug, Anda dapat menjalankan alur kerja Anda segera setelah melakukan perubahan secara lokal. Dapatkan umpan balik dalam hitungan detik atau menit, bukan dalam hitungan menit atau puluhan menit. Ini secara drastis mempercepat proses pengembangan dan debugging untuk file .github/workflows/ Anda.
  2. Runner Tugas Lokal: Banyak proyek menggunakan alat seperti make, npm scripts, atau skrip shell khusus untuk mendefinisikan tugas pengembangan umum (membangun, menguji, linting, dll.). act memungkinkan Anda untuk mengkonsolidasikan tugas-tugas ini. Anda dapat mendefinisikan proses build, test, dan lainnya sebagai pekerjaan GitHub Actions, dan kemudian menggunakan act untuk menjalankan pekerjaan yang sama secara lokal untuk tujuan pengembangan. Ini mengurangi duplikasi dan memastikan konsistensi antara lingkungan pengembangan lokal Anda dan pipeline CI/CD Anda. Anda mendefinisikan tugas sekali di file alur kerja Anda, dan mereka berjalan identik (atau sangat mirip) di mana saja.
  3. Pengembangan Offline: Uji sintaks dan logika alur kerja dasar bahkan tanpa koneksi internet yang konstan (meskipun pengunduhan gambar awal dan tindakan tertentu mungkin memerlukan konektivitas).
  4. Penghematan Biaya: Sementara GitHub menyediakan tingkat gratis yang murah hati untuk repositori publik dan harga yang wajar untuk repositori pribadi, menjalankan alur kerja yang kompleks atau panjang secara berulang selama pengembangan dapat menghabiskan menit runner. Menguji secara lokal menghindari penggunaan ini.
  5. Kekuatan Debugging: Debugging Actions yang gagal di GitHub sering kali melibatkan penambahan logging tambahan, mendorong, dan menunggu. Dengan act, Anda dapat memeriksa lingkungan lokal, memasang volume, dan berpotensi menggunakan teknik debugging yang lebih canggih dalam kontainer Docker yang dijalankannya.

Bagaimana act Bekerja?

Memahami mekanisme di balik act membantu dalam menggunakannya secara efektif dan memecahkan masalah yang mungkin terjadi. Berikut adalah rincian operasinya:

  1. Pemrosesan Alur Kerja: Ketika Anda mengeksekusi perintah act di direktori root repositori Anda, ia memindai direktori .github/workflows/ untuk file YAML alur kerja Anda.
  2. Simulasi Pemicu Acara: Secara default, act mensimulasikan acara push, tetapi Anda dapat menentukan acara lain seperti pull_request, workflow_dispatch, dll. Ini menentukan alur kerja dan pekerjaan mana yang harus dijalankan berdasarkan acara yang ditentukan dan pemicu on: yang didefinisikan dalam file alur kerja Anda.
  3. Analisis Ketergantungan: act menganalisis ketergantungan antara pekerjaan dalam alur kerja (menggunakan kata kunci needs:) untuk menentukan urutan eksekusi yang benar.
  4. Manajemen Gambar Docker: Untuk setiap pekerjaan, act mengidentifikasi lingkungan runner yang ditentukan (misalnya, runs-on: ubuntu-latest). Ini kemudian memetakan ini ke gambar Docker tertentu. act menggunakan API Docker untuk:
  1. Eksekusi Kontainer: act menggunakan API Docker untuk membuat dan menjalankan kontainer untuk setiap langkah dalam sebuah pekerjaan. Ia mengonfigurasi kontainer ini untuk meniru lingkungan GitHub Actions sedekat mungkin:
  1. Streaming Log: act mengalirkan log dari kontainer yang sedang berjalan langsung ke terminal Anda, memberikan umpan balik waktu nyata tentang kemajuan eksekusi dan kesalahan yang terjadi.

Secara esensial, act mengorkestrasi kontainer Docker lokal untuk mereplikasi alur eksekusi dan lingkungan alur kerja GitHub Actions Anda.

Prasyarat: Instalasi Docker

Ketergantungan inti untuk act adalah Docker. act memanfaatkan mesin Docker untuk membuat lingkungan terisolasi yang dibutuhkan untuk menjalankan langkah-langkah alur kerja Anda. Sebelum menginstal act, Anda harus memiliki instalasi Docker yang berfungsi di sistem Anda.

Menginstal act

Setelah Docker berjalan, Anda dapat menginstal act. Ada beberapa cara untuk melakukannya, tergantung pada sistem operasi dan preferensi Anda.

1. Homebrew (macOS dan Linux)

Jika Anda menggunakan manajer paket Homebrew, instalasi cukup sederhana:

brew install act

Ini menginstal rilis stabil terbaru. Jika Anda ingin versi pengembangan terbaru (yang mungkin memerlukan kompiler), Anda dapat menggunakan:

brew install act --HEAD

2. Ekstensi GitHub CLI (macOS, Windows, Linux)

Jika Anda sudah menggunakan GitHub CLI (gh), Anda dapat menginstal act sebagai ekstensi:

gh extension install nektos/gh-act

Setelah instalasi, Anda memanggil act melalui perintah gh:

gh act          # Alih-alih hanya 'act'
gh act -l
gh act pull_request

3. Chocolatey (Windows)

Bagi pengguna manajer paket Chocolatey di Windows:

choco install act-cli

(Catatan: Beberapa sumber mungkin mencantumkan act sebagai pengganti act-cli. Periksa nama paket terbaru di repositori komunitas Chocolatey jika Anda mengalami masalah.)

4. Scoop (Windows)

Bagi pengguna manajer paket Scoop di Windows:

scoop install act

5. WinGet (Windows)

Bagi pengguna Windows Package Manager (winget):

winget install nektos.act

6. Skrip Instalasi Linux

Skrip kenyamanan tersedia untuk distribusi Linux tanpa akses mudah melalui manajer paket:

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

(Catatan: Selalu berhati-hati saat mengalirkan skrip langsung ke sudo. Tinjau konten skrip terlebih dahulu jika Anda memiliki kekhawatiran tentang keamanan.)

7. Metode Lain (Arch, COPR, MacPorts, Nix)

Petunjuk instalasi untuk manajer paket lain seperti pacman (Arch), COPR (Fedora), MacPorts, dan Nix tersedia di dokumentasi resmi act:

Verifikasi:

Setelah instalasi, buka jendela terminal baru dan jalankan:

act --version
# atau jika menggunakan ekstensi gh:
gh act --version

Ini harus mencetak versi act yang terpasang, mengonfirmasi bahwa instalasi berhasil.

Konfigurasi Awal: Gambar Runner

Ketika Anda menjalankan act untuk pertama kalinya dalam direktori proyek, mungkin akan meminta Anda untuk memilih ukuran gambar runner default. GitHub Actions menawarkan runner dengan sumber daya yang bervariasi dan perangkat lunak yang sudah diinstal sebelumnya. act berusaha meniru ini dengan menggunakan berbagai gambar Docker dasar.

Anda biasanya akan disajikan pilihan seperti ini:

? Silakan pilih gambar default yang ingin Anda gunakan dengan act:

  - Micro: Gambar minimal dengan dukungan nodejs (~200MB) docker.io/node:16-buster-slim
  - Medium: Gambar Act dengan alat dasar (~500MB) ghcr.io/catthehacker/ubuntu:act-latest
  - Large: Gambar runner GitHub Actions (~17GB) ghcr.io/catthehacker/ubuntu:full-latest

Gambar default? [Medium]:

Rekomendasi: Mulailah dengan gambar Medium. Ini memberikan keseimbangan yang baik dan bekerja untuk banyak kasus penggunaan umum. Jika Anda mengalami masalah karena perangkat lunak yang hilang, Anda dapat menginstal perangkat lunak tersebut dalam langkah-langkah alur kerja Anda atau beralih menggunakan gambar Large untuk runner tertentu tersebut (lebih lanjut tentang ini nanti).

act menyimpan pilihan Anda dalam file konfigurasi (~/.actrc). Anda dapat mengubah default nanti dengan mengedit file ini atau menjalankan kembali act di direktori di mana ia perlu dikonfigurasi.

Penggunaan Inti act: Menjalankan Alur Kerja Anda

Setelah diinstal dan dikonfigurasi, menggunakan act relatif sederhana. Arahkan ke direktori root proyek Anda (yang berisi folder .github) di terminal Anda.

1. Jalankan Acara Default (push)

Perintah paling sederhana menjalankan alur kerja yang dipicu oleh acara default push:

act
# atau
gh act

act akan mem-parsing alur kerja Anda, mengidentifikasi pekerjaan yang dipicu on: push, menarik gambar Docker yang diperlukan (jika belum di-cache), dan mengeksekusi pekerjaan tersebut.

2. Daftar Alur Kerja dan Pekerjaan yang Tersedia

Untuk melihat alur kerja dan pekerjaan mana yang dikenali act dan akan dijalankan untuk acara default:

act -l
# atau
gh act -l

Ini menghasilkan daftar seperti:

Stage  Job ID        Nama Pekerjaan  Nama Alur Kerja  File Alur Kerja  Acara
0      build         Membangun      CI Pipeline    ci.yaml        push
1      test          Uji           CI Pipeline    ci.yaml        push
1      lint          Lint          Kualitas Kode   codeql.yaml    push,pull_request

3. Jalankan Pekerjaan Tertentu

Jika Anda hanya ingin menguji satu pekerjaan dari sebuah alur kerja, gunakan flag -j diikuti dengan ID pekerjaan (dari output act -l):

act -j build
# atau
gh act -j build

4. Memicu Acara Tertentu

Alur kerja sering kali dipicu oleh acara selain push. Anda dapat mensimulasikan acara ini dengan memberikan nama acara sebagai argumen ke act:

# Simulasikan acara pull request
act pull_request

# Simulasikan acara workflow_dispatch (pemicu manual)
act workflow_dispatch

# Simulasikan acara jadwal
act schedule

# Simulasikan acara rilis
act release -e event.json # Berikan detail payload acara jika diperlukan

act akan hanya mengeksekusi alur kerja dan pekerjaan yang dikonfigurasi untuk dijalankan on: acara yang ditentukan.

5. Mengirim Input untuk workflow_dispatch

Alur kerja yang dipicu oleh workflow_dispatch dapat menerima input. Anda dapat memberikan input ini menggunakan flag --input atau -i:

# Asumsikan alur kerja Anda memiliki input bernama 'environment'
act workflow_dispatch --input environment=staging

6. Menangani Rahasia

Alur kerja GitHub Actions sering kali bergantung pada rahasia (seperti kunci API atau token). act tidak secara otomatis mengakses rahasia GitHub Anda. Anda perlu memberikan rahasia tersebut secara lokal.

act -s MY_SECRET_TOKEN -s ANOTHER_SECRET

Atau, cukup act -s akan meminta semua rahasia.

export SECRET_MY_SECRET_TOKEN="your_value"
act
MY_SECRET_TOKEN=your_value
ANOTHER_SECRET=another_value

Kemudian jalankan act dengan flag --secret-file:

act --secret-file .secrets

(Pastikan file ini ditambahkan ke .gitignore untuk menghindari komit rahasia!)

7. Menangani Variabel dan Variabel Lingkungan

act --env NODE_ENV=development --env CUSTOM_FLAG=true
act --env-file .env_vars

Mengelola Lingkungan dan Gambar Runner

Sementara gambar runner default (Micro, Medium, Large) mencakup banyak skenario, Anda sering kali memerlukan lebih banyak kontrol.

1. Keterbatasan Gambar Default

Ingat bahwa gambar runner default act (terutama Micro dan Medium) tidak identik dengan lingkungan yang disediakan oleh GitHub. Mereka mungkin kekurangan alat tertentu, pustaka, atau layanan sistem (seperti systemd) yang diharapkan oleh alur kerja Anda. Gambar Large menawarkan fidelitas yang lebih tinggi tetapi datang dengan kelemahan ukuran yang signifikan.

2. Menentukan Gambar Alternatif dengan -P

Jika sebuah pekerjaan memerlukan lingkungan atau seperangkat alat tertentu yang tidak ada di gambar default, Anda dapat memberi tahu act untuk menggunakan gambar Docker yang berbeda untuk platform tertentu menggunakan flag -P (platform).

Formatnya adalah -P <platform>=<docker-image>.

Contoh:

# Gunakan gambar Large khusus untuk pekerjaan yang berjalan di ubuntu-22.04
act -P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:full-22.04

# Gunakan versi Node.js tertentu untuk pekerjaan ubuntu-latest
act -P ubuntu-latest=node:18-bullseye

# Gunakan gambar yang lebih lengkap dari nektos/act-environments (sangat besar!)
# PERINGATAN: nektos/act-environments-ubuntu:18.04 adalah >18GB
act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04

# Tentukan beberapa platform jika alur kerja Anda menggunakannya
act -P ubuntu-20.04=node:16-buster -P ubuntu-22.04=node:18-bullseye

3. Menggunakan Gambar Runner Lokal (--pull=false)

Secara default, act mencoba menarik versi terbaru dari gambar Docker yang ditentukan setiap kali dijalankan. Jika Anda telah membangun gambar runner kustom secara lokal atau ingin memastikan bahwa Anda menggunakan versi yang persis sama yang telah Anda cache, Anda dapat menonaktifkan perilaku ini:

act --pull=false
# atau mungkin menggunakan mode offline
act --action-offline-mode

Ini memberi tahu act untuk menggunakan gambar yang tersedia secara lokal jika ada dan hanya mencoba menarik jika gambar tersebut hilang.

4. Menjalankan Secara Natif di Host (-self-hosted)

Untuk alur kerja yang menargetkan macOS atau Windows (runs-on: macos-latest atau runs-on: windows-latest), jika Anda menjalankan act di sistem operasi host yang sama, Anda dapat memberi instruksi kepada act untuk tidak menggunakan kontainer Docker untuk runner itu sendiri. Sebagai gantinya, ia akan menjalankan langkah-langkah langsung di mesin host Anda. Ini bisa berguna jika kompatibilitas Docker menjadi masalah atau jika Anda perlu mengakses sumber daya host secara langsung.

# Jalankan pekerjaan macos-latest langsung di host Mac Anda
act -P macos-latest=-self-hosted

# Jalankan pekerjaan windows-latest langsung di host Windows Anda
act -P windows-latest=-self-hosted

Perhatian: Menjalankan langsung di host melewati isolasi yang disediakan oleh Docker. Langkah-langkah dalam pekerjaan akan memiliki akses ke sistem file Anda dan berpotensi memodifikasi lingkungan host Anda. Gunakan opsi ini dengan hati-hati. Langkah-langkah dalam pekerjaan yang secara eksplisit menggunakan kontainer Docker (seperti kontainer layanan atau tindakan kontainer) akan tetap menggunakan Docker.

Keterbatasan dan Pertimbangan

Walaupun act sangat berguna, penting untuk menyadari keterbatasannya:

Rekomendasi: Gunakan act untuk pengembangan cepat, pemeriksaan sintaks, pengujian logika dasar, dan melakukan iterasi pada pekerjaan atau langkah individu. Selalu lakukan validasi akhir dengan menjalankan alur kerja Anda di GitHub itu sendiri sebelum menggabungkan perubahan kritis, terutama untuk pipeline penyebaran. Konsultasikan dokumentasi resmi act untuk matriks dukungan terperinci dan masalah yang diketahui.

Kesimpulan

Menguji GitHub Actions secara lokal adalah peningkatan produktivitas yang signifikan, mengubah siklus debug yang lambat dan membosankan menjadi proses yang cepat dan iteratif. Alat CLI act menyediakan cara yang tangguh dan fleksibel untuk mencapai ini dengan memanfaatkan Docker untuk mensimulasikan lingkungan runner GitHub Actions di mesin lokal Anda.

Dengan mengintegrasikan act ke dalam alur kerja Anda, Anda mendapatkan:

Walaupun memiliki keterbatasan dan bukan pengganti 1:1 yang sempurna untuk lingkungan GitHub yang langsung, act mencakup berbagai kasus penggunaan dan secara signifikan mengurangi hambatan dalam mengembangkan alur kerja GitHub Actions yang dapat diandalkan dan efektif. Instal, coba jalankan alur kerja Anda yang ada secara lokal, dan rasakan manfaat berpikir secara global sambil bertindak secara lokal.

💡
Ingin alat Pengujian API yang hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform terintegrasi, All-in-One untuk Tim Pengembang Anda bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Cara Menjalankan GitHub Actions Secara Lokal dengan Act