github-auth
github-auth — GitHub auth setup: HTTPS tokens, SSH keys, gh CLI login.
SKILL.mdskills/github-auth/SKILL.md
GitHubGitHub Authentication Setup
This skill sets up authentication so the agent can work with GitHub repositories, PRs, issues, and CI. It covers two paths:
git(always available) — uses HTTPS personal access tokens or SSH keysghCLI (if installed) — richer GitHub API access with a simpler auth flow
Detection Flow
When a user asks you to work with GitHub, run this check first:
# 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"
Decision tree:
- If
gh auth statusshows authenticated → you're good, useghfor everything - If
ghis installed but not authenticated → use "gh auth" method below - If
ghis not installed → use "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: Authenticate git — prefer the CLI or OS credential manager
# Recommended: log in with the GitHub CLI (token handled by gh/OS keychain)
gh auth login
# Or use git's built-in credential manager (macOS Keychain / Windows Credential Manager)
git config --global credential.helper osxkeychain # macOS
git config --global credential.helper manager # Windows
These keep the token out of plaintext files and command history.
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)
gh auth login
# Select: GitHub.com
# Select: HTTPS
# Authenticate via browser
Token-Based Login (Headless / SSH Servers)
echo "<THEIR_TOKEN>" | gh auth login --with-token
# Set up git credentials through gh
gh auth setup-git
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
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"
# Plaintext ~/.git-credentials is intentionally not used; prefer `gh auth login` or GITHUB_TOKEN in .env
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 |