GitHub Agentic Workflows: Otomasi Markdown dengan gh aw

Workflow yang biasanya saya tulis sebagai tumpukan shell dan curl ternyata, di halaman contoh GitHub, hanya satu paragraf bahasa biasa: ringkas issue kemarin, buat satu laporan. Di atasnya ada satu layar YAML yang menentukan apa saja yang boleh disentuh paragraf itu. Pemisahan inilah inti GitHub Agentic Workflows: instruksi dalam prosa, otoritas dalam config.

Ini bacaan mendalam, bukan laporan lapangan. Saya membaca changelog GitHub, halaman dokumentasi gh-aw tentang architecture, safe outputs, engines, frontmatter dan triggers, README, serta contoh repo-status dari repository githubnext/agentics. Saya belum menjalankan gh-aw di repository produksi, dan saya sebutkan itu di bagian yang relevan. Setiap flag dan default di bawah berasal dari halaman yang saya baca pada 17 Oktober 2026.

Markdown adalah sumber, lock file yang dijalankan

Changelog GitHub mengumumkan technical preview pada 13 Februari 2026. Anda menjelaskan tujuan otomasi dalam file Markdown di .github/workflows/, lalu CLI gh aw mengubahnya menjadi workflow Actions standar. FAQ proyek kini menyebut gh-aw berstatus public preview, dan repository-nya berlisensi MIT. Trigger-nya yang sudah familier: event issue dan pull request, schedule, manual dispatch, atau perintah di komentar.

Hasilnya dua file. File Markdown, misalnya repo-status.md, adalah yang Anda edit. File repo-status.lock.yml hasil generate adalah yang dijalankan GitHub Actions, dan FAQ meminta kedua file di-commit karena lock file harus di-generate ulang setelah frontmatter berubah. Frontmatter adalah kontraknya: trigger, permissions, tools, safe outputs, engine. Body adalah prompt yang dibaca agent. Quick start hanya meminta compile ulang bila frontmatter berubah, yang saya baca sebagai tanda bahwa body dibaca saat run, bukan ditanam di lock file. Itu inferensi saya, jadi uji dulu sebelum bergantung padanya.

Workflow nyata, dibaca baris demi baris

Cara terbaik memahami gh-aw adalah contoh yang diarahkan GitHub untuk pengguna baru: repo-status dari repository githubnext/agentics. Workflow ini membuat issue status harian. Berikut frontmatter-nya dengan komentar dari saya, dan body dipangkas.

# .github/workflows/repo-status.md  (the frontmatter of GitHub's sample,
# githubnext/agentics, comments shortened)
---
description: |
  This workflow creates daily repo status reports.

on:
  schedule: daily          # the page shows this shorthand; no cron string
  workflow_dispatch:       # so you can also press the button

permissions:               # what the AGENT job may read. Nothing here writes.
  contents: read
  issues: read
  pull-requests: read

network: defaults          # egress allowlist; explicit, no wildcard domains

tools:
  bash: ["cat", "ls", "find", "grep", "head", "tail", "wc"]
  github:
    lockdown: false        # public repo: allow reading 3rd-party issues
    min-integrity: none    # the sample opts OUT of the integrity filter

safe-outputs:              # the only writes that can ever happen
  mentions: false
  allowed-github-references: []
  create-issue:
    title-prefix: "[repo-status] "
    labels: [report, daily-status]
    close-older-issues: true
---

# Repo Status

Create an upbeat daily status report for the repo as a GitHub issue.
## What to include
- Recent repository activity (issues, PRs, discussions, releases, code changes)
- Actionable next steps for maintainers

Bacalah dari bawah. Safe outputs menyatakan satu-satunya write adalah satu issue, dengan prefix judul dan label tetap, dan issue status lama ditutup. Mentions dimatikan dan referensi eksternal diblokir, jadi at-mention hasil halusinasi tidak bisa memanggil siapa pun. Blok permissions semuanya read. Tool bash hanya allowlist tujuh perintah read-only, bukan shell bebas.

Satu baris patut dicurigai: min-integrity none. Halaman architecture menyebut konten dari penulis berpercaya rendah disaring dengan threshold min-integrity, dan repository publik otomatis memakai approved. Contoh ini sengaja mematikan filter itu dan komentarnya sendiri mengatakan boleh memeriksa issue apa pun. Itu pilihan wajar untuk laporan status, tetapi default yang buruk untuk disalin ke workflow yang juga bisa menulis.

Install, autentikasi, jalankan, dan awasi tagihan

Quick start hanya lima perintah. Wizard menanyakan engine yang Anda mau, mengatur autentikasi, menulis file ke .github/workflows/ dan bisa memicu run pertama. Autentikasi adalah tempat engine berbeda, dan untuk Claude Code halaman itu spesifik soal satu jebakan.

# 1. Install the GitHub CLI extension
gh extension install github/gh-aw

# 2. Pull the sample in. The wizard asks for an engine, sets up auth,
#    writes the files into .github/workflows/ and can trigger a first run.
gh aw add-wizard githubnext/agentics/repo-status

# 3. Give the chosen engine a credential. For Claude Code that is an API key.
#    A CLAUDE_CODE_OAUTH_TOKEN from "claude login" is NOT supported.
gh secret set ANTHROPIC_API_KEY < /path/to/key.txt

# 4. Only if you edited the frontmatter by hand
gh aw compile

# 5. Run it, then look at what it cost
gh aw run repo-status
gh aw status
gh aw logs                 # tokens, AI Credits and turns per run
gh aw audit RUN_ID         # one run, broken down

Copilot CLI adalah engine default, jadi field engine boleh dihilangkan untuknya. Tabel ini adalah halaman engines yang diringkas. Satu hal yang perlu diketahui: Codex tidak punya model default di gh-aw, jadi Anda harus menentukannya sendiri.

Biaya punya tiga tuas yang terdokumentasi. Halaman frontmatter menyebut max-turns dengan default 500, max-ai-credits dengan default 1000, dan timeout-minutes dengan default 20. Situs proyek menyatakan 1 AI Credit sama dengan satu sen, jadi dengan hitungan itu batas default per run sekitar sepuluh dolar. Itu batas atas, bukan perkiraan. FAQ menambahkan bahwa gh-aw sendiri gratis dan Anda juga membayar menit Actions, gratis untuk repository publik dan berbayar untuk privat. Pasang max-ai-credits yang lebih rendah sebelum schedule pertama, bukan setelah tagihan pertama.

Apa yang sebenarnya dilakukan gh aw compile

Kompilasi membuat ini lebih dari sekadar prompt di dalam YAML. Halaman architecture menyebut compiler menjalankan schema validation, expression allowlist dan action SHA pinning, lalu security scanner, dan quick start menambahkan bahwa hasilnya di-commit. Kegagalan yang perlu dihindari itu senyap, dan bentuknya seperti ini.

# Wrong: edit the frontmatter, commit only the Markdown. Actions runs the
# .lock.yml, so the OLD triggers and permissions keep executing.
git add .github/workflows/repo-status.md
git commit -m "Run twice a day"

# Right: recompile, then commit both files and review the lock diff.
gh aw compile
git add .github/workflows/repo-status.md .github/workflows/repo-status.lock.yml
git commit -m "Run twice a day"

# The architecture page also lists extra scanners the compiler can run:
gh aw compile --actionlint --zizmor --poutine

Strict mode aktif secara default. Halaman frontmatter menyebut workflow yang di-compile dengan strict false tidak bisa berjalan di repository publik, dan halaman architecture mendaftar apa yang ditegakkan strict: tidak ada write permission di konfigurasi agent, konfigurasi network harus eksplisit, tidak ada wildcard domain dan tidak ada field deprecated. Semua itu pemeriksaan atas file, makanya ada di compile time.

Halaman yang sama jujur soal batasnya: compiler tidak membatasi perilaku saat runtime. Ia bisa membuktikan frontmatter Anda konservatif. Ia tidak bisa membuktikan model akan berperilaku baik, dan itulah alasan bagian berikutnya ada.

Pemisahan permission: agent membaca, job lain menulis

Halaman architecture menggambarkan pipeline job, dan cara mudah mengingatnya adalah dari siapa yang boleh menulis. Agent tidak pernah. Outputnya ditampung sebagai artifact, job detection memeriksanya, baru kemudian job dengan permission sempit menerapkannya.

Halaman itu mencantumkan issues: write untuk job issue dan label, serta contents: write plus pull-requests: write untuk pembuatan pull request. Untuk job activation tidak ada permission yang disebut, jadi saya tidak menebaknya. Safe outputs adalah kosakata permintaan yang boleh diajukan agent. Halaman safe outputs mendaftar puluhan, dari create-issue sampai merge-pull-request yang ditandai experimental, dan masing-masing punya batas default: create-issue 1, add-comment 1, close-pull-request 10.

# Safe outputs are a vocabulary of requests, each with its own ceiling.
safe-outputs:
  staged: true             # preview in the step summary, write nothing
  add-labels:
    allowed: [bug, team-*, area/*]   # anything else is refused
    blocked: ["~*", "*[bot]"]        # evaluated BEFORE allowed
    max: 10                          # label operations per run
    max-labels: 5
  add-comment:
    max: 3
    hide-older-comments: true
  submit-pull-request-review:
    allowed-events: [COMMENT]        # the agent can never APPROVE

Kredensial mengikuti aturan yang sama. Halaman architecture menyebut secret dikirim lewat environment variable, dan sebelum artifact diunggah, file di bawah /tmp/gh-aw dipindai lalu nilai secret di-mask dengan exact string match, bukan regex. Agent juga berjalan di balik firewall yang egress-nya lewat allowlist domain, sehingga instruksi injeksi untuk mengirim token Anda ke orang asing tidak punya tujuan yang tidak Anda daftarkan.

Kapan lebih baik dari workflow tulisan tangan, dan kapan tidak

FAQ tegas soal batasnya: gh-aw melengkapi Actions, bukan menggantikannya. Pekerjaan deterministik tetap deterministik. Tabel ini perbandingan saya, hanya dari klaim di halaman-halaman di atas.

Pola yang ditunjuk katalog contoh adalah pekerjaan yang butuh penilaian dengan permukaan write kecil: triage, laporan status, perawatan dokumentasi, pengecekan link, meninjau CI yang gagal. Situs proyek mencantumkan Repo Assist, CI Doctor, Repo Status dan Test Improver sebagai empat unggulannya. Itu tugas yang jawaban salahnya hanya berujung issue tertutup, bukan deploy rusak.

Apa yang bisa salah: trade-off yang harus disebut

Pertama, jaring pengaman punya lapisan lunak. Job detection sendiri adalah AI agent, jadi ia pemeriksaan probabilistik, dan halaman architecture tidak membahas tingkat false-negative-nya. Ia berdiri di belakang kontrol deterministik, yaitu permission read-only, firewall dan batas safe output. Anggap ia lapisan ketiga, bukan yang pertama.

Kedua, tool ini bergerak cepat dan sudah pernah punya security advisory. README menyebut GHSA-8h78-hpm7-29gg memengaruhi versi dari 0.83.3 sampai sebelum 0.85.4, dan rilis itu ditarik sebagai langkah berjaga-jaga. Halaman releases GitHub menampilkan v0.91.14 pada 14 Oktober, v0.92.0 pada 15 Oktober dan v0.92.3 pada 16 Oktober 2026. Ritme itu bagus untuk perbaikan dan merepotkan siapa pun yang butuh toolchain beku yang sudah direview.

Ketiga, drift senyap dari bagian sebelumnya: ubah frontmatter, lupa compile ulang, dan Actions terus menjalankan permission dan trigger lama. Step CI yang menjalankan gh aw compile dan gagal bila ada diff kotor mengubahnya jadi kegagalan yang berisik. Pemeriksaan itu saran saya, bukan fitur yang terdokumentasi.

Keempat, batas dukungan. FAQ menyebut runner macOS tidak didukung karena tidak punya container job, workflow yang dipakai sebagai required status check butuh inlined-imports bernilai true agar runtime import ter-resolve, dan GitHub Enterprise Server lama butuh compatibility mode. Staging juga bukan sandbox: halaman staged mode mengingatkan bahwa custom job, script dan MCP server eksternal butuh kontrol sendiri.

Yang dilakukan hari Senin

Jangan mulai dengan workflow unggulan di repository utama. Mulai dengan satu otomasi berisiko rendah di repository percobaan, dan perluas hanya setelah preview-nya membosankan.

1. Install extension lalu jalankan gh aw add-wizard githubnext/agentics/repo-status di repository percobaan. Baca lock file hasilnya sekali dari awal sampai akhir.
2. Tulis satu workflow sendiri, sekecil sketsa di bawah, dengan staged bernilai true di bawah safe-outputs. Mode staged menjalankan agent sepenuhnya tetapi mengganti write dengan preview di step summary.
3. Atur max-ai-credits dan timeout-minutes lebih rendah dari default sebelum schedule pertama.
4. Jalankan gh aw compile di CI dengan scanner tambahan, dan gagalkan build bila lock file berbeda dari yang di-commit.
5. Setelah seminggu, baca gh aw logs. Pertahankan workflow hanya jika biaya credit-nya lebih kecil dari pekerjaan manual yang dihapusnya, dan hapus baris staged hanya setelah membaca beberapa preview.

# .github/workflows/issue-labeler.md
# Composed by me from the documented fields. Run gh aw compile before
# trusting it: I have not compiled this exact file.
---
description: Suggest one label for each newly opened issue.

on:
  issues:
    types: [opened]

permissions:
  contents: read
  issues: read

engine: claude             # needs the ANTHROPIC_API_KEY secret
network: defaults
timeout-minutes: 10        # the documented default is 20
max-ai-credits: 100        # 1 AI Credit is $0.01 per the project site

safe-outputs:
  staged: true             # delete this line only after reading a few previews
  add-labels:
    allowed: [bug, question, docs]
    max: 1
---

# Issue labeler

Read the newly opened issue. Choose exactly one of bug, question or docs.
If none clearly fits, choose nothing. Never comment, never close.

Sketsa itu meminta satu keputusan dari agent dan mengizinkan tepat satu write. Itu bentuk yang akan saya percaya lebih dulu: pertanyaan sempit, daftar jawaban tertutup, dan batas satu.

Aturan yang saya bawa dari sini: taruh otoritas di frontmatter dan penilaian di prosa, dan jangan biarkan prosa melebarkan apa yang diizinkan frontmatter. gh-aw membuat pemisahan itu mekanis, dengan compiler di satu sisi dan agent read-only di sisi lain. Ia masih preview yang berubah tiap minggu, jadi pakai untuk tugas kecil yang bisa dibatalkan dan biarkan build serta deploy tetap di Actions biasa.