genesis-cicd

genesis-cicd

向 genesis monorepo 添加一个 .github/workflows/ci.yml。reference.md 中提供 Railway 和 Overwatcher 模板；Kubernetes 使用 kubernetes.md 中的配置，并依赖外部 lwlee2608/release-manifest actions。

• Kubernetes：changes -> resolve 之后，独立的 server -> build-server-image 和 web -> build-web-image 路径在 publish -> deploy 汇合。
• Overwatcher：changes 之后，server -> build-server-image 和 web -> build-web-image 两条路径彼此独立；外部部署要求两个构建都成功。
• Railway：changes -> server/web。

问题流程

1. 先阅读参数。 railway/kubernetes/overwatcher 是 CD 目标；main-prod/release-prod 是分支模型；sticky-disk 表示选择 Blacksmith 付费 Docker 缓存。只询问缺少的信息。
2. 在一次 AskUserQuestion 调用中询问其余问题：
   • CD 目标：railway (Recommended) | kubernetes | overwatcher（运行 Docker Compose 的 VM，由 Overwatcher GitHub App 部署）
   • 分支模型：main = production (Recommended) | main = staging, release = production
   • Docker 层缓存，仅适用于 kubernetes/overwatcher：GitHub Actions cache (Recommended) — 免费 | Blacksmith sticky disk — $0.50/GB/月，还会保留 RUN --mount=type=cache
3. 写入前解决目标的前置条件。 对于 Kubernetes，检查 chart 并收集缺失的 GCP 项目、集群位置、命名空间、发布名称和环境值文件路径。要求 chart 支持完整的摘要引用，而不是仅按标签构建镜像。如果缺少 chart，则停止并询问是将其作为单独的前置任务创建，还是选择其他目标。验证 lwlee2608/release-manifest 是否有已发布的 commit，并将两个 actions 都固定到该版本；在该版本可用之前，报告依赖阻塞问题，不要编造版本。生成的工作流中不得留下部署占位符。
4. 用一句话确认，然后写入。 示例：“kubernetes，main→staging / release→prod，GCR，GHA 缓存——继续吗？”

规则

1. 先阅读目标项目。 确认服务目录名称、服务端 Makefile 中的 make test，以及 web 中的 packageManager: pnpm@… 和 pnpm-lock.yaml。将 pnpm/action-setup 的 package_json_file 设为服务本地文件；defaults.run.working-directory 不会影响 actions。对于 Kubernetes，验证 Chart.yaml、环境值文件，以及两个镜像引用键是否与正在发布的镜像匹配。绝不能留下 project-00。

2. 只用一个工作流文件，通过 needs: 连接作业。 使用 workflow_run 串联第二个工作流会破坏 Actions 图；除非传入 head_sha，否则它会检出默认分支的最新提交，并且同一提交的 push 和 PR 运行都会触发。

   只取消已被取代的 PR 运行。为 push 运行设置不同的并发组，避免无关的 push 取消或挤掉待处理的相关构建。按发布轨道串行执行 Kubernetes 发布，并按部署目标串行执行 Helm 作业，同时不取消正在运行的作业。每个轨道由一个发布工作流负责，因为 github.run_number 的作用域是工作流。发布和部署是独立操作；该 action 不保证部署顺序。

3. 每个服务一个测试作业。 对于 Railway/Overwatcher 和 Kubernetes PR，通过 changes（dorny/paths-filter）筛选测试套件。为其授予 contents: read 和 pull-requests: read 权限；使用 base: ${{ github.ref }}。服务变更会运行对应测试套件；ci.yml 变更会运行两者。在这些作业的筛选器中排除文档，不要在工作流触发条件中排除：同时使用 paths: 和 paths-ignore: 可能导致必需的 PR 检查一直处于待处理状态。changes 还会报告部署相关性；包含实际的 chart/值文件路径和共享输入。对于 Kubernetes push，则测试 resolve 请求的每个镜像，包括构建失败后尚未发布的变更。显式的作业状态门控必须允许在有意跳过 resolve 时运行 PR 测试。

4. 仅在相关且前置条件成功时才允许下游工作，不要仅依据测试是否跳过来判断。 Overwatcher 会在变更相关时构建两个镜像，或在每次发布推送时构建；构建分别在独立的 build-server-image 和 build-web-image 作业中进行。每个作业只依赖 changes 和自身的测试套件（服务器作业还可选依赖 store）；保留基础相关性判断和发布测试跳过策略。测试套件或镜像构建失败不会阻止另一条镜像路径，但外部部署要求两个镜像作业都成功。Kubernetes 会在每次符合条件的推送中运行 resolve，将调用方计算的指纹与该轨道已发布的基线进行比较，并且只构建请求的镜像。每个镜像作业都要求解析成功及自身测试套件成功，不受另一个测试套件的影响。publish 要求变更检测和解析成功、存在相关性（请求构建、部署变更或发布推送）、每个已请求的镜像作业成功，以及每个未请求的镜像作业均已跳过。没有请求构建时，两个镜像作业都会跳过；Helm 变更和发布推送仍会发布保留的引用。某个测试套件失败时，另一个镜像可能已推送，但发布会被阻止。可选的 store 测试只控制 build-server-image；publish 通过该构建成功来强制执行此要求。deploy 要求发布成功。绝不允许 PR 发布或部署。

5. 分支模型：

   • main-prod：push: branches: [main] + pull_request。
   • release-prod：push: branches: [main, release] + pull_request。Kubernetes 在 main 上使用 staging，在 release 上使用 production。将 main 合并到 release 后，会自动测试并构建 release 提交中变更的镜像，并部署到 production；未变更的 production 摘要会保留。不添加手动调度、source-release 或 staging 镜像晋级。对于 Railway/Overwatcher，保留基础发布测试策略：只有在确认 main 树受保护且测试成功后才跳过测试；否则，在 release 推送时运行所有测试套件。不要对 release 推送使用路径过滤。

6. CD 目标：

   • railway：不设镜像构建作业，也不设部署作业。Railway 会在推送时根据 Dockerfile 构建；采用 release-prod 时，将其 production 环境指向 release，staging 环境指向 main。分别配置 Wait for CI 和服务监视路径；仅跳过 GitHub 作业不会阻止 Railway 部署。晋级例外情况请参阅参考检查清单。
   • kubernetes：使用完整的 Kubernetes 参考配置，不要使用基础 GHCR 工作流再附加 Helm 步骤。GCR 用于存储镜像；应用仓库中的 GitHub Release 资源用于存储清单。感知轨道的 deploy 作业会使用成功的发布操作所输出的 manifest，通过 Helm 部署两个完整的摘要引用。采用 main-prod 时，main 部署到 production；采用 release-prod 时，main 部署到 staging，release 部署到 production。保留 production 环境门控。
   • overwatcher：镜像推送到 GHCR，不设部署作业。还需按照参考配置编写 docker-compose.prod.yml 和 .env.example；genesis 脚手架没有生产版 compose 文件。使用 overwatcher 技能配置 owctl。将服务的 Workflow 字段设为 ci.yml。Overwatcher 只部署服务分支上成功的运行；镜像作业失败会导致运行失败，而无操作的运行会重新拉取未变更的分支标签。

7. 绝不部署共享的 latest。 Overwatcher 为每个服务部署固定标签，因此 compose 会固定到部署分支的标签；镜像作业仍会推送 SHA 标签，以便追踪和手动回滚。Kubernetes 只使用唯一的运行/尝试构建标签进行推送，随后记录并部署 repository@sha256:...。指纹涵盖完整的服务上下文、工作流以及所有构建输入/参数。服务器的 COMMIT_SHA 使用稳定的构建输入提交，并将其纳入指纹，而不是使用当前无关的工作流 SHA。整个上下文中的文档可能触发重建；构建输入之外的根目录文档不会触发重建。不要将已弃用的 Python 发布管理器复制到生成的项目中。

8. Blacksmith runner：server、build-server-image 和两个镜像构建目标中的 build-web-image 使用 blacksmith-4vcpu-ubuntu-2404；其他位置使用 blacksmith-2vcpu-ubuntu-2404。保留上游的 actions/setup-go / actions/setup-node，并启用 cache；Blacksmith 会透明地加速 GitHub 缓存 API，其 useblacksmith/setup-* 封装已弃用。

9. Docker 层缓存：type=gha，每个镜像使用一个 scope，除非用户选择了 sticky-disk。useblacksmith/setup-docker-builder + useblacksmith/build-push-action 会让构建器使用按 GB 计费的 sticky disk；除非用户选择启用，否则绝不要仅为“提速”而添加它们，也不要在同一作业中混用这两种方案。对于 Kubernetes 和 Overwatcher，在每个镜像作业中替换构建器，并使用独立的 sticky 缓存键 <app>-server 和 <app>-web；作业门控使得无需设置按步骤判断所请求镜像的条件。

10. **绝不提交密钥。**GHCR 仅在 build-server-image 和 build-web-image 上使用带有 packages: write 权限的 GITHUB_TOKEN；测试作业保持只读。Kubernetes 仅向 publish 授予 contents: write；解析需要 contents: read。GCR/GKE 需要用户在仓库设置中添加服务账号 JSON。Kubernetes 注册表身份验证作业导出标量摘要，而非 JSON：多行密钥屏蔽可能会抑制 JSON 作业输出。在 publish 的 images 步骤中组装新构建的引用；发布操作会提供保留的引用。

验证流程

1. 运行 actionlint .github/workflows/ci.yml，并配置其允许使用的 Blacksmith 自托管 runner 标签。YAML 解析器只能作为语法检查的后备手段，不能验证 Actions 表达式或依赖关系；如果无法使用 actionlint，请报告。
2. grep -n project-00 .github/workflows/ci.yml 不返回任何结果。
3. 在本地运行相同的步骤：go vet ./... && make test；pnpm install --frozen-lockfile && pnpm lint && pnpm build。
4. 验证所选目标的单一作业图。Kubernetes PR 测试必须能在 resolve 被跳过时正常运行；所有写入/部署作业都必须跳过。没有观察到实际运行的 Actions 时，不要声称已完成线上验证。
5. Kubernetes：验证 bootstrap 会构建两个镜像，并且每个镜像都在其自身测试套件结束后立即开始构建，而无需等待另一个镜像。仅更改 server 时保留 web；仅更改 Helm 时跳过两个镜像作业，但 publish/deploy 会使用保留的摘要。构建失败后，后续无关推送会重试尚未发布的更改。健康的、仅更改根目录文档的 main 推送会跳过两个镜像作业，且不会执行 publish/deploy。即使另一个镜像已推送，请求的测试套件或构建失败/取消也会阻止发布。检查标量摘要输出和 publish 端的 JSON 组装、带有独立镜像缓存的两种缓存方案，以及仅阻止 server 构建和发布的可选 store 门控。
6. Kubernetes release-prod：将 main 合并到 release 后，会自动使用生产基线、测试/构建 release 分支请求的镜像，并部署两个已发布的摘要。在 kubernetes.md 中验证无需构建新镜像的发布路径，以及发布/Helm 失败后的恢复流程。
7. Railway/Overwatcher：保留参考配置的行为检查，包括 Overwatcher 的双镜像 SHA 构建，以及外部空操作/部署配置。验证每个镜像都在其自身测试套件结束后立即开始构建，而无需等待另一个镜像；测试套件/构建失败或可选 store 失败不会阻止另一个镜像路径，但会阻止部署。检查 PR/空操作时的跳过行为、故意跳过检查的发布构建，以及各镜像独立的缓存。不要根据 GitHub 作业跳过情况推断外部 CD 行为。

常见错误

• Kubernetes 构建只使用上一次提交的差异——失败构建中的更改会在下一次无关推送后消失；应与已发布的清单进行比较。
• 接受请求的测试被跳过——跳过必须表示有意保留镜像，而不是依赖项失败。
• 在 Kubernetes 中使用当前 SHA 部署两个镜像——未更改的镜像会保留较旧的摘要，而非当前提交的标签。
• 在 PR 上使用工作流级别的 paths: 或 paths-ignore:——必需的 PR 检查不会报告结果，从而阻止合并。
• 将工作流成功视为镜像已发布的证明——无操作和 PR 运行可能在镜像作业被跳过时成功；仅运行 Helm 的 Kubernetes 发布，以及没有新镜像的发布推送，也可能在两个镜像作业都被跳过时发布保留的引用。
• 为 Railway 或 Overwatcher 编写部署作业——两者都会自行部署；Helm/SSH 作业会与它们冲突。
• 对 web 使用 npm ci——它会忽略 pnpm-lock.yaml。
• 让 server 和 web 共用一个 type=gha scope——每次构建都会清除另一方的层。