---
name: github-ssh-headless-pitfalls
description: "Common pitfalls when setting up GitHub auth in SSH/headless environments (gh CLI device flow timeouts, missing scopes, etc.)"
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [GitHub, Authentication, SSH, Headless, gh-cli, Troubleshooting]
    related_skills: [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
```bash
$ 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`

```bash
# 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
```bash
$ 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
```bash
# 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
```bash
$ ssh -T git@github.com
Permission denied (publickey).
```

### Fix
```bash
# 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](../github-auth/SKILL.md) — Main GitHub authentication setup skill
- [github-pr-workflow](../github-pr-workflow/SKILL.md) — PR workflow with gh
- [github-code-review](../github-code-review/SKILL.md) — Code review via gh
- [github-issues](../github-issues/SKILL.md) — Issue management via gh
- [github-repo-management](../github-repo-management/SKILL.md) — Repo operations via gh