Triage Kegagalan CI Agentic Workflow dengan gh-aw CI Doctor

Menit paling mahal dalam pipeline yang merah adalah menit pertama: seseorang membuka run, men-scroll ribuan baris log, lalu menebak error mana yang penyebab dan mana yang hanya dampak. Saya ingin tahu apakah agent bisa mengerjakan menit itu tanpa diberi izin menyentuh kode.

CI Doctor dari GitHub, salah satu workflow unggulan di gh-aw (GitHub Agentic Workflows), dibuat persis untuk itu. Saya membaca dokumentasinya, source workflow aslinya, dan halaman keamanan di baliknya. Saya belum menjalankannya di production untuk tulisan ini, jadi setiap klaim di bawah bersumber dari halaman yang saya baca, dan bila halaman diam soal sesuatu, saya katakan begitu.

Mendiagnosis, bukan memperbaiki: keputusan desain yang penting

Output CI Doctor adalah issue, bukan patch. Halaman utama gh-aw menggambarkannya sebagai workflow yang berjalan saat CI gagal, membaca log job yang gagal bersama commit dan pull request pemicunya, lalu membuka satu issue berisi dugaan penyebab dan langkah berikutnya. Jika kegagalan yang sama berulang, ia memperbarui issue yang ada, bukan membuat yang baru.

Itu blast radius yang sengaja dibuat kecil. Agent yang hanya bisa membuat issue bisa saja salah, tetapi tidak bisa mendorong commit yang rusak, dan diagnosis yang salah hanya memakan satu menit untuk ditepis. Prompt workflow-nya sendiri memperkuat hal ini: ia meminta tingkat keyakinan high, medium atau low untuk setiap diagnosis dan melarang menyajikan tebakan sebagai fakta.

Seluruh file workflow, dibaca baris per baris

Workflow ini ada di githubnext/agentics sebagai file Markdown dengan frontmatter YAML dan isi berbahasa natural. Frontmatter di bawah adalah yang saya baca pada file itu pada 17 Oktober 2026; field description dan prompt (sebuah protokol investigasi yang panjang) saya pangkas.

---
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches: [main]

# workflow_run also fires for green and cancelled runs. Filter here so
# the agent job is never even scheduled for them.
if: ${{ github.event.workflow_run.conclusion == 'failure' }}

permissions:          # the agent job is read-only
  actions: read
  contents: read
  issues: read
  pull-requests: read

safe-outputs:         # the only writes, applied by a separate job
  create-issue:
    title-prefix: "[CI failure] "
  add-comment:

timeout-minutes: 10
---

Tiga bagian memikul desainnya. Kondisi if pada conclusion workflow mencegah agent berjalan untuk run yang sukses atau dibatalkan. Blok permissions hanya memberi akses baca pada agent job, termasuk actions: read yang memungkinkannya mengambil log job. Lalu safe-outputs menyebut satu-satunya dua jenis tulisan: issue dengan title prefix, dan comment.

Isi prompt layak dibaca utuh karena itulah produk sebenarnya. Ia menyuruh agent mulai dari job gagal paling awal dan error bermakna pertama, bukan error-error belakangan yang mungkin hanya akibat, mengklasifikasikan kegagalan sebagai code atau test, dependency atau toolchain, konfigurasi workflow, runner atau network, flaky, atau external service, dan mencari issue yang sudah ada berdasarkan nama workflow, nama job dan teks error khas sebelum membuat apa pun.

Memasangnya, dan alasan Anda harus commit dua file

Dokumentasi CI Doctor memberi instalasi dua perintah lewat extension gh, lalu siklus kustomisasi: ubah trigger, jalankan gh aw compile, dan commit Markdown beserta lock file hasil generate ke default branch. Langkah compile adalah tempat pertahanan pertama gh-aw, karena halaman arsitektur menyebut ia menegakkan schema validation, expression allowlisting dan action pinning, serta bisa menjalankan actionlint, zizmor dan poutine pada hasilnya.

# Install the extension, then add the workflow with the wizard
gh extension install github/gh-aw
gh aw add-wizard githubnext/agentics/ci-doctor

# After editing the Markdown (trigger names, branches, prompt), recompile.
# The extra flags run actionlint, zizmor and poutine over the generated YAML.
gh aw compile --actionlint --zizmor --poutine

# Commit BOTH files to the default branch. The Markdown alone changes nothing:
# Actions runs the compiled .lock.yml.
git add .github/workflows/
git commit -m "ci: add CI Doctor failure triage"

Peringatan di dokumentasi mudah terlewat: mengedit Markdown tanpa compile ulang dan commit lock file tidak memperbarui workflow yang berjalan. Perlakukan file .md sebagai source dan .lock.yml sebagai build artefact yang harus ikut dikirim, lalu tambahkan pengecekan CI yang gagal bila keduanya tidak sinkron.

Jebakan trigger: yang tidak dipantau oleh default

Secara default CI Doctor memantau kegagalan workflow bernama CI pada branch main, dan dokumentasi menyuruh Anda mengubah on.workflow_run.workflows serta on.workflow_run.branches sesuai repository. Namanya harus persis sama dengan nama workflow Anda, sehingga repository dengan pipeline bernama Build, atau deploy di workflow kedua, mendapat keheningan, bukan error.

# Wrong: the default watches only a workflow named "CI" on main.
# A failing "Deploy" workflow or a release branch is never diagnosed.
on:
  workflow_run:
    workflows: ["CI"]
    branches: [main]

# Right: name every workflow you want diagnosed, and the branches that matter.
on:
  workflow_run:
    workflows: ["CI", "Deploy", "Nightly integration"]
    types: [completed]
    branches: [main, "release/*"]

safe-outputs:
  staged: true            # week one: preview the issues in the step summary, write nothing
  create-issue:
    title-prefix: "[CI failure] "
    labels: [ci-failure, agentic]
    max: 1                # one new issue per run
    expires: 14           # integer = days; stale diagnoses close themselves
    close-older-issues: true  # supersede earlier issues from this workflow

Blok kedua adalah varian yang saya sesuaikan, disusun dari opsi di halaman referensi safe-outputs, bukan file yang saya jalankan. Setting staged adalah yang pertama akan saya aktifkan: referensi menyebut staged mode melewati semua penulisan dan menampilkan preview berlabel di step summary Actions, sehingga Anda bisa menilai diagnosis sebelum satu issue pun muncul.

Safe outputs: bagaimana satu kegagalan menjadi satu issue

Output create-issue punya opsi yang menentukan apakah alat ini membantu atau mengganggu. Inilah yang akan saya lihat lebih dulu, dengan default hanya bila halaman menyebutkannya.

CI Doctor sudah melakukan dedup di tingkat prompt, karena instruksinya menyuruh menambah comment pada issue terbuka dengan root cause yang sama alih-alih membuat yang lain. Opsi-opsi ini adalah jaring kedua, ditegakkan oleh handler safe-output dan bukan oleh penilaian model. Halaman yang sama menyebut isi issue harus 20 sampai 65.000 karakter, sehingga diagnosis yang nyaris kosong langsung ditolak.

Enam lapis pertahanan, dipetakan ke build yang gagal

Halaman utama gh-aw membingkai risikonya sebagai lethal trifecta: data privat, konten tidak tepercaya dan akses keluar yang dipegang satu agent sekaligus. Satu run CI Doctor punya ketiga bahannya, karena log adalah teks tidak tepercaya, repository adalah data privat, dan agent bisa berbicara dengan model. Enam lapis di halaman itu adalah cara memecah trifecta tersebut.

Halaman arsitektur menjelaskan pemisahannya: agent job berjalan dengan permission read-only minimal dan tulisannya di-buffer sebagai artifact, sebuah job deteksi tanpa permission tulis mengunduh dan menilainya, baru kemudian job safe-output berjalan dengan permission terbatas seperti issues: write untuk create_issue. Jika deteksi menemukan ancaman, workflow gagal dan tidak ada yang ditulis.

Di mana ia bisa gagal: noise, biaya, titik buta, dan skip yang diam-diam

Mode kegagalan pertama adalah yang saya duga paling dulu muncul: tidak ada output. Trigger default memantau satu workflow di satu branch, kondisi if membuang semua yang bukan kegagalan, dan prompt menyuruh agent tidak membuat issue untuk run yang dibatalkan, duplikat, atau kegagalan tanpa informasi baru yang dapat ditindaklanjuti. Semuanya perilaku yang benar, dan semuanya tampak sama dengan instalasi yang rusak, jadi minggu pertama butuh staged mode dan build merah yang sengaja dibuat.

Yang kedua adalah perilaku lapisan deteksi itu sendiri. Halaman threat detection menyebut timeout default 10 menit untuk job deteksi, catatan bahwa patch besar mungkin perlu lebih lama, dan peringatan bahwa analisis berbasis AI bisa menandai konten yang sah. Halaman itu juga menyebut continue-on-error default true, dengan warning dan kegagalan menghasilkan caution notice alih-alih memblokir. Saya tidak menjalankan workflow untuk melihat interaksinya dengan output yang diblokir, jadi baca lock file hasil compile Anda sebelum mengandalkan deteksi sebagai gerbang keras.

Yang ketiga adalah cakupan dan biaya. Halaman utama menyebut max-ai-credits (default 1.000 per run), max-turns dan max-daily-ai-credits (default 5.000 per 24 jam), sehingga branch main yang merah dengan push gagal tiap beberapa menit tetap terbatas, bukan tanpa batas. Terpisah dari itu, catatan rilis v0.88.4 pekan 7 September 2026 membahas hardening firewall, perbaikan routing Pi Anthropic dan pembuatan kebijakan DIFC untuk workflow GitHub App, dan tidak menyebut CI Doctor sama sekali, jadi jangan menganggap rilis itu perubahan CI Doctor. Terakhir, halaman integrity tidak menjelaskan bagaimana data workflow_run ditangani, dan pada repository publik tanpa min-integrity ia memakai approved secara default, jadi periksa apa yang berubah menurut visibilitas repository Anda.

Yang dikerjakan hari Senin

Jalankan ini sebagai eksperimen satu minggu pada satu repository, dengan penulisan dimatikan, dan nilai dari diagnosisnya, bukan dari daftar fiturnya.

1. Daftar nama workflow dan kegagalan terbaru Anda dengan perintah gh di bawah, agar trigger cocok persis dan Anda punya test set.
2. Pasang dengan gh aw add-wizard, ubah on.workflow_run.workflows dan branches, set safe-outputs staged ke true, lalu compile dan commit kedua file.
3. Buat satu kegagalan yang disengaja pada branch yang dicakup trigger, lalu baca preview di step summary Actions.
4. Bandingkan diagnosisnya dengan kesimpulan manusia dari log yang sama, dan catat tingkat keyakinan yang dipilihnya.
5. Matikan staged hanya bila diagnosis lebih sering benar daripada berisik, lalu tambahkan labels, max, expires dan close-older-issues.

# 1. List the workflow names your repository actually has. These are the
#    strings workflow_run.workflows must match, character for character.
gh workflow list --all --json name,state --jq '.[] | [.name, .state] | @tsv'

# 2. Find your most recent real failures: the test set for the first week.
gh run list --status failure --limit 20   --json databaseId,workflowName,headBranch,displayTitle   --jq '.[] | [.databaseId, .workflowName, .headBranch, .displayTitle] | @tsv'

# 3. Read the log the agent will read, starting from the earliest failed job.
gh run view <run-id> --log-failed | head -80

Jika diagnosisnya bagus, pertanyaan berikutnya bukan bagaimana membiarkan agent memperbaiki sesuatu, melainkan apakah field confidence dan kategori klasifikasinya cukup konsisten untuk merutekan issue ke pemilik berbeda secara otomatis.

Agent triage kegagalan mendapat kepercayaan dengan menjadi membosankan: read-only saat masuk, satu penulisan terdeklarasi saat keluar, dan diagnosis yang bisa ditepis dalam semenit. Mulai dengan staged mode, buat trigger cocok dengan nama workflow asli Anda, dan nilai dari apakah paragraf pertama tiap issue menghemat waktu manusia dari scroll log.