如何快速在本地跑通 GitHub Actions?actrun 新手完整教程
如何快速在本地跑通 GitHub Actions?actrun 新手完整教程
还在为 GitHub Actions 的排队和慢启动烦恼吗?本文带你用 actrun(一个用 MoonBit 编写的 GitHub Actions 兼容本地 runner)在几分钟内把工作流跑起来:本地运行、查看日志、跳过无关步骤,最后再谈优化。
为什么选择 actrun 本地运行?
把 CI 搬到本地,你能获得这些好处:
- ⚡ 秒级反馈:不用等云端队列,
local模式启动约 0.13 秒 - 🐛 快速调试:直接读
run logs,甚至查看单条 step 日志 - 🔄 语义一致:保持与 GitHub Actions 相同的 YAML 与上下文,本地跑通后推上去基本不用改
- 🗂️ 可选隔离:支持
worktree、tmp、docker等工作区模式,不污染你的工作目录
性能基准(Apple Silicon):
| 模式 | 启动耗时 | 写 1k 文件 |
|---|---|---|
local |
~0.13s | 52ms |
nix-packages |
~0.70s | 47ms |
apple-container |
~0.93s | 14ms |
第一步:安装 actrun
安装方式任选其一,推荐新手直接用 npx,零安装:
# npx(无需安装)
npx @mizchi/actrun workflow run .github/workflows/ci.yml
# npm 全局安装
npm install -g @mizchi/actrun
# Docker
docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/mizchi/actrun workflow run .github/workflows/ci.yml
也可以从源码构建:
git clone https://gitcode.com/gh_mirrors/ac/actrun
cd actrun
moon build src/cmd/actrun --target native
5 分钟跑通你的第一个工作流
先用仓库自带的 01-hello.yml 体验一下:
name: hello
'on': push
jobs:
greet:
runs-on: ubuntu-latest
steps:
- run: echo "Hello from actrun!"
运行它就一条命令:
actrun workflow run examples/01-hello.yml
接下来是新手最常用的几个动作:
# 不真正执行,先看执行计划(推荐先跑一次确认)
actrun workflow run examples/01-hello.yml --dry-run
# 列出项目里所有工作流
actrun workflow list
# 查看历史运行与日志
actrun run list
actrun run view run-1
actrun run logs run-1 --task greet
💡 小技巧:省略
workflow run也可以,actrun .github/workflows/ci.yml是等价简写。
本地上下文自动填充
在普通 git 仓库里直接运行,actrun 会自动从本地仓库检测 github.repository、github.ref_name、github.sha 和 github.actor,通常不需要任何额外配置。如果你需要固定这些值(比如演示、截图场景),可以在 actrun.toml 里写 <a href="https://link.gitcode.com/i/03516361805891068d71d69aba35a145" target="_blank">local_context] 覆盖,优先级规则见 [local-context.md。
让本地更快:跳过与裁剪
先跑起来,再变快——下面这些开关就是"变快"的部分,全都无需改动工作流文件:
| 目标 | 命令 / 配置 | 说明 |
|---|---|---|
| 跳过本地不需要的 action | --skip-action actions/checkout |
可重复使用,也可写入 actrun.toml 的 local_skip_actions |
| 只跑失败的部分 | actrun ci.yml --retry |
复跑时跳过已成功的 job |
| 按文件变更跳过整个工作流 | actrun ci.yml --affected HEAD~3 |
类似 nx / turborepo 的 affected 机制 |
| 只跑某个 job / step | actrun ci.yml --job build --step test |
定向调试 |
| 本地专属调试步骤 | 条件 if: ${{ env.ACTRUN_LOCAL }} |
actrun 会设置 ACTRUN_LOCAL=true |
ACTRUN_LOCAL 是个非常实用的特性:本地执行时 actrun 会注入该环境变量,你可以在工作流里用它区分本地与云端。仓库里的 06-local-skip.yml 就是一个完整示例:本地跳过 checkout 和 setup-node,云端照常执行。
# 组合拳:跳过 checkout + 只跑 build job + 失败重试
actrun ci.yml --skip-action actions/checkout --job build --retry
更多参数速查请见 cheatsheet.md,--affected 的完整配置方式见 advanced-workflow.md。
常见工作流示例
仓库 examples/ 目录提供了 30+ 个可直接运行的样例,覆盖新手关心的大部分场景:
| 场景 | 示例文件 |
|---|---|
| 环境变量与 step 输出 | 02-env-and-outputs.yml |
| Matrix 矩阵 | 03-matrix.yml |
| Secrets 与条件分支 | 05-secrets.yml、09-conditional.yml |
| Artifacts 与 Cache | 07-artifacts.yml、08-cache.yml |
| 自定义 Action(composite / docker / node / wasm) | 11-custom-actions.yml |
| Nix 集成 | 15-nix-flake.yml |
Secrets 通过环境变量传入即可,无需配置文件,且会自动在日志中脱敏:
ACTRUN_SECRET_MY_TOKEN=xxx actrun workflow run .github/workflows/ci.yml
进阶工具:lint 与可视化
跑起来之后,还可以用 actrun 自带的分析命令提前发现问题:
# 类型检查表达式、检测未定义引用等(类似 actionlint)
actrun lint .github/workflows/ci.yml
# 画出 job 依赖图,直观理解执行顺序
actrun viz .github/workflows/ci.yml --mermaid
规则清单(如 undefined-context、circular-needs、script-injection 等 20 余条)详见 README.md。
总结:从跑通到变快
- 装:
npx @mizchi/actrun或npm install -g @mizchi/actrun - 跑:
actrun workflow run .github/workflows/ci.yml - 看:
actrun run logs <run-id> - 快:
--skip-action/--retry/--affected按需裁剪
actrun 的核心理念是"先跑起来,再谈优化":本地语义与 GitHub Actions 对齐,跑通即验证;之后用 actrun.toml 固化你的本地配置,把工作流从分钟级反馈提升到秒级反馈。更多契约与边界说明可查阅 public-api.md。