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

bash

brew install act

bash

brew install act

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

bash

choco install act-cli

bash

choco install act-cli

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

act

Equivalent to

act push

undefined

act push

undefined

Run Specific Events

运行特定事件

bash

undefined

bash

undefined

Pull request event

act pull_request

Workflow dispatch

act workflow_dispatch

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

act -W .github/workflows/ci.yml

Run specific job

act -j build

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

act -l

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

act --dryrun

Show what would run

act -n

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

act -g

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)

act

Use medium images (more tools)

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

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)

act --reuse

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

act -s GITHUB_TOKEN=ghp_token

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

act --secret-file .secrets.dev

Production secrets

act --secret-file .secrets.prod

undefined

act --secret-file .secrets.prod

undefined

Environment Variables

环境变量

Setting Variables

设置变量

bash

undefined

bash

undefined

Single variable

act --env NODE_ENV=development

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

act -v

Very verbose (debug)

act -vv

undefined

act -vv

undefined

Step-by-Step Execution

分步执行

bash

undefined

bash

undefined

Interactive mode - pause before each step

act --watch

undefined

act --watch

undefined

Inspect Containers

检查容器

bash

undefined

bash

undefined

Keep container running after workflow

act --reuse

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

act --bind

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

act --dryrun

Run tests

act -j test

Run full CI

act

undefined

act

undefined

Iterative Development

迭代开发

bash

undefined

bash

undefined

Edit workflow

vim .github/workflows/ci.yml

Test immediately

act --reuse -j build

Iterate quickly

act --reuse -j build

undefined

act --reuse -j build

undefined

Matrix Testing

矩阵测试

bash

undefined

bash

undefined

Run specific matrix combination

act --matrix os:ubuntu-latest --matrix node:20

Run all combinations

act

undefined

act

undefined

Troubleshooting

故障排除

Docker Issues

Docker 问题

bash

undefined

bash

undefined

Check Docker is running

docker ps

Pull required images manually

docker pull catthehacker/ubuntu:act-latest

Clean up Docker resources

docker system prune -a

undefined

docker system prune -a

undefined

Permission Issues

权限问题

bash

undefined

bash

undefined

Run with sudo (Linux)

sudo act

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

act -P ubuntu-latest=catthehacker/ubuntu:full-latest

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

ls -la .github/workflows/

Validate YAML syntax

yamllint .github/workflows/*.yml

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

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

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

undefined

undefined

Platform mappings

-P ubuntu-latest=catthehacker/ubuntu:act-latest

Default options

--reuse --secret-file .secrets --env-file .env

Container options

--container-architecture linux/amd64

undefined

--container-architecture linux/amd64

undefined

.github/workflows/.actrc

Project-specific overrides in workflows directory.

工作流目录中针对具体项目的覆盖配置。

CI/CD Integration

CI/CD 集成

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

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

act --reuse

Skip checkout if not needed

act --reuse -j test --no-recurse

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/

act-local-testing

Original

Translation

Act - Local Workflow Testing

Act - 本地工作流测试

Installation

安装

macOS

macOS

Linux

Linux

Windows

Windows

or

or

From Source

从源码安装

Basic Usage

基本用法

Run All Workflows

运行所有工作流

Run workflows triggered by push event

Run workflows triggered by push event

Equivalent to

Equivalent to

Run Specific Events

运行特定事件

Pull request event

Pull request event

Workflow dispatch

Workflow dispatch

Custom event

Custom event

Run Specific Workflows

运行特定工作流

Run specific workflow file

Run specific workflow file

Run specific job

Run specific job

Run specific workflow and job

Run specific workflow and job

List Available Workflows

列出可用工作流

List all workflows and jobs

List all workflows and jobs

List for specific event

List for specific event

Validation and Dry Runs

验证与试运行

Dry Run

试运行

Validate without executing

Validate without executing

Show what would run

Show what would run

Validate specific workflow

Validate specific workflow

Graph Visualization

图表可视化

Show workflow graph

Show workflow graph

Show graph for specific event

Show graph for specific event

Docker Configuration

Docker 配置

Default Runners

默认 Runner

Use default images (micro - minimal)

Use default images (micro - minimal)

Use medium images (more tools)

Use medium images (more tools)

Use large images (most compatible)

Use large images (most compatible)

Custom Platform Images

自定义平台镜像

Reusing Docker Containers

复用 Docker 容器

Reuse containers between runs (faster)

Reuse containers between runs (faster)

Clean up after run