GitHub 身份验证

使用 git（普遍可用）或 gh CLI 为代理设置 GitHub 身份验证。涵盖 HTTPS 令牌、SSH 密钥、凭据助手和 gh auth — 并提供检测流程以自动选择合适的方法。

技能元数据

来源	捆绑（默认安装）
路径	skills/github/github-auth
版本	1.1.0
作者	Hermes Agent
许可证	MIT
标签	GitHub, Authentication, Git, gh-cli, SSH, Setup
相关技能	github-pr-workflow, github-code-review, github-issues, github-repo-management

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

GitHub 身份验证设置

此技能设置身份验证，以便代理能够处理 GitHub 仓库、PR、问题和 CI。它涵盖两条路径：

• git（始终可用） — 使用 HTTPS 个人访问令牌或 SSH 密钥
• gh CLI（如果已安装） — 通过更简单的身份验证流程提供更丰富的 GitHub API 访问权限

检测流程

当用户要求你处理 GitHub 相关任务时，首先运行此检查：

# Check what's available
git --version
gh --version 2>/dev/null || echo "gh not installed"

# Check if already authenticated
gh auth status 2>/dev/null || echo "gh not authenticated"
git config --global credential.helper 2>/dev/null || echo "no git credential helper"

决策树：

1. 如果 gh auth status 显示已认证 → 一切正常，对所有操作使用 gh
2. 如果已安装 gh 但未认证 → 使用下面的“gh auth”方法
3. 如果未安装 gh → 使用下面的“仅 git”方法（无需 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 以存储令牌

# Set up the credential helper to cache credentials
# "store" saves to ~/.git-credentials in plaintext (simple, persistent)
git config --global credential.helper store

# Now do a test operation that triggers auth — git will prompt for credentials
# Username: <their-github-username>
# Password: <paste the personal access token, NOT their GitHub password>
git ls-remote https://github.com/<their-username>/<any-repo>.git

输入凭据一次后，它们将被保存并用于所有后续操作。

替代方案：缓存助手（凭据从内存中过期）

# Cache in memory for 8 hours (28800 seconds) instead of saving to disk
git config --global credential.helper 'cache --timeout=28800'

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

# Embed token in the remote URL (avoids credential prompts entirely)
git remote set-url origin https://<username>:<token>@github.com/<owner>/<repo>.git

步骤 3：配置 git 身份

# Required for commits — set name and email
git config --global user.name "Their Name"
git config --global user.email "their-email@example.com"

步骤 4：验证

# Test push access (this should work without any prompts now)
git ls-remote https://github.com/<their-username>/<any-repo>.git

# Verify identity
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：如有需要，生成密钥

# Generate an ed25519 key (modern, secure, fast)
ssh-keygen -t ed25519 -C "their-email@example.com" -f ~/.ssh/id_ed25519 -N ""

# Display the public key for them to add to GitHub
cat ~/.ssh/id_ed25519.pub

告知用户在以下位置添加公钥：https://github.com/settings/keys

• 点击“New SSH key”（新建 SSH 密钥）
• 粘贴公钥内容
• 赋予标题，如“hermes-agent-<machine-name>”

步骤 3：测试连接

ssh -T git@github.com
# Expected: "Hi <username>! You've successfully authenticated..."

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

# Rewrite HTTPS GitHub URLs to SSH automatically
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
# Select: GitHub.com
# Select: HTTPS
# Authenticate via browser

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

echo "<THEIR_TOKEN>" | gh auth login --with-token

# Set up git credentials through gh
gh auth setup-git

验证

gh auth status

---

在没有 gh 的情况下使用 GitHub API

当 gh 不可用时，你仍然可以使用带有个人访问令牌的 curl 访问完整的 GitHub API。其他 GitHub 技能正是通过这种方式实现其回退机制的。

为 API 调用设置令牌

# Option 1: Export as env var (preferred — keeps it out of commands)
export GITHUB_TOKEN="<token>"

# Then use in curl calls:
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user

从 Git 凭据中提取令牌

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

# Read from git credential store
grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|'

助手：检测身份验证方法

在任何 GitHub 工作流的开头使用此模式：

# Try gh first, fall back to git + curl
if command -v gh &>/dev/null && gh auth status &>/dev/null; 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 '\n\r')
  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 已禁用密码认证。使用个人访问令牌（Personal Access Token）作为密码，或切换到 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/config 中为每个主机别名使用不同的 SSH 密钥，或使用每个仓库独立的凭据 URL
gh: command not found 且无 sudo 权限	使用上述仅基于 git 的方法 1 — 无需安装