Act本地GitHub Actions — 本地运行GitHub Actions¶

# macOS（Homebrew）
brew install act

# Linux（包管理器）
# Arch: pacman -S act
# Nix: nix-env -i act

# 通用安装（curl）
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# GitHub CLI 插件（另一种方式）
gh extension install nektos/gh-act
# 使用：gh act

# 验证安装
act --version  # 应该显示 0.2.88

# 首次运行（选择 Runner 镜像）
act
# 会提示选择镜像大小：
# Micro  — 最小（~200MB），功能有限
# Medium — 中等（~500MB），推荐大多数场景
# Large  — 完整（~17GB），最接近 GitHub 真实环境

# .actrc — 项目级配置（放在项目根目录）
-P ubuntu-latest=catthehacker/ubuntu:act-latest  # 指定 Runner 镜像
--env-file .env.act                                # 环境变量文件
--secret-file .secrets                             # 密钥文件

# ~/.actrc — 全局配置
-P ubuntu-latest=catthehacker/ubuntu:act-latest

# 运行所有 push 触发的工作流（默认事件）
act

# 模拟 pull_request 事件
act pull_request

# 模拟特定事件
act workflow_dispatch        # 手动触发
act schedule                 # 定时触发

# 列出所有可用的工作流和 job
act -l                      # 列出所有 job
act -l push                 # 列出 push 事件的 job

# 运行指定 job
act -j build                # 只运行名为 build 的 job
act -j test                 # 只运行名为 test 的 job

# 运行指定工作流文件
act -W .github/workflows/ci.yml

# 试运行（不真的执行，看看会做什么）
act -n                      # dry-run 模式

# 方法1：命令行传入
act -s MY_TOKEN=abc123

# 方法2：交互式输入（不会显示在终端）
act -s MY_TOKEN

# 方法3：从文件读取（推荐）
# 创建 .secrets 文件（不要提交到 git！）
echo "GITHUB_TOKEN=ghp_xxxx" > .secrets
echo "DOCKER_PASSWORD=mypass" >> .secrets
act --secret-file .secrets

# 方法4：从环境变量读取
export MY_TOKEN=abc123
act -s MY_TOKEN              # 自动从环境变量读取

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install ruff
      - run: ruff check .

  test:
    runs-on: ubuntu-latest
    needs: lint                  # 依赖 lint job
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: pytest tests/ -v

# 本地测试这个工作流
act                          # 运行所有 push 触发的 job
act -j lint                  # 只运行 lint
act -j test                  # 只运行 test
act -v                       # 详细输出（调试用）

# 模拟带 payload 的事件
act pull_request --eventpath event.json

# event.json 内容：
# {
#   "pull_request": {
#     "number": 42,
#     "head": { "ref": "feature-branch" },
#     "base": { "ref": "main" }
#   }
# }

# 如果工作流中引用了本地 action
# .github/workflows/ci.yml
steps:
  - uses: ./.github/actions/my-action  # 本地 action
# Act 会自动处理本地 action

# 使用更完整的镜像（更接近 GitHub 环境）
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

# 使用特定版本
act -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

# 多平台配置（.actrc）
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04

# Act 不能完美模拟的 GitHub 功能：
# 1. services（docker-compose 风格的服务容器）— 部分支持
# 2. GitHub API 调用（如 github.token）— 需要提供真实 token
# 3. Matrix 策略 — 支持但有些边界情况
# 4. Artifacts 上传/下载 — 本地模拟
# 5. Caching（actions/cache）— 部分支持

# ===== 基本命令 =====
act                             # 运行 push 事件的工作流
act pull_request                # 模拟 PR 事件
act -l                          # 列出所有 job
act -j job-name                 # 运行指定 job
act -n                          # 试运行（不执行）
act -v                          # 详细输出

# ===== 配置选项 =====
act -s KEY=VALUE                # 传递 secret
act --secret-file .secrets      # 从文件读 secrets
act --env-file .env             # 环境变量文件
act -W path/to/workflow.yml     # 指定工作流文件
act --eventpath event.json      # 自定义事件 payload

# ===== 镜像选项 =====
act -P ubuntu-latest=image      # 指定 runner 镜像
act --pull=false                # 不拉取新镜像

# ===== 调试 =====
act -v                          # 详细模式
act --insecure-secrets          # 显示 secret 值（调试用）