GitHub Auth Setup for Hermes Agent

This skill configures authentication so Hermes Agent can work with GitHub repositories, pull requests, issues, and CI. You would reach for it when the agent needs to push code, open PRs, or query the API, and you want a repeatable setup that works across machines, including headless servers. It covers two paths: git with HTTPS tokens or SSH keys, and the gh CLI when available.

What it does

In practice, this skill walks through a detection flow to see what authentication is already in place, then sets up whichever method fits. The git-only path works anywhere git is installed, with no sudo and no extra tools. The gh CLI path gives richer API access and a simpler login flow, but it depends on gh being present. The skill also includes a fallback for using the GitHub API directly with curl and a token, which is how other GitHub skills operate when gh is missing.

Before you start

You need git installed on the machine. The gh CLI is optional; if it is not installed, the skill falls back to git-only authentication, which requires no sudo. The skill supports Linux, macOS, and Windows. For HTTPS token setup, the user must be able to create a personal access token on GitHub. For SSH, they need to add a public key to their GitHub account. No special permissions are required beyond what the user already has on GitHub.

Detection flow

Run this check first to see what is available and what is already authenticated:

# 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"

Then follow this decision tree:

If gh auth status shows authenticated, you are good, use gh for everything.
If gh is installed but not authenticated, use the "gh auth" method below.
If gh is not installed, use the "git-only" method below, no sudo needed.

Method 1: Git-only authentication (no gh, no sudo)

This works on any machine with git installed. No root access needed.

Option A: HTTPS with personal access token (recommended)

This is the most portable method, works everywhere, no SSH config needed.

Step 1: Create a personal access token

Tell the user to go to: https://github.com/settings/tokens

Click "Generate new token (classic)"
Give it a name like "hermes-agent"
Select scopes:
- repo (full repository access, read, write, push, PRs)
- workflow (trigger and manage GitHub Actions)
- read:org (if working with organization repos)
Set expiration (90 days is a good default)
Copy the token, it won't be shown again

Step 2: Configure git to store the token

# 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

After entering credentials once, they are saved and reused for all future operations.

Alternative: cache helper (credentials expire from memory)

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

Alternative: set the token directly in the remote URL (per-repo)

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

Step 3: Configure git identity

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

Step 4: Verify

# 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

Option B: SSH key authentication

Good for users who prefer SSH or already have keys set up.

Step 1: Check for existing SSH keys

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

Step 2: Generate a key if needed

# 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

Tell the user to add the public key at: https://github.com/settings/keys

Click "New SSH key"
Paste the public key content
Give it a title like "hermes-agent-<machine-name>"

Step 3: Test the connection

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

Step 4: Configure git to use SSH for GitHub

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

Step 5: Configure git identity

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

Method 2: gh CLI authentication

If gh is installed, it handles both API access and git credentials in one step.

Interactive browser login (desktop)

PITFALL (agent-driven sessions on Windows): when driving gh auth login through a pty background process, answer prompts with process(submit), never process(write) with a bare \n. Enter on a Windows PTY (ConPTY/pywinpty) is a carriage return; a lone \n is not delivered as a line terminator, so gh's "Press Enter to open the browser" prompt (a blocking line read) silently never returns and the login hangs. Also note the browser may not open on the user's desktop from a background session, if they report that, fall back to the device flow below.

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

Manual OAuth device flow (no TTY needed, PROVEN)

Fallback when interactive login is impractical (agent-driven sessions, no browser launch, headless). Uses gh's public OAuth client id; the user just enters a code at github.com/login/device. Scopes: repo,read:org,gist is the documented minimum for gh auth login --with-token; append ,workflow only if you need to push workflow files.

# 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

Note: on Windows winget installs, gh lands at /c/Program Files/GitHub CLI, add it to PATH in the same shell: export PATH="$PATH:/c/Program Files/GitHub CLI".

PITFALL (headless Linux): gh auth login --with-token can hang forever. On keyring-less/headless boxes (VPS, containers, no dbus session), gh's credential storage may block indefinitely waiting on a secret-service keyring, even with --insecure-storage, and with no output. If the command doesn't return within ~20s (wrap it in timeout 20 … to detect this), skip gh's login machinery and write the credential store directly:

# $TOKEN = the access token from the device flow above (never echo it)
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          # reads hosts.yml directly — verifies without the keyring
gh auth setup-git       # wires the git credential helper (does not hang)

gh auth status and setup-git read the file store without touching the keyring, so they work immediately. Proven on a headless x86_64 VPS (gh 2.97.0, Aug 2026) after --with-token hung twice.

Token-based login (headless / SSH servers)

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

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

If --with-token hangs here, use the hosts.yml fallback from the pitfall above.

Verify

gh auth status

Using the GitHub API without gh

When gh is not available, you can still access the full GitHub API using curl with a personal access token. This is how the other GitHub skills implement their fallbacks.

Setting the token for API calls

# 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

Extracting the token from git credentials

If git credentials are already configured (via credential.helper store), the token can be extracted:

# Read from git credential store
uv run python "${HERMES_HOME:-$HOME/.hermes}/skills/github/github-auth/scripts/git-credential-token.py"

Helper: detect auth method

Use this pattern at the start of any GitHub workflow:

# 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

Troubleshooting

Problem	Solution
`git push` asks for password	GitHub disabled password auth. Use a personal access token as the password, or switch to SSH
`remote: Permission to X denied`	Token may lack `repo` scope, regenerate with correct scopes
`fatal: Authentication failed`	Cached credentials may be stale, run `git credential reject` then re-authenticate
`ssh: connect to host github.com port 22: Connection refused`	Try SSH over HTTPS port: add `Host github.com` with `Port 443` and `Hostname ssh.github.com` to `~/.ssh/config`
Credentials not persisting	Check `git config --global credential.helper`, must be `store` or `cache`
Multiple GitHub accounts	Use SSH with different keys per host alias in `~/.ssh/config`, or per-repo credential URLs
`gh: command not found` + no sudo	Use git-only Method 1 above, no installation needed

When not to use it

The source does not list explicit exclusions, but you would not need this skill if authentication is already set up and working. The detection flow at the top tells you when to skip ahead. Also, if you need to work with a different Git host, this skill is GitHub-specific and would not apply.

Limits and gotchas

The source highlights two specific pitfalls. On Windows, driving gh auth login through a background pty can hang if you send a bare newline instead of a carriage return; use process(submit) and be ready to fall back to the device flow. On headless Linux, gh auth login --with-token can hang indefinitely waiting on a keyring; wrap it in timeout 20 and use the hosts.yml fallback if it does not return. Also note that the store credential helper saves tokens in plaintext, and the cache helper expires credentials from memory after a set timeout.

What pairs with this

Once authentication is in place, you can move on to the related skills that build on it: github-pr-workflow, github-code-review, github-issues, and github-repo-management. These skills assume you have working GitHub credentials, so run this setup first.

GitHub Authentication Setup for Hermes Agent