blog.dopana

Quay lại

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à:

  1. Sửa file workflow
  2. Commit và push code
  3. Chờ GitHub Actions chạy (có thể mất vài phút)
  4. Thấy lỗi xảy ra
  5. 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ẽ:

  1. Đọc file workflow từ .github/workflows/
  2. Tìm hiểu các actions cần chạy
  3. Tải hoặc build Docker image tương ứng
  4. Chạy từng action trong container
  5. 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:

Bạn chạy actĐọc workflow filesXác định actions cần chạyDocker APIPull/Build imagesChạy containersCấu hình env & filesystemThực thi workflow

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)

Homebrew
brew install act
bash

Cách 2: Bash script (tất cả platform)

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
bash

Cách 3: GitHub CLI extension

gh extension install https://github.com/nektos/gh-act
bash

Cá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:

act --version
bash

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:

act
bash

Chạy workflow với event cụ thể#

act pull_request

act schedule

act workflow_dispatch
bash

Xem danh sách workflows#

act -l pull_request
bash

Chạy workflow cụ thể#

act -W .github/workflows/checks.yml
bash

Chạy job cụ thể#

act -j test
bash

Cấ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 .secrets
bash

[!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 .env
bash

File 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_VALUE
bash

Bỏ qua Jobs và Steps khi chạy local#

Bỏ qua Jobs#

Sử dụng custom event property:

workflow.yml
on: push
jobs:
  deploy:
    if: ${{ !github.event.act }} # skip khi chạy local
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploy step"
yaml

Tạo file event.json:

event.json
{
  "act": true
}
json

Chạy với:

act -e event.json
bash

Bỏ qua Steps#

act cung cấp environment variable ACT:

workflow.yml
- name: Notify Slack
  if: ${{ !env.ACT }} # bỏ qua khi chạy local
  run: |
    curl -X POST $SLACK_WEBHOOK
yaml

Matrix và Advanced Features#

Chạy subset của Matrix#

Giả sử workflow có matrix với nhiều giá trị:

workflow.yml
strategy:
  matrix:
    node: [14, 16, 18]
    os: [ubuntu-latest, macos-latest]
yaml

Chỉ chạy với node 18:

act push --matrix node:18
bash

Chỉ chạy node 18 và ubuntu:

act push --matrix node:18 --matrix os:ubuntu-latest
bash

Action Offline Mode#

Tăng tốc độ và chạy offline khi đã cache:

act --action-offline-mode
bash

Lợ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:

.actrc
--container-architecture=linux/amd64
--action-offline-mode
-e event.json
bash

Vấ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/amd64
bash

Runner 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ặc catthehacker/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#

.github/workflows/test.yml
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 test
yaml

Chạy local:

act
bash

Workflow với secrets#

.github/workflows/deploy.yml
name: Deploy
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: |
          curl -X POST ${{ secrets.DEPLOY_URL }}
yaml

Chạy local:

act -s DEPLOY_URL
bash

So sánh với GitHub Actions#

Tính năngGitHub Actionsact (local)
Tốc độ feedbackChậm (phải push)Nhanh (chạy ngay)
Tốn tài nguyênGitHub tài khoảnMáy local của bạn
EnvironmentChính xácGần chính xác
OfflineKhôngCó (với offline mode)
Matrix testingTốn thời gianNhanh (chạy subset)
SecretsQuản lý trên GitHubTruyề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.

References#