tikz的GitHub Actions CI/CD完全拆解:矩阵作业、lychee死链检查与GitHub Pages零信任部署
tikz的GitHub Actions CI/CD完全拆解:矩阵作业、lychee死链检查与GitHub Pages零信任部署
tikz(Scientific Diagrams)是一个收录 159 张物理/化学/机器学习概念图解的开源项目:每张图都有 Typst 或 LaTeX 源文件、元数据 YAML 和多格式渲染产物。围绕这些"文档型"资产,项目用一条 GitHub Actions 流水线实现了矩阵作业并行检查、lychee 全仓库死链扫描、视觉回归构建,以及基于 OIDC 的 GitHub Pages 零信任部署——全文基于 workflows/ci.yml 逐段拆解。
🗺️ 流水线总览:6 个作业,1 个"闸门"
整条 CI 定义在 .github/workflows/ci.yml,触发条件为 push 到 main、针对 main 的 pull_request,以及手动 workflow_dispatch。作业拓扑如下:
| 作业 | 作用 | 权限 |
|---|---|---|
checks |
矩阵作业:lint / unit 两分支并行 |
只读 |
python-tests |
pytest 校验元数据、主题、几何 | 只读 |
link-check |
lychee 死链检查 | 只读 |
build |
构建站点 + Playwright 视觉回归 | 只读 |
check |
闸门:确认所有矩阵分支 success | 只读 |
deploy |
仅 main 分支:发布到 GitHub Pages | pages: write + id-token: write |
两个全局设置值得新手注意:
- 并发控制:
concurrency按"工作流 + 分支"分组并开启cancel-in-progress,同一分支连推多次时,旧运行会自动取消,只保留最新一次,省 runner 分钟数。 - 最小权限:工作流顶层声明
permissions: contents: read,所有作业默认只能读代码,唯一的写权限被精确隔离到deploy作业里。
🧪 矩阵作业:lint 与单元测试并行
checks 作业用 strategy.matrix 把任务拆成 lint 和 unit 两个并行实例:
fail-fast: false:任一分支失败不会取消另一分支,方便一次看全所有报错。- lint 分支通过
j178/prek-action运行prek(pre-commit 的 Rust 版)。注意一个精妙的细节:setup-uv仅在 lint 分支安装——注释解释 unit 分支从不会创建 uv 缓存目录,若其 post 步骤在缓存未命中时报错,整条作业会被误判失败。 - unit 分支在 site/ 子目录执行
pnpm test,即 Vitest 单测(画廊状态、URL 参数、路由加载等逻辑)。
环境准备上也有讲究:
actions/checkout全部加了persist-credentials: false,让检出的代码目录里不留任何 GitHub token。- 依赖安装使用
pnpm install --no-lockfile,并用actions/cache缓存~/.cache/pnpm、~/.npm与 Typst 包缓存,缓存键绑定 site/package.json 与assets/**/*.typ的哈希,源文件不变时秒级命中。 - pull_request_template.md 为贡献者提供了"新增图解"清单:源文件、元数据 YAML、citation.cff 署名三项缺一不可,从 PR 源头减少 CI 反复返工。
🔍 Python 测试作业:uv 一条命令跑完
python-tests 作业用 uv run --no-project --with pytest --with pyyaml pytest -q 一条命令在临时环境里执行 tests/ 下的三个校验器,无需维护虚拟环境:
- test_metadata.py:校验每个
assets/*/下 元数据 YAML 的必填字段、日期格式与未知字段; - test_diagram_themes.py:校验透明导出与明暗主题预览一致性;
- test_diagram_geometry.py:校验图解几何属性。
一个容易踩的坑被注释写明:runner 的 apt 源只有 ImageMagick 6(没有 magick 命令、不支持 AVIF),所以改用 Homebrew 安装 ImageMagick 7 与 zopfli,再把 brew 前缀追加到 GITHUB_PATH。这类"runner 环境差异"是 CI 排错的高频原因。
🔗 lychee 死链检查:一条 args 扫全仓库
文档型仓库最大的隐患是失效引用:assets/ 下数百个 .typ/.tex/.yml 里都写着参考文献 URL。link-check 作业用 lycheeverse/lychee-action@v2 扫描 ./**/*.{typ,tex,md,svelte,ts,yml},参数堪称"实战手册":
--accept 100..=103,200..=299,403,429,500,503:把限流与瞬时故障算作可接受,避免"网站防爬"误杀流水线;--exclude-private:跳过所有内网地址;--exclude正则排除未渲染的模板变量(如${...}被百分号编码后的$%7B...%7D形态)、arXiv、ScienceDirect 等对爬虫不友好的站点,以及个别证书不稳定的期刊站点;--max-redirects 10 --timeout 30:给学术网站留足跳转与响应时间。
🏗️ build 作业:从构建到视觉回归
build 作业串起"构建 → 截图对比 → 上传产物"三步:
- 构建:
pnpm exec vp build产出静态站点到site/build。图片处理缓存(imagetools)用actions/cache/restore先尝试命中,命中键基于assets/**/*.png与转换逻辑 site/src/lib/index.ts 的哈希;仅在未命中时才用actions/cache/save回写,避免重复上传。 - 视觉回归:
pnpm exec playwright install --only-shell chromium装精简版 Chromium 后运行pnpm test:visual。配置见 site/playwright.config.ts——允许最多 100 个抗锯齿像素差异(maxDiffPixels: 100),既不会因字体渲染噪声误报,也能抓住真实的布局/颜色变化;CI 下forbidOnly: true防止误提交的it.only漏跑用例。 - 失败取证:
if: failure()时上传playwright-report与test-results(含 trace)为构建产物,保留 7 天,失败原因可追溯。 - 发布物:
actions/upload-pages-artifact把site/build交给 Pages。
🚀 GitHub Pages 零信任部署:全程无 token
deploy 作业是整条流水线唯一拥有写权限的节点,且被三重条件锁死:
if: github.ref == 'refs/heads/main'——只有主干推送才可能触发;needs: [check, python-tests, build]——闸门作业与全部检查通过后才运行;permissions: { pages: write, id-token: write }绑定github-pages环境,唯一一步就是actions/deploy-pages@v5,作业内没有任何run步骤、没有任何 secret。
这里的"零信任"指认证走 GitHub 平台的 OIDC 令牌(id-token)而非仓库里长期存放的 PAT/secret:token 短时效、由 runner 直接向 Pages 服务兑换,权限爆炸半径趋近于零。配合前面 checkout 的 persist-credentials: false,整条流水线里任何一步被恶意代码利用,都拿不到可持久使用的凭据。
🛡️ 用 pytest 测试 CI 本身
最具启发性的是 tests/test_ci.py:它把 ci.yml 当作 YAML 加载后断言——
- 闸门命令对
success/failure/cancelled/skipped四种上游结果的判定必须正确(真实调bash -c验证); - 含
actions/deploy-pages的作业必须恰好只有pages/id-token写权限、只跑在 main、且不含run步骤;其余作业权限必须为contents: read; - 所有
actions/checkout步骤必须persist-credentials: false。
也就是说,"最小权限配置"本身成为可回归测试的代码——有人误改权限,CI 先红。
✅ 新手可抄作业的 6 个要点
- 矩阵作业 +
fail-fast: false:并行提速,失败全量可见(ci.yml#L25-L31)。 - 闸门作业模式:用
needs.result汇总矩阵结果,方便设置"必需检查"。 - 缓存键绑定内容哈希:
hashFiles('site/package.json', 'assets/**/*.typ'),精准失效(ci.yml#L45-L52)。 - lychee 的宽容策略:
--accept放行瞬时故障、--exclude跳过模板变量与防爬站点(ci.yml#L88-L100)。 - 视觉回归的噪声容忍:
maxDiffPixels小阈值防误报,trace 失败留存可复核。 - OIDC 部署 + 自测 CI:
id-token零 secret,且用测试守护权限配置不回退。
相关入口:工作流 .github/workflows/ci.yml · 自测 tests/test_ci.py · 视觉回归 site/playwright.config.ts · 渲染脚本 scripts/render_typst.py 与 scripts/render_tikz.py


