tikz的GitHub Actions CI/CD完全拆解:矩阵作业、lychee死链检查与GitHub Pages零信任部署

原创2026-11-01 10:57:251,895 阅读
文章标签:文档科研

tikz的GitHub Actions CI/CD完全拆解:矩阵作业、lychee死链检查与GitHub Pages零信任部署

tikz(Scientific Diagrams)是一个收录 159 张物理/化学/机器学习概念图解的开源项目:每张图都有 Typst 或 LaTeX 源文件、元数据 YAML 和多格式渲染产物。围绕这些"文档型"资产,项目用一条 GitHub Actions 流水线实现了矩阵作业并行检查、lychee 全仓库死链扫描、视觉回归构建,以及基于 OIDC 的 GitHub Pages 零信任部署——全文基于 workflows/ci.yml 逐段拆解。

Scientific Diagrams 科学图解画廊首页

🗺️ 流水线总览: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 反复返工。

Otto 循环热机示意图:CI 守护的 Typst/LaTeX 渲染产物之一

🔍 Python 测试作业:uv 一条命令跑完

python-tests 作业用 uv run --no-project --with pytest --with pyyaml pytest -q 一条命令在临时环境里执行 tests/ 下的三个校验器,无需维护虚拟环境:

一个容易踩的坑被注释写明: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:给学术网站留足跳转与响应时间。

Ball Tree 球树图解:元数据 YAML 中的引用链接是 lychee 的重点扫描对象

🏗️ build 作业:从构建到视觉回归

build 作业串起"构建 → 截图对比 → 上传产物"三步:

  1. 构建:pnpm exec vp build 产出静态站点到 site/build。图片处理缓存(imagetools)用 actions/cache/restore 先尝试命中,命中键基于 assets/**/*.png 与转换逻辑 site/src/lib/index.ts 的哈希;仅在未命中时才用 actions/cache/save 回写,避免重复上传。
  2. 视觉回归:pnpm exec playwright install --only-shell chromium 装精简版 Chromium 后运行 pnpm test:visual。配置见 site/playwright.config.ts——允许最多 100 个抗锯齿像素差异(maxDiffPixels: 100),既不会因字体渲染噪声误报,也能抓住真实的布局/颜色变化;CI 下 forbidOnly: true 防止误提交的 it.only 漏跑用例。
  3. 失败取证:if: failure() 时上传 playwright-report 与 test-results(含 trace)为构建产物,保留 7 天,失败原因可追溯。
  4. 发布物: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 个要点

  1. 矩阵作业 + fail-fast: false:并行提速,失败全量可见(ci.yml#L25-L31)。
  2. 闸门作业模式:用 needs.result 汇总矩阵结果,方便设置"必需检查"。
  3. 缓存键绑定内容哈希:hashFiles('site/package.json', 'assets/**/*.typ'),精准失效(ci.yml#L45-L52)。
  4. lychee 的宽容策略:--accept 放行瞬时故障、--exclude 跳过模板变量与防爬站点(ci.yml#L88-L100)。
  5. 视觉回归的噪声容忍:maxDiffPixels 小阈值防误报,trace 失败留存可复核。
  6. 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

登录后查看全文
tikz