Chạy GitHub Actions Local với Act
Hướng dẫn sử dụng act để chạy GitHub Actions trên máy local, tiết kiệm thời gian và tăng hiệu quả phát triển.
Bạn đã bao giờ phải push code lên GitHub chỉ để test một workflow không hoạt động như mong đợi? Hoặc phải chờ đợi hàng phút để CI chạy lại sau mỗi thay đổi nhỏ? 🤔
Trong bài viết này, mình sẽ giới thiệu act - công cụ giúp bạn chạy GitHub Actions ngay trên máy local, thay vì phải đợi GitHub xử lý từ xa.
Tại sao cần chạy GitHub Actions local?#
Hãy tưởng tượng bạn đang sửa một workflow CI/CD. Quy trình hiện tại thường là:
- Sửa file workflow
- Commit và push code
- Chờ GitHub Actions chạy (có thể mất vài phút)
- Thấy lỗi xảy ra
- Quay lại bước 1
Điều này giống như việc bạn phải gửi email đến đồng nghiệp mỗi khi muốn sửa một câu trong tài liệu, thay vì tự sửa trực tiếp. Rất tốn thời gian và kém hiệu quả.
act giải quyết vấn đề này bằng cách:
- Fast Feedback - Chạy workflow ngay lập tức trên máy của bạn, không cần push
- Local Task Runner - Thay thế Makefile bằng GitHub Actions, tận dụng cấu trúc workflow đã có
- Giảm phụ thuộc - Không cần kết nối internet khi đã cache các action và image
Act hoạt động như thế nào?#
Hãy tưởng tượng GitHub Actions như một nhà máy sản xuất (factory). Khi bạn push code, GitHub sẽ:
- Đọc file workflow từ
.github/workflows/ - Tìm hiểu các actions cần chạy
- Tải hoặc build Docker image tương ứng
- Chạy từng action trong container
- Cấu hình environment variables và filesystem giống như GitHub
act làm chính xác điều đó, nhưng ngay trên máy của bạn thay vì trên server của GitHub:
Cài đặt Act#
Prerequisites#
act cần Docker để chạy workflows trong containers. Nếu bạn không cần container isolation (ví dụ chạy job windows/macOS trực tiếp trên máy), có thể bỏ qua Docker.
- macOS: Cài Docker Desktop for Mac
- Windows: Cài Docker Desktop for Windows
- Linux: Cài Docker Engine
Cài đặt nhanh#
Cách 1: Homebrew (macOS & Linux)
brew install actbashCách 2: Bash script (tất cả platform)
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashbashCách 3: GitHub CLI extension
gh extension install https://github.com/nektos/gh-actbashCách 4: Download trực tiếp
Tải từ GitHub releases ↗ và thêm vào PATH.
[!TIP] Kiểm tra cài đặt thành công:
bashact --version
Sử dụng Act cơ bản#
Chạy workflow mặc định#
Mặc định, act sẽ chạy tất cả workflows với event push:
actbashChạy workflow với event cụ thể#
act pull_request
act schedule
act workflow_dispatchbashXem danh sách workflows#
act -l pull_requestbashChạy workflow cụ thể#
act -W .github/workflows/checks.ymlbashChạy job cụ thể#
act -j testbashCấu hình với Secrets và Variables#
Sử dụng Secrets#
GitHub tự động cung cấp GITHUB_TOKEN khi chạy workflow trên server. Khi chạy local, bạn cần cung cấp:
act -s MY_SECRET=my-value
# Cách 2: Sử dụng environment variable (khuyến nghị)
act -s MY_SECRET
# Cách 3: Tự động lấy token từ GitHub CLI
act -s GITHUB_TOKEN="$(gh auth token)"
# Cách 4: Load từ file
act --secret-file .secretsbash[!WARNING] Khi nhập sensitive data vào terminal, có thể được lưu vào shell history. Sử dụng cách 2 hoặc 3 để an toàn hơn.
Sử dụng Repository Variables#
act --var VARIABLE=some-value
act --var-file .envbashFile cấu hình .env#
Format giống Ruby dotenv:
MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUEbashBỏ qua Jobs và Steps khi chạy local#
Bỏ qua Jobs#
Sử dụng custom event property:
on: push
jobs:
deploy:
if: ${{ !github.event.act }} # skip khi chạy local
runs-on: ubuntu-latest
steps:
- run: echo "Deploy step"yamlTạo file event.json:
{
"act": true
}jsonChạy với:
act -e event.jsonbashBỏ qua Steps#
act cung cấp environment variable ACT:
- name: Notify Slack
if: ${{ !env.ACT }} # bỏ qua khi chạy local
run: |
curl -X POST $SLACK_WEBHOOKyamlMatrix và Advanced Features#
Chạy subset của Matrix#
Giả sử workflow có matrix với nhiều giá trị:
strategy:
matrix:
node: [14, 16, 18]
os: [ubuntu-latest, macos-latest]yamlChỉ chạy với node 18:
act push --matrix node:18bashChỉ chạy node 18 và ubuntu:
act push --matrix node:18 --matrix os:ubuntu-latestbashAction Offline Mode#
Tăng tốc độ và chạy offline khi đã cache:
act --action-offline-modebashLợi ích:
- Không pull images đã có sẵn
- Chạy được khi không có internet
- Tránh rate limit từ GitHub
- Tiết kiệm thời gian khi kết nối kém
Cấu hình file .actrc#
Để không phải nhập flags mỗi lần, tạo file .actrc:
--container-architecture=linux/amd64
--action-offline-mode
-e event.jsonbashVấn đề và Giới hạn#
Apple Silicon (M1/M2/M3)#
Nếu bạn dùng Apple M-series chip, có thể gặp vấn đề với architecture:
act --container-architecture linux/amd64bashRunner Images#
act sử dụng Docker images khác với GitHub runners. Một số tools có thể không hoạt động:
ubuntu-latest→node:16-buster-slim(light) hoặccatthehacker/ubuntu:act-latest(medium)- Nếu cần environment giống GitHub chính xác, dùng
nektos/act-environments-ubuntu:18.04
Unsupported Features#
Một số tính năng GitHub Actions không hỗ trợ:
- Docker context
- Một số complex matrix configurations
- Một số GitHub Actions specific features
Ví dụ thực tế#
Workflow đơn giản#
name: Test
on: push
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install
run: npm install
- name: Test
run: npm testyamlChạy local:
actbashWorkflow với secrets#
name: Deploy
on: push
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: |
curl -X POST ${{ secrets.DEPLOY_URL }}yamlChạy local:
act -s DEPLOY_URLbashSo sánh với GitHub Actions#
| Tính năng | GitHub Actions | act (local) |
|---|---|---|
| Tốc độ feedback | Chậm (phải push) | Nhanh (chạy ngay) |
| Tốn tài nguyên | GitHub tài khoản | Máy local của bạn |
| Environment | Chính xác | Gần chính xác |
| Offline | Không | Có (với offline mode) |
| Matrix testing | Tốn thời gian | Nhanh (chạy subset) |
| Secrets | Quản lý trên GitHub | Truyền thủ công |
Kết luận#
act là công cụ invaluable cho bất kỳ developer nào sử dụng GitHub Actions. Nó giúp:
- Tăng tốc độ phát triển và debug workflow
- Giảm phụ thuộc vào GitHub infrastructure
- Test workflow trước khi push
- Tận dụng GitHub Actions như local task runner
[!TIP] Best practice: Luôn test workflow với act trước khi push, đặc biệt khi sửa cấu trúc workflow phức tạp.