skip to content

With the GitHub CLI, which credential does gh use when GH_TOKEN, GH_ENTERPRISE_TOKEN and a stored login all exist?

level: middleimportance: should knowfreq 34%

answer

  1. first the host, then the token
  2. two families of variables
  3. Enterprise Server is its own family
  4. the variable outranks the keyring
  5. the source in parentheses

basics

~20 s

gh picks the credential by target host. For github.com and ghe.com hosts, GH_TOKEN, then GITHUB_TOKEN, overrides any stored login; for Enterprise Server hosts, GH_ENTERPRISE_TOKEN, then GITHUB_ENTERPRISE_TOKEN, does. Otherwise the host's active stored account is used.

solid answer

~40 s

gh first decides the host: an explicit `--hostname`, URL or `-R`/`GH_REPO` value in `[HOST/]OWNER/REPO` form, else the current repository's remote, else a default of github.com that `GH_HOST` can change. Then it picks the token for that host. For github.com and any `ghe.com` subdomain it checks `GH_TOKEN`, then `GITHUB_TOKEN`; for a GitHub Enterprise Server host it checks `GH_ENTERPRISE_TOKEN`, then `GITHUB_ENTERPRISE_TOKEN`. A variable that applies **takes precedence over stored credentials**; only when none is set does gh use the host's active stored account from the keyring or `hosts.yml`. So `GH_TOKEN` is never sent to `ghe.example.com`, a forgotten export silently shadows your browser login, and `gh auth login`, `refresh` and `switch` refuse to touch a host while a variable supplies its token. `gh auth status` shows which source won.

go deeper

for a junior

Remember that GH_TOKEN is for github.com, GH_ENTERPRISE_TOKEN for Enterprise Server hosts, and that an exported token beats whatever gh auth login stored.

for a middle

Walk through the two steps: how gh picks the host (flag, GH_REPO, repository remote, GH_HOST) and then which variable or stored account supplies the token for it.

for a senior

Diagnose wrong-identity reports quickly: read the source in gh auth status, look for stray GITHUB_TOKEN exports, and keep tokens for different host families in their own variables.

for a principal

Weigh convenience against blast radius: shell-wide token exports are easy but silently override personal logins, so prefer per-command or per-job injection for automation identities.

## Two decisions on every command Before it sends a request, the GitHub CLI decides **which host** the command targets and then **which credential** to present to that host. Nearly every "gh is using the wrong account" report is one of these two decisions landing somewhere unexpected, so it pays to keep them apart. ## Step 1: which host gh takes the host from the most specific source it has: 1. **An explicit target** — `--hostname` on the commands that accept it (for example `gh auth status` and `gh api`), a full URL given to commands such as `gh pr view`, or a repository written as `HOST/OWNER/REPO` with `-R` or in `GH_REPO`. 2. **The current repository** — inside a clone, gh reads the Git remote, so in a clone from `ghe.example.com` commands go to that host without any flag. 3. **A default** — with no repository context (`gh repo list`, say), gh targets github.com, or the host named in `GH_HOST`. `GH_HOST` only chooses a host. In the words of gh's help, if that host was logged in to before, its stored credentials are used; otherwise a token variable for that kind of host is required. ## Step 2: which credential for that host | Target host | Variables checked, in order | When no variable is set | |---|---|---| | github.com, or a subdomain of ghe.com | `GH_TOKEN`, then `GITHUB_TOKEN` | the host's active stored account | | a GitHub Enterprise Server host, such as `ghe.example.com` | `GH_ENTERPRISE_TOKEN`, then `GITHUB_ENTERPRISE_TOKEN` | the host's active stored account | A variable that applies to the host **takes precedence over previously stored credentials**. Stored credentials are kept per host and per account: each host recorded in `hosts.yml` has one **active** account, whose token sits in the system credential store or, as a fallback, in `hosts.yml` itself. ## What follows from the rules - **A forgotten export shadows your login.** A `GH_TOKEN` left in a shell profile — perhaps a fine-grained token limited to a single repository — wins over the browser login for every github.com command, and the resulting 403s and 404s look like a permissions problem on GitHub. - **`GITHUB_TOKEN` counts too.** It is second in line, so a token another tool exported under that name quietly becomes gh's credential whenever `GH_TOKEN` is unset. - **Variables do not cross host families.** `GH_TOKEN` is never sent to an Enterprise Server host and `GH_ENTERPRISE_TOKEN` is never sent to github.com, so a script that touches both hosts can set both without conflict. - **The auth commands step aside.** While a variable supplies the token for a host, `gh auth login`, `gh auth refresh` and `gh auth switch` refuse to change stored credentials for it and tell you to clear the variable first. - **Git follows the same lookup.** When gh is Git's credential helper, the token it hands Git comes from exactly this order. ## Seeing which rule fired `gh auth status` prints, per host, the account and the token's source in parentheses: ```bash GH_TOKEN=ghp_xxxxxxxx gh auth status --hostname github.com # github.com # ✓ Logged in to github.com account deploy (GH_TOKEN) # - Active account: true ``` A source of `keyring` or a `hosts.yml` path means a stored login is in use; a variable's name means the environment won. When the source is a variable, gh asks the API who owns the token, because no account name is stored for it. ## The same rules in CI In a GitHub Actions job the usual line is `GH_TOKEN: ${{ github.token }}`, and commands run inside the checked-out clone, so the host comes from its remote. A job on another runner that drives an Enterprise Server host is different on both counts: it needs `GH_ENTERPRISE_TOKEN`, and when it has no clone it must name the host itself, through `GH_HOST`, `--hostname` or `-R ghe.example.com/acme/api`. Getting only one of the two right ends in an authentication error, because a headless job has no way to log in interactively. ## A checklist for "wrong account" reports 1. List which of `GH_TOKEN`, `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GITHUB_ENTERPRISE_TOKEN`, `GH_HOST` and `GH_REPO` are set in that shell or job — names only, never the values in a shared log. 2. Run `gh auth status --hostname <host>` for the host the command should reach and read the source. 3. If the command ran inside a clone, check which host its remote points at; that, not `GH_HOST`, decided the target. 4. Unset the stray variable, or use `gh auth switch` when the right account is stored but not active.

  • What does GH_REPO change, and how does it differ from GH_HOST?
    `GH_REPO` names the repository, in `[HOST/]OWNER/REPO` form, for commands that would otherwise use the local clone, so it can set the host too. `GH_HOST` only sets the host for commands that cannot infer one, such as `gh repo list` outside a clone. Neither supplies a token.
  • A script talks to github.com and an Enterprise Server host in one run. How do you give gh both tokens?
    Set `GH_TOKEN` for github.com and `GH_ENTERPRISE_TOKEN` for the Enterprise Server host. They belong to different host families, so each is used only for its own kind of host, and the target host of each command comes from its repository, `-R` or `--hostname`.

  • A stored login always outranks an exported GH_TOKEN
  • GH_TOKEN is used for every host, Enterprise Server included
  • Setting GH_HOST is enough to authenticate gh to that host
  • GITHUB_TOKEN is ignored by gh outside GitHub Actions
  • gh auth login can override GH_TOKEN for the same host