act-local-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Act - 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 act
bash
brew install act

Linux

Linux

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

Windows

Windows

bash
choco install act-cli
bash
choco install act-cli

or

or

scoop install act
undefined
scoop install act
undefined

From Source

从源码安装

bash
go install github.com/nektos/act@latest
bash
go install github.com/nektos/act@latest

Basic Usage

基本用法

Run All Workflows

运行所有工作流

bash
undefined
bash
undefined

Run workflows triggered by push event

Run workflows triggered by push event

act
act

Equivalent to

Equivalent to

act push
undefined
act push
undefined

Run Specific Events

运行特定事件

bash
undefined
bash
undefined

Pull 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
undefined
act repository_dispatch -e event.json
undefined

Run Specific Workflows

运行特定工作流

bash
undefined
bash
undefined

Run 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
undefined
act -W .github/workflows/deploy.yml -j production
undefined

List Available Workflows

列出可用工作流

bash
undefined
bash
undefined

List 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
undefined
act pull_request -l
undefined

Validation and Dry Runs

验证与试运行

Dry Run

试运行

bash
undefined
bash
undefined

Validate 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
undefined
act --dryrun -W .github/workflows/ci.yml
undefined

Graph Visualization

图表可视化

bash
undefined
bash
undefined

Show workflow graph

Show workflow graph

act -g
act -g

Show graph for specific event

Show graph for specific event

act pull_request -g
undefined
act pull_request -g
undefined

Docker Configuration

Docker 配置

Default Runners

默认 Runner

Act uses Docker images to simulate GitHub's runners:
bash
undefined
Act 使用 Docker 镜像来模拟 GitHub 的 Runner:
bash
undefined

Use 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
undefined
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
undefined

Custom Platform Images

自定义平台镜像

Create
.actrc
file in project root:
-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
Or 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.04

Reusing Docker Containers

复用 Docker 容器

bash
undefined
bash
undefined

Reuse containers between runs (faster)

Reuse containers between runs (faster)

act --reuse
act --reuse

Clean up after run

Clean up after run

act --rm
undefined
act --rm
undefined

Secrets Management

密钥管理

Using .secrets File

使用 .secrets 文件

Create
.secrets
in project root:
GITHUB_TOKEN=ghp_your_token_here
NPM_TOKEN=npm_your_token_here
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
Add to
.gitignore
:
.secrets
Run with secrets:
bash
act --secret-file .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
使用密钥运行:
bash
act --secret-file .secrets

Inline Secrets

内联密钥

bash
undefined
bash
undefined

Single 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
undefined
act -s GITHUB_TOKEN=ghp_token
-s NPM_TOKEN=npm_token
undefined

Environment-Specific Secrets

环境特定的密钥

bash
undefined
bash
undefined

Development secrets

Development secrets

act --secret-file .secrets.dev
act --secret-file .secrets.dev

Production secrets

Production secrets

act --secret-file .secrets.prod
undefined
act --secret-file .secrets.prod
undefined

Environment Variables

环境变量

Setting Variables

设置变量

bash
undefined
bash
undefined

Single 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
undefined
act --env NODE_ENV=development
--env DEBUG=true
undefined

Using .env File

使用 .env 文件

Create
.env
file:
NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug
Run with env file:
bash
act --env-file .env
创建
.env
文件:
NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug
使用 env 文件运行:
bash
act --env-file .env

GitHub 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=true
Act 自动设置以下变量:
GITHUB_ACTOR=nektos/act
GITHUB_REPOSITORY=owner/repo
GITHUB_EVENT_NAME=push
GITHUB_SHA=abc123...
GITHUB_REF=refs/heads/main
ACT=true

Debugging

调试

Verbose Output

详细输出

bash
undefined
bash
undefined

Verbose mode

Verbose mode

act -v
act -v

Very verbose (debug)

Very verbose (debug)

act -vv
undefined
act -vv
undefined

Step-by-Step Execution

分步执行

bash
undefined
bash
undefined

Interactive mode - pause before each step

Interactive mode - pause before each step

act --watch
undefined
act --watch
undefined

Inspect Containers

检查容器

bash
undefined
bash
undefined

Keep 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
undefined
docker ps docker exec -it <container-id> /bin/bash
undefined

Bind Mount Local Files

绑定挂载本地文件

bash
undefined
bash
undefined

Mount current directory

Mount current directory

act --bind
act --bind

Mount specific directory

Mount specific directory

act -b /host/path:/container/path
undefined
act -b /host/path:/container/path
undefined

Common Workflows

常见工作流

Test Before Push

推送前测试

bash
undefined
bash
undefined

Validate 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
undefined
act
undefined

Iterative Development

迭代开发

bash
undefined
bash
undefined

Edit 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
undefined
act --reuse -j build
undefined

Matrix Testing

矩阵测试

bash
undefined
bash
undefined

Run 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
undefined
act
undefined

Troubleshooting

故障排除

Docker Issues

Docker 问题

bash
undefined
bash
undefined

Check 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
undefined
docker system prune -a
undefined

Permission Issues

权限问题

bash
undefined
bash
undefined

Run 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
undefined
sudo usermod -aG docker $USER newgrp docker
undefined

Missing Tools

缺少工具

bash
undefined
bash
undefined

Use 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
undefined

Workflow Not Found

未找到工作流

bash
undefined
bash
undefined

Check 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
undefined
act -l
undefined

Action Compatibility

Action 兼容性

Some actions don't work with act:
yaml
undefined
某些 action 无法与 act 配合工作:
yaml
undefined

Skip 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"
undefined

Best Practices

最佳实践

DO

应该做

✅ Use
act --dryrun
before running full workflows ✅ Create
.actrc
for consistent configuration ✅ Use
.secrets
file and add it to
.gitignore
✅ Use
--reuse
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 的用法

DON'T

不应做

❌ Commit
.secrets
or
.env
files ❌ Use
latest
Docker tags in production ❌ Skip validation with
--dryrun
❌ Run act without understanding what it will do ❌ Ignore Docker disk space usage ❌ Assume all actions work perfectly with act
❌ 提交
.secrets
或
.env
文件 ❌ 在生产环境中使用
latest
Docker 标签 ❌ 跳过使用
--dryrun
进行验证 ❌ 在不了解 act 行为的情况下运行它 ❌ 忽视 Docker 磁盘空间占用 ❌ 假定所有 action 都能完美配合 act 运行

Configuration Files

配置文件

.actrc

.actrc

undefined
undefined

Platform 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-push
:
bash
#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
  echo "Workflow validation failed"
  exit 1
fi
.git/hooks/pre-push
:
bash
#!/bin/bash
echo "Validating workflows..."
act --dryrun
if [ $? -ne 0 ]; then
  echo "Workflow validation failed"
  exit 1
fi

Make Target

Make Target

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

.PHONY: ci-local
ci-local:
 act --reuse
makefile
.PHONY: test-workflows
test-workflows:
 act --dryrun
 act -j test

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

Performance Tips

性能提示

Faster Iteration

更快迭代

bash
undefined
bash
undefined

Use 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
undefined
act -P ubuntu-latest=node:20-alpine
undefined

Caching

缓存

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 使用模式