# Github Auth

> Authenticate gh and git inside the workbench using openhost's oauth-v2 app. Use when gh is not logged in, when a git push or clone of a private repo fails with auth errors, when you need to open a PR, or when an oauth token call returns permission_required.

- Skill: `cloud-in-a-bottle/github-auth` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cloud-in-a-bottle/github-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloud-in-a-bottle/github-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: cloud-in-a-bottle (https://skillmd.com/u/cloud-in-a-bottle)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cloud-in-a-bottle/github-auth

---


# GitHub auth in the workbench

**Read the "GitHub auth" section of `/app/README.md` first** (that's this repo's `README.md`, baked
into the image). It has the exact commands for listing
granted accounts, minting a token, and using it — along with the two failures that block almost
every attempt (`account` being required, and `gh auth login --with-token` rejecting the token for
want of `read:org`). Follow it rather than improvising; don't ask the user for a personal access
token until that flow has actually failed.

What follows is only the judgement that doesn't belong in a reference doc.

## Handling `permission_required`

The response carries a `grant_url` that only the user can approve in a browser. Give them the URL,
say plainly that you're blocked until they approve, and stop. Do not poll for it — approval can't
be waited into existence, and a retry loop just burns turns. Retry once they say they've done it.

## Don't leak the token

Never print an access token. Write it to a file or a variable, and pipe any command that might echo
it through `sed -E 's/gh[a-z]_[A-Za-z0-9]+/<REDACTED>/g'`. Prefer embedding it in a one-off remote
URL over configuring stored git credentials.

## Before pushing

Check you actually have write access instead of assuming it:

```bash
gh api repos/<owner>/<repo> -q '{push:.permissions.push, admin:.permissions.admin}'
```

Fork when `push` is `false`. And treat pushing a branch, opening a PR, or commenting as
outward-facing: confirm with the user before the first one unless they've already asked for it.

## If a call that worked starts failing

Tokens are short-lived. A sudden 401 usually means re-mint, not a broken setup.