act-local-testing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAct - Local Workflow Testing
Act - 本地工作流测试
Use this skill when testing GitHub Actions workflows locally with act. This covers act CLI commands, Docker setup, debugging, and best practices for fast local iteration on CI/CD workflows.
当需要使用 act 在本地测试 GitHub Actions 工作流时,请使用此 skill。本 skill 涵盖 act CLI 命令、Docker 设置、调试,以及在本地快速迭代 CI/CD 工作流的最佳实践。
Installation
安装
macOS
macOS
bash
brew install actbash
brew install actLinux
Linux
bash
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashbash
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashWindows
Windows
bash
choco install act-clibash
choco install act-clior
or
scoop install act
undefinedscoop install act
undefinedFrom Source
从源码安装
bash
go install github.com/nektos/act@latestbash
go install github.com/nektos/act@latestBasic Usage
基本用法
Run All Workflows
运行所有工作流
bash
undefinedbash
undefinedRun workflows triggered by push event
Run workflows triggered by push event
act
act
Equivalent to
Equivalent to
act push
undefinedact push
undefinedRun Specific Events
运行特定事件
bash
undefinedbash
undefinedPull request event
Pull request event
act pull_request
act pull_request
Workflow dispatch
Workflow dispatch
act workflow_dispatch
act workflow_dispatch
Custom event
Custom event
act repository_dispatch -e event.json
undefinedact repository_dispatch -e event.json
undefinedRun Specific Workflows
运行特定工作流
bash
undefinedbash
undefinedRun specific workflow file
Run specific workflow file
act -W .github/workflows/ci.yml
act -W .github/workflows/ci.yml
Run specific job
Run specific job
act -j build
act -j build
Run specific workflow and job
Run specific workflow and job
act -W .github/workflows/deploy.yml -j production
undefinedact -W .github/workflows/deploy.yml -j production
undefinedList Available Workflows
列出可用工作流
bash
undefinedbash
undefinedList all workflows and jobs
List all workflows and jobs
act -l
act -l
List for specific event
List for specific event
act pull_request -l
undefinedact pull_request -l
undefinedValidation and Dry Runs
验证与试运行
Dry Run
试运行
bash
undefinedbash
undefinedValidate without executing
Validate without executing
act --dryrun
act --dryrun
Show what would run
Show what would run
act -n
act -n
Validate specific workflow
Validate specific workflow
act --dryrun -W .github/workflows/ci.yml
undefinedact --dryrun -W .github/workflows/ci.yml
undefinedGraph Visualization
图表可视化
bash
undefinedbash
undefinedShow workflow graph
Show workflow graph
act -g
act -g
Show graph for specific event
Show graph for specific event
act pull_request -g
undefinedact pull_request -g
undefinedDocker Configuration
Docker 配置
Default Runners
默认 Runner
Act uses Docker images to simulate GitHub's runners:
bash
undefinedAct 使用 Docker 镜像来模拟 GitHub 的 Runner:
bash
undefinedUse default images (micro - minimal)
Use default images (micro - minimal)
act
act
Use medium images (more tools)
Use medium images (more tools)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
act -P ubuntu-latest=catthehacker/ubuntu:act-latest
Use large images (most compatible)
Use large images (most compatible)
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
undefinedact -P ubuntu-latest=catthehacker/ubuntu:full-latest
undefinedCustom Platform Images
自定义平台镜像
Create file in project root:
.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.04Or use command line:
bash
act -P ubuntu-latest=node:18 \
-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或者使用命令行:
bash
act -P ubuntu-latest=node:18 \
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04Reusing Docker Containers
复用 Docker 容器
bash
undefinedbash
undefinedReuse containers between runs (faster)
Reuse containers between runs (faster)
act --reuse
act --reuse
Clean up after run
Clean up after run
act --rm
undefinedact --rm
undefinedSecrets Management
密钥管理
Using .secrets File
使用 .secrets 文件
Create in project root:
.secretsGITHUB_TOKEN=ghp_your_token_here
NPM_TOKEN=npm_your_token_here
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secretAdd to :
.gitignore.secretsRun with secrets:
bash
act --secret-file .secrets在项目根目录创建 :
.secretsGITHUB_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使用密钥运行:
bash
act --secret-file .secretsInline Secrets
内联密钥
bash
undefinedbash
undefinedSingle secret
Single secret
act -s GITHUB_TOKEN=ghp_token
act -s GITHUB_TOKEN=ghp_token
Multiple secrets
Multiple secrets
act -s GITHUB_TOKEN=ghp_token
-s NPM_TOKEN=npm_token
-s NPM_TOKEN=npm_token
undefinedact -s GITHUB_TOKEN=ghp_token
-s NPM_TOKEN=npm_token
-s NPM_TOKEN=npm_token
undefinedEnvironment-Specific Secrets
环境特定的密钥
bash
undefinedbash
undefinedDevelopment secrets
Development secrets
act --secret-file .secrets.dev
act --secret-file .secrets.dev
Production secrets
Production secrets
act --secret-file .secrets.prod
undefinedact --secret-file .secrets.prod
undefinedEnvironment Variables
环境变量
Setting Variables
设置变量
bash
undefinedbash
undefinedSingle variable
Single variable
act --env NODE_ENV=development
act --env NODE_ENV=development
Multiple variables
Multiple variables
act --env NODE_ENV=development
--env DEBUG=true
--env DEBUG=true
undefinedact --env NODE_ENV=development
--env DEBUG=true
--env DEBUG=true
undefinedUsing .env File
使用 .env 文件
Create file:
.envNODE_ENV=development
DEBUG=true
LOG_LEVEL=debugRun with env file:
bash
act --env-file .env创建 文件:
.envNODE_ENV=development
DEBUG=true
LOG_LEVEL=debug使用 env 文件运行:
bash
act --env-file .envGitHub Context Variables
GitHub 上下文变量
Act automatically sets these:
GITHUB_ACTOR=nektos/act
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=push
GITHUB_SHA=abc123...
GITHUB_REF=refs/heads/main
ACT=trueAct 自动设置以下变量:
GITHUB_ACTOR=nektos/act
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=push
GITHUB_SHA=abc123...
GITHUB_REF=refs/heads/main
ACT=trueDebugging
调试
Verbose Output
详细输出
bash
undefinedbash
undefinedVerbose mode
Verbose mode
act -v
act -v
Very verbose (debug)
Very verbose (debug)
act -vv
undefinedact -vv
undefinedStep-by-Step Execution
分步执行
bash
undefinedbash
undefinedInteractive mode - pause before each step
Interactive mode - pause before each step
act --watch
undefinedact --watch
undefinedInspect Containers
检查容器
bash
undefinedbash
undefinedKeep container running after workflow
Keep container running after workflow
act --reuse
act --reuse
Then in another terminal
Then in another terminal
docker ps
docker exec -it <container-id> /bin/bash
undefineddocker ps
docker exec -it <container-id> /bin/bash
undefinedBind Mount Local Files
绑定挂载本地文件
bash
undefinedbash
undefinedMount current directory
Mount current directory
act --bind
act --bind
Mount specific directory
Mount specific directory
act -b /host/path:/container/path
undefinedact -b /host/path:/container/path
undefinedCommon Workflows
常见工作流
Test Before Push
推送前测试
bash
undefinedbash
undefinedValidate workflow syntax
Validate workflow syntax
act --dryrun
act --dryrun
Run tests
Run tests
act -j test
act -j test
Run full CI
Run full CI
act
undefinedact
undefinedIterative Development
迭代开发
bash
undefinedbash
undefinedEdit workflow
Edit workflow
vim .github/workflows/ci.yml
vim .github/workflows/ci.yml
Test immediately
Test immediately
act --reuse -j build
act --reuse -j build
Iterate quickly
Iterate quickly
act --reuse -j build
undefinedact --reuse -j build
undefinedMatrix Testing
矩阵测试
bash
undefinedbash
undefinedRun specific matrix combination
Run specific matrix combination
act --matrix os:ubuntu-latest --matrix node:20
act --matrix os:ubuntu-latest --matrix node:20
Run all combinations
Run all combinations
act
undefinedact
undefinedTroubleshooting
故障排除
Docker Issues
Docker 问题
bash
undefinedbash
undefinedCheck Docker is running
Check Docker is running
docker ps
docker ps
Pull required images manually
Pull required images manually
docker pull catthehacker/ubuntu:act-latest
docker pull catthehacker/ubuntu:act-latest
Clean up Docker resources
Clean up Docker resources
docker system prune -a
undefineddocker system prune -a
undefinedPermission Issues
权限问题
bash
undefinedbash
undefinedRun with sudo (Linux)
Run with sudo (Linux)
sudo act
sudo act
Fix Docker permissions (Linux)
Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
newgrp docker
undefinedsudo usermod -aG docker $USER
newgrp docker
undefinedMissing Tools
缺少工具
bash
undefinedbash
undefinedUse fuller image
Use fuller image
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
Or install in workflow
Or install in workflow
- run: | apt-get update apt-get install -y some-tool
undefined- run: | apt-get update apt-get install -y some-tool
undefinedWorkflow Not Found
未找到工作流
bash
undefinedbash
undefinedCheck workflow files exist
Check workflow files exist
ls -la .github/workflows/
ls -la .github/workflows/
Validate YAML syntax
Validate YAML syntax
yamllint .github/workflows/*.yml
yamllint .github/workflows/*.yml
List detected workflows
List detected workflows
act -l
undefinedact -l
undefinedAction Compatibility
Action 兼容性
Some actions don't work with act:
yaml
undefined某些 action 无法与 act 配合工作:
yaml
undefinedSkip action in act
Skip action in act
- name: GitHub-only action if: ${{ !env.ACT }} uses: github/some-action@v1
- name: GitHub-only action if: ${{ !env.ACT }} uses: github/some-action@v1
Use alternative in act
Use alternative in act
- name: Local alternative if: env.ACT == 'true' run: echo "Running local version"
undefined- name: Local alternative if: env.ACT == 'true' run: echo "Running local version"
undefinedBest Practices
最佳实践
DO
应该做
✅ Use before running full workflows
✅ Create for consistent configuration
✅ Use file and add it to
✅ Use for faster iteration
✅ Test workflows locally before pushing
✅ Use appropriate image sizes for your needs
✅ Document act usage in README
act --dryrun.actrc.secrets.gitignore--reuse✅ 运行完整工作流前使用
✅ 创建 以保持配置一致
✅ 使用 文件并将其添加到
✅ 使用 加快迭代速度
✅ 推送前在本地测试工作流
✅ 根据需求选择合适的镜像大小
✅ 在 README 中记录 act 的用法
act --dryrun.actrc.secrets.gitignore--reuseDON'T
不应做
❌ Commit or files
❌ Use Docker tags in production
❌ Skip validation with
❌ Run act without understanding what it will do
❌ Ignore Docker disk space usage
❌ Assume all actions work perfectly with act
.secrets.envlatest--dryrun❌ 提交 或 文件
❌ 在生产环境中使用 Docker 标签
❌ 跳过使用 进行验证
❌ 在不了解 act 行为的情况下运行它
❌ 忽视 Docker 磁盘空间占用
❌ 假定所有 action 都能完美配合 act 运行
.secrets.envlatest--dryrunConfiguration Files
配置文件
.actrc
.actrc
undefinedundefinedPlatform mappings
Platform mappings
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-latest=catthehacker/ubuntu:act-latest
Default options
Default options
--reuse
--secret-file .secrets
--env-file .env
--reuse
--secret-file .secrets
--env-file .env
Container options
Container options
--container-architecture linux/amd64
undefined--container-architecture linux/amd64
undefined.github/workflows/.actrc
.github/workflows/.actrc
Project-specific overrides in workflows directory.
工作流目录中针对具体项目的覆盖配置。
CI/CD Integration
CI/CD 集成
Pre-Push Hook
Pre-Push Hook
.git/hooks/pre-pushbash
#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
echo "Workflow validation failed"
exit 1
fi.git/hooks/pre-pushbash
#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
echo "Workflow validation failed"
exit 1
fiMake Target
Make Target
makefile
.PHONY: test-workflows
test-workflows:
act --dryrun
act -j test
.PHONY: ci-local
ci-local:
act --reusemakefile
.PHONY: test-workflows
test-workflows:
act --dryrun
act -j test
.PHONY: ci-local
ci-local:
act --reusePerformance Tips
性能提示
Faster Iteration
更快迭代
bash
undefinedbash
undefinedUse reuse flag
Use reuse flag
act --reuse
act --reuse
Skip checkout if not needed
Skip checkout if not needed
act --reuse -j test --no-recurse
act --reuse -j test --no-recurse
Use smaller images for simple tests
Use smaller images for simple tests
act -P ubuntu-latest=node:20-alpine
undefinedact -P ubuntu-latest=node:20-alpine
undefinedCaching
缓存
Act respects GitHub Actions caching:
yaml
- uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}Cache location on host:
~/.cache/act/Act 支持 GitHub Actions 缓存:
yaml
- uses: actions/cache@v4
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}主机上的缓存位置:
~/.cache/act/Related Skills
相关 Skill
- act-workflow-syntax: Creating and structuring workflow files
- act-docker-setup: Configuring Docker for act
- act-advanced-features: Advanced act usage patterns
- act-workflow-syntax:创建和构建工作流文件
- act-docker-setup:为 act 配置 Docker
- act-advanced-features:高级 act 使用模式