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.
--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, 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, 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, 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, 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.
1---
2name: glab-artifact-registry
3description: Exchange GitLab credentials for short-lived Artifact Registry tokens, verify token identity, and configure package-manager authentication with glab. Use when checking GitLab Artifact Registry access, obtaining an ephemeral registry token, or configuring Docker, Maven, Gradle, npm, or sbt for a GitLab Artifact Registry. Triggers on artifact registry, glab artifact-registry, glab ar, get-token, token exchange, registry access status, artifact-registry login, Docker credential helper, Maven registry, Gradle registry, npm auth, sbt credentials.
4metadata:
5 source: https://skillmd.com/skills/vince-winkintel/glab-artifact-registry
6---
7
8# glab artifact-registry
9
10Exchange 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.
11
12## Prerequisites
13
14- GitLab Enterprise Edition 19.1 or later.
15- The instance administrator enabled the `gate_token_exchange_endpoint` feature flag.
16- `glab` is authenticated to the intended hostname.
17
18The 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.
19
20## Check access first
21
22`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.
23
24```bash
25glab artifact-registry status --hostname gitlab.example.com --output json
26
27# Extract only non-secret expiry metadata
28glab artifact-registry status \
29 --hostname gitlab.example.com \
30 --output json \
31 --jq '.expires_at'
32```
33
34Confirm that the issuer, subject, and audience identify the intended instance, actor, and registry before requesting a token for another process.
35
36## Request a short-lived token
37
38Text 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.
39
40```bash
41# Avoid command tracing and keep the token only in a process-local variable
42set +x
43artifact_token="$(glab artifact-registry get-token \
44 --hostname gitlab.example.com \
45 --duration 15m)"
46
47# Feed via stdin, not as a command-line argument. Obtain the registry host and
48# required username from the target registry's documentation or administrator.
49printf '%s' "$artifact_token" | \
50 docker login <artifact-registry-host> \
51 --username '<registry-username>' \
52 --password-stdin
53unset artifact_token
54```
55
56Use `--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.
57
58## Configure package-manager authentication
59
60`glab artifact-registry login` configures exactly one package manager per run:
61
62- `--docker` installs the `docker-credential-glab` shim and registers `glab` under Docker's per-registry `credHelpers`.
63- `--maven` writes a `<server>` block to `~/.m2/settings.xml`, keyed by `--registry-alias`; the consuming `<repository>` must use the same `<id>`.
64- `--gradle` writes `{alias}Url`, `{alias}Username`, and `{alias}Password` to `~/.gradle/gradle.properties`, where `{alias}` is `--registry-alias`.
65- `--npm` writes a `//{host}{path}/:_authToken` entry to `~/.npmrc`; you must still configure `registry=` or `@scope:registry=` to point npm at the registry.
66- `--sbt` writes a `credentials +=` line to `~/.sbt/1.0/credentials.sbt`; sbt installs with a custom global base may not read that file.
67
68```bash
69# Inspect the intended Docker config and stored GitLab identity first
70printf 'Docker config: %s\n' "${DOCKER_CONFIG:-$HOME/.docker}/config.json"
71glab auth status --hostname gitlab.example.com
72
73# Configure only the verified Artifact Registry hostname
74glab artifact-registry login \
75 --hostname gitlab.example.com \
76 --docker \
77 --registry registry.example.com
78
79# Configure Maven for a two-hour token
80glab artifact-registry login \
81 --hostname gitlab.example.com \
82 --maven \
83 --registry https://ar.example.com \
84 --registry-alias gitlab-ar \
85 --duration 2h
86```
87
88Safety and compatibility rules:
89
90- For `--docker`, `--registry` must be a bare hostname, optionally with a port. For Maven, Gradle, npm, and sbt, `--registry` is typically a URL.
91- Docker exchanges a fresh token for every pull or push, so `--duration` does not apply. Maven, Gradle, npm, and sbt receive one static token; rerun the command before `--duration` elapses.
92- 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, and sbt login paths can read `GITLAB_TOKEN` because `glab` writes the exchanged token into each tool's config file.
93- 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.
94- Review the destination config path before writing: `${DOCKER_CONFIG:-$HOME/.docker}/config.json`, `~/.m2/settings.xml`, `~/.gradle/gradle.properties`, `~/.npmrc`, or `~/.sbt/1.0/credentials.sbt`.
95- `--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.
96- 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.
97
98## Troubleshooting
99
100- **Unsupported or not found:** verify GitLab EE 19.1+ and the `gate_token_exchange_endpoint` feature flag with the instance administrator.
101- **Wrong issuer/subject/audience:** stop; re-check `--hostname`, environment-token precedence, and `glab auth status --hostname <host>`.
102- **Duration rejected:** use a Go-style duration between `1s` and `12h`.
103- **Expired token:** request a new short-lived token; do not persist or attempt to refresh the old one.
104- **Stored-token error during Docker setup:** run `glab auth login --hostname <host>`; an environment-only token is not used by the Docker helper.
105- **Credential-helper conflict:** inspect Docker's existing `credHelpers` entry and keep the current helper unless the operator explicitly approves a migration.
106- **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.
107
108See [references/commands.md](references/commands.md) for captured command help.