名称: act-本地测试用户可调用: false 描述: 用于在本地使用act测试GitHub Actions工作流。涵盖act CLI使用、Docker配置、调试工作流以及在本地机器上运行工作流时常见问题的故障排除。允许工具:

读取
写入
编辑
Bash
Grep
Glob

Act - 本地工作流测试

当使用act在本地测试GitHub Actions工作流时使用此技能。这包括act CLI命令、Docker设置、调试以及快速本地迭代CI/CD工作流的最佳实践。

安装

macOS

brew install act

Linux

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

Windows

choco install act-cli
# 或
scoop install act

从源代码安装

go install github.com/nektos/act@latest

基本使用

运行所有工作流

# 运行由push事件触发的工作流
act

# 等同于
act push

运行特定事件

# Pull request事件
act pull_request

# Workflow dispatch
act workflow_dispatch

# 自定义事件
act repository_dispatch -e event.json

运行特定工作流

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

# 运行特定作业
act -j build

# 运行特定工作流和作业
act -W .github/workflows/deploy.yml -j production

列出可用工作流

# 列出所有工作流和作业
act -l

# 列出特定事件的工作流
act pull_request -l

验证和干运行

干运行

# 验证而不执行
act --dryrun

# 显示将要运行的内容
act -n

# 验证特定工作流
act --dryrun -W .github/workflows/ci.yml

图形可视化

# 显示工作流图
act -g

# 显示特定事件的图
act pull_request -g

Docker配置

默认运行器

Act使用Docker镜像模拟GitHub的运行器：

# 使用默认镜像（micro - 最小）
act

# 使用中等镜像（更多工具）
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# 使用大型镜像（最兼容）
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

自定义平台镜像

在项目根目录创建.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 -P ubuntu-latest=node:18 \
    -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

重用Docker容器

# 在运行之间重用容器（更快）
act --reuse

# 运行后清理
act --rm

秘密管理

使用.secrets文件

在项目根目录创建.secrets：

GITHUB_TOKEN=ghp_your_token_here
NPM_TOKEN=npm_your_token_here
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret

添加到.gitignore：

.secrets

使用秘密运行：

act --secret-file .secrets

内联秘密

# 单个秘密
act -s GITHUB_TOKEN=ghp_token

# 多个秘密
act -s GITHUB_TOKEN=ghp_token \
    -s NPM_TOKEN=npm_token

环境特定秘密

# 开发秘密
act --secret-file .secrets.dev

# 生产秘密
act --secret-file .secrets.prod

环境变量

设置变量

# 单个变量
act --env NODE_ENV=development

# 多个变量
act --env NODE_ENV=development \
    --env DEBUG=true

使用.env文件

创建.env文件：

NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug

使用env文件运行：

act --env-file .env

GitHub上下文变量

Act自动设置这些：

GITHUB_ACTOR=nektos/act
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=push
GITHUB_SHA=abc123...
GITHUB_REF=refs/heads/main
ACT=true

调试

详细输出

# 详细模式
act -v

# 非常详细（调试）
act -vv

逐步执行

# 交互模式 - 在每个步骤前暂停
act --watch

检查容器

# 工作流后保持容器运行
act --reuse

# 然后在另一个终端中
docker ps
docker exec -it <container-id> /bin/bash

绑定挂载本地文件

# 挂载当前目录
act --bind

# 挂载特定目录
act -b /host/path:/container/path

常见工作流

推送前测试

# 验证工作流语法
act --dryrun

# 运行测试
act -j test

# 运行完整CI
act

迭代开发

# 编辑工作流
vim .github/workflows/ci.yml

# 立即测试
act --reuse -j build

# 快速迭代
act --reuse -j build

矩阵测试

# 运行特定矩阵组合
act --matrix os:ubuntu-latest --matrix node:20

# 运行所有组合
act

故障排除

Docker问题

# 检查Docker是否运行
docker ps

# 手动拉取所需镜像
docker pull catthehacker/ubuntu:act-latest

# 清理Docker资源
docker system prune -a

权限问题

# 使用sudo运行（Linux）
sudo act

# 修复Docker权限（Linux）
sudo usermod -aG docker $USER
newgrp docker

缺少工具

# 使用完整镜像
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

# 或在工作流中安装
- run: |
    apt-get update
    apt-get install -y some-tool

工作流未找到

# 检查工作流文件是否存在
ls -la .github/workflows/

# 验证YAML语法
yamllint .github/workflows/*.yml

# 列出检测到的工作流
act -l

动作兼容性

一些动作不适用于act：

# 在act中跳过动作
- name: GitHub-only action
  if: ${{ !env.ACT }}
  uses: github/some-action@v1

# 在act中使用替代方案
- name: 本地替代方案
  if: env.ACT == 'true'
  run: echo "运行本地版本"

最佳实践

应做

✅ 使用 act --dryrun 在运行完整工作流前验证 ✅ 创建 .actrc 以保持配置一致 ✅ 使用 .secrets 文件并添加到 .gitignore ✅ 使用 --reuse 以加快迭代速度 ✅ 在推送前本地测试工作流 ✅ 根据需求使用合适大小的镜像 ✅ 在README中记录act使用

不应做

❌ 提交 .secrets 或 .env 文件 ❌ 在生产中使用 latest Docker标签 ❌ 跳过 --dryrun 验证 ❌ 在不了解act将做什么的情况下运行 ❌ 忽略Docker磁盘空间使用 ❌ 假设所有动作都能完美与act配合

配置文件

.actrc

# 平台映射
-P ubuntu-latest=catthehacker/ubuntu:act-latest

# 默认选项
--reuse
--secret-file .secrets
--env-file .env

# 容器选项
--container-architecture linux/amd64

.github/workflows/.actrc

工作流目录中的项目特定覆盖。

CI/CD集成

预推送钩子

.git/hooks/pre-push：

#!/bin/bash
echo "验证工作流..."
act --dryrun
if [ $? -ne 0 ]; then
  echo "工作流验证失败"
  exit 1
fi

Make目标

.PHONY: test-workflows
test-workflows:
 act --dryrun
 act -j test

.PHONY: ci-local
ci-local:
 act --reuse

性能技巧

更快迭代

# 使用reuse标志
act --reuse

# 如果不需要则跳过检出
act --reuse -j test --no-recurse

# 对简单测试使用较小镜像
act -P ubuntu-latest=node:20-alpine

缓存

Act尊重GitHub Actions缓存：

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

主机上的缓存位置：~/.cache/act/