GitLabgitlab-org

cli

main
ply6 git calls50 ms103 KiB5 cachedprotocol v2
392 lines18 KiBRaw

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

The GitLab CLI supports several authentication methods: OAuth, personal access tokens, and CI job tokens. To get started, run glab auth login and follow the interactive setup.

When running glab auth login interactively inside a Git repository, glab automatically detects GitLab instances from your Git remotes and presents them as options. This saves you from having to manually type the hostname.

OAuth (GitLab.com)

To authenticate your installation of glab with an OAuth application connected to GitLab.com:

  1. Start interactive setup with glab auth login.
  2. For the GitLab instance you want to sign in to, select GitLab.com.
  3. For the login method, select Web to authenticate through your local browser, or Device for headless environments (such as SSH sessions or containers) where no local browser is available. The device flow displays a one-time code and a verification URL that you open on any other device with a browser.
  4. Authorize the application when prompted.
  5. Complete the authentication process in your terminal, selecting the appropriate options for your needs.

For GitLab.com, glab always uses its built-in OAuth application and ignores client_id and GITLAB_CLIENT_ID.

OAuth (GitLab Self-Managed, GitLab Dedicated)

Prerequisites:

  • You've created an OAuth application at the user, group, or instance level, and you have its application ID. For instructions, see how to configure GitLab as an OAuth 2.0 authentication identity provider in the GitLab documentation.
  • Your OAuth application is configured with these parameters:
    • Redirect URI is http://localhost:7171/auth/redirect. Not required if you only intend to use --device.
    • Confidential is not selected. If it's selected, glab auth login fails with an invalid_client error. For more information, see the troubleshooting section.
    • Scopes are openid, profile, read_user, write_repository, and api.
  • To use the OAuth 2.0 device authorization flow (glab auth login --device), the application must also have device_code in its allowed grant types, and the GitLab instance must be running GitLab 17.9 or later. For more information, see the device authorization grant flow documentation.

To authenticate your installation of glab with an OAuth application connected to your GitLab Self-Managed or GitLab Dedicated instance:

  1. Store the application ID with glab config set client_id <CLIENT_ID> --host <HOSTNAME>. For <CLIENT_ID>, provide your application ID.
  2. Start interactive setup with glab auth login --hostname <HOSTNAME>.
  3. For the login method, select Web to authenticate through your local browser, or Device for headless environments where no local browser is available.
  4. Follow the prompts to authorize the application:
    • For Web, complete authorization in the browser window that opens.
    • For Device, copy the displayed one-time code, open the verification URL on any device with a browser, and approve the request.
  5. Complete the authentication process in your terminal, selecting the appropriate options for your needs.

Personal access token

To authenticate your installation of glab with a personal access token:

  1. Get a GitLab personal access token with at least the api and write_repository scopes. Use the method appropriate for your instance:
    • For GitLab.com, create one at the personal access tokens page.
    • For GitLab Self-Managed and GitLab Dedicated, visit https://gitlab.example.com/-/user_settings/personal_access_tokens/legacy/new?scopes=api,write_repository, modifying gitlab.example.com to match the domain name of your instance. On GitLab 18.8 and earlier that page does not exist; use https://gitlab.example.com/-/user_settings/personal_access_tokens?scopes=api,write_repository instead.
  2. Start interactive setup: glab auth login
  3. Authenticate with the method appropriate for your GitLab instance:
    • For GitLab SaaS, authenticate against gitlab.com by reading the token from a file: glab auth login --stdin < myaccesstoken.txt
    • For GitLab Self-Managed and GitLab Dedicated, authenticate by reading from a file: glab auth login --hostname gitlab.example.com --stdin < myaccesstoken.txt. This will allow you to perform authenticated glab commands against your instance when you are in a Git repository with a remote matching your instance's host. Alternatively, set GITLAB_HOST to direct your command to your instance.
    • Authenticate with token and hostname: glab auth login --hostname gitlab.example.org --token xxxxx Not recommended for shared environments.
    • Credentials are stored in the global configuration file.

Standardize setup across an organization

If you deploy glab to many users, you can set the instance details centrally as environment variables instead of asking each user to run glab config set. Environment variables take precedence over the configuration file, so users cannot drift from your settings, and glab auth login skips the prompt for any value the environment variables supply.

Each user then authenticates with a single command and only has to complete the browser authentication step.

Prerequisites:

Set these variables on each machine, for example through your configuration management tool or a login script:

VariableExamplePurpose
GITLAB_HOSTgitlab.example.comThe instance to sign in to. Without it, glab prompts users to select one of the repository's Git remotes, or gitlab.com.
GITLAB_CLIENT_ID<application ID>Your OAuth application ID. Required for GitLab Self-Managed and GitLab Dedicated.
GITLAB_API_HOSTgitlab.example.comSkips the API hostname prompt. Set it even when it matches GITLAB_HOST.
GITLAB_SSH_HOSTgitlab.example.comSkips the SSH hostname prompt. Set it even when it matches GITLAB_HOST.
GLAB_API_PROTOCOLhttpsSkips the API protocol prompt.
GLAB_GIT_PROTOCOLsshSkips the Git protocol prompt.
GLAB_CONTAINER_REGISTRY_DOMAINSregistry.gitlab.example.comSkips the container registry prompt. Use none if your instance has no container registry.

[!note] The instance is set with GITLAB_HOST. When you set GITLAB_API_HOST and GITLAB_SSH_HOST, they suppress the related prompts but glab does not use those values to set the instance.

Users then run:

shell
glab auth login --web

For headless environments without a local browser, users run this command instead:

shell
glab auth login --device

This approach has the following constraints:

  • A token set through an environment variable is sent only to the host named by GITLAB_HOST or GITLAB_REPO, and to hosts in the configuration file. This approach suits organizations with a single instance. If your users also work against other instances, have them run glab auth login --hostname <HOSTNAME> for each one, which stores per-host settings in the configuration file.
  • On a machine that already has credentials for the host, glab auth login asks the user to confirm re-authentication. No variable or flag suppresses that prompt.

Use personal access tokens

To use personal access tokens instead of OAuth, set GITLAB_HOST, GITLAB_API_HOST, GITLAB_SSH_HOST, GLAB_API_PROTOCOL, GLAB_GIT_PROTOCOL, and GLAB_CONTAINER_REGISTRY_DOMAINS on each machine. Don't set GITLAB_CLIENT_ID because it applies only to OAuth.

Then, each user provides their token in one of two ways:

  • In the environment, as GITLAB_TOKEN. No glab auth login step is needed.
  • Through glab by running glab auth login --stdin < token.txt. glab stores the token in the operating system keyring or in the configuration file.

If a user does both, the environment variable takes precedence and the stored token is ignored. For more information, see token precedence.

CI job token

To authenticate your installation of glab with a CI job token, the glab command must be run in a GitLab CI job. The token is automatically provided by the GitLab Runner through the CI_JOB_TOKEN environment variable.

Endpoints allowing the use of the CI job token are listed in the GitLab documentation.

Auto-login

To enable CI auto-login, set GLAB_ENABLE_CI_AUTOLOGIN=true. When enabled, glab automatically detects if it's running in a GitLab CI job and uses the predefined CI/CD variables to sign in.

shell
GLAB_ENABLE_CI_AUTOLOGIN=true glab release list -R $CI_PROJECT_PATH

The following predefined CI/CD variables are used automatically:

Predefined CI/CD variableEquivalent glab auth login flag
CI_SERVER_FQDN--hostname
CI_JOB_TOKEN--job-token
CI_SERVER_PROTOCOL--api-protocol
CI_SERVER_SHELL_SSH_HOST--ssh-hostname

Manual login

Use manual login when the command does not support CI job tokens, or you need a personal access token:

shell
glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_FQDN --api-protocol $CI_SERVER_PROTOCOL
GITLAB_HOST=$CI_SERVER_FQDN glab release list -R $CI_PROJECT_PATH

Token precedence

For every authenticated command, glab resolves the token to use in this order:

  1. If any of these environment variables are set, including in a CI/CD environment, glab uses the first available, in this order:

    • GITLAB_TOKEN
    • GITLAB_ACCESS_TOKEN
    • OAUTH_TOKEN

    These variables apply only to trusted hosts. A trusted host is the one named by GITLAB_HOST (or the host configuration key, or gitlab.com when neither is set), the host of a GITLAB_REPO URL, or a host in the configuration file. For any other host, such as one named only in a command argument, glab skips them and warns you.

  2. The credentials stored for the host, either in your operating system's keyring or in the configuration file. glab auth login and glab config set token write them there.

  3. If CI/CD auto-login is enabled (GLAB_ENABLE_CI_AUTOLOGIN=true and GITLAB_CI=true), a CI/CD job token (CI_JOB_TOKEN). To use a job token, make sure none of the environment variables above are set in the CI/CD job.

If no token is found, glab sends the request unauthenticated.

Because an environment variable wins over stored credentials, glab auth login warns you when one is set: the token you just stored is not the one later commands use. Run type glab to find the source. An alias such as op plugin run -- glab means a wrapper is injecting it, which is expected. A plain path means it is set in your shell profile or CI/CD configuration, and you should remove it there.

[!note] Do not set GITLAB_TOKEN=$CI_JOB_TOKEN in a CI/CD job. glab sends GITLAB_TOKEN as an access token in the PRIVATE-TOKEN header, which does not accept CI/CD job tokens. Requests fail with 401 Unauthorized, or 404 Not Found on endpoints that support job tokens.

For the full list of variables that configure glab, see environment variables.

Credential storage

By default, glab auth login stores your credentials in the operating system's keyring:

  • macOS: Keychain
  • Windows: Credential Manager
  • Linux: Secret Service (GNOME Keyring, KWallet, and other implementations)

If no keyring is available, if you pass --insecure-storage, or if you use glab in CI/CD environments where GITLAB_CI or CI is set to true, glab stores credentials as plaintext in the configuration file and prints a warning.

To move an existing plaintext token into the keyring later, run glab auth login --hostname <HOSTNAME> again. glab auth status reports where each token is stored and nudges you to migrate when it finds one in plaintext.

Snap installations

The snap package runs under strict confinement, so it cannot reach the Secret Service until the password-manager-service interface is connected.

To connect the interface:

  1. On a fresh install, run:

    shell
    sudo snap connect glab:password-manager-service
  2. Run (or re-run) glab auth login to store your token in the keyring.

Without this connection, glab warns and falls back to plaintext file storage.

Git credential helper

glab can act as the Git credential helper for HTTP and HTTPS remotes on a host. It supplies your stored token to Git and refreshes expired OAuth tokens.

To configure it, run:

shell
glab auth login --hostname <HOSTNAME> --setup-git-credential-helper

Interactive sign-in offers this setup in a prompt. Use the flag instead when no prompt is available, such as in a CI/CD job.

On instances where personal access tokens are disabled, use glab instead of Git Credential Manager. Unlike Git Credential Manager, glab needs no OAuth client secret. On GitLab Self-Managed and GitLab Dedicated, an administrator sets up one OAuth application for all users.

To sign in with OAuth and configure the helper, run:

shell
glab auth login --hostname <HOSTNAME> --web --setup-git-credential-helper

Without a local browser, use --device instead of --web.

Claude Code sandboxing

By default, the Claude Code sandbox allows writes only to the current working directory. Because glab stores credentials elsewhere, it cannot save refreshed OAuth credentials and commands fail until you run glab auth login again. Configure one of the following options to avoid this.

Option 1: Run glab outside the sandbox

Add glab to excludedCommands in the settings.json file for Claude Code:

json
{
  "sandbox": {
    "excludedCommands": ["glab"]
  }
}

When you use this option, glab clones repositories and connects to the hosts you give it without the sandbox's filesystem and network restrictions. Be aware that a compromised or prompt-injected agent could write outside the working directory or send data to an external host.

Option 2: Grant write access to credential storage

Update the settings.json for Claude Code to allow write access to the configuration directory and, on macOS, the login keychain:

json
{
  "sandbox": {
    "filesystem": {
      "allowWrite": [
        "~/Library/Keychains/login.keychain-db*",
        "<CONFIG_DIR>"
      ]
    }
  }
}

Replace <CONFIG_DIR> with the output of glab config path --dir.

The keychain entry applies to macOS only. On Linux, glab reaches the keyring over D-Bus instead of the filesystem, so omit the keychain entry.

Grant write access to the directory rather than the configuration file, and keep the trailing * on the keychain path because both glab and macOS write a temporary file and rename it into place.

When you use this option, glab stays inside the sandbox but gains write access to your whole login keychain and to every command in the sandbox, not just glab. Be aware that keychain items share a single file, so access cannot be narrowed to the credentials glab manages.

Troubleshooting

When authenticating with glab, you might encounter the following issues.

Error: invalid_client during OAuth login

When authenticating with an OAuth application, glab auth login might fail with an error:

plaintext
Oauth2: "invalid_client" "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.".

This happens when the OAuth application has the Confidential option enabled. glab is a public client and cannot keep a client secret, so it authenticates without one. Confidential applications require a client secret, which causes GitLab to reject the request.

To resolve this issue, edit your OAuth application and clear the Confidential checkbox.

After saving the change, run glab auth login again. For the full list of required application settings, see OAuth (GitLab Self-Managed, GitLab Dedicated).

Error: invalid_grant when refreshing credentials

When running an authenticated command, glab might fail with an error:

plaintext
Oauth2: "invalid_grant" "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.".

This means the stored refresh token is no longer valid. Common causes include:

  • You revoked the OAuth application or its authorization.
  • The session expired after a long period of inactivity.
  • A previous refresh did not save the replacement credentials, so the stored token remains the one GitLab already invalidated. This happens when glab cannot write to its credential storage, most often inside a sandbox such as Claude Code.

To resolve this issue, run glab auth login to authenticate again.

If you see this error regularly and you run glab inside a sandbox, fix the write restriction. For details, see Claude Code sandboxing.

1---
2title: Authenticate with GitLab
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{{< details >}}
10- Tier: Free, Premium, Ultimate
11- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
13{{< /details >}}
15The GitLab CLI supports several authentication methods: OAuth, personal access tokens, and
16CI job tokens. To get started, run `glab auth login` and follow the interactive setup.
18When running `glab auth login` interactively inside a Git repository, `glab` automatically
19detects GitLab instances from your Git remotes and presents them as options. This saves you
20from having to manually type the hostname.
22## OAuth (GitLab.com)
24To authenticate your installation of `glab` with an OAuth application connected to GitLab.com:
261. Start interactive setup with `glab auth login`.
271. For the GitLab instance you want to sign in to, select **GitLab.com**.
281. For the login method, select **Web** to authenticate through your local browser, or
29 **Device** for headless environments (such as SSH sessions or containers) where no
30 local browser is available. The device flow displays a one-time code and a
31 verification URL that you open on any other device with a browser.
321. Authorize the application when prompted.
331. Complete the authentication process in your terminal, selecting the appropriate options for your needs.
35For GitLab.com, `glab` always uses its built-in OAuth application and ignores `client_id`
36and `GITLAB_CLIENT_ID`.
38## OAuth (GitLab Self-Managed, GitLab Dedicated)
40Prerequisites:
42- You've created an OAuth application at the user, group, or instance level, and you
43 have its application ID. For instructions, see how to configure GitLab
44 [as an OAuth 2.0 authentication identity provider](https://docs.gitlab.com/integration/oauth_provider/)
45 in the GitLab documentation.
46- Your OAuth application is configured with these parameters:
47 - **Redirect URI** is `http://localhost:7171/auth/redirect`. Not required if you only intend to use `--device`.
48 - **Confidential** is not selected. If it's selected, `glab auth login` fails with an
49 `invalid_client` error. For more information, see the
50 [troubleshooting section](#error-invalid_client-during-oauth-login).
51 - **Scopes** are `openid`, `profile`, `read_user`, `write_repository`, and `api`.
52- To use the OAuth 2.0 device authorization flow (`glab auth login --device`), the application must
53 also have `device_code` in its allowed grant types, and the GitLab instance must be running
54 GitLab 17.9 or later. For more information, see the
55 [device authorization grant flow](https://docs.gitlab.com/api/oauth2/#device-authorization-grant-flow)
56 documentation.
58To authenticate your installation of `glab` with an OAuth application connected
59to your GitLab Self-Managed or GitLab Dedicated instance:
611. Store the application ID with `glab config set client_id <CLIENT_ID> --host <HOSTNAME>`.
62 For `<CLIENT_ID>`, provide your application ID.
631. Start interactive setup with `glab auth login --hostname <HOSTNAME>`.
641. For the login method, select **Web** to authenticate through your local browser, or
65 **Device** for headless environments where no local browser is available.
661. Follow the prompts to authorize the application:
67 - For **Web**, complete authorization in the browser window that opens.
68 - For **Device**, copy the displayed one-time code, open the verification URL on any
69 device with a browser, and approve the request.
701. Complete the authentication process in your terminal, selecting the appropriate options for your needs.
72## Personal access token
74To authenticate your installation of `glab` with a personal access token:
761. Get a GitLab personal access token with at least the `api`
77 and `write_repository` scopes. Use the method appropriate for your instance:
78 - For GitLab.com, create one at the [personal access tokens](https://gitlab.com/-/user_settings/personal_access_tokens/legacy/new?scopes=api%2Cwrite_repository) page.
79 - For GitLab Self-Managed and GitLab Dedicated, visit `https://gitlab.example.com/-/user_settings/personal_access_tokens/legacy/new?scopes=api,write_repository`,
80 modifying `gitlab.example.com` to match the domain name of your instance.
81 On GitLab 18.8 and earlier that page does not exist; use
82 `https://gitlab.example.com/-/user_settings/personal_access_tokens?scopes=api,write_repository` instead.
831. Start interactive setup: `glab auth login`
841. Authenticate with the method appropriate for your GitLab instance:
85 - For GitLab SaaS, authenticate against `gitlab.com` by reading the token
86 from a file: `glab auth login --stdin < myaccesstoken.txt`
87 - For GitLab Self-Managed and GitLab Dedicated, authenticate by reading from a file:
88 `glab auth login --hostname gitlab.example.com --stdin < myaccesstoken.txt`. This will allow you to perform
89 authenticated `glab` commands against your instance when you are in a Git repository with a remote
90 matching your instance's host. Alternatively, set `GITLAB_HOST` to direct your command to your instance.
91 - Authenticate with token and hostname: `glab auth login --hostname gitlab.example.org --token xxxxx`
92 Not recommended for shared environments.
93 - Credentials are stored in the global
94 [configuration file](configuration.md#configuration-file-locations).
96## Standardize setup across an organization
98If you deploy `glab` to many users, you can set the instance details centrally as
99[environment variables](configuration.md#environment-variables) instead of asking
100each user to run `glab config set`. Environment variables take precedence over the
101configuration file, so users cannot drift from your settings, and `glab auth login`
102skips the prompt for any value the environment variables supply.
104Each user then authenticates with a single command and only has to complete the browser authentication step.
106Prerequisites:
108- An OAuth application for your instance, as described in
109 [OAuth (GitLab Self-Managed, GitLab Dedicated)](#oauth-gitlab-self-managed-gitlab-dedicated).
111Set these variables on each machine, for example through your configuration
112management tool or a login script:
114| Variable | Example | Purpose |
115|----------|---------|---------|
116| `GITLAB_HOST` | `gitlab.example.com` | The instance to sign in to. Without it, `glab` prompts users to select one of the repository's Git remotes, or `gitlab.com`. |
117| `GITLAB_CLIENT_ID` | `<application ID>` | Your OAuth application ID. Required for GitLab Self-Managed and GitLab Dedicated. |
118| `GITLAB_API_HOST` | `gitlab.example.com` | Skips the API hostname prompt. Set it even when it matches `GITLAB_HOST`. |
119| `GITLAB_SSH_HOST` | `gitlab.example.com` | Skips the SSH hostname prompt. Set it even when it matches `GITLAB_HOST`. |
120| `GLAB_API_PROTOCOL` | `https` | Skips the API protocol prompt. |
121| `GLAB_GIT_PROTOCOL` | `ssh` | Skips the Git protocol prompt. |
122| `GLAB_CONTAINER_REGISTRY_DOMAINS` | `registry.gitlab.example.com` | Skips the container registry prompt. Use `none` if your instance has no container registry. |
124> [!note]
125> The instance is set with `GITLAB_HOST`.
126> When you set `GITLAB_API_HOST` and `GITLAB_SSH_HOST`, they suppress the related prompts but `glab`
127> does not use those values to set the instance.
129Users then run:
131```shell
132glab auth login --web
133```
135For headless environments without a local browser, users run this command instead:
137```shell
138glab auth login --device
139```
141This approach has the following constraints:
143- A token set through an environment variable is sent only to the host named by
144 `GITLAB_HOST` or `GITLAB_REPO`, and to hosts in the configuration file. This approach suits
145 organizations with a single instance. If your users also work against other instances,
146 have them run `glab auth login --hostname <HOSTNAME>` for each one, which stores
147 per-host settings in the configuration file.
148- On a machine that already has credentials for the host, `glab auth login` asks the user
149 to confirm re-authentication. No variable or flag suppresses that prompt.
151### Use personal access tokens
153To use personal access tokens instead of OAuth, set `GITLAB_HOST`, `GITLAB_API_HOST`, `GITLAB_SSH_HOST`, `GLAB_API_PROTOCOL`, `GLAB_GIT_PROTOCOL`, and `GLAB_CONTAINER_REGISTRY_DOMAINS` on each machine. Don't set `GITLAB_CLIENT_ID` because it applies only to OAuth.
155Then, each user provides their token in one of two ways:
157- In the environment, as `GITLAB_TOKEN`. No `glab auth login` step is needed.
158- Through `glab` by running `glab auth login --stdin < token.txt`. `glab` stores the
159 token in the operating system keyring or in the configuration file.
161If a user does both, the environment variable takes precedence and the stored token
162is ignored. For more information, see [token precedence](#token-precedence).
164## CI job token
166To authenticate your installation of `glab` with a CI job token, the `glab` command must be run in a GitLab CI job.
167The token is automatically provided by the GitLab Runner through the `CI_JOB_TOKEN` environment variable.
169Endpoints allowing the use of the CI job token are listed in the
170[GitLab documentation](https://docs.gitlab.com/ci/jobs/ci_job_token/#job-token-access).
172### Auto-login
174To enable CI auto-login, set `GLAB_ENABLE_CI_AUTOLOGIN=true`. When enabled, `glab` automatically
175detects if it's running in a GitLab CI job and uses the predefined CI/CD variables to sign in.
177```shell
178GLAB_ENABLE_CI_AUTOLOGIN=true glab release list -R $CI_PROJECT_PATH
179```
181The following predefined CI/CD variables are used automatically:
183| Predefined CI/CD variable | Equivalent `glab auth login` flag |
184|----------------------------|-----------------------------------|
185| `CI_SERVER_FQDN` | `--hostname` |
186| `CI_JOB_TOKEN` | `--job-token` |
187| `CI_SERVER_PROTOCOL` | `--api-protocol` |
188| `CI_SERVER_SHELL_SSH_HOST` | `--ssh-hostname` |
190### Manual login
192Use manual login when the command does not support CI job tokens, or you need a personal access token:
194```shell
195glab auth login --job-token $CI_JOB_TOKEN --hostname $CI_SERVER_FQDN --api-protocol $CI_SERVER_PROTOCOL
196GITLAB_HOST=$CI_SERVER_FQDN glab release list -R $CI_PROJECT_PATH
197```
199## Token precedence
201For every authenticated command, `glab` resolves the token to use in this order:
2031. If any of these environment variables are set, including in a CI/CD environment,
204 `glab` uses the first available, in this order:
205 - `GITLAB_TOKEN`
206 - `GITLAB_ACCESS_TOKEN`
207 - `OAUTH_TOKEN`
209 These variables apply only to trusted hosts. A trusted host is the one named by
210 `GITLAB_HOST` (or the `host` configuration key, or `gitlab.com` when neither is set),
211 the host of a `GITLAB_REPO` URL, or a host in the configuration file. For any other
212 host, such as one named only in a command argument, `glab` skips them and warns you.
2131. The credentials stored for the host, either in your operating system's keyring or in the
214 [configuration file](configuration.md#configuration-file-locations).
215 `glab auth login` and `glab config set token` write them there.
2161. If CI/CD auto-login is enabled (`GLAB_ENABLE_CI_AUTOLOGIN=true` and `GITLAB_CI=true`),
217 a CI/CD job token (`CI_JOB_TOKEN`). To use a job token, make sure none of the
218 environment variables above are set in the CI/CD job.
220If no token is found, `glab` sends the request unauthenticated.
222Because an environment variable wins over stored credentials, `glab auth login` warns you
223when one is set: the token you just stored is not the one later commands use. Run
224`type glab` to find the source. An alias such as `op plugin run -- glab` means a wrapper
225is injecting it, which is expected. A plain path means it is set in your shell profile or
226CI/CD configuration, and you should remove it there.
228> [!note]
229> Do not set `GITLAB_TOKEN=$CI_JOB_TOKEN` in a CI/CD job. `glab` sends `GITLAB_TOKEN` as an
230> access token in the `PRIVATE-TOKEN` header, which does not accept CI/CD job tokens.
231> Requests fail with `401 Unauthorized`, or `404 Not Found` on endpoints that support job tokens.
233For the full list of variables that configure `glab`, see
234[environment variables](configuration.md#environment-variables).
236## Credential storage
238By default, `glab auth login` stores your credentials in the operating system's
239keyring:
241- macOS: Keychain
242- Windows: Credential Manager
243- Linux: Secret Service (GNOME Keyring, KWallet, and other implementations)
245If no keyring is available, if you pass `--insecure-storage`, or if you use `glab` in CI/CD
246environments where `GITLAB_CI` or `CI` is set to `true`, `glab` stores credentials as plaintext in the
247[configuration file](configuration.md#configuration-file-locations) and prints a warning.
249To move an existing plaintext token into the keyring later, run
250`glab auth login --hostname <HOSTNAME>` again. `glab auth status` reports where
251each token is stored and nudges you to migrate when it finds one in plaintext.
253### Snap installations
255The snap package runs under strict confinement, so it cannot reach the Secret
256Service until the `password-manager-service` interface is connected.
258To connect the interface:
2601. On a fresh install, run:
262 ```shell
263 sudo snap connect glab:password-manager-service
264 ```
2661. Run (or re-run) `glab auth login` to store your token in the keyring.
268Without this connection, `glab` warns and falls back to plaintext file storage.
270## Git credential helper
272`glab` can act as the Git credential helper for HTTP and HTTPS remotes on a host. It supplies
273your stored token to Git and refreshes expired OAuth tokens.
275To configure it, run:
277```shell
278glab auth login --hostname <HOSTNAME> --setup-git-credential-helper
279```
281Interactive sign-in offers this setup in a prompt. Use the flag instead when no prompt is
282available, such as in a CI/CD job.
284On instances where personal access tokens are disabled, use `glab` instead of Git Credential Manager.
285Unlike Git Credential Manager, `glab` needs no OAuth client secret. On GitLab Self-Managed and
286GitLab Dedicated, an administrator sets up one
287[OAuth application](#oauth-gitlab-self-managed-gitlab-dedicated) for all users.
289To sign in with OAuth and configure the helper, run:
291```shell
292glab auth login --hostname <HOSTNAME> --web --setup-git-credential-helper
293```
295Without a local browser, use `--device` instead of `--web`.
297## Claude Code sandboxing
299By default, the Claude Code sandbox allows writes only to the current working directory.
300Because `glab` stores credentials elsewhere, it cannot save refreshed OAuth credentials
301and commands fail until you run `glab auth login` again.
302Configure one of the following options to avoid this.
304### Option 1: Run `glab` outside the sandbox
306Add `glab` to `excludedCommands` in the `settings.json` file for Claude Code:
308```json
310 "sandbox": {
311 "excludedCommands": ["glab"]
312 }
314```
316When you use this option, `glab` clones repositories and connects to the hosts you give it without
317the sandbox's filesystem and network restrictions.
318Be aware that a compromised or prompt-injected agent could write outside the working directory or
319send data to an external host.
321### Option 2: Grant write access to credential storage
323Update the `settings.json` for Claude Code to allow write access to the configuration directory and, on macOS, the login keychain:
325```json
327 "sandbox": {
328 "filesystem": {
329 "allowWrite": [
330 "~/Library/Keychains/login.keychain-db*",
331 "<CONFIG_DIR>"
332 ]
333 }
334 }
336```
338Replace `<CONFIG_DIR>` with the output of `glab config path --dir`.
340The keychain entry applies to macOS only. On Linux, `glab` reaches the keyring over D-Bus
341instead of the filesystem, so omit the keychain entry.
343Grant write access to the directory rather than the configuration file, and keep the trailing `*` on
344the keychain path because both `glab` and macOS write a temporary file and rename it into place.
346When you use this option, `glab` stays inside the sandbox but gains write access to your whole login
347keychain and to every command in the sandbox, not just `glab`.
348Be aware that keychain items share a single file, so access cannot be narrowed to the credentials
349`glab` manages.
351## Troubleshooting
353When authenticating with `glab`, you might encounter the following issues.
355### Error: `invalid_client` during OAuth login
357When authenticating with an OAuth application, `glab auth login` might fail with an error:
359```plaintext
360Oauth2: "invalid_client" "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method.".
361```
363This happens when the OAuth application has the **Confidential** option enabled. `glab` is a
364public client and cannot keep a client secret, so it authenticates without one. Confidential
365applications require a client secret, which causes GitLab to reject the request.
367To resolve this issue, edit your OAuth application and clear the **Confidential** checkbox.
369After saving the change, run `glab auth login` again. For the full list of required application
370settings, see [OAuth (GitLab Self-Managed, GitLab Dedicated)](#oauth-gitlab-self-managed-gitlab-dedicated).
372### Error: `invalid_grant` when refreshing credentials
374When running an authenticated command, `glab` might fail with an error:
376```plaintext
377Oauth2: "invalid_grant" "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.".
378```
380This means the stored refresh token is no longer valid. Common causes include:
382- You revoked the OAuth application or its authorization.
383- The session expired after a long period of inactivity.
384- A previous refresh did not save the replacement credentials, so the stored token
385 remains the one GitLab already invalidated. This happens when `glab` cannot write to
386 its credential storage, most often inside a sandbox such as Claude Code.
388To resolve this issue, run `glab auth login` to authenticate again.
390If you see this error regularly and you run `glab` inside a sandbox, fix the write restriction.
391For details, see
392[Claude Code sandboxing](#claude-code-sandboxing).
Diagnostics6 git calls · 50 ms
CallStatusSizeTime050 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 KiB · hit3 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=HIT
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 · hit3 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=1744
git.response.cache=HIT
git.response.duration_ms=3
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
fetch2006.1 KiB · hit42 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=41
git.response.bytes=6283
git.response.cache=HIT
git.response.duration_ms=42
git.fetch.wants=0ebe81a83f46c7389b03f70dc10929de117785f3
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=6283
git.pkt.payload.max=6256
git.sideband.band1.bytes=6256
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
a5e1181cbbd75e37
Request
f6e8753c…
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