safe-push

安全推送

针对 GitHub 仓库的推送前卫生检查。用户要求推送代码时使用，尤其是推送到公开仓库时。

触发条件

当用户说“推送”“安全推送”“推送到 GitHub”，或运行 /safe-push 时。

安装

此技能会从 ~/.claude/safe-push-blocklist 加载模式。复制随附的模板并根据需要自定义：

cp safe-push-blocklist.template ~/.claude/safe-push-blocklist
$EDITOR ~/.claude/safe-push-blocklist

模板中包含客户端名称、主机名、IP 范围、跟踪 ID 和 Slack 令牌格式的注释示例。请替换为适用于你环境的值。

如果文件不存在，此技能会发出警告并继续运行，而不会报错；但个人模式检查会被跳过，因此强烈建议创建该文件。

操作步骤

1. 对仓库分类

# Check if public repo
git remote -v
# Check for .public-repo marker
test -f .public-repo && echo "PUBLIC" || echo "private or unmarked"

如果是公开仓库（或推送到公开远程仓库）：执行以下所有检查。 如果是私有仓库：仅执行 PII 扫描（步骤 2）。

2. PII 和机密扫描

从 ~/.claude/safe-push-blocklist 加载你的个人模式列表并据此扫描。同一组模式会同时应用于差异内容（步骤 2）和提交消息（步骤 3）——两者都以同一个真实来源为准。

默认模式——根据目标分支扫描差异内容：

# Load personal patterns (graceful fallback if file missing):
if [ -f ~/.claude/safe-push-blocklist ]; then
  PATTERNS=$(grep -v '^#' ~/.claude/safe-push-blocklist | grep -v '^$' | paste -sd '|' -)
else
  PATTERNS=""
  echo "WARNING: ~/.claude/safe-push-blocklist not found. Personal pattern checks skipped."
fi

git diff origin/main...HEAD
[ -n "$PATTERNS" ] && git diff origin/main...HEAD | grep -nE "$PATTERNS" \
  || echo "NO MATCHES IN DIFF"

完整仓库模式（/safe-push --full）——扫描所有已跟踪文件，而不只是差异内容。可用于基线审计、首次推送已有仓库，或定期卫生检查：

git ls-files | xargs grep -n -E "$PATTERNS" \
  --include='*.md' --include='*.py' --include='*.js' --include='*.ts' \
  --include='*.html' --include='*.sh' --include='*.json' \
  --include='*.yml' --include='*.yaml'

检查以下类别（~/.claude/safe-push-blocklist 涵盖可用正则表达式匹配的类别）：

• 客户名称或内部项目代号
• 个人基础设施：主机名、内部目录名称、设备 ID、硬件型号、自托管服务名称
• 电子邮件地址（个人或客户）、电话号码、地址
• API 密钥、令牌、机密（AWS、GitHub、Slack、Telegram、通用类型）
• 私有 IP 地址、内部主机名
• 私钥材料
• Slack 令牌（xoxb-）、Slack 频道 ID
• 跟踪 ID：GA4（G-XXXXXXXXXX）、GTM（GTM-XXXXXXX）

编辑 ~/.claude/safe-push-blocklist 以维护你的个人模式。切勿在此技能文件中硬编码真实客户名称或基础设施标识符——模式阻止列表才是唯一可信来源。

如果发现任何问题：

• 列出每项发现的文件、行号和检测到的内容
• 要求用户修复后再继续
• 在问题解决之前，切勿推送

3. 提交消息审查

审查推送范围内每次提交的完整消息，包括主题（标题）和正文（描述）。敏感模式可能出现在其中任一部分：

# Print the full message (subject + body) for every commit:
git log origin/main..HEAD --format="===%h %s===%n%b"

# Programmatically scan the full message text against the same
# blocklist used for diff content (graceful fallback if file missing):
if [ -f ~/.claude/safe-push-blocklist ]; then
  PATTERNS=$(grep -v '^#' ~/.claude/safe-push-blocklist | grep -v '^$' | paste -sd '|' -)
  git log origin/main..HEAD --format="%B" | grep -nE "$PATTERNS" \
    || echo "NO MATCHES IN MESSAGES"
else
  echo "WARNING: ~/.claude/safe-push-blocklist not found. Personal pattern checks skipped on commit messages."
fi

~/.claude/safe-push-blocklist 中用于阻止差异内容（步骤 2）的相同模式，也会阻止提交消息。对标题和正文都应用完整的模式阻止列表，而不只是检查差异内容。对于公开仓库，还要标记：

• 个人信息（电子邮件、电话、地址）——按类别检查，不一定总能通过模式匹配
• 你拥有的私有仓库名称（例如上游开发镜像）——发出软警告，并在推送前询问用户
• 含糊的消息（“fix”“update”“wip”）——建议改写

如果发现问题，请建议使用交互式变基清理提交消息（需用户批准）。

4. 分批推送（速率限制）

为避免触发 GitHub 批量操作／自动化滥用检测：

• 如果只推送一个分支且提交数少于 50：正常推送
• 如果推送多个分支或提交数超过 50：
  • 一次推送一个分支
  • 每次推送分支之间等待 5 秒
  • 对于非常大的推送（100 个以上提交），每 50 个提交分成一批，并在批次之间等待 10 秒
• 如果新建仓库并推送包含多个分支的初始内容：
  • 先推送 main/default 分支
  • 等待 10 秒
  • 其余分支逐个推送，每次间隔 5 秒
• 切勿在公开远程仓库上使用 git push --all 或 git push --mirror，除非采用分批推送

# Example staggered multi-branch push
for branch in main develop feature/foo; do
  git push origin "$branch"
  sleep 5
done

5. 最终确认

执行推送之前，先展示摘要：

• 仓库：名称及公开/私有状态
• 即将推送的分支
• 提交数量
• 推送范围内每个提交的完整提交信息预览（标题和正文）——包括经过 amend 的提交和本次会话中编写的提交
• 步骤 2-4 中的任何警告
• 推送策略（直接或分批）

使用以下内容展示完整提交信息：

git log origin/main..HEAD --format="commit %h%n%n%s%n%n%b%n---"

用户必须在推送前逐条查看并确认这些信息。这样可以发现：

• 原始审查已不再适用的 amend 提交
• 步骤 3 中因 grep 遗漏而未显示的正文内容
• 本次会话中临时编写、未经过内容审查的任何内容

等待用户明确确认后再推送。

6. 推送并验证

推送后：

git push origin <branch>
# Verify
git log origin/<branch> --oneline -5

报告操作成功，并提供远程 URL。

配置文件

• ~/.claude/safe-push-blocklist — 个人模式阻止列表。每行一个正则表达式；注释以 # 开头。每次调用 /safe-push 时都会加载。编辑此文件以添加或移除模式；切勿在此技能文件中硬编码模式。有关设置，请参阅上文的安装。
• 仓库本地的 .pii-allowlist — 每行一个正则表达式，匹配内容会从 PII 扫描中排除（用于允许文档中的示例密钥等误报）。
• 仓库本地的 .commit-msg-blocklist — 此特定仓库的公开提交信息中绝不能出现的词语。

备注

• 此技能不会绕过全局 pre-commit hook——两者会协同工作
• 对于公开/私有仓库分离的项目（开发镜像 → 公开发布）：始终先推送到开发仓库，通过同步脚本同步，然后再安全推送公开仓库
• 如有疑问，将仓库视为公开仓库