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 — 無需安裝