发布与同步#

release.yaml — 构建并发布 wheel 包#

触发条件： 推送匹配 v[0-9]+.[0-9]+.[0-9]+ 格式的标签（仅稳定版发布； dev、rc 等预发布标签不会匹配该规则）。

• build-wheels 在 manylinux_2_28_x86_64 容器内构建 Python wheel 包， 并作为工作流构件（artifact）上传。
• publish 下载该构件，并使用 Trusted Publishing 机制 （通过 id-token: write 实现 OIDC 认证，无需存储 PyPI token）将其发布到 PyPI。

标签命名规则决定了哪些标签会触发该工作流，详见版本管理； 构建细节请参阅打包。

hugo-site.yaml — 构建并发布文档站点#

触发条件： 推送到 gh-pages 分支；coverage 工作流执行完成后触发 （workflow_run）；此外也可通过 workflow_call 被调用（当一个带有 documentation 标签的 PR 被合并时，由 unittest.yaml 中的 build-doc 作业触发），以及手动触发（workflow_dispatch）。

从 docs/ 目录构建 Hugo 站点并发布到 GitHub Pages。concurrency 配置为串行化部署（cancel-in-progress: false），避免多次发布相互抢占、 产生竞态。

sync-docs.yaml — 将文档分支 rebase 到 master#

触发条件： 仅支持 workflow_call（由 unittest.yaml 调用）。

将 gh-pages 分支 rebase 到最新的 master 分支并强制推送，使文档内容 与代码变更保持同步，而不必等待完整的站点重新构建。

auto-sync.yaml — 镜像同步到其他远端#

触发条件： 推送到 master 分支；此外支持手动触发 （workflow_dispatch）。

使用共享的可复用工作流 （flagos-ai/build-infra/.github/workflows/sync-to-remote.yaml），将仓库 镜像同步到 gitcode.com 和 code.gitlink.org.cn，确保项目在国内 Git 托管平台上同样保持可用。

build-deb.yml 与 build-rpm.yml —— 发行版安装包#

触发条件： 推送 v* 标签；针对 master 且改动了 packaging/debian/**（或 packaging/rpm/**）、 packaging/verify-installed-package.py 的 pull_request；此外支持手动触发 （workflow_dispatch）。

与 release.yaml 不同，这两个工作流使用宽泛的 v* 标签匹配，因此预发布 标签也会构建安装包（但不发布，仅作为构件附带）。pull_request 的路径过滤 是有意为之：纯粹的源码 PR 没有 .deb 或 .rpm 的使用方，这类改动由仓库 自身的测试覆盖即可。

两个工作流均在 manylinux_2_28_x86_64 容器内构建安装包，随后把产物安装到 干净的 ubuntu:22.04（.deb）或 fedora:43（.rpm）镜像中运行 packaging/verify-installed-package.py 做冒烟测试。这一步很有必要，因为 安装成功并不代表可用：未加版本约束的 Depends:/Requires: 可能解析到发行版 中过旧的版本，而缺少 __init__.py 的子包会被 find_packages() 静默丢弃。 这两种问题都要到导入时才暴露，而那时 dpkg -l 或 rpm -q 早已显示安装成功。

构件分别以 flag-gems-amd64-packages 和 flag-gems-amd64-rpm-packages 上传，保留 7 天。

upload-nexus.yml —— 上传发布产物到 Nexus#

触发条件： 推送 v* 标签；此外支持手动触发（workflow_dispatch）， 可选输入 run_id（留空则使用最近一次成功的运行）。

它是共享工作流 flagos-ai/build-infra/.github/workflows/upload-nexus.yml@main 的薄调用层，上传逻辑位于共享工作流中。该文件不做任何按仓库的修改，原样放入 每个 FlagOS 组件仓库；组织级密钥通过 secrets: inherit 传递给共享工作流。

其他运维类工作流#

不涉及发布、需要手动触发的工具类工作流 —— probe-node.yaml、 random-test.yaml、review-stats.yaml，以及由评论触发的 fix-sort.yaml —— 统一记录在 定时与按需测试，凡是需要手动启动的 工作流都归那一页。