GitHub 认证配置

本技能设置认证，让 agent 可以操作 GitHub 仓库、PR、Issues 和 CI。涵盖两条路径：

• git（始终可用）——使用 HTTPS 个人访问令牌或 SSH 密钥
• gh CLI（如已安装）——更丰富的 GitHub API 访问，认证流程更简单

检测流程

当用户要求你操作 GitHub，先运行此检查：

# 检查可用工具
git --version
gh --version 2>/dev/null || echo "gh not installed"

# 检查是否已认证
gh auth status 2>/dev/null || echo "gh not authenticated"
git config --global credential.helper 2>/dev/null || echo "no git credential helper"

决策树：

• 如果 gh auth status 显示已认证 → 一切就绪，使用 gh 处理所有操作
• 如果 gh 已安装但未认证 → 使用下方"gh auth"方法
• 如果 gh 未安装 → 使用下方"git-only"方法（无需 sudo）

---

方法 1：纯 Git 认证（无 gh，无 sudo）

适用于任何安装了 git 的机器。无需 root 权限。

选项 A：HTTPS + 个人访问令牌（推荐）

这是最通用的方法——任何地方都可用，无需 SSH 配置。

步骤 1：创建个人访问令牌

告诉用户访问：https://github.com/settings/tokens

• 点击"Generate new token (classic)"
• 给它起个名字，如"hermes-agent"
• 选择权限范围：
  • repo（完整仓库访问——读、写、推送、PR）
  • workflow（触发和管理 GitHub Actions）
  • read:org（如需操作组织仓库）
• 设置过期时间（90 天是不错的默认值）
• 复制令牌——不会再显示

步骤 2：配置 git 存储令牌

# 设置凭据辅助器缓存凭据
# "store" 保存到 ~/.git-credentials 明文存储（简单、持久）
git config --global credential.helper store

# 现在做一个触发认证的测试操作——git 会提示输入凭据
# Username: 
# Password: 
git ls-remote https://github.com//.git

输入一次凭据后，它们会被保存并在后续操作中复用。

替代方案：cache 辅助器（凭据在内存中过期）

# 在内存中缓存 8 小时（28800 秒），而不保存到磁盘
git config --global credential.helper 'cache --timeout=28800'

替代方案：直接在 remote URL 中设置令牌（每个仓库）

# 在 remote URL 中嵌入令牌（完全避免凭据提示）
git remote set-url origin https://:@github.com//.git

步骤 3：配置 git 身份

# 提交必需——设置名称和邮箱
git config --global user.name "Their Name"
git config --global user.email "their-email@example.com"

步骤 4：验证

# 测试推送访问（现在应该无需任何提示即可工作）
git ls-remote https://github.com//.git

# 验证身份
git config --global user.name
git config --global user.email

选项 B：SSH 密钥认证

适合偏好 SSH 或已有密钥设置的用户。

步骤 1：检查现有 SSH 密钥

ls -la ~/.ssh/id_*.pub 2>/dev/null || echo "No SSH keys found"

步骤 2：如需要则生成密钥

# 生成 ed25519 密钥（现代、安全、快速）
ssh-keygen -t ed25519 -C "their-email@example.com" -f ~/.ssh/id_ed25519 -N ""

# 显示公钥供用户添加到 GitHub
cat ~/.ssh/id_ed25519.pub

告诉用户在 https://github.com/settings/keys 添加公钥：

• 点击"New SSH key"
• 粘贴公钥内容
• 给它起个标题，如"hermes-agent-"

步骤 3：测试连接

ssh -T git@github.com
# 预期："Hi ! You've successfully authenticated..."

步骤 4：配置 git 对 GitHub 使用 SSH

# 自动将 GitHub HTTPS URL 重写为 SSH
git config --global url."git@github.com:".insteadOf "https://github.com/"

步骤 5：配置 git 身份

git config --global user.name "Their Name"
git config --global user.email "their-email@example.com"

---

方法 2：gh CLI 认证

如果 gh 已安装，它一步搞定 API 访问和 git 凭据。

交互式浏览器登录（桌面）

gh auth login
# 选择：GitHub.com
# 选择：HTTPS
# 通过浏览器认证

基于令牌的登录（无头 / SSH 服务器）

echo "" | gh auth login --with-token

# 通过 gh 设置 git 凭据
gh auth setup-git

验证

gh auth status

---

不使用 gh 调用 GitHub API

当 gh 不可用时，仍可使用 curl 加个人访问令牌访问完整 GitHub API。其他 GitHub 技能的备选方案就是这样实现的。

为 API 调用设置令牌

# 方式 1：导出为环境变量（推荐——保持命令中不出现）
export GITHUB_TOKEN=""

# 然后在 curl 调用中使用：
curl -s -H "Authorization: token $GITHUB_TOKEN" 
  https://api.github.com/user

从 Git 凭据中提取令牌

如果 git 凭据已配置（通过 credential.helper store），可以提取令牌：

# 从 git 凭据存储中读取
grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:([^@]*)@.*|1|'

辅助：检测认证方式

在任何 GitHub 工作流开始时使用此模式：

# 优先尝试 gh，回退到 git + curl
if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
  echo "AUTH_METHOD=gh"
elif [ -n "$GITHUB_TOKEN" ]; then
  echo "AUTH_METHOD=curl"
elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d 'nr')
  echo "AUTH_METHOD=curl"
elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
  export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:([^@]*)@.*|1|')
  echo "AUTH_METHOD=curl"
else
  echo "AUTH_METHOD=none"
  echo "Need to set up authentication first"
fi

---

常见问题

问题	解决方案
git push 要求输入密码	GitHub 已禁用密码认证。使用个人访问令牌作为密码，或切换到 SSH
remote: Permission to X denied	令牌可能缺少 repo 权限——用正确权限重新生成
fatal: Authentication failed	缓存的凭据可能过期——运行 git credential reject 然后重新认证
ssh: connect to host github.com port 22: Connection refused	尝试通过 HTTPS 端口使用 SSH：在 ~/.ssh/config 中添加 Host github.com 并设置 Port 443 和 Hostname ssh.github.com
凭据不持久	检查 git config --global credential.helper——必须是 store 或 cache
多个 GitHub 账号	使用 SSH 并在 ~/.ssh/config 中为不同 host alias 配置不同密钥，或使用每个仓库的凭据 URL
gh: command not found + 无 sudo	使用上方 git-only 方法 1——无需安装