github-auth

name	github-auth
description	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.

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:

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.