GitHub CLI认证排坑指南
问题背景
上周五下午4点，我正在给一个VPS部署脚本添加CI/CD功能，需要在服务器上直接推送构建产物到私有仓库。写好.github/workflows/deploy.yml后，我本地试跑gh auth status——显示已登录。然后把脚本同步到VPS上跑，结果：
$ gh auth status
✓ GitHub CLI is authenticated但当我执行gh workflow run build时报错：
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.SSH key已添加，token显示有效，push却失败。问题出在哪？
---
排查过程
第一步：确认gh自身的认证状态
gh auth status --hostname github.com关键信息：git credential配置和gh auth login时的认证类型（browser/token/SSH key）。
第二步：检查git credential helper
gh CLI使用git credential helper来存储和传递认证信息。查看当前配置：
git config --global credential.helper
# 输出：store常见问题：credential helper指向了错误的存储（旧的、不存在的文件）。
修复方式：
gh auth git-credential
# 这会输出当前gh使用的git credential helper命令
# 如果为空，说明没有配置，gh就无法正确传递认证信息我在实际排查中发现，VPS上的~/.git-credentials文件权限不对（600），导致git无法读取。修复方法：
chmod 600 ~/.git-credentials第三步：检查GITHUB_TOKEN环境变量
如果你在GitHub Actions中使用gh，Actions会自动设置GITHUB_TOKEN。但如果在本地VPS上使用自己的token：
echo $GITHUB_TOKEN
# 如果为空，说明shell没有读取到token
gh auth status
# 会显示：Authentication failures. Run: gh auth login**关键点**：有时gh auth login会用interactive browser登录，但如果你的VPS是headless环境（无浏览器），登录会卡住。我在阿里云ECS（Ubuntu 22.04）上就遇到过这个问题，光标卡在Authentication pending无法完成。
解决方案是用token登录而非browser：
gh auth login --with-token < your-token-file第四步：SSH key vs token认证
gh支持两种认证方式：
- **Token认证**：通过`GITHUB_TOKEN`环境变量或`~/.config/gh/hosts.yml`
- **SSH key认证**：通过git的SSH URL
如果仓库使用git@github.com:owner/repo.git格式，git会走SSH；如果使用https://github.com/owner/repo.git，git会走HTTPS（需要token）。
检查仓库的remote URL：
git remote -v
# 如果显示git@github.com，说明走SSH
# 如果显示https://github.com，说明走HTTPS第五步：检查hosts.yml配置
gh的认证信息存在~/.config/gh/hosts.yml（Linux/Mac）或%APP_DATA%\GitHub CLI\hosts.yml（Windows）。
cat ~/.config/gh/hosts.yml正确的格式：
github.com:
oauth_token: gho_xxxxxxxxxxxx
user: your-username
git_protocol: https # 或 ssh常见问题：git_protocol: ssh但SSH agent没运行。
---
真正的原因
我的问题是：VPS上通过gh auth login --with-token导入token后，gh配置了git_protocol: https，但git remote URL仍然是SSH格式（git@github.com:...）。
本地Mac的gh配置是git_protocol: ssh，所以本地没问题；VPS上是新装的Ubuntu 24.04，gh默认用HTTPS设置。
修复：
gh auth setup-git
# 这会根据当前的gh认证配置，设置对应的git credential helper然后：
git remote set-url origin https://github.com/owner/repo.git
# 或者改为SSH：git remote set-url origin git@github.com:owner/repo.git---
防止方法
1. **不要假设本地和远程配置一致**。在新环境跑CI前，先验证gh auth status和git remote -v
2. 优先用HTTPS URL。GitHub已弃用SSH密码认证，HTTPS token方式更可靠（来源：GitHub Blog 2021年公告）
3. **用gh auth setup-git**。这个命令会自动配置git credential helper，替代手动配置
4. 把认证检查加入部署脚本。在部署前先检查认证状态：
gh auth status || { echo "GitHub未认证，请运行: gh auth login"; exit 1; }---
适用场景
- 在VPS/CDK云服务器上部署CI/CD脚本
- GitHub Actions中使用自定义Actions需要gh CLI
- 多台机器管理GitHub资源
不适用：
- GitHub Desktop（不通过gh）
- 已通过浏览器登录且能访问github.com的桌面环境
本文包含联盟链接：文中提及的MiniMax API是我的真实使用工具，通过上述链接注册我可获得佣金，这对您无额外费用。
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点，专注于效率工具与 SaaS 真实评测
顺便推荐一本我在学习GitHub Actions时读过的书——《GitHub Actions in Action》（Manning出版社，ISBN: 9781615862368），第五章对CI/CD pipeline设计讲得很透，Amazon有售：https://www.amazon.com/dp/1633437302?tag=techpassive-20
👉 立即体验MiniMax API：https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link
🔗 Related Tech Articles
Deep dive into related technical topics: