--- title: Authenticate with GitLab stage: AI Clients group: Developer Clients info: To determine the technical writer assigned to the Stage/Group associated with this page, see --- {{< 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`. 1. For the GitLab instance you want to sign in to, select **GitLab.com**. 1. 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. 1. Authorize the application when prompted. 1. 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](https://docs.gitlab.com/integration/oauth_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](#error-invalid_client-during-oauth-login). - **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](https://docs.gitlab.com/api/oauth2/#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 --host `. For ``, provide your application ID. 1. Start interactive setup with `glab auth login --hostname `. 1. For the login method, select **Web** to authenticate through your local browser, or **Device** for headless environments where no local browser is available. 1. 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. 1. 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](https://gitlab.com/-/user_settings/personal_access_tokens/legacy/new?scopes=api%2Cwrite_repository) 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. 1. Start interactive setup: `glab auth login` 1. 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](configuration.md#configuration-file-locations). ## Standardize setup across an organization If you deploy `glab` to many users, you can set the instance details centrally as [environment variables](configuration.md#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: - An OAuth application for your instance, as described in [OAuth (GitLab Self-Managed, GitLab Dedicated)](#oauth-gitlab-self-managed-gitlab-dedicated). Set these variables on each machine, for example through your configuration management tool or a login script: | Variable | Example | Purpose | |----------|---------|---------| | `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`. | | `GITLAB_CLIENT_ID` | `` | Your OAuth application ID. Required for GitLab Self-Managed and GitLab Dedicated. | | `GITLAB_API_HOST` | `gitlab.example.com` | Skips the API hostname prompt. Set it even when it matches `GITLAB_HOST`. | | `GITLAB_SSH_HOST` | `gitlab.example.com` | Skips the SSH hostname prompt. Set it even when it matches `GITLAB_HOST`. | | `GLAB_API_PROTOCOL` | `https` | Skips the API protocol prompt. | | `GLAB_GIT_PROTOCOL` | `ssh` | Skips the Git protocol prompt. | | `GLAB_CONTAINER_REGISTRY_DOMAINS` | `registry.gitlab.example.com` | Skips 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 ` 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](#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](https://docs.gitlab.com/ci/jobs/ci_job_token/#job-token-access). ### 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 variable | Equivalent `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. 1. The credentials stored for the host, either in your operating system's keyring or in the [configuration file](configuration.md#configuration-file-locations). `glab auth login` and `glab config set token` write them there. 1. 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](configuration.md#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](configuration.md#configuration-file-locations) and prints a warning. To move an existing plaintext token into the keyring later, run `glab auth login --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 ``` 1. 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 --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](#oauth-gitlab-self-managed-gitlab-dedicated) for all users. To sign in with OAuth and configure the helper, run: ```shell glab auth login --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*", "" ] } } } ``` Replace `` 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)](#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](#claude-code-sandboxing).