git authentication failed 处理检查清单

这份清单用于处理 git authentication failed。完整解释见 git authentication failed 怎么解决。排查时重点不是收集更多密码，而是确认连接方式、权限范围和客户侧授权。

适合谁

适合遇到 git clone、git fetch、git pull 或 git push 认证失败的新手。你可以按清单逐项填写，避免在 HTTPS、SSH、token、权限之间来回猜。

也适合项目前做初步诊断。客户说“Git 认证失败”时，可能只是远端地址错了，也可能是组织权限限制。先拆清楚，才知道是否能接。

不适合谁

不适合要求客户发送账号密码、私钥或长期 token 的人。客户授权应通过平台完成，敏感凭据不应该出现在聊天记录、源码或交付文档中。

也不适合在不了解客户组织规则时承诺马上修好的人。组织 SSO、二次验证、仓库权限、分支保护都可能影响认证和推送。

风险提醒

认证失败经常和权限有关。权限问题不是靠“多试几次密码”解决的，错误尝试还可能触发平台安全限制。

如果客户仓库涉及私有代码、生产配置、账单或组织权限，把授权步骤写成客户待确认事项。你可以诊断和说明，但不要代管敏感凭据。

具体步骤

1. 保存原始信息

• 完整命令：
• 完整报错：
• 远端地址：
• 当前分支：
• 平台名称：
• 操作系统：

不要只写“认证失败”。不同平台的错误提示会告诉你是 token、SSH、权限还是组织授权问题。

2. 检查远端连接方式

运行：

git remote -v

记录地址是 HTTPS 还是 SSH。HTTPS 和 SSH 的排查路径不同，先分清这一点。

3. HTTPS 检查项

• 是否使用了 token，而不是账户密码。
• token 是否过期。
• token 是否有当前仓库权限。
• 当前凭据管理器里是否缓存了旧账号。
• 远端地址是否指向正确仓库。

如果是客户仓库，token 应由客户侧创建和管理。你可以告诉客户需要什么权限，但不要让客户把长期 token 发给你。

4. SSH 检查项

• 本机是否有 SSH key。
• 公钥是否添加到正确平台账号。
• 当前 key 是否对应有仓库权限的账号。
• SSH 远端地址是否写对。
• 平台是否要求额外组织授权。

可以运行：

ssh -T git@github.com

如果不是 GitHub，把域名换成真实平台。这个命令只能说明 SSH 认证状态，不等于你一定有目标仓库写权限。

5. 权限检查项

• 浏览器是否能打开仓库。
• 是否有 clone 权限。
• 是否有 push 权限。
• 是否只能推新分支。
• 是否必须通过 PR。
• 是否启用了组织 SSO。

如果你没有权限，下一步不是改命令，而是请客户添加协作者、授权组织访问，或确认其他交付方式。

6. 最小验证

认证修复后先运行：

git fetch origin

fetch 成功后，再测试 pull、push 或创建 PR。这样能避免把认证问题和分支冲突混在一起。

最低交付记录

最低记录包含：平台、远端地址类型、报错原文、已检查项目、判断结果、是否需要客户授权、下一步建议。客户看这份记录时，应该能判断问题卡在技术配置还是权限流程。

如果客户需要自己操作，记录要写成具体动作，比如“请在 GitHub 仓库设置里添加协作者”或“请确认当前 token 是否允许访问这个私有仓库”。不要写成含糊的“请给权限”。

撤销与收尾检查

认证问题修好后，还要检查临时权限是否需要撤销。比如客户临时添加了协作者、创建了短期 token、开启了某个组织授权，任务结束时应确认这些权限是否继续保留。新手项目练习时，这一步很容易忘，但它直接关系到客户对你是否信任。

收尾记录可以写三项：本次使用了哪种授权方式、是否接触过敏感凭据、任务结束后建议客户撤销或保留哪些权限。如果你全程没有接收密码、私钥或长期 token，也可以明确写出来。这样客户知道你处理的是诊断和配置，而不是私下保存访问能力。

如果客户后续还需要你维护仓库，建议让客户通过平台协作者权限管理，而不是每次重新发送凭据。长期合作也应该使用可撤销、可审计、范围明确的授权方式。

CTA：下一步

把这份清单复制到你的排查记录里，先填远端地址和连接方式。需要拆报错用 报错解释器，需要写客户确认消息去 模板库。

免责声明

本文是学习和排查流程，不构成法律、安全或职业承诺。令牌、SSH key、私有仓库、组织权限和客户账号授权，需要结合平台规则和客户授权人工判断。