GitHub Actions Minute Control Runbook

Purpose

• Giữ GitHub-hosted Actions ở mức đủ dùng, không đốt quota vì cron dày hoặc failure loop.
• Là file ngắn để AI và owner dùng lại khi sửa .github/workflows/**.

Khi nào phải đọc

• Khi thêm hoặc sửa workflow trong .github/workflows/**.
• Khi repo private bị chạm quota, billing limit, hoặc có failure loop từ scheduled workflows.
• Khi muốn thêm automation mới cho reminder, sync, reconcile, deploy, hoặc review queue.

Hard rules

1. Repo private không dùng cron dày hơn 6 giờ/lần nếu chưa có owner approval rõ ràng.
2. Ưu tiên push, repository_dispatch, hoặc trigger thủ công hơn schedule.
3. Workflow kiểu reminder/inbox không chạy 24/7; mặc định chỉ chạy thứ 2-6 và tối đa 2 lần/ngày.
4. Mọi scheduled workflow phải có đủ:
   • workflow_dispatch
   • concurrency.cancel-in-progress: true
   • timeout-minutes
5. Mọi early-exit phải xảy ra trước setup-node, npm ci, build, hoặc network-heavy steps nếu có thể.
6. Không tạo thêm job notify-failure riêng cho cron trừ khi alert đó quan trọng hơn chi phí; mặc định chỉ alert ở manual lane.
7. Tổng baseline từ tất cả cron trong repo private phải thấp hơn 25% quota tháng. Nếu vượt, giảm lịch trước khi thêm workflow mới.
8. Khi billing bị block hoặc quota cạn, ưu tiên disable workflow scheduled trên GitHub remote thay vì để nó fail lặp.

Current paused set

• Trạng thái khẩn cấp hiện tại: pause scheduled workflows đến kỳ reset Actions vào 2026-04-01.
• Disabled manually:
  • Auto Sync External Docs To Repo
  • Review Inbox
  • High Risk SLA Reminder
  • Governance Weekly Report
  • Reconcile Doc Artifact Drift ở repo dol-wiki

Re-enable after reset

gh workflow enable "Auto Sync External Docs To Repo" -R wblekhoa/DOL-Education-Documentation
gh workflow enable "Review Inbox" -R wblekhoa/DOL-Education-Documentation
gh workflow enable "High Risk SLA Reminder" -R wblekhoa/DOL-Education-Documentation
gh workflow enable "Governance Weekly Report" -R wblekhoa/DOL-Education-Documentation
gh workflow enable "Reconcile Doc Artifact Drift" -R wblekhoa/dol-wiki

Manual ship window

• Áp dụng từ bây giờ đến khi scheduled workflows được bật lại.
• Mục tiêu: vẫn ship được thay đổi cần thiết, nhưng không phụ thuộc vào scheduled GitHub Actions.

Lane 1: Manual docs commit

• Dùng khi thay đổi nằm chủ yếu ở docs/** hoặc openspec/** trong repo docs.
• Flow mặc định:
  1. cd "DOL Education Documentation"
  2. npm run collab:quick:check
  3. npm run ai:ship:preview
  4. nếu preview đúng scope, npm run ai:ship:push
• Nếu thay đổi chạm workflow, root governance docs, hoặc file ngoài scope docs:
  • dùng npm run ai:ship:all:preview
  • rồi npm run ai:ship:all:push

Lane 2: Manual wiki verify

• Dùng khi cần chắc nội dung docs hiện tại render/bundle ổn ở wiki.
• Flow tối thiểu:
  1. cd "DOL Wiki/site"
  2. npm run verify:assets
• Nếu cần release-grade confidence:
  • npm run verify:release:style
  • hoặc npm run verify:release

Lane 3: Manual artifact publish

• Dùng khi docs đã đổi và cần publish lại doc-artifacts mà không chờ reconcile cron.
• Thực hiện từ repo DOL Wiki/site sau khi verify:
  1. npm run sync
  2. npm run build:artifacts:full
  3. node ./scripts/publish-doc-artifacts.mjs --dir ./.cache/doc-artifacts || node ./scripts/publish-doc-artifacts.mjs
  4. node ./scripts/purge-cache-paths.mjs
• Chỉ chạy lane này khi credentials Cloudflare/R2 đã sẵn sàng trong local env.

Lane 4: Manual deploy

• GitHub Pages deploy qua GitHub-hosted Actions vẫn có thể bị block khi billing chưa reset.
• Safe default trong giai đoạn này:
  • commit/push thủ công trước
  • chỉ deploy khi có yêu cầu rõ từ owner cho từng lần ship
  • ưu tiên lane local đã có sẵn trong repo hơn là bật lại cron
• Nếu cần thử local Cloudflare lane từ repo DOL Wiki/site:
  • npm run deploy:cf
• Chỉ coi deploy là hoàn tất sau khi có bằng chứng URL/endpoint đã lên bản mới.

Default schedules now

• Auto Sync External Docs To Repo: 17 */6 * * *
• Review Inbox: 15 2,9 * * 1-5
• High Risk SLA Reminder: 0 3 * * 1-5
• Governance Weekly Report: 0 1 * * 1
• Reconcile Doc Artifact Drift: 47 */6 * * *

Decision shortcut

• Nếu workflow không cần gần realtime: tăng interval.
• Nếu workflow chỉ để “fallback consistency”: giữ schedule thưa, còn lane chính phải là event-driven.
• Nếu workflow fail vì môi trường hoặc billing: pause remote trước, debug sau.