GitLabgitlab-org

cli

main
ply7 git calls227 ms100 KiB4 cachedprotocol v2
138 lines7.1 KiBRaw

Authenticate with a GitLab instance.

Synopsis

Authenticates with a GitLab instance.

By default, glab stores your credentials in your operating system's keyring (macOS Keychain, Windows Credential Manager, or the Secret Service on Linux) when one is available. If no keyring is available, or if you pass --insecure-storage, glab stores them in the global configuration file (default ~/.config/glab-cli/config.yml) as plaintext instead. After authentication, all glab commands use the stored credentials.

If you previously signed in and your credentials are stored as plaintext in the configuration file, run glab auth login again to move them into the keyring.

In CI (when GITLAB_CI or CI is set), glab stores credentials in the configuration file rather than the keyring. Credentials in CI are usually supplied through environment variables, and an OS keyring is often unavailable there.

If GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, or OAUTH_TOKEN are set, they take precedence over the stored credentials. When CI auto-login is enabled, these variables also override CI_JOB_TOKEN. They apply only to the host named by GITLAB_HOST or GITLAB_REPO, and to hosts in the configuration file.

To pass a token on standard input, use --stdin.

On instances where personal access tokens are disabled, sign in with OAuth and use glab as the Git credential helper instead of Git Credential Manager. glab automatically refreshes the OAuth token for Git and doesn't need an OAuth client secret.

To configure glab as the Git credential helper non-interactively (for example, in a CI/CD job), use --setup-git-credential-helper.

In interactive mode, glab detects GitLab instances from your Git remotes and lists them as options, so you do not have to type the hostname manually.

After you sign in, glab can make the instance your default host, which glab uses outside a Git repository. glab does this automatically when the default is still gitlab.com and you have no gitlab.com credentials. Otherwise, it asks first, or in a non-interactive run prints the glab config set command to run. glab leaves host unchanged in CI, or when GITLAB_HOST, GITLAB_URI, or GL_HOST is set.

When you omit --hostname in a non-interactive run, glab authenticates with the first of these that applies:

  • The host of the base repository, if you're in a Git repository with a GitLab remote.
  • The GITLAB_HOST environment variable, if it's set.
  • The host key in your configuration file, if it's set.
  • gitlab.com, if none of the above apply.
plaintext
glab auth login [flags]

Examples

console
# Start interactive setup
# If in a Git repository, glab detects and suggests GitLab instances from remotes
glab auth login

# Authenticate against `gitlab.com` by reading the token from a file
glab auth login --stdin < myaccesstoken.txt

# Authenticate with GitLab Self-Managed or GitLab Dedicated
glab auth login --hostname salsa.debian.org

# Non-interactive setup
glab auth login --hostname gitlab.example.org --token glpat-xxx --api-host gitlab.example.org:3443 --api-protocol https --git-protocol ssh

# Non-interactive setup reading the token from a file
glab auth login --hostname gitlab.example.org --api-host gitlab.example.org:3443 --api-protocol https --git-protocol ssh --stdin < myaccesstoken.txt

# Semi-interactive OAuth login, skipping all prompts except browser auth
glab auth login --hostname gitlab.com --web --git-protocol ssh --container-registry-domains "gitlab.com,gitlab.com:443,registry.gitlab.com"

# Semi-interactive OAuth login for GitLab Self-Managed, with every
# prompted value supplied by a flag.
glab auth login --hostname gitlab.example.com --web --api-host gitlab.example.com --ssh-hostname gitlab.example.com --api-protocol https --git-protocol ssh --container-registry-domains registry.gitlab.example.com

# OAuth device authorization flow for headless environments without a local browser.
# glab displays a one-time code and verification URL; you authorize on any
# other device with a browser. Requires GitLab 17.9 or later.
glab auth login --hostname gitlab.com --device

# CI/CD setup: for most cases, prefer auto-login over manual login
GLAB_ENABLE_CI_AUTOLOGIN=true glab release list -R $CI_PROJECT_PATH

# CI/CD setup with manual login: use when the command does not support CI job tokens, or you need a personal access token
glab auth login --hostname $CI_SERVER_FQDN --job-token $CI_JOB_TOKEN --api-protocol $CI_SERVER_PROTOCOL

# Non-interactive setup that also lets Git push and pull with the same token
glab auth login --hostname $CI_SERVER_FQDN --token $GITLAB_TOKEN --setup-git-credential-helper

# Sign in with OAuth and configure glab as the Git credential helper (recommended when personal access tokens are disabled)
glab config set client_id <CLIENT_ID> --host gitlab.example.com
glab auth login --hostname gitlab.example.com --web --setup-git-credential-helper

Options

plaintext
  -a, --api-host string                     Hostname for the API endpoint, if different from --hostname. Accepts a hostname or hostname:port. Also skips the API hostname prompt in interactive mode.
  -p, --api-protocol string                 API protocol. Options: https, http.
      --container-registry-domains string   Container registry and image dependency proxy domains, comma-separated.
      --device                              Use the OAuth 2.0 device authorization flow. Useful for headless environments where a local browser is not available. Requires GitLab 17.9 or later.
  -g, --git-protocol string                 Git protocol. Options: ssh, https, http.
      --hostname string                     The hostname of the GitLab instance to authenticate with. When omitted, glab prompts in interactive mode, or uses the host resolved from your Git remotes, GITLAB_HOST, and your configuration.
      --insecure-storage                    Store the token as plaintext in the configuration file instead of the operating system's keyring.
  -j, --job-token string                    CI job token.
      --setup-git-credential-helper         Configure glab as the Git credential helper for this host without prompting. Use this in non-interactive runs, such as CI/CD jobs.
      --ssh-hostname string                 SSH hostname for instances with a different SSH endpoint. A port is not required; Git uses the port from the remote URL. Also skips the SSH hostname prompt in interactive mode.
      --stdin                               Read the token from standard input.
  -t, --token string                        Your GitLab access token.
      --web                                 Skip the login type prompt and use web/OAuth login.

Options inherited from parent commands

plaintext
  -h, --help   Show help for this command.
1---
2title: '`glab auth login`'
3stage: AI Clients
4group: Developer Clients
5info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
6---
8<!--
9This documentation is auto generated by a script.
10Please do not edit this file directly. Run `make gen-docs` instead.
11-->
13Authenticate with a GitLab instance.
15## Synopsis
17Authenticates with a GitLab instance.
19By default, glab stores your credentials in your operating system's
20keyring (macOS Keychain, Windows Credential Manager, or the Secret
21Service on Linux) when one is available. If no keyring is available,
22or if you pass `--insecure-storage`, glab stores them in the global
23configuration file (default `~/.config/glab-cli/config.yml`) as
24plaintext instead. After authentication, all glab commands use the
25stored credentials.
27If you previously signed in and your credentials are stored as
28plaintext in the configuration file, run `glab auth login` again to
29move them into the keyring.
31In CI (when `GITLAB_CI` or `CI` is set), glab stores credentials in the
32configuration file rather than the keyring. Credentials in CI are
33usually supplied through environment variables, and an OS keyring is
34often unavailable there.
36If `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, or `OAUTH_TOKEN` are set,
37they take precedence over the stored credentials. When CI auto-login is
38enabled, these variables also override `CI_JOB_TOKEN`. They apply only
39to the host named by `GITLAB_HOST` or `GITLAB_REPO`, and to hosts in the
40configuration file.
42To pass a token on standard input, use `--stdin`.
44On instances where personal access tokens are disabled, sign in with OAuth and use glab as the Git credential helper instead of Git Credential Manager. glab automatically refreshes the OAuth token for Git and doesn't need an OAuth client secret.
46To configure glab as the Git credential helper non-interactively (for example, in a CI/CD job), use `--setup-git-credential-helper`.
48In interactive mode, glab detects GitLab instances from your Git remotes
49and lists them as options, so you do not have to type the hostname manually.
51After you sign in, glab can make the instance your default `host`, which
52glab uses outside a Git repository. glab does this automatically when the
53default is still `gitlab.com` and you have no `gitlab.com` credentials.
54Otherwise, it asks first, or in a non-interactive run prints the
55`glab config set` command to run. glab leaves `host` unchanged in CI,
56or when `GITLAB_HOST`, `GITLAB_URI`, or `GL_HOST` is set.
58When you omit `--hostname` in a non-interactive run, glab authenticates
59with the first of these that applies:
61- The host of the base repository, if you're in a Git repository with a GitLab remote.
62- The `GITLAB_HOST` environment variable, if it's set.
63- The `host` key in your configuration file, if it's set.
64- `gitlab.com`, if none of the above apply.
66```plaintext
67glab auth login [flags]
68```
70## Examples
72```console
73# Start interactive setup
74# If in a Git repository, glab detects and suggests GitLab instances from remotes
75glab auth login
77# Authenticate against `gitlab.com` by reading the token from a file
78glab auth login --stdin < myaccesstoken.txt
80# Authenticate with GitLab Self-Managed or GitLab Dedicated
81glab auth login --hostname salsa.debian.org
83# Non-interactive setup
84glab auth login --hostname gitlab.example.org --token glpat-xxx --api-host gitlab.example.org:3443 --api-protocol https --git-protocol ssh
86# Non-interactive setup reading the token from a file
87glab auth login --hostname gitlab.example.org --api-host gitlab.example.org:3443 --api-protocol https --git-protocol ssh --stdin < myaccesstoken.txt
89# Semi-interactive OAuth login, skipping all prompts except browser auth
90glab auth login --hostname gitlab.com --web --git-protocol ssh --container-registry-domains "gitlab.com,gitlab.com:443,registry.gitlab.com"
92# Semi-interactive OAuth login for GitLab Self-Managed, with every
93# prompted value supplied by a flag.
94glab auth login --hostname gitlab.example.com --web --api-host gitlab.example.com --ssh-hostname gitlab.example.com --api-protocol https --git-protocol ssh --container-registry-domains registry.gitlab.example.com
96# OAuth device authorization flow for headless environments without a local browser.
97# glab displays a one-time code and verification URL; you authorize on any
98# other device with a browser. Requires GitLab 17.9 or later.
99glab auth login --hostname gitlab.com --device
101# CI/CD setup: for most cases, prefer auto-login over manual login
102GLAB_ENABLE_CI_AUTOLOGIN=true glab release list -R $CI_PROJECT_PATH
104# CI/CD setup with manual login: use when the command does not support CI job tokens, or you need a personal access token
105glab auth login --hostname $CI_SERVER_FQDN --job-token $CI_JOB_TOKEN --api-protocol $CI_SERVER_PROTOCOL
107# Non-interactive setup that also lets Git push and pull with the same token
108glab auth login --hostname $CI_SERVER_FQDN --token $GITLAB_TOKEN --setup-git-credential-helper
110# Sign in with OAuth and configure glab as the Git credential helper (recommended when personal access tokens are disabled)
111glab config set client_id <CLIENT_ID> --host gitlab.example.com
112glab auth login --hostname gitlab.example.com --web --setup-git-credential-helper
114```
116## Options
118```plaintext
119 -a, --api-host string Hostname for the API endpoint, if different from --hostname. Accepts a hostname or hostname:port. Also skips the API hostname prompt in interactive mode.
120 -p, --api-protocol string API protocol. Options: https, http.
121 --container-registry-domains string Container registry and image dependency proxy domains, comma-separated.
122 --device Use the OAuth 2.0 device authorization flow. Useful for headless environments where a local browser is not available. Requires GitLab 17.9 or later.
123 -g, --git-protocol string Git protocol. Options: ssh, https, http.
124 --hostname string The hostname of the GitLab instance to authenticate with. When omitted, glab prompts in interactive mode, or uses the host resolved from your Git remotes, GITLAB_HOST, and your configuration.
125 --insecure-storage Store the token as plaintext in the configuration file instead of the operating system's keyring.
126 -j, --job-token string CI job token.
127 --setup-git-credential-helper Configure glab as the Git credential helper for this host without prompting. Use this in non-interactive runs, such as CI/CD jobs.
128 --ssh-hostname string SSH hostname for instances with a different SSH endpoint. A port is not required; Git uses the port from the remote URL. Also skips the SSH hostname prompt in interactive mode.
129 --stdin Read the token from standard input.
130 -t, --token string Your GitLab access token.
131 --web Skip the login type prompt and use web/OAuth login.
132```
134## Options inherited from parent commands
136```plaintext
137 -h, --help Show help for this command.
138```
Diagnostics7 git calls · 227 ms
CallStatusSizeTime0227 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=UPDATING
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchtree:02001.7 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=1744
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=5e4007a5673eb3bf5d0d7f1a1463c3b2ca3fb3bd
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1744
git.pkt.payload.max=1717
git.sideband.band1.bytes=1717
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1717
git.pack.trailer=3f1b9ccc7756e8941d6705e8187c87fd922113e6
Open pack map
fetchtree:0200301 B · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=301
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=tree:0
git.fetch.wants=a981cfaa946035488dc52df8aaa8fe52e1b75f87
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=301
git.pkt.payload.max=274
git.sideband.band1.bytes=274
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=274
git.pack.trailer=efcfeba9507627dabdf01824d3dd25b963dfcf29
Open pack map
fetch2002.6 KiB216 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=216
git.response.bytes=2649
git.response.cache=MISS
git.response.duration_ms=216
git.fetch.wants=c2a124c0e2fb185720c095f400b89d88254b1ce6
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2649
git.pkt.payload.max=2622
git.sideband.band1.bytes=2622
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e1895a0c3c5e37
Request
0bcd9fd6…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format