摘要： Go Act 项目：在本地运行 GitHub Actions 的利器 项目概述 Go Act 是一个用 Go 语言开发的开源工具，它允许开发者在本地环境中运行 GitHub Act...

Go Act 项目：在本地运行 GitHub Actions 的利器

项目概述

Go Act 是一个用 Go 语言开发的开源工具，它允许开发者在本地环境中运行 GitHub Actions 工作流。这个项目解决了在本地测试和调试 GitHub Actions 工作流时的痛点，无需每次都将代码推送到远程仓库来触发工作流执行。

核心特性

1. 本地执行 GitHub Actions

• 完全模拟 GitHub Actions 的运行环境
• 支持绝大多数 GitHub Actions 语法和功能
• 无需互联网连接即可测试工作流

2. 跨平台支持

• 支持 macOS、Linux 和 Windows 系统
• 提供多种安装方式（包管理器、二进制下载等）

3. 灵活配置

• 支持自定义运行器镜像
• 可配置环境变量和密钥
• 支持多种事件触发

安装方法

使用包管理器安装

# macOS (Homebrew)
brew install act

# Linux (Snap)
sudo snap install act

# Windows (Chocolatey)
choco install act-cli

下载二进制文件

# 从 GitHub Releases 下载对应平台的二进制文件
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

使用实例

基础使用示例

1. 简单工作流测试

# 进入项目目录
cd your-project

# 运行默认工作流
act

# 运行特定事件的工作流
act push

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

1. 查看可用工作流

# 列出所有工作流
act -l

# 输出示例：
# Stage  Job ID  Job Name  Workflow Name
# -----  ------  --------  -------------
# test   test    Test      test.yml

实际应用场景

场景一：测试 CI/CD 流水线

假设你有一个 .github/workflows/ci.yml 文件：

name: CI Pipeline

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test

在本地测试这个工作流：

# 模拟 push 事件
act push

# 或指定工作流
act -W .github/workflows/ci.yml

场景二：调试复杂工作流

# 使用详细模式查看执行过程
act -v

# 只运行特定 job
act -j test

# 使用不同的运行器镜像
act -P ubuntu-latest=node:18-buster-slim

场景三：集成到开发流程

创建 Makefile 集成 act：

.PHONY: test-ci
test-ci:
	@echo "Testing GitHub Actions workflow locally..."
	act -W .github/workflows/ci.yml --container-architecture linux/amd64

高级配置

配置文件示例

创建 .actrc 配置文件：

# 默认平台
-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
-P ubuntu-22.04=ghcr.io/catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04

# 默认事件
--eventspath .github/events

# 绑定挂载
--bind

环境变量管理

# 设置环境变量
export MY_SECRET=supersecret

# 使用 secrets 文件
echo 'MY_TOKEN=abc123' > .secrets
act --secret-file .secrets

实际项目集成示例

示例：完整的开发工作流

# .github/workflows/development.yml
name: Development Checks

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run linter
        run: |
          go fmt ./...
          go vet ./...
          golangci-lint run

  test:
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: go test -v -race ./...

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v3
      - name: Build binary
        run: go build -o myapp ./cmd/myapp

本地测试命令：

# 测试整个工作流
act push

# 只测试构建步骤
act -j build

# 使用缓存加速
act --artifact-server-path /tmp/act-artifacts

最佳实践

1. 使用轻量级镜像

# 使用优化过的 act 镜像
act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest

1. 利用缓存机制

# 启用缓存
act --artifact-server-path $(pwd)/.cache/act

1. 隔离测试环境

# 使用不同的工作目录
act --workflows .github/workflows/test.yml --directory /tmp/test-run

1. 集成到预提交钩子

# 在 .git/hooks/pre-push 中添加
#!/bin/bash
echo "Running GitHub Actions locally..."
act push --dry-run

常见问题解决

性能优化

# 跳过 actions/checkout 步骤
act -s GITHUB_TOKEN="fake-token" --skip-checkout

# 使用更小的基础镜像
act -P ubuntu-latest=node:18-alpine

网络问题处理

# 使用本地镜像仓库
act -P ubuntu-latest=localhost:5000/ubuntu:latest

# 配置代理
export http_proxy=http://proxy:port
export https_proxy=http://proxy:port

总结

Go Act 项目为开发者提供了一个强大的本地 GitHub Actions 测试环境，显著提高了工作流开发的效率。通过本地测试，开发者可以：

• 快速迭代和调试工作流配置
• 减少对 GitHub 资源的依赖
• 在离线环境下开发工作流
• 集成到本地开发流程中

无论是简单的 CI/CD 流水线还是复杂的企业级部署流程，Go Act 都能提供可靠的本地测试方案，是每个使用 GitHub Actions 的开发者必备的工具之一。

项目地址: https://github.com/nektos/act