mesh-configs/skills/software-development/github-ssh-headless-pitfalls/SKILL.md

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	linux macos	hermes tags related_skills GitHub Authentication SSH Headless gh-cli Troubleshooting github-auth github-pr-workflow github-code-review github-issues github-repo-management

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:

1. Open the URL in a local browser
2. Enter the code
3. 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