Authenticate with artifact registry

Authentication with artifact registry requires a special artifact registry token. Standard GitLab authentication methods are not supported.

Specific authentication steps vary based on your package manager and package client.

Authentication workflow

You authenticate to artifact registry with your package client and a supported GitLab token:

1. The client uses your GitLab token to request an artifact registry token from GitLab.
2. GitLab returns the artifact registry token to the client.
3. The client sends the token to artifact registry in every request.
4. Artifact registry verifies the token’s signature.

During this exchange, artifact registry never calls back to GitLab.

If your account belongs to more than one organization that uses artifact registry, the token exchange returns a 409 Conflict error. GitLab chooses the organization from your memberships and does not guess between the two. For more information, see Troubleshooting Artifact Registry.

Supported GitLab tokens

Artifact registry accepts the following GitLab tokens for authentication:

• Fine-grained personal access tokens
• Legacy personal access tokens
• Project access tokens
• Group access tokens
• CI/CD job tokens
• OAuth tokens

Artifact registry does not require specific scopes for GitLab tokens. When artifact registry receives an artifact registry token, it retrieves the user’s identity and evaluates it against the registry’s role assignments before it authorizes or denies a request.

Deploy tokens are not supported.

Token lifetime

The token exchange endpoint issues a five-minute token by default. The GitLab CLI suggests a 15-minute expiry time for the token, but you can set it up to 12 hours.

A token cannot be revoked before it expires. Ask for the shortest lifetime your build requires.

Authenticate with artifact registry and the GitLab CLI

The GitLab CLI exchanges your GitLab token for a short-lived access token scoped to artifact registry.

Prerequisites:

• Install the GitLab CLI, version 1.115.0 or later.

To authenticate with artifact registry with the GitLab CLI, run the following commands:

1. Get an artifact registry token:

   # Prints a token to stdout so a shell can capture it directly
   glab artifact-registry get-token --duration <1h>

   • If not included, --duration defaults to five minutes.

2. Log in with your package client:

   # Writes the generated token into the configuration file for your package manager
   glab artifact-registry login --<package_format> --registry <registry>

   • For <package_format>, enter a supported package manager. For example, maven.
   • For <registry>, enter the value your format expects:
     • For --docker, enter a bare hostname, such as ar.example.com. The Docker credential helper stores credentials by hostname, so a URL does not work.
     • For every other format, enter the repository URL, such as https://ar.example.com/acme/maven/my-repo.

   Maven and Gradle also take --registry-alias <alias>. For the exact command for your tool, see artifact registry formats.

3. Check artifact registry access status:

   glab artifact-registry status

Running glab artifact-registry login --docker registers glab as a Docker credential helper. Docker ignores the GITLAB_TOKEN environment variable and refreshes the artifact registry token on every pull and push request. Run glab auth login first if you use --docker and have no stored credential for the host.

Every other flag reads the GITLAB_TOKEN environment variable instead. A CI/CD job that sets GITLAB_TOKEN does not require glab auth login first.

These commands are experiments. Their names and flags can change.

For more information about glab commands and flags for artifact registry, see glab artifact-registry.

Package client authentication methods

The Private-Token header used in the GitLab Maven package registry is not supported. Custom header authentication is also not supported.

Configure your package manager

The GitLab CLI writes the credential into your package manager’s configuration file. The exact command depends on the format:

• Maven, Gradle, and sbt
• npm, yarn, and pnpm
• Docker
• OCI

Troubleshooting

If your client gets a 401 or 403 response during authentication, see Troubleshooting Artifact Registry.