Tutorial Menjalankan AI Agent di GitHub Actions dengan Docker Sandboxes

GitHub Agentic Workflows kini mendukung Docker Sandboxes sebagai runtime untuk AI coding agent. Integrasi ini memungkinkan agent berjalan di dalam microVM yang terisolasi, sekaligus tetap memiliki kontrol penuh terhadap lingkungan kerjanya. Artikel ini membahas langkah demi langkah cara menjalankan AI agent di GitHub Actions dengan Docker Sandboxes.

Menurut Docker Blog, Docker Sandboxes hadir sebagai solusi isolasi bagi AI agent yang perlu menjalankan perintah shell, membangun container, dan menjalankan test suite secara otonom. Tanpa isolasi yang tepat, setiap kesalahan agent berpotensi memberikan dampak besar pada runner CI.

Apa itu GitHub Agentic Workflows dan Docker Sandboxes

GitHub Agentic Workflows (gh-aw) adalah ekstensi CLI open source yang mengubah workflow Markdown menjadi GitHub Actions workflow standar. Docker Sandboxes (sbx) sendiri adalah microVM dengan kernel, filesystem, dan network stack tersendiri. Setiap sandbox menjalankan Docker daemon pribadi, sehingga agent mendapatkan root access di dalam VM tanpa pernah menguasai Docker daemon host.

Integrasi antara keduanya resmi tersedia sejak gh-aw versi 0.82.9. Kombinasi ini memungkinkan developer menjalankan agent dengan kebebasan tinggi di dalam batasan yang ketat.

Persiapan Repository dan Dependensi

Sebelum memulai, pastikan repository kamu memiliki struktur yang mendukung agent exploration. Buat file REQUIREMENTS.md di root repository untuk mendokumentasikan invariant yang harus dijaga. Siapkan juga test suite yang dapat dijalankan secara otomatis, misalnya dengan Testcontainers untuk integrasi test.

Pastikan repository memiliki file REQUIREMENTS.md yang jelas, script test yang dapat dieksekusi, serta konfigurasi dependensi yang dapat diinstal oleh agent secara otonom. Semakin eksplisit dokumentasi kamu, semakin akurat hasil eksplorasi agent.

Langkah 1: Membuat Workflow Markdown

Buat file Markdown di .github/workflows/sandbox-explorer.md. File ini akan dikompilasi menjadi GitHub Actions workflow dengan ekstensi .lock.yml. Berikut contoh konfigurasi frontmatter yang diperlukan:

---
name: "Docker Sandboxes sample: exploratory test"
on:
  workflow_dispatch:
runs-on: ubuntu-24.04
permissions:
  contents: read
  copilot-requests: write
engine: copilot
network:
  allowed:
    - defaults
    - github
    - containers
    - java
sandbox:
  agent:
    id: awf
    runtime: docker-sbx
    elevated: true
tools:
  edit:
  bash: [":*"]
safe-outputs:
  create-pull-request:
    title-prefix: "[docker-sbx sample] "
    draft: true
    protected-files: blocked
    allowed-files:
      - "src/**"
---

Tiga baris di bawah sandbox.agent menentukan Docker Sandbox sebagai runtime. Di dalam sandbox, agent memiliki akses root dan shell tanpa batas untuk membangun aplikasi serta menjalankan infrastruktur test. Konfigurasi network.allowed membatasi akses jaringan ke destinasi yang telah ditentukan.

Langkah 2: Menentukan Tugas Agent dalam Markdown

Setelah frontmatter, tambahkan instruksi tugas dalam bahasa alami. Agent akan membaca dan mengeksekusi instruksi ini. Berikut contoh tugas untuk bounded exploratory testing:

Act as a bounded exploratory tester for this repository.

Then:
1. Read REQUIREMENTS.md and the relevant source and test files.
2. Run ./scripts/test-in-docker.sh without changing anything.
3. Add a PostgreSQL Testcontainers test that checks registration of two
   addresses that differ only in letter case.
4. Run the focused test and explain the observed behavior.
5. If the implementation violates the documented invariant, make the
   smallest source correction and open a draft pull request.

Instruksi ini memberikan batasan yang jelas: baca dokumen, jalankan test baseline, tambahkan test baru, analisis hasilnya, dan perbaiki kode jika diperlukan. Pendekatan bounded exploratory testing mencegah agent melakukan perubahan di luar cakupan yang diminta.

Langkah 3: Mengompilasi dan Menjalankan Workflow

Instal ekstensi gh-aw melalui GitHub CLI, lalu kompilasi workflow:

gh extension install github/gh-aw
gh aw compile .github/workflows/sandbox-explorer.md

Perintah ini menghasilkan file .github/workflows/sandbox-explorer.lock.yml yang merupakan GitHub Actions workflow standar. Workflow tersebut dapat dijalankan melalui tab Actions di repository atau dengan workflow_dispatch.

Ketika workflow berjalan, GitHub Actions akan menginstal sandbox tooling, mengautentikasi sandbox, memeriksa runner, menjalankan agent di dalam microVM, dan membersihkan semua resource setelah selesai. Proses ini berjalan otomatis tanpa intervensi manual.

Langkah 4: Memahami Arsitektur Isolasi

Arsitektur isolasi Docker Sandboxes berlapis. Setiap sandbox adalah microVM dengan kernel tersendiri. Agent berjalan di dalam VM tersebut dan berkomunikasi dengan Docker daemon pribadi. Socket Docker ini dipasang ke container build, memungkinkan Testcontainers menjalankan database PostgreSQL seolah-olah di mesin lokal developer.

Untuk menjalankan Maven di dalam container sambil memberikan akses ke Docker socket sandbox, gunakan perintah seperti berikut:

docker run --rm \
  --add-host=host.testcontainers.internal:host-gateway \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.testcontainers.internal \
  -v "$PWD:/workspace" \
  -w /workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  maven:3.9.9-eclipse-temurin-21 \
  mvn --batch-mode test

Struktur berlapis ini memastikan agent dapat menjalankan test integration dengan database nyata tanpa mengorbankan keamanan runner CI.

Langkah 5: Mengamankan Output dengan Safe Outputs

Konfigurasi safe-outputs memastikan pull request yang dibuat oleh agent tetap dalam batasan aman. Dalam contoh di atas, draft PR hanya boleh mengubah file di bawah src/**. File sensitif seperti konfigurasi CI atau secret tidak dapat dimodifikasi.

Selain itu, blok network.allowed membatasi tujuan jaringan yang dapat diakses job. Agent tetap memiliki akses ke registry container, Maven repository, dan GitHub API, namun tidak dapat menghubungi endpoint arbitrer di internet. Pembatasan ini mengurangi surface area serangan secara signifikan.

Tips Optimasi dan Troubleshooting

Pastikan image container yang digunakan oleh agent sudah tersedia di registry publik agar proses build tidak terhambat. Gunakan image dengan tag spesifik dan hash digest untuk menghindari supply chain attack. Periksa juga log microVM secara berkala untuk memastikan agent tidak mengalami out-of-memory saat menjalankan test suite besar.

Jika agent gagal memulai Docker daemon di dalam sandbox, verifikasi bahwa runner menggunakan ubuntu-24.04 dan sandbox tooling sudah terinstal dengan benar. Kadangkala restart workflow dispatch dapat mengatasi masalah sementara yang disebabkan oleh race condition saat inisialisasi microVM.

Kesimpulan

Docker Sandboxes di GitHub Actions menawarkan keseimbangan antara kekuatan dan keamanan untuk AI coding agent. Dengan arsitektur microVM, agent memiliki kebebasan penuh di dalam lingkungan terisolasi tanpa membahayakan runner CI. Langkah-langkah di atas dapat diadaptasi untuk berbagai stack teknologi, mulai dari Node.js hingga Python dan Go.

Untuk contoh lengkap yang dapat di-deploy langsung, kunjungi repository demo Docker Sandboxes dengan GitHub Agentic Workflows.