pikasTech-unidesk/.agents/skills/unidesk-cicd/references/git-mirror.md

Git Mirror

Git mirror 是 HWLAB/AgentRun CI/CD 的 source authority 和 GitOps flush 入口。不要回退到 operator host git、目标 host fixed workspace 或第二套 source resolver。

HWLAB Git Mirror

bun scripts/cli.ts hwlab g14 git-mirror status
bun scripts/cli.ts hwlab g14 git-mirror apply [--dry-run|--confirm]
bun scripts/cli.ts hwlab g14 git-mirror sync [--dry-run|--confirm]
bun scripts/cli.ts hwlab g14 git-mirror flush [--dry-run|--confirm]

bun scripts/cli.ts hwlab nodes git-mirror status --node <node> --lane v03
bun scripts/cli.ts hwlab nodes git-mirror sync --node <node> --lane v03 --confirm --wait
bun scripts/cli.ts hwlab nodes git-mirror flush --node <node> --lane v03 --confirm --wait

• apply: 渲染并 apply devops-infra/git-mirror.yaml。
• sync: 把当前配置声明的 GitHub refs 拉入本地 mirror，并为 source branch tip 创建不可变 snapshot ref。
• flush: 把本地 lane GitOps ref 快进推回 GitHub。

PipelineRun gitops-promote 如果报 git mirror 控制面漂移、refs 不一致或 flush/publish 未完成，优先按当前 devops-infra/git-mirror.yaml 收敛：先 git-mirror apply --confirm，再 git-mirror sync --confirm --wait，然后用 control-plane cleanup-runs --pipeline-run <failed-run> --confirm 受控清理失败 PipelineRun 后重试。旧 branch/path allowlist gate 已删除，不要恢复旧 hook、直接 kubectl delete、手工 patch pod 内 hook 或绕过 flush。

手动 trigger closeout 不能只看 PipelineRun Completed。必须继续查 control-plane status --pipeline-run <name> 和 git-mirror status；node-scoped trigger-current --confirm --wait 会自动做必要的 mirror pre/post flush，但 closeout 仍要确认最终 pendingFlush=false、githubInSync=true。如果 lower-level 手工路径或旧 job 留下 pendingFlush=true，执行 git-mirror flush --confirm --wait 到 pendingFlush=false。

trigger-current --node D601|D518|JD01 --lane v03 --confirm --wait 的 source selection 必须走 k8s git-mirror source snapshot：confirmed trigger 先执行受控 git-mirror sync，sync 在 mirror cache 中为本轮 branch tip 创建不可变 refs/unidesk/snapshots/hwlab-node-runtime/<branch>/<commit>，随后 trigger/status/build 只读取该 snapshot ref 作为 authoritative source。旧 source-render / local-git-clone-worktree / 可变 branch ref 追 branch tip 的问题不得再用固定 worktree fetch/pull 修复。

node-scoped lane 可能在本次 PR 合并后又被后续 PR 推进。control-plane status --pipeline-run <name> 是定点观察某个 PipelineRun，但输出里的当前 sourceHead / summary.sourceCommit 可能已经是最新 branch tip。closeout 必须同时记录 PR merge commit、PipelineRun 名称/状态、Argo sync revision、当前 branch tip，并证明最新 tip 包含本次 PR。

D601 SSH Transport

D601/v03 git-mirror 的 GitHub upstream 标准传输固定为 YAML 声明的 SSH：githubTransport.mode=ssh，脚本通过 GIT_SSH wrapper 访问 ssh://git@ssh.github.com:443/...；node-global HTTP proxy 只作为 SSH CONNECT tunnel，不是 GitHub HTTPS auth/token transport。若 CLI 输出 transport=https、GITHUB_TOKEN、git-mirror-github-token 或 HTTPS token sourceRef，按 control-plane drift/配置回归处理：先修 YAML 并执行 hwlab nodes control-plane apply --node D601 --lane v03 --confirm，不要改走 HTTPS、不要增加 fallback、不要用 host workspace repair。

D601/node-scoped mirror status 的 githubGitops 来自本地 mirror cache 的 refs/mirror-stage/...；status 输出应通过 refSources.githubFieldsAreMirrorStageCache=true 显示这一点。flush --confirm --wait 如果已经显示推送成功，但 post-push fetch/recheck 因 GitHub SSH transient 失败导致非零退出，会标记 partialSuccess=push-succeeded-fetch-failed。CLI 应自动做一次受控 sync/recheck；恢复后输出 partialSuccessRecovered=true、postPushRecovery 且整体 ok=true，未恢复时才指向 sync --confirm --wait。