Skip to main content
You can authenticate in Container Registry with the help of a short-lived access token issued by the Nebius AI Cloud CLI each time, or with a long-lived static key token issued for the Container Registry service.

​
Working on a local machine

On your local machine, you can simply configure a Docker credential helper to work with Container Registry.
  1. Run the following command: 
    nebius registry configure-helper
  2. Check that the credential helper is configured:
    1. Open the file from the previous command output, for example, with the cat command: 
      cat ~/.docker/config.json
    2. Check that the credHelpers property contains the following lines: 
      "cr.eu-north1.nebius.cloud": "nebius"
"cr.eu-north2.nebius.cloud": "nebius"
"cr.eu-west1.nebius.cloud": "nebius"
"cr.me-west1.nebius.cloud": "nebius"
"cr.uk-south1.nebius.cloud": "nebius"
"cr.us-central1.nebius.cloud": "nebius"
When you run any docker command after this configuration, it requests credentials from nebius, which might require you to log in with the help of the Nebius AI Cloud web console.

​
Working in a CI/CD environment

In your CI/CD environment, you are unlikely to be able to log into the web console. Therefore, you need to create a service account and use it to get credentials. Make sure that the service account is in a group that has at least the viewer role within your tenant; for example, the default viewers group. There are two ways to work with a service account:
  • Issue a long-lived static key for Container Registry.
  • Get a short-lived access token in each run of your pipeline job.

​
Long-lived static key token

To use a long-lived token, you need to issue a static key and store the token in your CI/CD environment configuration.
  1. Create a static key for your service account: 
    nebius iam static-key issue \
  --account-service-account-id=<service_account_ID> \
  --service=CONTAINER_REGISTRY
    By default, the key lifetime is 6 months. If you need a different lifetime, add the --expires-at parameter to this command. It accepts the date of expiration in ISO 8601 format, for example 2025-11-23T11:44:43.232142Z. You can set a lifetime of up to 3 years.
  2. Get the static key token from the token parameter of the output.
  3. Configure the job that works with Container Registry to use this token: 
    docker login cr.<region>.nebius.cloud \
  --username iam \
  --password <token>
    In this command, set the region of the registry with which the pipeline is working.

​
Short-lived access token

To use a short-lived access token, you need to get it from Nebius AI Cloud CLI, which should be installed in your CI/CD environment. Access tokens have a lifetime of 12 hours.
  1. Create an authorized key for your service account.
  2. Install the Nebius AI Cloud CLI in your environment.
  3. Configure a profile for your service account in the .nebius/config.yaml file.
  4. Configure the job that works with Container Registry to generate credentials with nebius and pipe them directly into a docker command: 
    nebius iam get-access-token | \
  docker login cr.<region>.nebius.cloud \
    --username iam \
    --password-stdin
    In this command, set the region of the registry with which the pipeline is working.
You can do the same if you are using helm registry login: 
nebius iam get-access-token | \
  helm registry login cr.<region>.nebius.cloud \
    --username iam \
    --password-stdin

​
Troubleshooting

If you are getting the “Permission denied” error when trying to access Container Registry from your local machine, double-check that the Docker credential helper was configured correctly:
  • Check that the system can find the Nebius AI Cloud CLI binary: 
    which nebius
    It should return a path, for example: 
    /home/user/.nebius/bin/nebius
    If it does not, reinstall Nebius AI Cloud CLI, and then rerun nebius registry configure-helper.
  • Check that the system can find the credential helper: 
    which docker-credential-nebius
    It should return a path, for example: 
    /home/user/.nebius/bin/docker-credential-nebius
    If it does not, rerun nebius registry configure-helper.
  • Check that the region of the registry you are trying to access is present in the .docker/config.json file: 
    "cr.<region>.nebius.cloud": "nebius"
    If it is not, add it manually or rerun nebius registry configure-helper.