KennisBank

gh CLI workflow scope voor pushen van GitHub Actions

Uit wiki.jimvandenbreemen.nl, de persoonlijke kennisbank van Jim van den Breemen

4 minuten leestijd

gh CLI workflow scope voor pushen van GitHub Actions

Definitie

Een verse gh auth login geeft je OAuth-token standaard niet genoeg rechten om .github/workflows/*.yml naar GitHub te pushen. Je moet de extra workflow scope expliciet toevoegen via gh auth refresh. Zonder die scope faalt elke git push die een workflow-file aanraakt met een specifieke foutmelding van de remote.

Context

Tijdens een kennisbank-web push naar een net aangemaakte private fork Jvdbreemen/kennisbank-web bleek dat gh repo create --push de eerste push rejectte met: ! [remote rejected] HEAD -> main (refusing to allow an OAuth App to create or update workflow 'deploy.yml' without 'workflow' scope). De repo was al aangemaakt, alleen de push met de workflow-file werd geblokkeerd.

Dit is een GitHub-brede maatregel: OAuth apps mogen niet zomaar workflows schrijven want een workflow kan elke action uitvoeren (secrets lezen, packages publiceren, tokens exchangen). De workflow scope is een expliciete opt-in die je eenmalig per token geeft.

Kernpunten

Herkennen

De exacte foutmelding van de remote:

! [remote rejected] HEAD -> main (refusing to allow an OAuth App to create
or update workflow `.github/workflows/deploy.yml` without `workflow` scope)
error: failed to push some refs to 'https://github.com/<owner>/<repo>.git'

Het werkt pas zodra je token de workflow scope heeft. Pushes naar dezelfde repo zonder workflow-bestanden lopen gewoon door. De foutmelding wijst precies het blokkerende bestand aan.

Fix via gh auth refresh

Het juiste commando is:

gh auth refresh -h github.com -s workflow
  • -h github.com is verplicht als je niet-interactief draait of meerdere hosts hebt.
  • -s workflow voegt de scope toe aan je bestaande token. Eerdere scopes blijven.

gh start een device-code flow: het print een 8-cijferige code en opent (of toont) de URL https://github.com/login/device. Plak de code daar, authoriseer de extra scope, klaar. De scope wordt aan je bestaande token gekoppeld, je hoeft niet opnieuw in te loggen.

Waarom dit niet via ! in Claude Code werkt

Het commando ! gh auth refresh -h github.com -s workflow via de Claude Code prompt faalt op twee punten:

  1. gh detecteert de shell als niet-interactief en eist dan expliciete --hostname. Zonder -h krijg je de Usage-output terug.
  2. De device-code flow heeft een echte TTY nodig om de code te printen en input te accepteren. ! draait in een non-tty subshell.

Open dus een gewone Terminal (Terminal.app, iTerm, WezTerm, wat je ook gebruikt), draai het commando daar, doorloop de device-code flow, en kom dan terug naar Claude Code voor de push. De nieuwe scope zit meteen op hetzelfde token dat Claude gebruikt.

Verificatie

Check achteraf welke scopes je token heeft:

gh auth status

Onder de actieve account staat een Token scopes: regel. Als workflow daar tussen staat, kun je workflows pushen. Een typische post-refresh output:

Token scopes: 'gist', 'read:org', 'repo', 'workflow'

Voor wie dit vaak doet

Overweeg om bij een verse gh auth login direct de scope mee te geven:

gh auth login -s workflow

Dat scheelt de refresh-stap later. De scope is onschuldig voor wie wiki-repos en eigen projecten beheert; in een enterprise-context wil je dit afstemmen met de org admin omdat workflows secrets kunnen exposeren.

GitHub MCP vs gh CLI

De GitHub MCP-server (mcp__github__create_repository e.d.) en de gh CLI gebruiken een andere auth-laag. Als de MCP-server “Authentication Failed: Requires authentication” geeft terwijl gh auth status een geldig token toont, gebruik dan gewoon de gh CLI als fallback. De MCP-server heeft een eigen OAuth-flow die los staat van het keyring-token van de CLI. Bij eenvoudige repo-operaties (aanmaken, clonen, visibility) is de CLI altijd voldoende.

Verbanden

Bronnen

Sessie-herkomst

Verbanden

  1. Zie ook: wiki-quartz-fork-en-deploy-gotchas (deploy.yml in kennisbank-web was de eerste workflow die dit triggerde)
  2. Zie ook: wiki-claude-workspace-setup (initiele gh-setup op deze Mac)
  3. Gerelateerd project: 03-projecten/kennisbank-web
  4. Zie ook: wiki-github-repo-aanmaken-lokaal — references
  5. Zie ook: wiki-pre-publicatie-checklist-github — references

Bronnen

  1. [cli.github.com]GitHub CLI manual. (2026). gh auth refresh. https://cli.github.com/manual/gh_auth_refresh
  2. [docs.github.com]GitHub Docs. (2026). Scopes for OAuth apps. https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps
  3. [docs.github.com]GitHub Docs. (2026). Workflow permissions. https://docs.github.com/en/actions/security-guides/automatic-token-authentication

Backlinks

Grafiekweergave