MLSysBook 仓库级 CI 变量中心化管理实践GitHub Actionsvars.*配置全解【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book导读本指南以 docs/CI-VARIABLES.md 为骨架系统讲解 MLSysBook 单仓库monorepo如何通过 GitHub Actions仓库级变量Repository Variables对跨项目的源码路径、gh-pages 部署路径、运行时版本与生产域名进行一处修改、处处生效的集中管理。读完本文你将掌握${{ vars.NAME || fallback }}双写模式的完整用法、四类已定义变量的含义与消费方、新增/变更变量的五步标准流程以及如何用gh与git grep审计变量现状——这套约定可以直接复用到你自己的多项目 CI 编排中。设计动机为什么用仓库级变量而不是改代码MLSysBook 仓库同时承载了 StaffML、TinyTorch、BookVol I/II、MLSYSIM、Kits、Labs、Instructors、Slides 等多个可发布项目每个项目都拥有自己的一套 publish/preview/validate workflow。在没有统一约定之前同样的路径字符串如interviews/staffml会在数十个 workflow 文件中被硬编码多次一旦目录重命名或域名变更就需要逐个文件手工修改极易漏改。该仓库的解决方案是把跨项目共享的值提升为 GitHub Actions 仓库级变量workflow 中以${{ vars.NAME || fallback }}读取。这里的关键细节是变量名写为vars.NAMEGitHub Actions 会在运行时解析它|| fallback提供了硬编码兜底值即使变量在 Settings 中被删除、或 fork 克隆后未配置变量workflow 依然能正常运行修改变量值只需在仓库 Settings 中编辑一次下一次任何读取它的 workflow 运行即生效无需任何代码改动。从源码结构看这套约定已在 .github/workflows/ 下的所有项目 workflow 中落地。以 staffml-publish-live.yml 的env:块为例env: # Single source for paths and versions. Set via repo Settings → # Variables; the || fallback keeps the workflow runnable on # forks or if a var isnt set. See docs/CI-VARIABLES.md. STAFFML_ROOT: ${{ vars.STAFFML_ROOT || interviews/staffml }} VAULT_DIR: ${{ vars.VAULT_DIR || interviews/vault }} VAULT_CLI_DIR: ${{ vars.VAULT_CLI_DIR || interviews/vault-cli }} DEV_STAFFML_PATH: ${{ vars.DEV_STAFFML_PATH || staffml }} PYTHON_VERSION: ${{ vars.PYTHON_VERSION || 3.12 }}staffml-validate-dev.yml 中同样维护了这组 env并在注释中明确指向本文档说明 validate/preview/publish 三个环节共享同一份单一事实来源。变量配置入口与生效时机变量的管理入口不在代码仓库中而是位于 GitHub 仓库设置页面Settings → Secrets and variables → Actions → Variables在该页面新增或修改变量后变更会在下一个读取该变量的 workflow 运行时自动生效——这正是无需代码变更的核心收益运维人员改值、开发者不动 YAMLCI 行为即随之改变。注意仓库级变量Repository Variables与 Secrets 是两套独立体系。本文讨论的变量均为非敏感配置路径、版本号、域名通过vars.*读取而CLOUDFLARE_API_TOKEN等凭据则通过secrets.*读取见 staffml-publish-live.yml 的 D1 同步步骤。已定义变量总览四类清单以下四个表格为当前仓库中实际存储的变量值均可在 workflow 中找到对应引用。项目源码根Project source rootsVariableCurrent valueUsed bySTAFFML_ROOTinterviews/staffmlstaffml-publish-live, staffml-preview-dev, staffml-validate-devVAULT_DIRinterviews/vaultstaffml-publish-live, staffml-preview-dev, staffml-validate-dev, staffml-validate-vaultVAULT_CLI_DIRinterviews/vault-clisame as aboveTINYTORCH_ROOTtinytorch(existing — pre-cutover)TINYTORCH_SITEtinytorch/quartotinytorch-publish-liveBOOK_ROOTbook(existing — pre-cutover)BOOK_QUARTObook/quarto(existing — pre-cutover)MLSYSIM_ROOTmlsysimmlsysim-publish-live, mlsysim-preview-devMLSYSIM_DOCSmlsysim/docssame as aboveKITS_ROOTkitskits-publish-liveLABS_ROOTlabslabs-publish-liveINSTRUCTORS_ROOTinstructorsinstructors-publish-live (also hardcoded asinstructorsin some places)这些根路径不仅用于working-directory和run命令还深度参与了 checkout 环节。例如 staffml-validate-dev.yml 的稀疏检出sparse-checkout就依次列出${{ env.STAFFML_ROOT }}、${{ env.VAULT_DIR }}、${{ env.VAULT_CLI_DIR }}与design-grammar——design-grammar之所以必须检出是因为 StaffML 的prebuild钩子会执行scripts/sync-design-grammar.mjs读取根目录的design-grammar/grammar.yml缺少它会直接 ENOENT 失败。这是一个变量背后连带一整套构建依赖的典型例子。部署路径gh-pages 子路径VariableCurrent valueUsed byDEV_STAFFML_PATHstaffmlstaffml-publish-live, staffml-preview-devDEV_TINYTORCH_PATHtinytorch(existing)DEV_KITS_PATHkitskits-publish-liveDEV_LABS_PATHlabslabs-publish-liveDEV_MLSYSIM_PATHmlsysimmlsysim-publish-liveDEV_INSTRUCTORS_PATHinstructorsinstructors-publish-liveDEV_SLIDES_PATHslidesslides-publish-liveVOL1_DEPLOY_PATHvol1book-publish-liveVOL2_DEPLOY_PATHvol2book-publish-live这类变量决定站点部署到gh-pages分支的哪个子目录最终 URL 形如https://domain/deploy-path/。实际消费方式可从 staffml-publish-live.yml 看到peaceiris/actions-gh-pagesv4的destination_dir: ${{ env.DEV_STAFFML_PATH }}决定 gh-pages 中的落点同时NEXT_PUBLIC_BASE_PATH: /${{ env.DEV_STAFFML_PATH }}让 Next.js 静态导出带上正确的 base path。Book 的VOL1_DEPLOY_PATH/VOL2_DEPLOY_PATH在 book-publish-live.yml 中被明确注释为同时被 book-preview-dev.yml 读取确保 dev 与 live 上/vol1/、/vol2/的 URL 完全一致——即 preview 与 live 共用同一组部署路径变量避免出现preview 能打开、live 404的路径漂移。跨项目版本与 URLCross-cutting versions and URLsVariableCurrent valueUsed byWhy centralizeNODE_VERSION2020 workflowsCoordinated Node upgradesPYTHON_VERSION3.1220 workflowsCoordinated Python upgrades.Note:mlsysim is pinned at3.11separately (intentional — keeps mlsysim hash-stable). Dont change without verifying the Merkle hash.PRODUCTION_DOMAINhttps://mlsysbook.aiFunctional URLs in env vars canonical href in deployed HTMLDomain renames stay in one placeSTAFFML_VAULT_WORKER_URLhttps://staffml-vault.mlsysbook-ai-account.workers.devstaffml-publish-live, staffml-preview-devWorker rename / migration这一组变量体现了中心化收益最大的场景运行时版本统一升级NODE_VERSION20、PYTHON_VERSION3.12被 20 个 workflow 共享实测 grep 结果vars.NODE_VERSION出现在 7 个文件vars.PYTHON_VERSION出现在 24 个文件要协调一次 Node/Python 升级只需改一个变量。域名与 Worker 迁移PRODUCTION_DOMAIN被用于两个关键位置——staffml-publish-live.yml 中拼接NEXT_PUBLIC_ANALYTICS_URL、NEXT_PUBLIC_INTERVIEWER_ENDPOINT同源 Worker 端点避免 CORS 预检以及 redirect 页的link relcanonicalSTAFFML_VAULT_WORKER_URL则作为NEXT_PUBLIC_VAULT_API的取值。两者合并使得换域名/迁 Worker只需改一处变量。其他既有变量Other / existingVariableCurrent valueBOOK_DEPSbook/tools/dependenciesBOOK_DOCKERbook/dockerBOOK_TOOLSbook/toolsKITS_DOCSkitsLABS_DOCSlabsSLIDES_ROOTslidesTINYTORCH_SRCtinytorch/srcTINYTORCH_TESTStinytorch/testsDEV_REPOharvard-edge/cs249r_book_devDEV_REPO_URLgitgithub.com:harvard-edge/cs249r_book_dev.git这组变量在约定落地前就已存在本文档为完整起见一并登记。其中DEV_REPO_URL在 staffml-preview-dev.yml 中被用于git clone --depth1 ${{ vars.DEV_REPO_URL }}拉取 dev 仓库做对比检查。未 vars 化的部分及其原因约定并非所有字符串都变量化以下五类内容刻意保持硬编码理解这些边界有助于你判断自己的仓库该在哪画线paths:触发器过滤器workflow 顶部的interviews/staffml/**这类路径列表无法变量化——GitHub Actions 在workflow 加载时、变量解析之前就评估触发器。若重命名项目根目录必须手工更新触发器过滤器这也是这些文件里唯一需要手工编辑的部分staffml-validate-dev.yml 中可看到硬编码的paths:列表。注释与日志字符串如echo Site: https://...这类 step summary 输出保留字面值因为字面量在 CI 日志中更容易 grep 与阅读只有真正进入生产 HTML 的功能性位置才 vars 化。run:块中的内联 Python heredoc大多数通过 shell 环境变量引用路径如os.environ[STAFFML_ROOT]见 staffml-publish-live.yml 的 manifest 生成步骤env 由 job 的env:块流入少数短小的 heredoc 为可读性保留字面路径因为它们只在 workflow runner 内部执行。mlsysim 的python-version: 3.11刻意硬编码。原因是 mlsysim 的 Merkle 哈希输出对 Python 版本敏感Tier A 的release_hash是引用锚点若用通用的vars.PYTHON_VERSION升级到 3.12 会在不经意间使哈希等价性失效。实测 mlsysim-publish-live.yml 为python-version: 3.11而其 validate workflow 用的是3.12这印证了同一项目内不同环节可刻意使用不同版本的精细控制。interviews/staffml-vault-worker/、interviews/paper/它们是interviews/下的同级顶层项目不是STAFFML_ROOT的子路径。重命名STAFFML_ROOT不应级联影响到它们因此保持字面值staffml-publish-live.yml 的 Worker 部署步骤即用字面路径interviews/staffml-vault-worker。此外staffml-publish-live.yml 与 staffml-validate-dev.yml 中还有一处局部的版本例外Worker 构建使用硬编码NODE_VERSION: 22因为 wrangler 要求 Node ≥ 22而共享变量仍保持 20 以让其余 workflow 留在旧 LTS。这说明变量体系允许共享默认 局部覆盖的混合策略。新增一个变量的五步流程当某个值在 3 个以上 workflow 文件中重复出现时就达到了 vars 化的门槛识别找出跨 3 个 workflow 文件重复的值。命名采用UPPER_SNAKE_CASE项目专属值必须带项目前缀STAFFML_ROOT而不是ROOT。设置用ghCLI 写入仓库级变量gh variable set MY_NEW_VAR -R harvard-edge/cs249r_book \ --body the/value替换更新 workflow 为${{ vars.MY_NEW_VAR || the/value }}并确保 fallback 与当前变量值完全一致——这样即使变量被删除workflow 依然可运行。登记向 docs/CI-VARIABLES.md 添加一条记录保持文档与实际情况同步。第 4 步的 fallback 同步是可运行性的关键fork 仓库不会自动继承原仓库的变量fallback 就是 fork 与新克隆环境的第一道保险。修改变量含目录重命名的完整流程假设要将interviews/staffml迁移到新位置标准操作顺序如下在源码树中重命名目录。更新仓库 Settings → Variables 中的值或gh variable set NAME --body newvalue。同步更新每个 workflow 中的fallback${{ vars.X || fallback }}中的字符串保证 fork 与首次克隆仍可运行。手工更新所有paths:触发器过滤器它们读不到变量只能手改。更新本文档 docs/CI-VARIABLES.md。其中前三步是主体工作一旦目录移动完成仅凭第 2 步的变量变更即可让所有 CI 运行成功无需改动任何 workflow 代码——这正是中心化设计的核心价值。审计与排查命令运维中需要回答当前设了哪些变量和某个变量被谁引用两个问题# 查看当前设置的所有仓库级变量 gh variable list -R harvard-edge/cs249r_book # 查看某个变量在 workflow 中的所有引用位置 git grep vars\.STAFFML_ROOT .github/gh variable list直接列出 Settings 中的真实状态git grep则以代码库为索引反向追踪引用点两者结合可以快速发现变量已设但无人引用或代码中仍在使用字面值的漂移。与发布版本体系的协同CI 变量体系与仓库的发布版本化约定详见 docs/VERSIONING.md是同一套单一事实来源理念的两个侧面变量统一管理路径、版本号与域名版本化约定统一管理release_id、tag 与 release-manifest.json。例如 staffml-publish-live.yml 在部署前调用emit_manifest()生成规范形态的release-manifest.json到out/目录使所有 MLSysBook 站点共享统一的https://domain/project/release-manifest.jsonURL其中PRODUCTION_DOMAIN变量决定了该 URL 的域名前缀。因此变量的变更审计gh variable list与版本验证curlmanifest、比对releaseHash共同构成了发布可信度保障。最佳实践小结从这套约定中可以提炼出四条可直接复用的经验双写兜底所有vars.*引用必须带|| fallbackfallback 与当前值保持一致确保 fork/删变量场景下 CI 不中断。按类划分边界源码根、部署路径、跨项目版本/URL、历史遗留变量四类分表管理文档与代码互为镜像。明确不变量化清单触发器过滤器、日志字符串、内联 heredoc、对哈希敏感的版本固定、兄弟项目路径——这些刻意保持硬编码避免过度抽象。变更流程化新增/重命名都走改变量 → 同步 fallback → 手改 paths 触发器 → 更新文档的固定顺序把人为疏漏降到最低。对任何维护多项目单仓库的团队而言这套Settings 一处改、全仓 workflow 自动跟随的变量约定是降低 CI 维护成本的成熟范本。【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考