github-auth

GitHub 認証の設定

このスキルでは、エージェントが GitHub リポジトリ、PR、イシュー、CI を操作できるように認証を設定します。次の 2 つの方法を説明します。

• 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 "[email protected]"

ステップ 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 "[email protected]" -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」をクリックします
• 公開鍵の内容を貼り付けます
• 「hermes-agent-」のようなタイトルを付けます

ステップ 3：接続をテストする

ssh -T [email protected]
# Expected: "Hi <username>! You've successfully authenticated..."

ステップ 4：GitHub で SSH を使うよう git を設定する

# Rewrite HTTPS GitHub URLs to SSH automatically
git config --global url."[email protected]:".insteadOf "https://github.com/"

ステップ 5：git のユーザー情報を設定する

git config --global user.name "Their Name"
git config --global user.email "[email protected]"

---

方法 2：gh CLI 認証

gh がインストールされている場合は、API アクセスと git の認証情報を一度に設定できます。

インタラクティブなブラウザーログイン（デスクトップ）

落とし穴（Windows でのエージェント駆動セッション）： pty のバックグラウンドプロセスを通じて gh auth login を操作する場合、プロンプトへの応答には process(submit) を使用してください。単独の \n を指定した process(write) は使用しないでください。Windows の PTY（ConPTY/pywinpty）では Enter は復帰文字であり、単独の \n は行終端として送信されません。そのため、gh の「Press Enter to open the browser」というプロンプト（ブロックする行読み取り）が応答しないままとなり、ログインがハングします。また、バックグラウンドセッションからユーザーのデスクトップでブラウザーが開かない場合があります。その場合は、以下のデバイスフローに切り替えてください。

gh auth login
# Select: GitHub.com
# Select: HTTPS
# Authenticate via browser

手動 OAuth デバイスフロー（TTY 不要 — 実証済み）

対話型ログインが実用的でない場合（エージェント駆動のセッション、ブラウザーを起動できない、ヘッドレス環境）のフォールバックです。gh の公開 OAuth クライアント ID を使用し、ユーザーは github.com/login/device でコードを入力するだけです。スコープ：gh auth login --with-token で文書化されている最小要件は repo,read:org,gist です。ワークフローファイルをプッシュする必要がある場合に限り、,workflow を追加してください。

# 1. Request a device code (gh's official client_id)
RESP=$(curl -s -X POST -H "Accept: application/json" \
  -d "client_id=178c6fc778ccc68e1d6a&scope=repo,read:org,gist" \
  https://github.com/login/device/code)
DEVICE_CODE=$(echo "$RESP" | sed 's/.*"device_code":"\([^"]*\)".*/\1/')
USER_CODE=$(echo "$RESP" | sed 's/.*"user_code":"\([^"]*\)".*/\1/')
INTERVAL=$(echo "$RESP" | sed 's/.*"interval":\([0-9]*\).*/\1/'); INTERVAL=${INTERVAL:-5}
echo "Tell the user: go to https://github.com/login/device and enter code: $USER_CODE"

# 2. Poll for the token (respect interval; +5s on slow_down; ~15 min expiry).
#    Run this loop as a background process and show the user the code first.
while true; do
  sleep "$INTERVAL"
  POLL=$(curl -s -X POST -H "Accept: application/json" \
    -d "client_id=178c6fc778ccc68e1d6a&device_code=${DEVICE_CODE}&grant_type=urn:ietf:params:oauth:grant-type:device_code" \
    https://github.com/login/oauth/access_token)
  case "$POLL" in
    *access_token*)
      # Never echo the token; pipe it straight into gh.
      # timeout guards the headless-keyring hang (see pitfall below) —
      # on exit 124, fall back to writing ~/.config/gh/hosts.yml directly.
      echo "$POLL" | sed 's/.*"access_token":"\([^"]*\)".*/\1/' | timeout 20 gh auth login --with-token \
        || { echo "WITH_TOKEN_HUNG_OR_FAILED — use the hosts.yml fallback below"; exit 1; }
      gh auth setup-git
      gh auth status
      echo "LOGIN_COMPLETE"; break ;;
    *authorization_pending*) ;;                      # keep polling
    *slow_down*) INTERVAL=$((INTERVAL + 5)) ;;       # back off per GitHub docs
    *expired_token*) echo "CODE_EXPIRED — restart the flow"; exit 1 ;;
    *access_denied*) echo "USER_DENIED"; exit 1 ;;
    *) echo "UNEXPECTED: $POLL"; exit 1 ;;
  esac
done

注：Windows の winget インストールでは、gh は /c/Program Files/GitHub CLI にインストールされます。同じシェルで PATH に追加してください：export PATH="$PATH:/c/Program Files/GitHub CLI"。

落とし穴（ヘッドレス Linux）：gh auth login --with-token が永久にハングすることがあります。 キーリングのないヘッドレス環境（VPS、コンテナー、dbus セッションなし）では、 gh の認証情報ストレージがシークレットサービスのキーリングを待ち続け、 無期限にブロックされる場合があります。--insecure-storage を指定しても、 出力がないまま発生することがあります。コマンドが約 20 秒以内に戻らない場合 （検出するには timeout 20 … でラップしてください）、gh のログイン処理を 使わず、認証情報ストアに直接書き込んでください：

# $TOKEN = 上記のデバイスフローで取得したアクセストークン（絶対に表示しないこと）
mkdir -p ~/.config/gh
LOGIN=$(curl -s -H "Authorization: token $TOKEN" https://api.github.com/user \
  | sed 's/.*"login": *"\([^"]*\)".*/\1/')
printf 'github.com:\n    users:\n        %s:\n            oauth_token: %s\n    git_protocol: https\n    oauth_token: %s\n    user: %s\n' \
  "$LOGIN" "$TOKEN" "$TOKEN" "$LOGIN" > ~/.config/gh/hosts.yml
chmod 600 ~/.config/gh/hosts.yml
gh auth status          # hosts.yml を直接読み取り、キーリングを使わずに検証します
gh auth setup-git       # git 認証情報ヘルパーを設定します（ハングしません）

gh auth status と setup-git はキーリングに触れずにファイルストアを読み取るため、 すぐに動作します。--with-token が 2 回ハングした後のヘッドレス x86_64 VPS （gh 2.97.0、2026 年 8 月）で実証済みです。

トークンベースのログイン（ヘッドレス／SSH サーバー）

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

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

ここで --with-token がハングする場合は、上記の落とし穴に記載されている hosts.yml のフォールバックを使用してください。

確認

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
uv run python "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py"

ヘルパー：認証方法の検出

あらゆる 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 _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -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=$(uv run python "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py")
  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/config でホストエイリアスごとに異なるキーを使った SSH を使用するか、リポジトリごとの認証情報 URL を使用してください
gh: command not found かつ sudo なし	上記の Git のみを使う方法 1 を使用してください。インストールは不要です