act: chạy GitHub Actions ngay trên máy, hết vòng lặp commit fix ci

Quy trình sửa GitHub Actions quen thuộc là: sửa file YAML, commit "fix ci", push, chờ vài phút, thấy lỗi, lặp lại. Lịch sử commit đầy "fix ci 2", "fix ci 3" và mỗi vòng tốn vài phút. act chạy workflow GitHub Actions ngay trên máy bạn: đọc các file trong .github/workflows/, dựng container Docker tương ứng với runner, và chạy các bước như trên GitHub. Vòng phản hồi giảm từ vài phút xuống vài giây.

GitHub: https://github.com/nektos/act · khoảng 73 nghìn sao · Go · MIT

Cài đặt

brew install act                         # macOS/Linux
gh extension install nektos/gh-act       # dùng như "gh act"

act cần Docker đang chạy. Lần chạy đầu, act hỏi bạn chọn image runner mặc định: Micro (nhỏ, thiếu nhiều công cụ), Medium (cân bằng, đủ cho đa số) hoặc Large (giống runner GitHub nhất nhưng rất nặng, hàng chục GB). Lựa chọn được lưu vào file .actrc.

Cách dùng cơ bản

act -l                     # liệt kê mọi job và sự kiện kích hoạt
act                        # chạy các workflow kích hoạt bởi sự kiện push
act pull_request           # giả lập sự kiện pull_request
act -j test                # chỉ chạy job tên "test"
act -W .github/workflows/ci.yml   # chỉ chạy một file workflow
act -n                     # dry run: chỉ hiện sẽ làm gì

Secrets, biến và sự kiện

Ví dụ quy trình

# 1. Xem có những job nào
act -l
# 2. Chạy riêng job lint khi đang sửa
act -j lint
# 3. Chạy toàn bộ CI của PR với token thật
act pull_request -s GITHUB_TOKEN="$(gh auth token)"
# 4. Khi đã xanh trên máy, mới push

Giới hạn cần biết

• Môi trường container không giống hệt runner GitHub: thiếu công cụ cài sẵn, khác quyền, khác hệ điều hành. Runner macOS và Windows không được giả lập đầy đủ như Linux.
• Một số tính năng phụ thuộc hạ tầng GitHub (OIDC, cache, artifact, một số action chỉ chạy trên GitHub) có thể không hoạt động hoặc cần cấu hình thêm.
• Bước deploy thật sẽ thật sự deploy nếu bạn truyền secret thật. Dùng điều kiện như if: ${{ !env.ACT }} để bỏ qua bước nguy hiểm khi chạy bằng act (act đặt biến môi trường ACT).
• Image Large rất nặng; bắt đầu với Medium và chỉ đổi khi thiếu công cụ.

Áp dụng thế nào?

• Dev: Khi sửa workflow, chạy act -j <job> trước khi push. Ít commit "fix ci", ít phút CI bị đốt.
• Tech Lead: Thêm hướng dẫn act vào CONTRIBUTING, và đánh dấu các bước deploy bằng điều kiện ACT để chạy cục bộ an toàn.
• PM: Vòng phản hồi CI ngắn hơn giúp sửa pipeline nhanh, giảm thời gian chờ và chi phí phút chạy GitHub Actions.