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。

Node-scoped hwlab nodes control-plane apply --node <node> --lane v03 --confirm 会先执行同一套 YAML-first infra apply 来收敛 git-mirror；git-mirror ConfigMap、proxy、transport 和 Secret 绑定以 config/hwlab-node-control-plane.yaml 为权威。HWLAB source render 产出的 devops-infra/git-mirror.yaml 不是 node-scoped 正式 apply 来源，旧产物漂移时修 infra render 或显式 hwlab nodes control-plane infra apply，不要补 host worktree 或双路径兼容。

cicd branch-follower 已把 sync 和 flush 作为通用 Kubernetes-native stage 接入 HWLAB/AgentRun 自动跟随：trigger 前先 sync 并创建 immutable source snapshot，GitOps publish 后必须 flush，status/closeout 以 mirror cache ref 和 pendingFlush=false/githubInSync=true 为准。正常自动跟随不需要 operator 手动清理旧状态；旧 ConfigMap 或历史 PipelineRun 干扰时只用 cicd branch-follower cleanup-state --follower <id> --confirm 做显式 cleanup。

GitHub/GitHub SSH/HTTPS 相关 egress 必须从 YAML-first host proxy 配置进入 git-mirror Job/Pod：node-scoped lanes 读取 config/hwlab-node-control-plane.yaml#nodes.<NODE>.egressProxy 和 targets.<id>.gitMirror.egressProxy/githubTransport，branch-follower controller 读取 config/cicd-branch-followers.yaml#controller.source.githubSsh。状态和日志应披露 source=yaml、proxy mode、object/key/sourceRef 摘要和 redacted fingerprint，不得依赖未声明的 host env、trans proxy、裸直连 GitHub 或 CLI 输出解析。

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。