glab artifact-registry login

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/.

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

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

      --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

  -h, --help   Show help for this command.