在本地运行 GitHub Actions 工作流

1. 概述

在本教程中，我们将介绍一个名为 act 的命令行工具，它可以用于在本地运行 GitHub Actions 的工作流（Workflow）。这将极大提升我们开发和调试 CI/CD 流水线的效率。

2. GitHub Actions 工作流简介

GitHub Actions 是一个强大的 CI/CD（持续集成/交付）平台，允许我们通过 YAML 文件定义构建、测试和部署流程。这些 YAML 文件通常放在 .github/workflows 目录下，每个文件定义了一个或多个 Job，每个 Job 又由多个 Step 组成。

✅ 优势：声明式语法、与 GitHub 深度集成、支持丰富的 Action 市场
❌ 痛点：由于 GitHub Actions 本身只能在云端运行，本地开发和测试工作流时反馈周期较长，每次修改都需要 push 到远程仓库并手动触发流水线，效率低下。

3. act 工具介绍

act 是一个开源的命令行工具，允许我们在本地运行 GitHub Actions 工作流。它通过 Docker 模拟 GitHub Actions 的执行环境，使得我们可以在本地快速测试和验证工作流逻辑。

3.1. 安装 act

我们可以通过访问 nektos/act GitHub 仓库的发布页面下载对应的二进制文件。

以 Linux x86_64 系统为例，使用以下命令下载并解压：

$ wget -qO- https://github.com/nektos/act/releases/download/v0.2.64/act_Linux_x86_64.tar.gz | tar xvz

验证安装是否成功：

$ ./act --version
act version 0.2.64

✅ 安装完成后，我们就可以使用 act 命令来执行本地工作流了。

3.2. 准备测试仓库

我们以 github-actions-demo 仓库为例进行演示：

$ git clone git@github.com:cplee/github-actions-demo.git

进入目录后查看 .github/workflows/main.yml 文件内容：

name: CI
on: push

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v1
    - run: npm install
    - run: npm test

这是一个典型的 Node.js 项目构建流程，包含代码拉取、环境配置、安装依赖和执行测试四个步骤。

3.3. 基本使用

确保当前目录下包含 .github 文件夹，然后执行：

$ cd github-actions-demo && ../act

输出示例如下：

[CI/test] 🚀  Start image=catthehacker/ubuntu:act-latest
...
[CI/test] ⭐ Run Main actions/checkout@v2
...
[CI/test]   ✅  Success - Main actions/checkout@v2
...
[CI/test] ⭐ Run Main npm test
...
[CI/test]   ✅  Success - Main npm test
[CI/test] 🏁  Job succeeded

✅ act 会模拟 GitHub Actions 的执行环境，并逐步执行每个 Step。

⚠️ 如果我们尝试模拟一个不存在的触发事件（如 release）：

$ ../act release
Error: Could not find any stages to run...

我们需要创建一个监听 release 事件的 workflow 文件：

name: CI
on: release

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - run: echo 'on release'

再次运行：

$ ../act release
...
[CI/release] ⭐ Run Main echo 'on release'
...
[CI/release]   ✅  Success - Main echo 'on release'
[CI/release] 🏁  Job succeeded

✅ 成功执行！

3.4. 常用选项

act 支持多个选项，用于模拟 GitHub Actions 的上下文和环境变量。

3.4.1. 指定 actor

使用 --actor 指定触发工作流的用户：

$ ../act --actor Baeldung

对应工作流中可以使用：

- run: echo "I am ${{ github.actor }}"

3.4.2. 指定事件 payload

使用 --eventpath 注入事件数据：

$ ../act --eventpath release-event-payload.json

3.4.3. 注入密钥

使用 --secret 注入敏感信息：

$ ../act --secret DOCKER_PASSWORD=password

这些参数可以帮助我们更真实地模拟线上环境，便于本地调试。

4. 总结

GitHub Actions 是一个强大且灵活的 CI/CD 平台，但在本地开发时存在反馈周期长的问题。act 工具很好地弥补了这一短板，它让我们可以在本地运行和调试 GitHub Actions 工作流，从而提升开发效率，减少线上调试的风险。

✅ 主要优势包括：

支持本地运行 GitHub Actions 工作流
支持注入事件、上下文和密钥
使用 Docker 模拟真实运行环境

⚠️ 踩坑提示：确保当前目录包含 .github 文件夹，否则 act 无法识别工作流。

✅ 推荐在开发 GitHub Actions 工作流时优先使用 act 进行本地验证，再 push 到远程仓库。

Persistence

REST

Security