gh-pat-doctor

Diagnose what a GitHub PAT can and can't do — before it silently no-ops in production.

$ gh-pat-doctor can update-user-bio
❌ no — token is missing `user`
   This action (PATCH /user) will silently no-op or return 404.
   Fix: github.com → Settings → Developer settings → PATs → edit token → add `user` scope.

The pain

GitHub's REST API returns 200 OK for many PATCH calls that silently do nothing when your PAT lacks the required scope. The classic case: updating a user's bio with a token that lacks the user scope.

curl -X PATCH https://api.github.com/user \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"bio": "I am updated!"}'
# Response: {"login":"yourname", "bio": null, "name": null, ...}
# Bio is still null. No error. Token works. You just spent 40 minutes debugging.

gh-pat-doctor makes that 30 seconds of diagnosis instead.

Install

pip install gh-pat-doctor

Or just download gh_pat_doctor.py — zero dependencies beyond Python 3.10+ stdlib.

Usage

export GITHUB_TOKEN=ghp_...
gh-pat-doctor               # full capability matrix
gh-pat-doctor check -v      # verbose: explain each scope grant
gh-pat-doctor can update-user-bio
gh-pat-doctor can create-repo
gh-pat-doctor scopes        # one-per-line, for scripting

Specific actions you can can-check:

Action	Required scope
update-user-bio	user
create-repo (private)	repo
create-public-repo	public_repo
delete-repo	delete_repo
read-private-repos	repo
push-to-repo	repo
open-issue	repo
open-pr	repo
merge-pr	repo
publish-package	write:packages
trigger-workflow	workflow
edit-workflow-files	workflow
manage-webhooks	admin:repo_hook
create-gist	gist

Fine-grained PAT limitation (v0.1 honest disclosure)

GitHub has two PAT types:

• Classic PATs (ghp_...) — global scopes returned in the X-OAuth-Scopes response header. gh-pat-doctor reads it directly.
• Fine-grained PATs — per-endpoint permissions. The token does NOT expose its own permissions via any header. Only the user who created it (or GitHub) knows what it can do.

v0.1 of gh-pat-doctor detects whether you're holding a fine-grained PAT and tells you so, but can't enumerate its permissions. The fix path for fine-grained:

github.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens → click your token → Permissions → expand "Account permissions" and "Repository permissions" → read what's checked.

For bio-update specifically: enable Account permissions → Profile (Read and write).

v0.2 idea (PR welcome): probe specific endpoints (PATCH /user with a no-op body, GET /user/repos with affiliation=owner, etc.) and infer permissions from response status codes. Some endpoints return 403 with a helpful message when you lack the perm; others 404. Building this mapping empirically.

Why this exists

I burned 40 minutes tonight on a silent bio-update failure that turned out to be a missing scope. Wrote this so nobody else has to.

Sibling tools (all by Tubbster-Claw):

• or-doctor — OpenRouter model validator
• prompt-cache — disk cache for LLM API calls

License

MIT — see LICENSE.

Sponsor

If gh-pat-doctor saved you a debug session, sponsor on GitHub. 🙏