使用Act本地运行GitHub Actions
学习如何使用act在本地机器上运行GitHub Actions,节省时间并提高开发效率。
你是否曾经为了测试一个不按预期工作的workflow而不得不将代码推送到GitHub?或者每次小改动后都要等待几分钟让CI重新运行?🤔
在这篇文章中,我将介绍act - 一个工具,让你可以在本地机器上直接运行GitHub Actions,而不是等待GitHub远程处理它们。
为什么要在本地运行GitHub Actions?#
想象一下你正在修复CI/CD workflow。当前的过程通常是:
- 编辑workflow文件
- 提交并推送代码
- 等待GitHub Actions运行(可能需要几分钟)
- 看到错误发生
- 回到步骤1
这就像每次想要修复文档中的一句话都要给同事发邮件,而不是直接编辑它。非常耗时且低效。
act通过以下方式解决这个问题:
- 快速反馈 - 在你的机器上立即运行workflow,无需推送
- 本地任务运行器 - 用GitHub Actions替换Makefile,利用现有的workflow结构
- 减少依赖 - 当actions和镜像被缓存时,无需互联网连接
Act如何工作?#
将GitHub Actions想象成一个工厂。当你推送代码时,GitHub会:
- 从
.github/workflows/读取workflow文件 - 确定需要运行哪些actions
- 相应地拉取或构建Docker镜像
- 在容器中运行每个action
- 配置环境变量和文件系统以匹配GitHub
act在你的机器上而不是GitHub的服务器上做完全相同的事情:
安装Act#
前提条件#
act需要Docker在容器中运行workflow。如果不需要容器隔离(例如,在你的机器上直接运行windows/macOS作业),可以跳过Docker。
- macOS: 安装Docker Desktop for Mac
- Windows: 安装Docker Desktop for Windows
- Linux: 安装Docker Engine
快速安装#
方法1: Homebrew(macOS & Linux)
brew install actbash方法2: Bash脚本(所有平台)
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashbash方法3: GitHub CLI扩展
gh extension install https://github.com/nektos/gh-actbash方法4: 直接下载
从GitHub releases ↗下载并添加到PATH。
[!TIP] 验证安装:
bashact --version
Act基本使用#
运行默认workflow#
默认情况下,act使用事件push运行所有workflow:
actbash使用特定事件运行#
act pull_request
act schedule
act workflow_dispatchbash列出workflow#
act -l pull_requestbash运行特定workflow#
act -W .github/workflows/checks.ymlbash运行特定作业#
act -j testbash配置密钥和变量#
使用密钥#
GitHub在服务器上运行workflow时自动提供GITHUB_TOKEN。在本地运行时,你需要提供它:
act -s MY_SECRET=my-value
# 方法2: 使用环境变量(推荐)
act -s MY_SECRET
# 方法3: 从GitHub CLI自动获取令牌
act -s GITHUB_TOKEN="$(gh auth token)"
# 方法4: 从文件加载
act --secret-file .secretsbash[!WARNING] 在终端中输入敏感数据时,可能会保存到shell历史记录中。出于安全考虑,使用方法2或3。
使用仓库变量#
act --var VARIABLE=some-value
act --var-file .envbash.env文件格式#
格式匹配Ruby dotenv:
MY_ENV='value'
PRIV_KEY="---...\nrandom text\n...---"
JSON="{\n\"name\": \"value\"\n}"
SOME_VAR=SOME_VALUEbash本地运行时跳过作业和步骤#
跳过作业#
使用自定义事件属性:
on: push
jobs:
deploy:
if: ${{ !github.event.act }} # 本地运行时跳过
runs-on: ubuntu-latest
steps:
- run: echo "Deploy step"yaml创建event.json:
{
"act": true
}json运行:
act -e event.jsonbash跳过步骤#
act提供环境变量ACT:
- name: Notify Slack
if: ${{ !env.ACT }} # 本地运行时跳过
run: |
curl -X POST $SLACK_WEBHOOKyaml矩阵和高级功能#
运行矩阵子集#
如果workflow有多个值的矩阵:
strategy:
matrix:
node: [14, 16, 18]
os: [ubuntu-latest, macos-latest]yaml只运行node 18:
act push --matrix node:18bash只运行node 18和ubuntu:
act push --matrix node:18 --matrix os:ubuntu-latestbashAction离线模式#
缓存时加速并离线运行:
act --action-offline-modebash好处:
- 不拉取现有镜像
- 缓存时可以离线工作
- 避免GitHub速率限制
- 连接不佳时节省时间
.actrc配置文件#
为了避免每次都输入标志,创建.actrc:
--container-architecture=linux/amd64
--action-offline-mode
-e event.jsonbash问题和限制#
Apple Silicon(M1/M2/M3)#
如果使用Apple M系列芯片,可能会遇到架构问题:
act --container-architecture linux/amd64bash运行器镜像#
act使用与GitHub运行器不同的Docker镜像。某些工具可能无法工作:
ubuntu-latest→node:16-buster-slim(轻量)或catthehacker/ubuntu:act-latest(中等)- 对于与GitHub完全匹配的环境,使用
nektos/act-environments-ubuntu:18.04
不支持的功能#
某些GitHub Actions功能不受支持:
- Docker上下文
- 某些复杂的矩阵配置
- 某些GitHub Actions特定功能
实际示例#
简单workflow#
name: Test
on: push
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install
run: npm install
- name: Test
run: npm testyaml本地运行:
actbash使用密钥的workflow#
name: Deploy
on: push
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to production
run: |
curl -X POST ${{ secrets.DEPLOY_URL }}yaml本地运行:
act -s DEPLOY_URLbash与GitHub Actions的比较#
| 功能 | GitHub Actions | act(本地) |
|---|---|---|
| 反馈速度 | 慢(必须推送) | 快(立即运行) |
| 资源成本 | GitHub账户配额 | 你的本地机器 |
| 环境 | 精确 | 几乎精确 |
| 离线 | 不可 | 可以(离线模式) |
| 矩阵测试 | 耗时 | 快(运行子集) |
| 密钥 | 在GitHub上管理 | 手动传递 |
结论#
act对于任何使用GitHub Actions的开发者来说都是无价的工具。它有助于:
- 加速开发和workflow调试
- 减少对GitHub基础设施的依赖
- 推送前测试workflow
- 将GitHub Actions用作本地任务运行器
[!TIP] 最佳实践:特别是在修改复杂的workflow结构时,推送前始终使用act测试workflow。