Log in to GitHub Safely with gh auth login

The first time you run gh auth login it asks three quiet questions, and getting one wrong sends every later git push down the wrong protocol. This guide authenticates GitHub CLI on Linux, picks the right Git protocol, and verifies which account and host end up active. The examples use gh 2.87.3, installed from the gh package on this machine. Allow about ten minutes for a browser login, a little longer if you need to choose a token and host.

You need a shell, the gh package, and access to the GitHub account or GitHub Enterprise host you intend to use. Login changes local authentication state, so do it as the same Unix user who will run gh. It does not need sudo.

1. Check the installed command

Start with a read-only check. This confirms the executable and the version-specific options before you authenticate:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh auth login --help

The installed help lists browser login, standard-input token login, host selection, Git protocol selection, extra scopes and plain-text storage. If your output differs, follow that installed help and your local man page rather than copying options from another release.

2. Use the normal browser flow

For an interactive workstation, run:

$ gh auth login

The default host is github.com and the default authentication mode is a web-based browser flow. Answer the prompts for host and Git protocol, complete the GitHub authorisation in the browser, and the token is saved in the system credential store when one is available. For the browser path explicitly, use --web:

$ gh auth login --web

3. Verify the account and storage result

After the prompts finish, ask gh to report the active authentication state:

$ gh auth status
github.com
  ✓ Logged in to github.com account YOUR_ACCOUNT (keyring)
  - Active account: true
  - Git operations protocol: https
  - Token scopes: ...

The exact wording depends on account, protocol and credential store. Do not paste the token itself into a report; the useful checks are host, account, active marker, Git protocol and the storage label. If the output says credentials are stored in a plain-text file, fix the credential-store problem or accept that risk deliberately before using the account for sensitive work.

To check a particular host without changing anything, add --hostname:

$ gh auth status --hostname github.com

4. Select HTTPS or SSH deliberately

The Git protocol affects Git operations on the selected host:

• Choose HTTPS if your repository workflow already uses HTTPS credentials.
• Choose SSH if you have an SSH key and want Git remotes to use it.

$ gh auth login --git-protocol https
$ gh auth login --git-protocol ssh

These commands start login if the host is not already authenticated, or ask the questions needed to update the setup. With SSH, gh checks for an existing key and can prompt to create and upload one when none is found.

The protocol setting applies to the host, not just one repository. Check the final choice with gh auth status. To undo an unwanted account login, use the documented logout command for that host:

$ gh auth logout --hostname github.com

Logout removes the local login for the selected host. It does not delete repositories or revoke every token GitHub has issued. Confirm the host before accepting the logout prompt.

5. Log in to GitHub Enterprise Server

Pass the actual GitHub host name when the account is not on github.com:

$ gh auth login --hostname git.example.internal

Replace git.example.internal with the host name used by your organisation. The host must be reachable and must be a GitHub instance. Verify that the status command names the enterprise host, not github.com:

$ gh auth status --hostname git.example.internal

Keep separate host names explicit in scripts and documentation. A successful login to github.com does not authenticate the same command against an enterprise host.

6. Use a token only when the workflow requires it

--with-token reads a token from standard input, so the token does not need to be typed as a command-line argument:

$ gh auth login --with-token < /path/to/token-file

The installed manual documents the minimum scopes for a classic personal access token as repo, read:org and gist. Use a token with only the access the task needs, and keep the file readable only by the intended user:

$ chmod 600 /path/to/token-file
$ gh auth login --with-token < /path/to/token-file
$ unset GH_TOKEN GH_ENTERPRISE_TOKEN

For automation, prefer an environment variable supplied by the job's secret store:

env:
  GH_TOKEN: ${{ github.token }}

For a non-GitHub Actions job, the environment variable must be injected by the runner or secret manager. Do not commit it to a repository. Environment authentication is intended for headless use and avoids writing a local login during the job.

7. Diagnose a failed login

If the command rejects an option, run gh auth login --help and compare it with the command you copied; options are version-specific. If the browser does not open, rerun with --web and complete the displayed device flow in a browser you control. If the host is wrong, repeat the login with an explicit --hostname rather than overwriting credentials for another host.

If gh auth status shows no active account, the login either did not finish or was saved for a different host or Unix user. Check the exact host with --hostname, then retry as the intended user.