skip to content

A GitHub CLI command fails with a missing-scope error; how do you confirm it with gh auth status and fix it with gh auth refresh?

level: seniorimportance: should knowfreq 24%

answer

  1. the token, not the command
  2. a scopes line per account
  3. prefix decides whether scopes exist
  4. add without losing the old ones
  5. a variable blocks the refresh

basics

~20 s

gh auth status lists each account's scopes and flags a missing repo or read:org. gh auth refresh -s <scope> reruns the browser login and adds the scope to those already held. A token injected through GH_TOKEN must be reissued instead.

solid answer

~50 s

Start with `gh auth status --hostname <host>`: for each account it shows the token source, whether it is active, and, for classic (`ghp_`) and OAuth (`gho_`) tokens, a `Token scopes` line, with a warning and a suggested `gh auth refresh -h <host>` when `repo` or `read:org` is missing. Compare that list with what the command needs; gh's help names several, such as `project` for `gh project` and `delete_repo` for `gh repo delete`. Then run `gh auth refresh -s project`: it keeps the scopes the token already has, adds the new ones, reruns the browser flow and stores the new token. `-r` removes scopes (never `repo`, `read:org` or `gist`) and `--reset-scopes` returns to the default set. Refresh works only on the active account and refuses while `GH_TOKEN` supplies the token; then, and for fine-grained or installation tokens with no scopes line, fix the token where it was issued.

code

bash · 8 lines
bash
gh auth status --hostname github.com
# github.com
#   ✓ Logged in to github.com account alice (keyring)
#   - Active account: true
#   - Git operations protocol: https
#   - Token: gho_************************************
#   - Token scopes: 'gist', 'read:org', 'repo'
gh auth refresh --hostname github.com --scopes project

go deeper

for a junior

Know that a gh command can fail because the token lacks a scope, and that gh auth status shows the scopes while gh auth refresh -s adds one.

for a middle

Explain what refresh does with existing scopes, the -s, -r and --reset-scopes options, and why it touches only the active account.

for a senior

Separate stored logins from injected tokens: refresh fixes the first, while CI tokens and fine-grained or installation tokens must be reissued with the right permissions at their source.

for a principal

Treat scope creep as a risk: grant extra scopes only when a command needs them, remove them afterwards with -r, and keep high-privilege scopes off long-lived workstation tokens.

## Why the token is usually the culprit Every GitHub CLI command runs with one token, and a **classic personal access token** or the **OAuth token** that `gh auth login` obtains carries **scopes**: coarse permissions such as `repo`, `read:org` or `admin:org`. gh's login asks only for `repo`, `read:org` and `gist` (plus `workflow` or `admin:public_key` in some flows), so a command that needs anything else fails until the token gains that scope. gh's own help names several: - `gh project` needs `project`. - `gh repo delete` needs `delete_repo`. - `gh ruleset list --org` needs `admin:org`. Many such failures already print the fix, for example `your authentication token is missing required scopes [project]` followed by `To request it, run: gh auth refresh -s project`. The same class of problem shows up outside gh's own commands. A `git push` over HTTPS that changes files under `.github/workflows` is rejected when the token Git received lacks the `workflow` scope; if that token is gh's, because gh is Git's credential helper, `gh auth refresh -s workflow` fixes the push as well. ## Step 1: read `gh auth status` `gh auth status` tests every account on every known host (`--hostname` narrows it, `--active` shows only the active account) and prints, per account: - the login and the **token source** — `keyring`, a `hosts.yml` path, or a variable name such as `GH_TOKEN`; - whether it is the **active** account for that host, and the Git protocol; - the token, masked unless `--show-token` is given; - a **`Token scopes`** line, and a warning **`Missing required token scopes`** with a suggested `gh auth refresh -h <host>` when `repo` or `read:org` (or a broader org scope) is absent. The command exits with status 1 when any checked account has a problem, so it doubles as a cheap health check at the top of a script. Whether a scopes line appears depends on the token type, which gh recognises by prefix: | Prefix | Token | Scopes line in `gh auth status` | |---|---|---| | `gho_` | OAuth token from the browser login | shown | | `ghp_` | classic personal access token | shown | | `github_pat_` | fine-grained personal access token | not shown — its permissions are set on the token itself | | `ghs_` | installation token, such as an Actions job's token | not shown — permissions come from the installation or workflow | No scopes line therefore does not mean "no permissions"; it means the token is not governed by scopes, and `gh auth refresh` cannot help with it. How those token types compare is a separate subject. ## Step 2: fix a stored login with `gh auth refresh` `gh auth refresh` reruns the browser flow for the **active** account on a host and stores the new token in place of the old one: 1. `gh auth refresh -s project` — keeps the scopes the current token has and adds `project`. With no `-s`, it simply re-requests the existing set, which also restores the minimum if it was lost. 2. `gh auth refresh -r delete_repo` — removes a scope; removal is idempotent, and the minimum `repo`, `read:org` and `gist` cannot be removed. 3. `gh auth refresh --reset-scopes` — returns to the default scopes for the flow, dropping everything added since. Constraints that catch people out: - **Only the active account.** To refresh another stored account, `gh auth switch` to it, refresh, and switch back. - **The same account in the browser.** If the browser is signed in as someone else, gh stops with an error asking whether you used the correct account. - **Not while a variable supplies the token.** With `GH_TOKEN` set for the host, refresh prints that the variable is being used and asks you to clear it. - **Not headless.** Without a terminal it requires `--hostname` and still needs a person to approve the browser page, so it is no fix inside CI. ## Step 3: fix an injected token at its source When the token comes from `GH_TOKEN` or `GH_ENTERPRISE_TOKEN` — the normal case in CI — gh cannot widen it. Issue a token that carries the needed scope or permission and put that in the variable; for an Actions job's own token, its permissions are granted in the workflow, not by gh. Then rerun `gh auth status` and confirm the source and scopes before rerunning the job. ## A short checklist 1. Read the error: does it name a scope, or is it a 403 or 404 that could be a token limited to other repositories? 2. Run `gh auth status --hostname <host>` and note the source, the active account and the scopes line. 3. Stored login: `gh auth refresh -s <scope>` on the active account. Injected token: reissue it with the permission it lacks. 4. Remove scopes you added only for a one-off task with `gh auth refresh -r <scope>`.

  • gh auth status shows no Token scopes line at all. What does that tell you?
    gh prints scopes only for classic (`ghp_`) and OAuth (`gho_`) tokens. A fine-grained token or an installation token, such as an Actions job's, has no OAuth scopes; its permissions were set where it was issued, so `gh auth refresh` cannot change them and the fix is a token with the right permissions.
  • How do you refresh scopes for a stored account that is not the active one?
    `gh auth refresh` acts only on the active account for a host. Run `gh auth switch --hostname <host> --user <login>`, refresh with the scopes you need, and switch back. In the browser, sign in as that same account, or gh rejects the credentials it receives.

  • gh auth refresh can add scopes to the token in GH_TOKEN
  • No scopes line in gh auth status means the token has no permissions
  • gh auth refresh -s replaces all existing scopes with the new one
  • gh auth refresh -r can remove the repo scope
  • A missing-scope error means the gh command itself is broken