skip to content

With the GitHub CLI, how do you authenticate gh on your own laptop compared with inside a CI job?

level: juniorimportance: must knowfreq 48%

answer

  1. one path is interactive, one headless
  2. a one-time code in the browser
  3. where the token is kept afterwards
  4. an environment variable beats the store
  5. standard input for a pasted token

basics

~20 s

On a laptop, gh auth login runs a browser flow with a one-time code and keeps the token in the system credential store. In CI, set GH_TOKEN in the job's environment; gh prefers it to any stored login and never prompts.

solid answer

~40 s

On a workstation, `gh auth login` defaults to a web-browser flow: gh prints a one-time code, you approve it on a GitHub page, and gh saves the resulting OAuth token in the operating system's credential store, falling back to a plain-text `hosts.yml` only when no store works (`--insecure-storage` chooses that file on purpose). A CI job should not log in at all: expose the token as `GH_TOKEN` (or `GITHUB_TOKEN`) in the job's environment, which gh reads on every command and prefers over stored credentials; in GitHub Actions gh's help gives `GH_TOKEN: ${{ github.token }}` under `env`. `gh auth login --with-token` reads a classic personal access token from standard input and needs at least `repo`, `read:org` and `gist`. Either way, `gh auth status` shows the account and where its token came from.

go deeper

for a junior

Recall the two paths: gh auth login with the browser and a one-time code on your machine, GH_TOKEN in the environment for automation, and gh auth status to confirm which account is active.

for a middle

Explain where the token ends up (credential store, plain-text hosts.yml fallback, or an environment variable), why the variable outranks stored logins, and what --with-token checks.

for a senior

Show judgement about secrets: keep tokens off command lines, avoid plain-text storage on shared hosts, never run an interactive login in an ephemeral job, and verify the source with gh auth status.

for a principal

Frame workstation and automation credentials as separate lifecycles: people log in and refresh interactively, while jobs receive short-lived injected tokens that nobody stores or reuses.

## What gh needs before any command works Almost every GitHub CLI command calls the GitHub API, so `gh` must present a **token** for the host it is talking to: github.com, a `ghe.com` subdomain, or a GitHub Enterprise Server host such as `ghe.example.com`. There are two ways to give it one, and they suit different machines: - **An interactive login** with `gh auth login`, which obtains a token once and stores it so every later command reuses it. This is the laptop path. - **An environment variable** such as `GH_TOKEN`, which gh reads on every command and which needs no login and no storage. This is the CI path. ## The laptop path: `gh auth login` Run with no flags in a terminal, `gh auth login` asks a short series of questions: 1. **Where do you use GitHub?** GitHub.com or another host. The `--hostname` flag answers it up front, for example `--hostname ghe.example.com`. 2. **Preferred protocol for Git operations on this host** — HTTPS or SSH (`--git-protocol`). Choosing SSH offers to upload an existing public key or to generate one; `--skip-ssh-key` skips that step. 3. **Authenticate Git with your GitHub credentials?** — asked for HTTPS; answering yes lets Git push and pull with the same token, by making gh Git's credential helper for that host or by handing the token to a helper Git already has. 4. **How would you like to authenticate GitHub CLI?** — *Login with a web browser* (the default) or *Paste an authentication token*. The browser option prints a **one-time code**, opens a GitHub page and waits while you enter the code and approve the request. You can complete that page in any browser, which is why the flow also works from an SSH session on a remote box. When it finishes, gh holds an **OAuth token** for the account, carrying the scopes it asked for: `repo`, `read:org` and `gist`, plus `workflow` when gh is to serve Git and `admin:public_key` when it uploads an SSH key. ## Where the token is kept | Storage | When it is used | Source shown by `gh auth status` | |---|---|---| | System credential store (keyring) | the default after a successful login | `keyring` | | Plain-text `hosts.yml` in gh's config directory | no usable credential store, or `--insecure-storage` | the path of `hosts.yml` | | Environment variable | `GH_TOKEN` or a sibling variable is set | the variable's name | gh's config directory is `GH_CONFIG_DIR` when set, otherwise `$XDG_CONFIG_HOME/gh` (if that variable is set), `$AppData/GitHub CLI` on Windows, or `$HOME/.config/gh`. `hosts.yml` records which accounts are logged in to which host; gh prints a warning whenever it has had to save credentials in plain text there. ## The CI path: an environment variable A CI runner has nobody to approve a browser page and usually no credential store, so a job should skip `gh auth login` and hand gh the token through its environment: - `GH_TOKEN`, then `GITHUB_TOKEN`, is used for github.com and `ghe.com` hosts. - `GH_ENTERPRISE_TOKEN`, then `GITHUB_ENTERPRISE_TOKEN`, is used for GitHub Enterprise Server hosts. - Setting one **avoids every authentication prompt and takes precedence over previously stored credentials**. For a GitHub Actions job, gh's own help gives the line to add to the step's `env`: `GH_TOKEN: ${{ github.token }}`. The workflow's token is not picked up unless it is mapped in this way, and what it may change is decided by the workflow, not by gh. ## Pasting a token with `--with-token` `gh auth login --with-token` reads a token from **standard input**, so it never lands in shell history or in the process list: ```bash gh auth login --hostname ghe.example.com --with-token < ~/.config/acme/gh-token.txt gh auth status --hostname ghe.example.com ``` The help names the minimum scopes for a **classic personal access token** as `repo`, `read:org` and `gist`. At login gh reads the scopes GitHub reports for the token and rejects a classic token that lacks `repo` or `read:org` with an `error validating token` message. For **fine-grained tokens** the help advises setting `GH_TOKEN` instead, because their per-repository limits confuse commands that reach other resources. A token pasted this way is then stored exactly like a browser login, so it belongs on a workstation or a long-lived build host, not in an ephemeral job. ## Checking the result `gh auth status` lists every known host and account, marks the **active** account per host, and shows the token source and, for classic and OAuth tokens, the scopes. It exits with status 1 when an account has a problem, which makes it a cheap first step in a CI job. One trap: while `GH_TOKEN` is set, `gh auth login` refuses to store anything and says the environment value is being used — clear the variable first.

  • Why does gh auth login stop with a message on a machine where GH_TOKEN is already exported?
    gh sees that the credential for github.com comes from an environment variable and refuses to store another, printing that the value of `GH_TOKEN` is being used and must be cleared first. Since the variable always wins over stored credentials, a stored login would be ignored anyway. Unset it, then log in.
  • What happens to the token when the machine has no working credential store?
    gh falls back to writing it in plain text to `hosts.yml` in its config directory and warns that credentials were saved in plain text; `gh auth status` then shows that file as the source. `--insecure-storage` makes the same choice deliberately, which suits some containers, but anyone who can read the file holds the token.
  • In a GitHub Actions job, why does gh ask for authentication even though the workflow has a token?
    gh reads only its token environment variables and its own stored login; the workflow's token is not exported to gh by itself. Map it into the step with `GH_TOKEN: ${{ github.token }}` under `env`, as gh's help shows. What that token may then change is bounded by the workflow's own settings, not by gh.

  • gh auth login is the right way to authenticate a CI job
  • gh always keeps its token in plain text in hosts.yml
  • A stored gh login takes priority over GH_TOKEN
  • gh accepts any pasted token without checking its scopes
  • gh picks up the Actions workflow token without any env mapping