glab-artifact-registry

glab artifact-registry

アクティブな GitLab 認証情報を、短期間有効な Artifact Registry アクセストークンと交換します。このコマンドグループでは、エイリアス glab ar も使用できます。このコマンドグループは試験的な機能です。永続的な自動化で使用する前に、最新のヘルプと対象の GitLab インスタンスを確認してください。

前提条件

• GitLab Enterprise Edition 19.1 以降。
• インスタンス管理者が gate_token_exchange_endpoint 機能フラグを有効にしていること。
• glab が対象のホスト名に対して認証済みであること。

トークンは一時的なものですが、認証情報であることに変わりはありません。ログに出力したり、リポジトリに保存したり、コマンドの引数に含めたり、イシューや MR の内容に貼り付けたりしないでください。

先にアクセスを確認する

status はトークン交換を行い、機密情報ではない識別メタデータ（発行者、サブジェクト、オーディエンス、有効期限）を出力します。確認するたびにサーバー側でトークンが発行され、直ちに破棄されます。自動化では JSON を優先し、短い間隔で繰り返し呼び出さないでください。

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'

別のプロセス用にトークンを要求する前に、発行者、サブジェクト、オーディエンスが意図したインスタンス、ユーザー、レジストリを示していることを確認してください。

短期間有効なトークンを要求する

テキスト出力では、シェルでの取得やパイプ処理ができるよう、トークンのみが標準出力に出力されます。デフォルトの有効期間は 15 分です。指定できる期間は 1 秒から 12 時間までです。操作を完了するのに必要な最短の期間を指定してください。

# 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

有効期限も必要な場合に限り、--output json を使用してください。JSON ドキュメントにはトークンが含まれているため、機密情報として扱ってください。トークンをログに出力する --jq 式は渡さないでください。

パッケージマネージャーの認証を設定する

glab artifact-registry login は、実行ごとに1つのパッケージマネージャーのみを設定します。

• --docker は docker-credential-glab シムをインストールし、Docker のレジストリごとの credHelpers に glab を登録します。
• --maven は --registry-alias をキーとして、~/.m2/settings.xml に <server> ブロックを書き込みます。利用側の <repository> では同じ <id> を使用する必要があります。
• --gradle は {alias}Url、{alias}Username、{alias}Password を ~/.gradle/gradle.properties に書き込みます。{alias} は --registry-alias の値です。
• --npm は //{host}{path}/:_authToken エントリーを ~/.npmrc に書き込みます。npm がレジストリを使用するように、引き続き registry= または @scope:registry= を設定する必要があります。
• --yarn は Yarn 2 以降を ~/.yarnrc.yml で設定します。npmRegistries エントリーには npmAuthToken と npmAlwaysAuth が格納されます。一致する npmRegistryServer は別途設定してください。Yarn 1 では --npm を使用してください。既存の npmScopes 認証情報がレジストリトークンを上書きする場合があります。警告を確認し、変更する前にスコープを見直してください。YAML の書き換えにより、書式が変わることがあります。
• --sbt は credentials += 行を ~/.sbt/1.0/credentials.sbt に書き込みます。カスタムのグローバルベースでインストールした sbt では、このファイルが読み込まれない場合があります。

# 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

安全性と互換性に関するルール：

• --docker の場合、--registry はポートを付けてもかまいませんが、ホスト名のみを指定する必要があります。Maven、Gradle、npm、Yarn、sbt の場合、--registry には通常 URL を指定します。
• Docker はプルまたはプッシュのたびに新しいトークンを取得するため、--duration は適用されません。Maven、Gradle、npm、Yarn、sbt には静的トークンが1つ渡されます。--duration の期限が切れる前にコマンドを再実行してください。
• Docker ヘルパーのサブプロセスは、意図的に GITLAB_TOKEN を無視します。通常は glab auth login によって保存されたトークンを読み取ります。GitLab CI ジョブ内では、GLAB_ENABLE_CI_AUTOLOGIN=true で CI 自動ログインが有効になっている場合、CI_JOB_TOKEN も使用します。Maven、Gradle、npm、Yarn、sbt のログイン処理では、glab が交換後のトークンを各ツールの設定ファイルに書き込むため、GITLAB_TOKEN を読み取ることができます。
• GitLab Artifact Registry が実際にバックエンドとなっているレジストリにのみ使用してください。通常のコンテナレジストリを誤って分類すると、交換後の Artifact Registry トークンが優先され、すべてのプルが失敗する可能性があります。
• 書き込み前に、設定ファイルの保存先を確認してください：${DOCKER_CONFIG:-$HOME/.docker}/config.json、~/.m2/settings.xml、~/.gradle/gradle.properties、~/.npmrc、~/.yarnrc.yml、または ~/.sbt/1.0/credentials.sbt。
• --registry-alias は Maven と Gradle にのみ適用されます。Gradle では、ビルドスクリプトで有効な識別子となるエイリアスを選んでください。派生するデフォルト値にはハイフンが含まれる場合があります。
• 同じレジストリに対してコマンドを再実行すると、一致するエントリーが更新または置換されます。設定後は、認証情報を表示せずに、対象のホストに対する破壊的でないパッケージマネージャーの操作をテストしてください。

取得したコマンドヘルプについては、references/commands.md を参照してください。