glab-artifact-registry

glab artifact-registry

Exchange the active GitLab credential for a short-lived Artifact Registry access token. The command group also accepts the glab ar alias. This command group is experimental; verify live help and the target GitLab instance before using it in durable automation.

Prerequisites

• GitLab Enterprise Edition 19.1 or later.
• The instance administrator enabled the gate_token_exchange_endpoint feature flag.
• glab is authenticated to the intended hostname.

The token is ephemeral but still a credential. Never print it in logs, store it in a repository, include it in command arguments, or paste it into issue/MR content.

Check access first

status performs the token exchange and prints non-secret identity metadata: issuer, subject, audience, and expiry. Each check mints and immediately discards a server-side token; prefer JSON for automation and do not call it in a tight loop.

glab artifact-registry status --hostname gitlab.example.com --output json

# Extract only non-secret expiry metadata
glab artifact-registry status \
  --hostname gitlab.example.com \
  --output json \
  --jq '.expires_at'

Confirm that the issuer, subject, and audience identify the intended instance, actor, and registry before requesting a token for another process.

Request a short-lived token

Text output is the bare token on stdout so a shell can capture or pipe it. Default duration is 15 minutes; accepted durations range from 1 second through 12 hours. Use the shortest duration that covers the operation.

# Avoid command tracing and keep the token only in a process-local variable
set +x
artifact_token="$(glab artifact-registry get-token \
  --hostname gitlab.example.com \
  --duration 15m)"

# Feed via stdin, not as a command-line argument. Obtain the registry host and
# required username from the target registry's documentation or administrator.
printf '%s' "$artifact_token" | \
  docker login <artifact-registry-host> \
    --username '<registry-username>' \
    --password-stdin
unset artifact_token

Use --output json only when a consumer also needs the expiry. Treat the JSON document as secret because it contains the token. Do not pass --jq expressions that print the token into logs.

Configure package-manager authentication

glab artifact-registry login configures exactly one package manager per run:

• --docker installs the docker-credential-glab shim and registers glab under Docker's per-registry credHelpers.
• --maven writes a <server> block to ~/.m2/settings.xml, keyed by --registry-alias; the consuming <repository> must use the same <id>.
• --gradle writes {alias}Url, {alias}Username, and {alias}Password to ~/.gradle/gradle.properties, where {alias} is --registry-alias.
• --npm writes a //{host}{path}/:_authToken entry to ~/.npmrc; you must still configure registry= or @scope:registry= to point npm at the registry.
• --yarn configures Yarn 2 or later in ~/.yarnrc.yml: an npmRegistries entry holds npmAuthToken and npmAlwaysAuth. Set a matching npmRegistryServer separately. For Yarn 1 use --npm. Existing npmScopes credentials can override the registry token; inspect the warning and review the scope before changing it. Rewriting YAML can change formatting.
• --sbt writes a credentials += line to ~/.sbt/1.0/credentials.sbt; sbt installs with a custom global base may not read that file.

# Inspect the intended Docker config and stored GitLab identity first
printf 'Docker config: %s\n' "${DOCKER_CONFIG:-$HOME/.docker}/config.json"
glab auth status --hostname gitlab.example.com

# Configure only the verified Artifact Registry hostname
glab artifact-registry login \
  --hostname gitlab.example.com \
  --docker \
  --registry registry.example.com

# Configure Maven for a two-hour token
glab artifact-registry login \
  --hostname gitlab.example.com \
  --maven \
  --registry https://ar.example.com \
  --registry-alias gitlab-ar \
  --duration 2h

Safety and compatibility rules:

• For --docker, --registry must be a bare hostname, optionally with a port. For Maven, Gradle, npm, Yarn, and sbt, --registry is typically a URL.
• Docker exchanges a fresh token for every pull or push, so --duration does not apply. Maven, Gradle, npm, Yarn, and sbt receive one static token; rerun the command before --duration elapses.
• The Docker helper subprocess intentionally ignores GITLAB_TOKEN. It normally reads a token stored by glab auth login; inside a GitLab CI job, it also honors CI_JOB_TOKEN when CI auto-login is enabled with GLAB_ENABLE_CI_AUTOLOGIN=true. Maven, Gradle, npm, Yarn, and sbt login paths can read GITLAB_TOKEN because glab writes the exchanged token into each tool's config file.
• Use this only for a registry actually backed by GitLab Artifact Registry. Misclassifying a normal container registry can make every pull fail because an exchanged Artifact Registry token takes precedence.
• Review the destination config path before writing: ${DOCKER_CONFIG:-$HOME/.docker}/config.json, ~/.m2/settings.xml, ~/.gradle/gradle.properties, ~/.npmrc, ~/.yarnrc.yml, or ~/.sbt/1.0/credentials.sbt.
• --registry-alias applies only to Maven and Gradle. For Gradle, choose an alias that is a valid identifier in the build script; the derived default can contain hyphens.
• Re-running the command for the same registry refreshes or replaces the matching entry. After configuration, test a non-destructive package-manager operation against the intended host without printing credentials.

Troubleshooting

• Unsupported or not found: verify GitLab EE 19.1+ and the gate_token_exchange_endpoint feature flag with the instance administrator.
• Wrong issuer/subject/audience: stop; re-check --hostname, environment-token precedence, and glab auth status --hostname <host>.
• Duration rejected: use a Go-style duration between 1s and 12h.
• Expired token: request a new short-lived token; do not persist or attempt to refresh the old one.
• Stored-token error during Docker setup: run glab auth login --hostname <host>; an environment-only token is not used by the Docker helper.
• Credential-helper conflict: inspect Docker's existing credHelpers entry and keep the current helper unless the operator explicitly approves a migration.
• Build tool still unauthenticated: verify the tool reads the file that glab artifact-registry login wrote, and that its registry URL or repository ID matches the written key.

See references/commands.md for captured command help.