Local CI兼容GitHub Actions语法全览:matrix、if表达式、secrets支持矩阵一张表看懂
Local CI兼容GitHub Actions语法全览:matrix、if表达式、secrets支持矩阵一张表看懂
Local CI 是一款把 GitHub Actions 工作流直接跑在你本机 的工具:不重写 runner,而是用官方 runner 二进制 + 本地 API 模拟层,让你提交代码之前就能完成「运行 → 失败暂停 → 修复 → 重试」的完整闭环。本文用一张支持矩阵,帮你看懂 Local CI 对 matrix、if 表达式、secrets 等语法的支持程度,以及哪些功能需要绕道实现。
为什么需要「GitHub Actions 本地运行」工具?
远程 CI 每次重试都要付一次全新运行的成本:push → 等待 → 读日志 → 再 push。Local CI 把它变成起飞前检查:
| 对比项 | GitHub Actions | 其他本地运行工具 | Local CI |
|---|---|---|---|
| Runner 二进制 | 官方 | 自行重写 | 官方 runner |
| API 层 | GitHub.com | 兼容补丁 | 完整本地模拟 |
| 缓存往返 | 网络(数秒) | 视实现而定 | 约 0 ms(本地文件系统) |
| 失败后 | 从头再来 | 从头再来 | 暂停 → 修复 → 只重试失败步骤 |
| 需要干净 commit | 是 | 是 | 否,直接跑工作树 |
因为执行的是官方 runner,语法兼容性来自「真身」,Local CI 只需补齐解析、上下文和 API 模拟层——这也是 compatibility.md 这份支持矩阵存在的意义。
图例:5 个状态符号,看懂支持矩阵
完整矩阵定义在 compatibility.json,渲染结果即 compatibility.md:
- ✅ Supported —— 完整实现,行为与 GitHub Actions 一致
- ⚠️ Partial —— 能用但有限制,注意备注
- ❌ Not supported —— 未实现,会被跳过或报错
- 🟡 Ignored (no-op) —— 解析不报错,但对运行无影响
- 🚫 Not planned —— 架构上无法实现(如依赖 GitHub 侧队列的
concurrency)
matrix 支持矩阵:策略键逐个看
来自 compatibility.md 的 Strategy / Matrix 区块:
| 语法键 | 状态 | 说明 |
|---|---|---|
strategy.matrix |
✅ | 各键数组值完全做笛卡尔积展开 |
strategy.matrix.include |
❌ | 未实现,include 条目会被静默丢弃 |
strategy.matrix.exclude |
❌ | 同上,对象形式的条目不进解析器 |
strategy.fail-fast |
✅ | fail-fast: false 时,某个组合失败后其余组合继续跑 |
strategy.max-parallel |
❌ | 并发由 Local CI 宿主机限制(基于 CPU 核数)接管,--jobs <N> 可显式覆盖 |
配套的表达式上下文 matrix.*、strategy.job-total、strategy.job-index 均已支持。最简示例见 matrix.yml:
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node: [18, 20]
steps:
- run: echo node ${{ matrix.node }}
💡 实用技巧:只想快速验证工作流、不想展开全部组合时,加 --no-matrix 可把所有矩阵坍缩成单个 job(每个键取第一个值)。
if 表达式支持矩阵:job 级全支持,step 级有讲究
| 表达式 | 状态 | 说明 |
|---|---|---|
success() / failure() / always() |
⚠️ | 按依赖波次(dependency waves)中累积的 job 状态求值;cleanup 类收尾 job 用 always() 完全可行,见 status-functions.yml |
cancelled() |
⚠️ | 本地没有取消信号,恒返回 false,if: cancelled() 的步骤不会执行 |
==、!=、<、>、&&、||、!、括号 |
✅ | 大小写不敏感;数值强制转换遵循 GitHub Actions 语义 |
needs.*.outputs.* / needs.*.result |
✅ | 依赖 job 完成后真实解析,跨 job 传值的主力手段 |
steps.*.outputs.* |
⚠️ | 解析期为空串(步骤尚未运行),cache-hit 类引用会失效,建议改用 needs.*.outputs.* |
steps.*.conclusion / outcome |
❌ | 步骤结果状态未暴露 |
纯布尔值/字符串条件(如 if: ${{ false }}) |
✅ | 见 skip-if.yml |
要点:job 级 if 放心用;step 级 if 会原样交给官方 runner 运行时求值,但引用前置 step 输出的场景是已知短板。
secrets 支持矩阵:3 个来源按序解析
${{ secrets.FOO }} 的解析顺序(与 README.md 的 Secrets 章节一致):
| 优先级 | 来源 | 用法 |
|---|---|---|
| 1 | .env.local-ci 文件(仓库根目录) |
KEY=VALUE 语法,支持 # 注释 |
| 2 | Shell 环境变量 | 与 secret 同名即可兜底,无需额外配置 |
| 3 | --github-token / LOCAL_CI_GITHUB_TOKEN |
自动填充 secrets.GITHUB_TOKEN |
# 方式一:写入本地 env 文件(推荐,不入库)
echo "CLOUDFLARE_API_TOKEN=xxx" >> .env.local-ci
# 方式二:内联环境变量
CLOUDFLARE_API_TOKEN=xxx local-ci run -w .github/workflows/deploy.yml
# 方式三:为 GITHUB_TOKEN 单独授权
local-ci run -w .github/workflows/ci.yml --github-token
⚠️ 注意:jobs.<id>.secrets 的 job 级继承/过滤属于 🚫 Not planned(本地无法访问 GitHub 的 secret 存储),但 with: 中直接引用 ${{ secrets.* }} 完全可用。与 secrets 相对的 vars.* 则通过 --var KEY=VALUE 或 --var-file 注入,缺失的 var 会在预检阶段直接报出清单。
其他语法速查:工作流级 / 步骤级 / 表达式
工作流级:on(push / pull_request)✅、分支与路径过滤 ✅(配合 --all 生效)、workflow_call 可复用工作流 ✅(本地 ./ 引用内联展开,远程引用需 token)、env / defaults.run.shell ✅;concurrency 🚫、tag 过滤 ❌、事件触发类(schedule 等)🟡 仅手动运行。
步骤级:run / uses(含本地 ./ action)/ with / env / shell / working-directory ✅;docker:// 镜像形式的 action ❌;timeout-minutes、continue-on-error ❌——这是有意为之:Local CI 的失败暂停模型才是处理长任务和错误的正道,硬超时会毁掉本地调试所需的容器状态。
表达式:hashFiles()、format()、toJSON / fromJSON、contains、startsWith / endsWith、join ✅;github.sha / github.repository ✅(脏工作树会合成树 SHA);github.event.* 与大部分 github.* 字段 ⚠️ 返回静态默认值;* 对象过滤运算符 ❌。
API 模拟层:actions/checkout ✅(rsync 进容器并保留本地改动)、actions/cache ⚠️(本地文件系统缓存、约 0 ms,但无按 ref 隔离)、artifact 上传下载 ✅、setup-* 工具链 ✅。
快速上手:3 步验证你的工作流
# 1. 安装依赖
git clone https://gitcode.com/gh_mirrors/ag/local-ci local-ci
# 2. 运行单个工作流
npx run-local-ci run --workflow .github/workflows/ci.yml
# 3. 失败时暂停并只重试失败步骤
npx run-local-ci run --pause-on-failure --workflow .github/workflows/ci.yml
npx run-local-ci retry --name <runner-name>
前置要求是运行中的 Docker(macOS 推荐 OrbStack);runs-on: macos-* 任务需在 Apple Silicon 上另装 tart + sshpass。
结论:哪些语法可以放心写,哪些要绕
- ✅ 放心写:matrix 基础矩阵 +
fail-fast、job 级if+ 状态函数、needs.*.outputs、secrets.*/vars.*、常用字符串与 JSON 函数 - ⚠️ 能跑但有坑:step 级
if引用前置输出、github.event.*、actions/cache的跨分支隔离 - ❌ / 🚫 要绕:
include/exclude(拆成显式 job 或独立工作流)、concurrency(本地无状态队列)、docker://action(改用仓库形式 action)
完整条目级支持矩阵以 compatibility.md 为准,机器可读版本见 compatibility.json;更多场景可参考 third-party-workflows/ 下收录的 Turborepo、Playwright 等真实第三方 workflow 作为差分解析样本。
