# Use registry aliases

Send a workflow's ghcr.io image references to your registry when its CI jobs run, without editing the workflow.

A workflow moved from GitHub pushes its images to `ghcr.io/<owner>/…`. An alias from
`ghcr.io/acme` to `acme` rewrites those references when a job runs.

## Prerequisites

- Permission for `ecr:PutRegistryAliases`; to list the aliases, `ecr:DescribeRegistryAliases`.

## Set the aliases

**Console:** not available. Aliases are set through the CLI or the API.
**CLI**
```sh
dcloud ecr registry-aliases put --aliases '{"from":"ghcr.io/acme","to":"acme"}'
```

**API**
```http
PUT /ecr/api/registry-aliases
{ "aliases": [{ "from": "ghcr.io/acme", "to": "acme" }] }
```

The list replaces the previous one; `[]` removes every alias. At most 20; `from` is `host/owner`,
`to` a namespace in your registry, both lowercased.

## Result

In the job a runner receives, `ghcr.io/acme/` becomes `<organization>.ecr.<platform domain>/acme/`,
and `docker login ghcr.io` (or `docker/login-action`'s `registry: ghcr.io`) your registry host,
where the job's `GITHUB_TOKEN` logs in (see [Log in to the registry](log-in.md)).
`docker push ghcr.io/acme/app:1.2` then pushes `acme/app:1.2` here, and a job with
`packages: write` may create repositories inside `acme/`.

- Rewritten: what is written in the workflow file, such as run scripts, `env`, `with:`,
  `container:` and `services:` images.
- Not rewritten: references inside repository scripts, composite actions, Dockerfiles and compose
  files, and other owners on the same host (`ghcr.io/someone-else/tool` is pulled from ghcr.io as
  before).

## If it is refused

`400` `Each from may appear once` when a `from` is listed twice.

## Related

- [Log in to the registry](log-in.md)
- `ecr.registry-aliases.put` · `dcloud ecr registry-aliases put`
