145 lines
4.8 KiB
Markdown
145 lines
4.8 KiB
Markdown
---
|
|
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 |