github-codespace

Files (2)

• SKILL.md
• selkies-package-discrepancy.md · references/

SKILL.md (first lines)

# GitHub Operations in GitHub Codespaces

Covers auth, CI monitoring, CI debugging, and API access patterns specific to
GitHub Codespaces. This skill complements `github-auth` (general setup),
`github-pr-workflow` (lifecycle), and `systematic-debugging` (general root
cause analysis) by addressing Codespace-specific pitfalls and shortcuts.

## Prerequisites

- Running inside a GitHub Codespace (`CODESPACES=true` in env)
- `gh` CLI installed (comes with Codespaces)

---

## Authentication

### The Invalid GH_TOKEN Pitfall

Codespaces set `GH_TOKEN` and `GITHUB_CODESPACE_TOKEN` env vars. These tokens
can be expired or scoped only to Codespace management — not repo write access.
When `GH_TOKEN` is set to an invalid token, `gh auth login` silently refuses
to work, claiming "The value of the GH_TOKEN environment variable is being
used for authentication."

**This is the #1 auth blocker in Codespaces. Always check for it first.**

### Fix: Device Code Flow

```bash
# Step 1: Unset the invalid token
unset GH_TOKEN

# Step 2: Use device code flow (works in any Codespace terminal)
gh auth login --hostname github.com --git-protocol https --web

# This prints a one-time code and URL.
# The user visits the URL and enters the code — one-time browser approval.
# No PAT creation needed. This IS the Codespace auth path.
```

### Auth Detection

```bash
# Quick check: does gh work for write operations?
if gh auth status 2>&1 | grep -q "Logged in"; then
  echo "OK: gh authenticated"
elif [ -n "$GH_TOKEN" ]; then
  echo "PROBLEM: GH_TOKEN is set but likely invalid"
  echo "FIX: unset GH_TOKEN && gh auth login --hostname github.com --git-protocol https --web"
else
  echo "NOT AUTHENTICATED"
  gh auth login --hostname github.com --git-protocol https --web
fi
```

### User Preference

**Do not ask Codespace users to create PATs or run manual auth commands.**
The device code flow IS the expected auth path in a Codespace. If the agent
can't authenticate, try the device code flow first — the user just needs to
open a URL and paste a code, which is seamless.

### Token Extraction from VS Code Server (Preferred — No Browser)

The VS Code server process has a GitHub App user-to-server token (`ghu_xxx`) in its
environment. This is the preferred auth method in Codespaces — no browser,
no device flow, no user interaction needed.

```bash
# 1. Find the VS Code server PID
VSCODE_PID=$(pgrep -f "server-main.js" | head -1)

# 2. Extract the real GITHUB_TOKEN from its process environment
GITHUB_TOKEN=$(cat /proc/$VSCODE_PID/environ 2>/dev/null \
  | tr '\0' '\n' \
  | grep "^GITHUB_TOKEN=" \
  | cut -d= -f2-)

# 3. Verify it works
curl -s -H "Authorization: token ***" \
  https://api.github.com/user | python3 -c "import json,sys; print(json.load(sys.stdin).get('login','FAILED'))"
```

**Critical limitation**: This token is a **GitHub App token** (from the GitHub Codespaces app).
It has `repo` scope but is **gated by GitHub App installation**. It works for:
- The Codespace's origin repository
- Other repositories where the GitHub Codespaces app is installed

It will **FAIL (403)** on repositories where the user has access but the Codespaces app is not installed.

Use it for API calls, PR comments, and even `gh` CLI **on supported repos**:

```bash
unset GH_TOKEN
export GH_TOKEN="$GITHUB_TOKEN"
gh auth status  # Should show authenticated
```

**Why this works**: The agent session does NOT inherit the VS Code server's
environment — `GITHUB_CODESPACE_TOKEN` and `GH_TOKEN` in the shell are
different (limited/invalid) tokens. The real token lives in the server
process's `/proc/PID/environ` and must be extracted explicitly.

### Token Scope Comparison

| Method | Token Type | Scope | Works On |
|--------|------------|-------|----------|
| **Extract from VS Code** | GitHub App user-to-server (`ghu_`) | `repo` (app-gated) | Origin repo + Codespaces-connected repos only |
| **Device code flow** | Classic OAuth (`gho_`/`ghp_`) | Full user scopes | **All repos the user has access to** |
| **Unauthenticated API** | None | Public only | Public repos (read-only) |

**When to use device flow instead**: Working on repos outside the Codespaces app installation (other users' repos, orgs without Codespaces app).

### Pitfall: Multiple VS Code Server Processes

`pgrep -f "server-main.js"` may return multiple PIDs. The main server is the
one running `server-main.js` directly (not `bootstrap-fork` children). If token
extraction returns empty, try each PID:

From gitricko/.minions, MIT.

More from gitricko/.minions