GitLabgitlab-org

cli

main
ply7 git calls35 ms100 KiB6 cachedprotocol v2
161 lines7.6 KiBRaw

Authenticate a package manager against the GitLab Artifact Registry. (EXPERIMENTAL)

Synopsis

Configure a package manager to authenticate against the GitLab Artifact Registry, using a short-lived access token exchanged from your GitLab session.

Use the flag for your package manager:

  • --docker: registers glab as a Docker credential helper for the registry.
  • --maven: writes a <server> block in ~/.m2/settings.xml, or --config-file, keyed by --registry-alias. Reference it from a <repository> carrying the same <id>. The token is written in plain text, so keep a --config-file out of version control.
  • --gradle: writes {alias}Url, {alias}Username, and {alias}Password in ~/.gradle/gradle.properties, where {alias} is --registry-alias.
  • --npm: writes a //{host}{path}/:_authToken entry in ~/.npmrc. You still need to point npm at the registry, with a registry= or @scope:registry= line.
  • --yarn: writes an npmRegistries entry with npmAuthToken and npmAlwaysAuth in ~/.yarnrc.yml, for Yarn 2 and later. Set an npmRegistryServer that matches --registry. Rewriting the file can change its formatting, like indentation, blank lines, and line endings.
  • --sbt: writes a credentials += line in ~/.sbt/1.0/credentials.sbt, which sbt 1.x reads, and the same line in 2/credentials.sbt in the sbt 2.x global base, which sbt 2.x reads. That base is ~/.config/sbt, or %LOCALAPPDATA%\sbt on Windows, unless SBT_CONFIG_HOME or XDG_CONFIG_HOME moves it. On Windows it also writes %LOCALAPPDATA%\sbt\credentials.sbt. The sbt.bat of sbt 2.x points every build it starts, on either version, at that file only, even when SBT_CONFIG_HOME is set. The sbt.version in a project's project/build.properties decides which file its build reads. An sbt started with any other -Dsbt.global.base reads none of them. An sbt shell or sbt 2.x server that is already running keeps the credentials it loaded, so run reload in it, or sbt shutdown, after you log in. To write a different file, pass it with --config-file. It must be a .sbt file that sbt loads, not a properties file such as ~/.sbt/.credentials.

Token lifetime:

  • --docker exchanges a fresh token on every pull or push, so --duration does not apply.
  • Every other flag writes one token, and nothing refreshes it. Run the command again before --duration elapses. The default is 15 minutes and the maximum is 12 hours.

Credential resolution:

  • Docker runs the credential helper as its own subprocess, which reads your credentials from the configuration file and ignores GITLAB_TOKEN. This command verifies the login the same way, so run glab auth login first if no token is stored for the host.
  • Every other flag does read GITLAB_TOKEN. glab writes the token into each file itself, so the tool can read it without fetching credentials itself.

Registry and alias selection:

  • Use --registry only for a registry the Artifact Registry actually backs. If you name a container registry here, it receives the wrong token and the error only surfaces on the next pull.
  • --registry-alias applies to --maven and --gradle only, because --npm, --sbt, and --yarn key their entries on --registry itself. For --gradle, use an alias that is a valid identifier in your build script: the default is derived from the registry host and contains hyphens, which Groovy cannot interpolate as ${...}.

This feature is an experiment and is not ready for production use. It might be unstable or removed at any time. For more information, see https://docs.gitlab.com/policy/development_stages_support/.

plaintext
glab artifact-registry login [flags]

Examples

console
# Configure Docker to authenticate against a registry
glab artifact-registry login --docker --registry registry.example.com

# Configure Maven to authenticate against a registry for two hours
glab artifact-registry login --maven --registry https://ar.example.com --duration 2h

# Configure Gradle to authenticate against a registry for two hours
glab artifact-registry login --gradle --registry https://ar.example.com --duration 2h

# Configure npm to authenticate against a registry for two hours
glab artifact-registry login --npm --registry https://ar.example.com --duration 2h

# Configure Yarn 2 or later to authenticate against a registry for two hours
glab artifact-registry login --yarn --registry https://ar.example.com --duration 2h

# Configure sbt to authenticate against a registry for two hours
glab artifact-registry login --sbt --registry https://ar.example.com --duration 2h

# Configure Maven through a settings.xml passed to mvn with -s
glab artifact-registry login --maven --registry https://ar.example.com --config-file ~/.m2/ci-settings.xml

Environment variables

plaintext
DOCKER_CONFIG: the directory holding Docker's config.json, written by --docker. Defaults to ~/.docker.
GRADLE_USER_HOME: the directory holding gradle.properties, written by --gradle. Defaults to ~/.gradle.
npm_config_userconfig: the .npmrc written by --npm. Defaults to ~/.npmrc.
SBT_CONFIG_HOME: the sbt 2.x global base; --sbt writes 2/credentials.sbt in it. Defaults to $XDG_CONFIG_HOME/sbt, else ~/.config/sbt. On Windows, the sbt.bat of sbt 2.x overrides it with %LOCALAPPDATA%\sbt. --sbt skips a blank or relative value of this variable and the next two.
XDG_CONFIG_HOME: used by --sbt for the sbt 2.x base when SBT_CONFIG_HOME is unset. Not read on Windows.
LOCALAPPDATA: on Windows, used by --sbt in place of XDG_CONFIG_HOME, and for the base the sbt.bat of sbt 2.x passes.

Options

plaintext
      --config-file string      File to write (Maven/sbt only). Defaults to ~/.m2/settings.xml for --maven and the sbt 1.x and 2.x global bases for --sbt, where it replaces every file --sbt writes.
      --docker                  Configure Docker to authenticate against the registry. Writes to $DOCKER_CONFIG, or ~/.docker when it is unset.
      --duration duration       How long the exchanged token should remain valid. Ignored for --docker. (default 15m0s)
      --gradle                  Configure Gradle to authenticate against the registry. Writes to ~/.gradle/gradle.properties.
      --hostname string         GitLab hostname to request the token from. Defaults to the configured GitLab instance.
      --maven                   Configure Maven to authenticate against the registry. Writes to ~/.m2/settings.xml.
      --npm                     Configure npm to authenticate against the registry. Writes to ~/.npmrc.
      --registry string         Registry to authenticate against. For --docker, a bare hostname; for others, typically a URL.
      --registry-alias string   Alias/ID to register the registry under (Maven/Gradle only). Defaults to a name derived from --registry.
      --sbt                     Configure sbt to authenticate against the registry. Writes credentials.sbt to the sbt 1.x and 2.x global bases.
      --yarn                    Configure Yarn 2 or later to authenticate against the registry. Writes to ~/.yarnrc.yml. For Yarn 1, use --npm.

Options inherited from parent commands

plaintext
  -h, --help   Show help for this command.
1---
2title: '`glab artifact-registry login`'
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<!--
9This documentation is auto generated by a script.
10Please do not edit this file directly. Run `make gen-docs` instead.
11-->
13Authenticate a package manager against the GitLab Artifact Registry. (EXPERIMENTAL)
15## Synopsis
17Configure a package manager to authenticate against the GitLab Artifact
18Registry, using a short-lived access token exchanged from your GitLab
19session.
21Use the flag for your package manager:
23- `--docker`: registers `glab` as a Docker credential
24 helper for the registry.
25- `--maven`: writes a `<server>` block in
26 `~/.m2/settings.xml`, or `--config-file`, keyed by
27 `--registry-alias`.
28 Reference it from a `<repository>` carrying the same
29 `<id>`. The token is written in plain text, so keep a
30 `--config-file` out of version control.
31- `--gradle`: writes `{alias}Url`,
32 `{alias}Username`, and `{alias}Password` in
33 `~/.gradle/gradle.properties`, where `{alias}` is
34 `--registry-alias`.
35- `--npm`: writes a `//{host}{path}/:_authToken` entry
36 in `~/.npmrc`. You still need to point npm at the registry, with a
37 `registry=` or `@scope:registry=` line.
38- `--yarn`: writes an `npmRegistries` entry with `npmAuthToken`
39 and `npmAlwaysAuth` in `~/.yarnrc.yml`, for Yarn 2 and later. Set
40 an `npmRegistryServer` that matches `--registry`. Rewriting the
41 file can change its formatting, like indentation, blank lines, and line endings.
42- `--sbt`: writes a `credentials +=` line in
43 `~/.sbt/1.0/credentials.sbt`, which sbt 1.x reads, and the
44 same line in `2/credentials.sbt` in the sbt 2.x global base,
45 which sbt 2.x reads. That base is `~/.config/sbt`, or
46 `%LOCALAPPDATA%\sbt` on Windows, unless
47 `SBT_CONFIG_HOME` or `XDG_CONFIG_HOME` moves it.
48 On Windows it also writes
49 `%LOCALAPPDATA%\sbt\credentials.sbt`. The `sbt.bat`
50 of sbt 2.x points every build it starts, on either version, at
51 that file only, even when `SBT_CONFIG_HOME` is set.
52 The `sbt.version` in a project's
53 `project/build.properties` decides which file its build
54 reads. An sbt started with any other `-Dsbt.global.base`
55 reads none of them. An sbt shell or sbt 2.x server that is
56 already running keeps the credentials it loaded, so run
57 `reload` in it, or `sbt shutdown`, after you log in.
58 To write a different file, pass it with `--config-file`. It
59 must be a `.sbt` file that sbt loads, not a properties file
60 such as `~/.sbt/.credentials`.
62Token lifetime:
64- `--docker` exchanges a fresh token on every pull or push,
65 so `--duration` does not apply.
66- Every other flag writes one token, and nothing refreshes it. Run
67 the command again before `--duration` elapses. The default
68 is 15 minutes and the maximum is 12 hours.
70Credential resolution:
72- Docker runs the credential helper as its own subprocess, which
73 reads your credentials from the configuration file and ignores
74 `GITLAB_TOKEN`. This command verifies the login the same
75 way, so run `glab auth login` first if no token is stored
76 for the host.
77- Every other flag does read `GITLAB_TOKEN`. `glab`
78 writes the token into each file itself, so the tool can read it
79 without fetching credentials itself.
81Registry and alias selection:
83- Use `--registry` only for a registry the Artifact Registry
84 actually backs. If you name a container registry here, it receives the
85 wrong token and the error only surfaces on the next pull.
86- `--registry-alias` applies to `--maven` and
87 `--gradle` only, because `--npm`, `--sbt`,
88 and `--yarn` key their entries on `--registry`
89 itself.
90 For `--gradle`, use an alias that is a valid identifier
91 in your build script: the default is derived from the registry
92 host and contains hyphens, which Groovy cannot interpolate as
93 `${...}`.
95This feature is an experiment and is not ready for production use.
96It might be unstable or removed at any time.
97For more information, see
98<https://docs.gitlab.com/policy/development_stages_support/>.
100```plaintext
101glab artifact-registry login [flags]
102```
104## Examples
106```console
107# Configure Docker to authenticate against a registry
108glab artifact-registry login --docker --registry registry.example.com
110# Configure Maven to authenticate against a registry for two hours
111glab artifact-registry login --maven --registry https://ar.example.com --duration 2h
113# Configure Gradle to authenticate against a registry for two hours
114glab artifact-registry login --gradle --registry https://ar.example.com --duration 2h
116# Configure npm to authenticate against a registry for two hours
117glab artifact-registry login --npm --registry https://ar.example.com --duration 2h
119# Configure Yarn 2 or later to authenticate against a registry for two hours
120glab artifact-registry login --yarn --registry https://ar.example.com --duration 2h
122# Configure sbt to authenticate against a registry for two hours
123glab artifact-registry login --sbt --registry https://ar.example.com --duration 2h
125# Configure Maven through a settings.xml passed to mvn with -s
126glab artifact-registry login --maven --registry https://ar.example.com --config-file ~/.m2/ci-settings.xml
128```
130## Environment variables
132```plaintext
133DOCKER_CONFIG: the directory holding Docker's config.json, written by --docker. Defaults to ~/.docker.
134GRADLE_USER_HOME: the directory holding gradle.properties, written by --gradle. Defaults to ~/.gradle.
135npm_config_userconfig: the .npmrc written by --npm. Defaults to ~/.npmrc.
136SBT_CONFIG_HOME: the sbt 2.x global base; --sbt writes 2/credentials.sbt in it. Defaults to $XDG_CONFIG_HOME/sbt, else ~/.config/sbt. On Windows, the sbt.bat of sbt 2.x overrides it with %LOCALAPPDATA%\sbt. --sbt skips a blank or relative value of this variable and the next two.
137XDG_CONFIG_HOME: used by --sbt for the sbt 2.x base when SBT_CONFIG_HOME is unset. Not read on Windows.
138LOCALAPPDATA: on Windows, used by --sbt in place of XDG_CONFIG_HOME, and for the base the sbt.bat of sbt 2.x passes.
139```
141## Options
143```plaintext
144 --config-file string File to write (Maven/sbt only). Defaults to ~/.m2/settings.xml for --maven and the sbt 1.x and 2.x global bases for --sbt, where it replaces every file --sbt writes.
145 --docker Configure Docker to authenticate against the registry. Writes to $DOCKER_CONFIG, or ~/.docker when it is unset.
146 --duration duration How long the exchanged token should remain valid. Ignored for --docker. (default 15m0s)
147 --gradle Configure Gradle to authenticate against the registry. Writes to ~/.gradle/gradle.properties.
148 --hostname string GitLab hostname to request the token from. Defaults to the configured GitLab instance.
149 --maven Configure Maven to authenticate against the registry. Writes to ~/.m2/settings.xml.
150 --npm Configure npm to authenticate against the registry. Writes to ~/.npmrc.
151 --registry string Registry to authenticate against. For --docker, a bare hostname; for others, typically a URL.
152 --registry-alias string Alias/ID to register the registry under (Maven/Gradle only). Defaults to a name derived from --registry.
153 --sbt Configure sbt to authenticate against the registry. Writes credentials.sbt to the sbt 1.x and 2.x global bases.
154 --yarn Configure Yarn 2 or later to authenticate against the registry. Writes to ~/.yarnrc.yml. For Yarn 1, use --npm.
155```
157## Options inherited from parent commands
159```plaintext
160 -h, --help Show help for this command.
161```
Diagnostics7 git calls · 35 ms
CallStatusSizeTime035 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
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 · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=2
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
fetchtree:0 · deepen 1020032 KiB · hit4 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=4
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
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit10 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=10
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:02001.7 KiB · hit2 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=1744
git.response.cache=HIT
git.response.duration_ms=2
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
fetchtree:0200200 B · hit2 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=200
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=0a6f7b942754cd35d64fde385b2a8edac3df43b0
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=200
git.pkt.payload.max=173
git.sideband.band1.bytes=173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=173
git.pack.trailer=950b840b0689e88f124085ae4bc4b79e503d911d
Open pack map
fetch2002.8 KiB · hit19 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=18
git.response.bytes=2902
git.response.cache=HIT
git.response.duration_ms=19
git.fetch.wants=e4accc967986400e26d52fb9b976ba8b55ce3acd
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=2902
git.pkt.payload.max=2875
git.sideband.band1.bytes=2875
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
a5e18fe8b90b5b65
Request
5dea6fad…
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