解决 GitLab Token 轮换后 SourceTree 认证失败问题

问题描述

在 GitLab 中更新个人访问令牌 (Personal Access Token) 后，虽然已经在配置中使用了新令牌，但 SourceTree 执行 git pull 操作时仍然报错：

remote: HTTP Basic: Access denied. If a password was provided for Git authentication, 
the password was incorrect or you're required to use a token instead of a password.
fatal: Authentication failed for 'https://your-gitlab-domain.com/your-repo.git/'

问题根源

这个问题的根本原因是凭证缓存。虽然你已经生成了新的 GitLab 访问令牌，但以下位置可能仍然缓存着旧的凭证：

• 系统凭证管理器（Windows 凭据管理器或 macOS 钥匙串）
• Git 的配置缓存
• SourceTree 的内部缓存

解决方案

方法一：更新远程仓库 URL（推荐）

最直接的方法是在远程仓库 URL 中直接嵌入新的访问令牌。

1. 检查当前远程仓库地址：

git remote -v

2. 更新远程仓库 URL：

# 使用 oauth2 作为用户名
git remote set-url origin https://oauth2:你的新令牌@your-gitlab-domain.com/your-repo-path.git

# 或者使用 git 作为用户名（某些 GitLab 配置）
git remote set-url origin https://git:你的新令牌@your-gitlab-domain.com/your-repo-path.git

方法二：清理系统凭证缓存

Windows 系统

1. 打开控制面板 → 凭据管理器
2. 选择 Windows 凭据
3. 在普通凭据中查找与你的 GitLab 域名相关的凭据
4. 选择并删除这些凭据

macOS 系统

1. 打开钥匙串访问 (keychain access)应用
2. 在搜索框中输入你的 GitLab 服务器域名
3. 找到相关的"互联网密码"条目
4. 右键选择删除

方法三：在 SourceTree 中重新配置

如果上述方法无效，可以尝试在 SourceTree 中重新配置仓库：

1. 在 SourceTree 的仓库列表中右键选择问题仓库
2. 选择移除（注意：这不会删除本地文件）
3. 通过 文件 → 新建/克隆 重新添加仓库
4. 使用包含新令牌的 HTTPS URL 地址

方法四：检查令牌权限

确保新的个人访问令牌具有足够的权限：

• ✅ read_repository - 读取仓库内容
• ✅ write_repository - 写入仓库内容（如需推送）
• ✅ 根据需求选择其他相应权限

在 GitLab 中检查路径：Preferences → Access Tokens

验证解决

完成上述任一方法后，在 SourceTree 中重新执行 git pull 操作：

git pull origin main

如果配置正确，现在应该能够成功拉取代码而不再出现认证错误。

预防措施

1. 定期轮换令牌：按照安全最佳实践定期更新访问令牌
2. 使用 SSH 替代：考虑使用 SSH 密钥认证，避免频繁的令牌管理
3. 最小权限原则：只为令牌分配必要的最小权限
4. 文档记录：记录令牌的过期时间和权限范围

总结

GitLab 令牌轮换后的认证问题通常是由于系统或应用程序缓存了旧凭证所致。通过更新远程 URL、清理系统凭证或在 SourceTree 中重新配置仓库，可以有效地解决这一问题。