正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

コンテナレジストリを使用して認証する

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

コンテナレジストリを使用して認証するには、以下を使用できます:

トークンベースの認証方式に必要な最小限のスコープ:

  • 読み取り（プル）アクセスの場合、read_registryである必要があります
  • 書き込み（プッシュ）アクセスの場合、write_registryおよびread_registryである必要があります

コンテナレジストリで認証する際には、管理者モードは適用されません。管理者モードが有効になっている管理者が、admin_modeスコープなしでパーソナルアクセストークンを作成した場合、管理者モードが有効になっていても、そのトークンは機能します。詳細については、管理者モードを参照してください。

ユーザー名とパスワードで認証する

GitLabのユーザー名とパスワードを使用して、コンテナレジストリで認証できます:

docker login registry.example.com -u <username> -p <password>

セキュリティ上の理由から、-pの代わりに--password-stdinフラグを使用することをお勧めします:

echo "<password>" | docker login registry.example.com -u <username> --password-stdin

2要素認証（2FA）が有効になっている場合、ユーザー名とパスワードによる認証は使用できません。この場合、トークンベースの認証方法を使用する必要があります。

トークンで認証する

トークンで認証するには、docker loginコマンドを実行します:

TOKEN=<token>
echo "$TOKEN" | docker login registry.example.com -u <username> --password-stdin

認証後、クライアントは認証情報をキャッシュします。以降の操作では、指定された操作の実行だけが承認された、JWTトークンを返す認証リクエストを行います。トークンは引き続き有効です:

GitLab CI/CDを使用して認証する

CI/CDを使用してコンテナレジストリで認証する場合、以下を使用できます:

  • CI_REGISTRY_USER CI/CD変数。

    この変数は、コンテナレジストリへの読み取り/書き込みアクセス権があるジョブごとのユーザーを保持します。そのパスワードも自動的に作成され、CI_REGISTRY_PASSWORDで使用できます。

    echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

  • CIジョブトークン。

    このトークンは、読み取り（プル）アクセスのみに使用できます。read_registryスコープがありますが、プッシュ操作に必要なwrite_registryスコープはありません。

    echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin

    gitlab-ci-tokenスキームを使用することもできます:

    echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u gitlab-ci-token --password-stdin

  • 最小スコープを持つGitLabデプロイトークン:

    • 読み取り（プル）アクセスの場合、read_registry。
    • 書き込み（プッシュ）アクセスの場合、read_registryおよびwrite_registry。
    echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin

  • 最小スコープを持つパーソナルアクセストークン:

    • 読み取り（プル）アクセスの場合、read_registry。
    • 書き込み（プッシュ）アクセスの場合、read_registryおよびwrite_registry。
    echo "<access_token>" | docker login $CI_REGISTRY -u <username> --password-stdin

トラブルシューティング

docker loginコマンドがaccess forbiddenで失敗する

コンテナレジストリは、認証情報を検証するために、GitLab API URLをDockerクライアントに返します。Dockerクライアントは基本認証を使用するので、リクエストにはAuthorizationヘッダーが含まれています。レジストリ設定のtoken_realmで設定された/jwt/authエンドポイントへのリクエストでAuthorizationヘッダーが見つからない場合、access forbiddenエラーメッセージが表示されます。

例:

> docker login gitlab.example.com:4567

Username: user
Password:
Error response from daemon: Get "https://gitlab.company.com:4567/v2/": denied: access forbidden

このエラーを回避するには、Authorizationヘッダーがリクエストから削除されないようにしてください。たとえば、GitLabの前にあるプロキシが/jwt/authエンドポイントにリダイレクトされている可能性があります。

Dockerクライアントでの認証情報の検証の詳細については、コンテナレジストリアーキテクチャを参照してください。

大きなイメージをプッシュしている場合のunauthorized: authentication required

大きなイメージをプッシュすると、次のような認証エラーが発生する可能性があります:

docker push gitlab.example.com/myproject/docs:latest
The push refers to a repository [gitlab.example.com/myproject/docs]
630816f32edb: Preparing
530d5553aec8: Preparing
...
4b0bab9ff599: Waiting
d1c800db26c7: Waiting
42755cf4ee95: Waiting
unauthorized: authentication required

このエラーは、イメージのプッシュが完了する前に認証トークンが期限切れになった場合に発生します。デフォルトでは、GitLab Self-Managedインスタンスのコンテナレジストリのトークンが期限切れになるのは5分後です。GitLab.comでのトークンの有効期限は15分です。