git-push-to-github

name	git-push-to-github
description	Safely commits intended local changes and pushes them to a GitHub branch. 当用户明确要求提交并推送代码到 GitHub 时调用。

Git Push to GitHub

Use this skill when

• 用户明确要求提交并推送本地代码到 GitHub。
• 用户明确指定要更新的远程分支。
• 用户要求把已经完成的提交同步到 GitHub。

不要用于只读状态查询、回滚、强制推送或未经授权的分支合并。

Inputs

• repo_path: 仓库路径，默认当前目录。
• remote: 远程名称，默认 origin。
• branch: 目标分支，默认当前分支；不要擅自假定为 main。
• commit_message: 可选提交说明；未提供时根据本次明确范围内的变更生成简短中文说明。
• paths: 本次允许暂存的文件路径；应从任务范围和 git status 中明确得出。
• scope: 提交范围，可选值为 task、all-worktree 或 existing-commits-only，默认 task。即使选择 all-worktree，仍必须排除敏感信息、缓存和构建产物。

Outputs

• success: 是否完成。
• branch: 实际推送的目标分支。
• commit_hash: 推送后的提交哈希。
• commit_message: 提交说明。
• push_result: 推送与远程校验结果。
• error_message: 失败原因及安全的下一步建议。

Safe workflow

1. 确认仓库与范围：
   • 运行 git status --short --branch、git remote、git branch -vv，并确认当前不是 detached HEAD。
   • 可读取远程 URL 以确认目标，但对外展示或报告错误前必须移除 URL 中的用户名、令牌和其他凭据；不要直接输出可能包含凭据的 git remote -v 结果。
   • 确认目标远程和目标分支与用户要求一致。
   • 工作区包含无关或来源不明的改动时，保留它们且不要暂存；无法隔离时停止并说明。
   • 当前分支与目标分支不一致时停止并请求确认；不要默认切换分支、合并或 cherry-pick。
2. 获取远程状态：
   • 运行 git fetch <remote> --prune。
   • 使用 git rev-list --left-right --count HEAD...<remote>/<branch> 判断分叉：
     • 远端不存在：只有用户明确允许创建新远程分支时才继续。
     • 本地与远端一致，或本地单纯领先：可以继续。
     • 本地单纯落后且工作区干净：可以先执行 git pull --ff-only <remote> <branch>；工作区不干净时停止，不自动 stash。
     • 本地与远端均有独立提交：停止并报告分叉，不自动 merge、rebase 或 cherry-pick。
3. 暂存与审查：
   • 只运行 git add -- <明确文件路径...>，禁止无条件使用 git add .、git add -A。
   • 用 git diff --cached --check 和 git diff --cached --stat 检查暂存内容。
   • 检查 .env、证书、私钥、凭据、数据库、日志、构建缓存和临时文件是否被意外纳入。
   • 检查大文件；GitHub 单文件达到 100 MB 时停止，可能需要 Git LFS 的文件先向用户说明。
   • 仓库已配置可信的敏感信息扫描器时运行它；扫描结果不得输出疑似密钥的完整内容。
4. 验证：
   • 先读取并遵守仓库中的 AGENTS.md、CONTRIBUTING.md 或等效项目规范。
   • 运行与改动风险相匹配的测试、类型检查、Lint 或构建。
   • 验证失败时不要提交或推送；报告失败并保留现场。
5. 提交：
   • 仅在存在已暂存变更时执行 git commit -m "<说明>"。
   • 若改动已经提交，复用现有提交，不创建空提交。
   • 不使用 --no-verify 绕过 Git Hooks。
   • 提交后运行 git status --porcelain 和 git show --stat --oneline HEAD；若 Hook 或工具产生新改动，明确说明并重新确认范围。
6. 推送前复核：
   • 再次运行 git fetch <remote>，防止验证和提交期间远端已发生变化。
   • 确认 <remote>/<branch> 仍是 HEAD 的祖先；若远端出现新的独立提交，停止并报告，不在此阶段执行 pull、merge 或 rebase。
7. 推送：
   • 使用 git push <remote> HEAD:<branch>。
   • 禁止 --force、--force-with-lease，除非用户在了解风险后单独明确授权。
8. 远程校验：
   • 再次 git fetch <remote>。
   • 确认 git rev-parse HEAD 与 git rev-parse <remote>/<branch> 一致。
   • 再次运行 git status --porcelain，不得把仍有未提交改动的状态描述为“工作区干净”。
   • 输出分支、提交哈希、提交说明、验证结果和剩余工作区状态。

Failure handling

• 非 Git 仓库或远程缺失：停止并报告；未经确认不要初始化仓库或新增远程。
• 身份缺失：报告缺失项；不要自行设置 user.name 或 user.email。
• Detached HEAD 或分支不一致：停止并报告；未经确认不要切换分支或移动提交。
• 远程领先或非快进：先 fetch 并展示分叉计数；默认停止，只有用户明确选择后才使用 rebase、merge 或 cherry-pick。
• 认证或权限失败：对 GitHub 错误中的 URL、用户名和凭据脱敏后再报告，建议用户检查凭据和仓库权限。
• Git Hook 失败：保留 Hook 输出和现场，不使用 --no-verify 绕过。
• 网络、HTTP/2、SSL、SSH 失败：先执行只读诊断；不要自动修改远程 URL、/etc/hosts、SSH 配置或全局 Git 配置。
• 推送后连接中断：先 fetch 并比较远程提交，确认是否其实已经成功，避免重复操作。

Security and repository hygiene

• 不读取或输出令牌、私钥、密码和凭据内容。
• 不关闭 SSL 校验，不修改全局 Git 配置。
• 不使用破坏性命令，例如 git reset --hard、git clean -fd 或强制推送。
• 不覆盖用户已有改动；所有暂存文件都必须属于当前任务范围。
• 不自动 stash、切换分支、merge、rebase 或 cherry-pick。
• 修改远程地址、本地身份、代理、SSH 或系统网络配置前必须取得用户确认。

---