act 使用指南：在本地运行 GitHub Actions

act 使用指南：在本地运行 GitHub Actions

act 是一个可以在本地运行 GitHub Actions 的命令行工具，它通过 Docker 模拟 GitHub 提供的执行环境，适合用来本地调试 CI/CD 工作流和作为通用任务执行器。
项目地址：nektos/act

1. 使用场景

• 本地调试 GitHub Actions：修改 workflow 后不用频繁 git push，直接本地验证。
• 加速反馈：避免等 GitHub 远程排队和执行时间。
• 本地任务跑脚本：用 .github/workflows/*.yml 替代 Makefile，当作本地任务编排器。

2. 安装方式

2.1 macOS（推荐）

brew install act

2.2 Linux / 其他方式（脚本安装）

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

安装完成后验证：

act --version

前提条件：

• 已安装 Docker
• 当前用户可以直接运行 docker 命令

3. 基本概念

• Workflow：.github/workflows/*.yml 中定义的工作流。
• Event：触发工作流的事件，比如 push、pull_request、workflow_dispatch 等。
• Job：Workflow 中的一个或多个 jobs.<job_id>。
• Runner：runs-on: ubuntu-latest 等，act 会用对应 Docker 镜像模拟。

4. 最常用命令

在项目根目录（包含 .github/workflows/）执行：

4.1 列出可执行 workflows / jobs

act -l

4.2 运行默认事件（push）

act
# 等价于
act push

4.3 运行指定事件

# 模拟 pull_request 事件
act pull_request

4.4 只运行某个 job

# 只跑 build 这个 job（job id 在 workflow 里定义）
act -j build
 
# 指定事件 + job
act push -j build

5. Runner 镜像与配置

GitHub Actions 中的：

runs-on: ubuntu-latest

在 act 中会映射为某个 Docker 镜像。常见做法：

# 指定 ubuntu-latest 用的镜像
act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

可以在项目根目录创建 .actrc，配置默认参数，例如：

-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
--container-architecture linux/amd64

之后直接运行 act 就会自动使用这些参数。

6. 事件数据与环境变量

6.1 自定义事件 payload

有些 workflow 会依赖 github.event 内容，可以通过 -e 传入本地 JSON 文件：

# event.json 为 GitHub 事件 payload（push / pull_request 等）
act pull_request -e event.json

6.2 传入 secrets 与 env

命令行直接设置（简单测试）

# 传 secret
act -s MY_SECRET=123456
 
# 传 env
act -s NODE_ENV=production

从文件读取 secrets（推荐）

创建 .secrets 文件：

MY_SECRET=123456
API_TOKEN=xxxx

运行时指定：

act --secret-file .secrets

在 workflow 中使用方式与 GitHub 上一致：

env:
  API_TOKEN: ${{ secrets.API_TOKEN }}

7. 调试与日志

7.1 查看详细日志

# 开启详细日志
act -v
 
# 更高调试级别
act -v --debug

8. 与 GitHub Actions 工作流配合示例

8.1 典型 CI workflow 示例

.github/workflows/ci.yml：

name: CI
 
on:
  push:
    branches: [ main ]
  pull_request:
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
 
      - name: Install dependencies
        run: npm ci
 
      - name: Run tests
        run: npm test

在本地运行：

# 模拟 push
act push -j build
 
# 模拟 pull_request
act pull_request -j build

8.2 当作本地任务执行器

把常用任务（lint、test、build、deploy）写进 workflow，然后用 act 在本地执行：

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run lint
 
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

本地使用：

# 本地跑 lint
act -j lint
 
# 本地跑 test
act -j test

9. 常见问题（FAQ）

9.1 第一次运行很慢？

• act 需要首次拉取 Runner Docker 镜像，体积较大。
• 之后会显著加速（镜像已缓存）。

9.2 某些 GitHub 官方服务在本地不可用？

• 部分 Action 或服务依赖 GitHub 云端环境，本地无法 100% 模拟。
• 可以通过条件跳过某些步骤，例如：

if: ${{ !env.ACT }}

运行时注入：

ACT=true act

9.3 如何在不同项目里统一 act 配置？

• 在每个仓库内维护一个 .actrc；
• 或写一个包装脚本（例如 scripts/act-ci.sh）封装常用命令。

10. 推荐使用习惯

• 开发 workflow 时：每次改完先跑一遍 act，确认无误再 git push。
• 调试复杂 CI：先在本地用 act -v 多次迭代，减少对 GitHub 资源的浪费。
• 文档化：在项目 README 或部署文档中写上推荐的 act 命令，方便团队统一使用。