4.8 KiB
4.8 KiB
name, description, version, author, license, platforms, metadata
| name | description | version | author | license | platforms | metadata | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| github-ssh-headless-pitfalls | Common pitfalls when setting up GitHub auth in SSH/headless environments (gh CLI device flow timeouts, missing scopes, etc.) | 1.0.0 | Hermes Agent | MIT |
|
|
GitHub Auth in SSH/Headless Environments — Pitfalls & Fixes
This skill documents the common issues encountered when setting up GitHub authentication (especially gh CLI) on remote servers, SSH sessions, or headless environments where interactive browser flows don't work reliably.
Pitfall 1: gh auth login --web Times Out (Device Code Flow)
Symptom
$ gh auth login --web
! First copy your one-time code: XXXX-XXXX
Open this URL to continue in your web browser: https://github.com/login/device
[Command timed out after 180s]
Cause
The device code flow requires the user to:
- Open the URL in a local browser
- Enter the code
- Authorize the app All within 180 seconds. In SSH sessions, users often don't realize they need to do this locally, or get distracted.
Fix: Use PAT with --with-token
# Create a Personal Access Token at https://github.com/settings/tokens
# Scopes needed: repo, workflow, read:org (minimum)
# Then:
echo "ghp_xxxxxxxxxxxx" | gh auth login --with-token
gh auth setup-git
No browser, no timeout, works 100% headless.
Pitfall 2: Token Missing read:org Scope
Symptom
$ echo "ghp_xxx" | gh auth login --with-token
error validating token: missing required scope 'read:org'
Cause
The gh CLI requires read:org scope to query organization membership (even if you only work with personal repos).
Fix
When creating the PAT at https://github.com/settings/tokens, ensure these scopes are checked:
repo(full repo access)workflow(Actions/workflows)read:org(org membership queries — required by gh CLI)
Pitfall 3: Git Credential Helper Not Configured
Symptom
After gh auth login --with-token, git push still prompts for credentials.
Cause
gh auth setup-git configures the credential helper, but it may not persist if run in a different shell context.
Fix
# Ensure credential helper is set globally
gh auth setup-git
# Verify
git config --global credential.helper
# Should output: "gh" or "!/usr/bin/gh auth git-credential"
Pitfall 4: SSH Key Not Added to GitHub
Symptom
$ ssh -T git@github.com
Permission denied (publickey).
Fix
# Generate key if needed
ssh-keygen -t ed25519 -C "your-email@example.com" -f ~/.ssh/id_ed25519 -N ""
# Copy public key
cat ~/.ssh/id_ed25519.pub
# User adds it at: https://github.com/settings/keys
# Then test:
ssh -T git@github.com
# Should show: "Hi <username>! You've successfully authenticated..."
Quick Reference: Headless Setup Checklist
| Step | Command | Notes |
|---|---|---|
| 1. Install gh (if needed) | curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null && sudo apt update && sudo apt install -y gh |
Ubuntu/Debian |
| 2. Create PAT | Browser: github.com/settings/tokens → Generate token (classic) | Scopes: repo, workflow, read:org |
| 3. Login with token | echo "<PAT>" | gh auth login --with-token |
No browser, instant |
| 4. Setup git credentials | gh auth setup-git |
Configures credential helper |
| 5. Verify | gh auth status |
Should show authenticated |
| 6. Test git | git ls-remote https://github.com/<user>/<repo>.git |
Should work without prompts |
When to Use Which Method
| Environment | Recommended Method |
|---|---|
| Local desktop with browser | gh auth login (interactive) |
| SSH server / headless / CI | gh auth login --with-token + PAT |
No gh installed, no sudo |
Git-only: git config --global credential.helper store + PAT as password |
| Persistent server, multiple users | SSH keys per user + git config --global url."git@github.com:".insteadOf "https://github.com/" |
Related Skills
- github-auth — Main GitHub authentication setup skill
- github-pr-workflow — PR workflow with gh
- github-code-review — Code review via gh
- github-issues — Issue management via gh
- github-repo-management — Repo operations via gh