# 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.

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](security.md)).

## 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.

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

## Log in with a login token

**Console**
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**.

**CLI**
```sh
dcloud ecr auth login-token
```

Then run `docker login org-example1234.ecr.example.com -u token` and paste the `token`
from the answer.

**API**
```http
POST /ecr/api/login-token
```

The answer holds `token`, `registryHost`, `expiresIn` (43200 seconds) and `id`.

To manage your tokens, see [Manage login tokens](manage-login-tokens.md).

## Log in from a CI job

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

```sh
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](use-registry-aliases.md)). 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.

## Related

- [Push an image](push-an-image.md)
- [Manage login tokens](manage-login-tokens.md)
- `ecr.auth.login-token` · `dcloud ecr auth login-token`
