GitHub Safe Sync

此技能适用于镜像上游 GitHub 仓库的仓库，且需保留本地 .github 工作流文件，并配置了 safe-sync.yml 工作流。

前提条件

• 运行脚本前，请设置 GITHUB_TOKEN 环境变量。
• 传入仓库时使用 owner/repo 格式。
• 将 token 视为敏感信息。切勿将其硬编码到技能中，或提交至仓库文件中。

快速开始

检查一个镜像仓库：

export GITHUB_TOKEN=...
./scripts/github_safe_sync.py status 
  --owner grey00758 
  --repo ai-code-board 
  --upstream grey0758/ai-code-board

触发一次手动同步：

export GITHUB_TOKEN=...
./scripts/github_safe_sync.py dispatch 
  --owner grey00758 
  --repo ai-code-board

在工作流修复后清理误报产生的残留产物：

export GITHUB_TOKEN=...
./scripts/github_safe_sync.py close-force-push-issues 
  --owner grey00758 
  --repo ai-code-board

./scripts/github_safe_sync.py delete-backups 
  --owner grey00758 
  --repo ai-code-board

工作流程

1. 使用 status 检查镜像仓库状态。
2. 若工作流处于非活跃状态，或最近一次运行失败，请在触发任何操作前先人工审查该仓库。
3. 若镜像仓库此时应执行同步，请运行 dispatch。
4. 若工作流修复已消除误报的强制推送（force-push）告警，则运行 close-force-push-issues 和 delete-backups。
5. 再次运行 status，确认仓库状态已恢复正常。

status 输出解读

• effective_state=exact：镜像仓库与上游仓库对应分支的 HEAD 完全一致。
• effective_state=metadata-ahead：镜像仓库仅在本地 .github 目录内有额外提交，其余内容与上游一致。此类状态在 safe-sync 镜像仓库中通常属于健康状态。
• effective_state=behind：上游仓库已有更新提交，而镜像仓库尚未同步跟进。
• effective_state=local-ahead：镜像仓库包含若干非元数据类提交（即修改了代码或文档等非 .github 内容），但这些提交在上游仓库中并不存在。请在执行任何强制操作前仔细审查。
• effective_state=metadata-diverged：双方历史记录存在差异，但镜像仓库独有的变更仅限于元数据（如 .github 文件）。这通常意味着同步工作流逻辑仍需进一步审查。
• effective_state=diverged：镜像仓库与上游仓库均发生了互不兼容的变更。除非另有明确证据，否则应视其为真实同步问题。

命令说明

status

请始终优先使用 status。它将返回包含以下字段的 JSON 结果：

• 工作流元数据
• 最近几次工作流运行记录
• 当前打开的强制推送告警 Issue 数量
• backup/ 分支数量
• 可选的上游分支比对结果

若指定的上游分支不存在，脚本将自动回退至上游仓库的默认分支。

dispatch

使用 dispatch 可向同步工作流触发 workflow_dispatch 事件。仅当您明确希望跳过常规的“无操作（no-op）”路径时，才添加 --force-sync 参数。

close-force-push-issues

仅在您已确认相关强制推送告警确属误报后，方可使用该命令。它将关闭所有标题中包含 检测到上游强制推送 的已打开 Issue。

delete-backups

仅在您已确认 backup/ 分支确属冗余噪声后，方可使用该命令。如需预览将被删除的内容，建议先加上 --dry-run 参数执行。

安全准则

• 在确认强制推送告警确属误报之前，不得关闭相关 Issue。
• 在镜像工作流恢复健康、且备份分支已无必要之前，不得删除 backup/ 分支。
• 不要假定默认分支为 main；若仓库使用了其他上游默认分支，请显式传入 --branch 或 --upstream 参数。
• 每次执行写入操作后，均应重新运行 status 进行验证。