gh auth login Command Reference

By Kaveh Alemi·Latchkey

Authenticate the GitHub CLI so later gh commands can call the API.

gh auth login signs the GitHub CLI in to a host. In CI you authenticate non-interactively with a token rather than the interactive web flow.

What it does

gh auth login establishes credentials for a GitHub host. Interactively it offers a browser or token flow; in automation you pipe a token to it or simply set GH_TOKEN, which gh reads directly without an explicit login.

Common flags and usage

--with-token: read an auth token from stdin (non-interactive)
--hostname HOST: target GitHub Enterprise Server
--git-protocol https|ssh: protocol for git operations
GH_TOKEN / GITHUB_TOKEN env var: gh uses it directly, no login needed

Example

shell

- name: Authenticate gh
  run: echo "${{ secrets.GH_PAT }}" | gh auth login --with-token

In CI

The simplest path on GitHub Actions is to set env GH_TOKEN to the workflow token; gh then works with no login step. Use gh auth login --with-token when you need a different identity than the default GITHUB_TOKEN.

Using this in CI

Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.

Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange id-token: write for cloud credentials with no stored secret.
Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
Set the output format explicitly (--output json) rather than relying on the default, which can differ by version and configuration profile.

Key takeaways

Pipe a token to gh auth login --with-token for non-interactive auth.
Setting GH_TOKEN lets gh work with no explicit login step.
Use --hostname for GitHub Enterprise Server targets.

Frequently asked questions

gh auth login Command Reference?