Log in to the registry

Log docker in to your registry with an access key, a login token, or a CI job's GITHUB_TOKEN.

Last updated 18 November 2026View as Markdown

The registry speaks the standard v2 token flow: GET /v2/ answers 401 with a Bearer challenge, docker exchanges your credentials at /v2/token for a registry token, and sends that token with each request. Replace org-example1234.ecr.example.com with your registry host.

Credentials

Credential Username Password Works for
Access key the access key id the access key's secret while the key is active and not expired
Login token any value, such as token the token 12 hours, or until revoked
A CI job's token any value the job's GITHUB_TOKEN see below

For a login token, do not use a username that has the form of an access key id; it is then checked as an access key. The registry token docker receives works for one hour; docker fetches a new one by itself. What a credential may do is decided by the IAM policies of its user, per repository (see Security in Container registry).

Prerequisites

  • An access key from IAM, or permission for ecr:GetAuthorizationToken to create a login token.

Log in with an access key

Pass the secret on standard input, never with -p: a password on the command line lands in your shell history and the process list.

echo "$REGISTRY_SECRET" | docker login org-example1234.ecr.example.com \
  -u EWS1EXAMPLEEXAMPLE00 --password-stdin

Log in with a login token

  1. Open Container registry, then choose Access.
  2. Under Login tokens, choose Create a login token.
  3. Run the docker login command shown, and paste the token at the Password: prompt. The token is shown only once.

The Push commands tab of a repository has the same: Generate a login token.

To manage your tokens, see Manage login tokens.

Log in from a CI job

In a GitHub-syntax workflow, the job's own GITHUB_TOKEN logs in, with any username:

echo "$GITHUB_TOKEN" | docker login org-example1234.ecr.example.com -u ci --password-stdin

What it may do follows the job's packages: permission, within the policies of the run's principal: read pulls, write pulls and pushes. It never deletes, and it creates a new repository only inside a registry alias's namespace (see Use registry aliases). A token without packages: read or write is refused with 401 "Only a CI job token with packages: read or write can log in here (set permissions: packages: write in the workflow)".

If the login is refused

  • 401 Invalid credentials for a wrong access key id or secret.
  • 401 Invalid or expired token for an expired, revoked or mistyped login token.
  • 403 Credentials do not grant access to this organization when the credential belongs to another organization than the registry host.

A login succeeds even when the credential may not push or pull a given repository; that refusal comes with the push or pull.

Did this page help you?