Skip to content

Authenticate with the container registry

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

To authenticate with the container registry, you can use a:

All of these authentication methods require the minimum scope:

  • For read (pull) access, to be read_registry.
  • For write (push) access, to be write_registry and read_registry.

NOTE: Admin Mode does not apply during authentication with the container registry. If you are an administrator with Admin Mode enabled, and you create a personal access token without the admin_mode scope, that token works even though Admin Mode is enabled.

To authenticate, run the docker login command. For example:

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

Use GitLab CI/CD to authenticate

To use CI/CD to authenticate with the container registry, you can use:

  • The CI_REGISTRY_USER CI/CD variable.

    This variable holds a per-job user with read-write access to the container registry. Its password is also automatically created and available in CI_REGISTRY_PASSWORD.

    echo "$CI_REGISTRY_PASSWORD" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
  • A CI job token.

    echo "$CI_JOB_TOKEN" | docker login $CI_REGISTRY -u $CI_REGISTRY_USER --password-stdin
  • A deploy token with the minimum scope of:

    • For read (pull) access, read_registry.
    • For write (push) access, read_registry and write_registry.
    echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin
  • A personal access token with the minimum scope of:

    • For read (pull) access, read_registry.
    • For write (push) access, read_registry and write_registry.
    echo "<access_token>" | docker login $CI_REGISTRY -u <username> --password-stdin