act: 70,410 GitHub Stars — 本地运行 GitHub Actions，2026 生产级 CI/CD 指南

# 通过 Homebrew 安装 act
brew install act

# 验证安装
act --version
# act version 0.2.88

# 一行命令安装（需要 bash 和 curl）
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# 备选方案：下载预构建二进制文件
wget https://github.com/nektos/act/releases/download/v0.2.88/act_Linux_x86_64.tar.gz
tar xzf act_Linux_x86_64.tar.gz
sudo mv act /usr/local/bin/

# Chocolatey
choco install act-cli

# Scoop
scoop install act

# WinGet
winget install nektos.act

# 作为 gh CLI 扩展安装
gh extension install https://github.com/nektos/gh-act

# 通过 gh 运行
gh act

git clone https://github.com/nektos/act.git
cd act/
make build
sudo make install

# 首次运行 — 选择默认 runner 镜像
act
? Please choose the default image you want to use with act:
  - Large size image: ~17GB download, ~75GB disk space, closest to GitHub runners
  - Medium size image: ~500MB, includes essential tools (RECOMMENDED)
  - Micro size image: <200MB, Node.js only

# ~/.actrc — 默认配置
cat ~/.actrc
-P ubuntu-latest=catthehacker/ubuntu:act-latest

# 确认 Docker 正在运行
docker info

# 确认 Docker API 可访问
docker version

# 使用自定义 runner 镜像运行
act -P ubuntu-latest=node:20-slim

# 指定自定义 Docker 主机（远程引擎）
export DOCKER_HOST=tcp://remote-docker:2376
act

# 在 Apple Silicon 上使用容器架构标志
act --container-architecture linux/amd64

# .github/workflows/dind-test.yml
name: Docker Build Test
on: push
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build Docker image
        run: docker build -t myapp:latest .

# 从 VS Code 市场安装扩展
# 按 Cmd+Shift+P → "Extensions: Install Extensions" → 搜索 "GitHub Local Actions"

# 针对 GitHub Enterprise Server 运行
act --github-instance github.company.com

# 带身份验证
act --github-instance github.company.com -s GITHUB_TOKEN=ghp_xxxxxxxx

# .github/workflows/tasks.yml
name: Local Tasks
on: workflow_dispatch
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run linter
        run: npm run lint
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm run build

# 在本地运行任务替代 make
act -j lint
act -j test
act -j build

# 选项 1：交互式提示（推荐手动运行）
act -s MY_SECRET

# 选项 2：环境变量查找
export MY_SECRET=supersecurevalue
act -s MY_SECRET

# 选项 3：密钥文件 (.secrets，格式与 .env 相同)
cat > .secrets << 'EOF'
MY_SECRET=supersecurevalue
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
EOF
act --secret-file .secrets

# 选项 4：对于 GITHUB_TOKEN（建议使用只读 PAT）
act -s GITHUB_TOKEN=ghp_xxxxxxxxxxxx

echo ".secrets" >> .gitignore
echo "*.secrets" >> .gitignore

# 设置变量
act --var DEPLOY_ENV=staging --var API_VERSION=v2

# 或使用变量文件
cat > .variables << 'EOF'
DEPLOY_ENV=staging
API_VERSION=v2
EOF
act --var-file .variables

# 模拟 pull_request 事件
cat > pull-request.json << 'EOF'
{
  "pull_request": {
    "head": { "ref": "feature/new-login" },
    "base": { "ref": "main" },
    "number": 42
  }
}
EOF
act pull_request -e pull-request.json

# 模拟带标签的 push
cat > tag-push.json << 'EOF'
{ "ref": "refs/tags/v1.2.3" }
EOF
act push -e tag-push.json

# 模拟带输入的 workflow_dispatch
cat > workflow-inputs.json << 'EOF'
{
  "inputs": {
    "environment": "production",
    "version": "2.0.0"
  }
}
EOF
act workflow_dispatch -e workflow-inputs.json

# 列出所有将要运行的作业
act -l

# Dry run（不实际执行）
act -n

# 带详细输出的 dry run
act -n -v

# 项目根目录的 .actrc
cat > .actrc << 'EOF'
--container-architecture linux/amd64
--action-offline-mode
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--env-file .env
--secret-file .secrets
EOF

# 在你的工作流文件中
jobs:
  deploy:
    if: ${{ !github.event.act }}  # 本地运行时跳过部署作业
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

  notify:
    runs-on: ubuntu-latest
    steps:
      - name: 本地运行时跳过 Slack 通知
        if: ${{ !env.ACT }}
        run: |
          curl -X POST -H 'Content-type: application/json' \
            --data '{"text":"Deployment complete"}' ${{ secrets.SLACK_WEBHOOK }}

cat > event.json << 'EOF'
{ "act": true }
EOF
act -e event.json

# 指定产物服务器路径
act --artifact-server-path /tmp/artifacts

# 产物将保存到 /tmp/artifacts/<workflow>/<artifact-name>/
ls -la /tmp/artifacts/

# 预拉取镜像
act --action-offline-mode

# 这将重用本地缓存的操作仓库和 Docker 镜像
# 无需从 GitHub 或 Docker Hub 获取

# 只运行 "test" 作业
act -j test

# 从特定工作流文件运行作业
act -j lint -W .github/workflows/checks.yml

act --github-instance github.mycompany.com -s GITHUB_TOKEN=ghp_xxx

# 详细输出
act -v

# 对特定作业使用详细输出
act -j test -v

# 容器名称会打印在日志中；失败后检查它
docker exec -it <container-name> /bin/bash

# Homebrew
brew upgrade act

# Chocolatey
choco upgrade act-cli

# Scoop
scoop update act

# Bash 脚本（重新运行安装器）
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash