# Pull from another registry

Give an app a stored credential for ghcr.io, Docker Hub or a self-hosted registry, so its machines can pull a private image from there.

An image in another registry is pulled with a stored credential when the app has one for that
registry host. The password or token is a Deutsche Cloud secret; the app holds a reference to it, never
the value. Your own organization's registry needs no credential. An app holds up to 20 credentials,
one per registry host. The host is the first part of the image reference: `ghcr.io`,
`registry.example.com:5000`, or `docker.io` for a Docker Hub image written without a host
(`nginx:1.27`). Without a credential, an image is pulled anonymously. Replace app-id with the app's id and secret-id with the
secret's id.

## Prerequisites

- An `image` or `compose` app.
- The password or token stored as a secret in **Secrets**.
- Permission for `deploy:UpdateApp` on the app and `secrets:GetSecretValue` on the secret. Binding
  grants the secret to the `deploy` consumer.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Add the credential

**Console**
1. Open the app's **Runtime** tab.
2. Under **Registry credentials**, choose **Add registry**.
3. For **Registry host**, enter the host, for example `ghcr.io`.
4. For **Username**, enter the user name.
5. For **Password secret**, choose the secret that holds the password or token.
6. Choose **Save credentials**. **Saved** appears beside the button.

The section is shown only for an `image` or `compose` app, and only to someone with
`deploy:UpdateApp`.

**CLI**
```sh
dcloud deploy registry-credentials replace app-id \
  --credentials '{"registryHost":"ghcr.io","username":"example-bot","passwordSecretId":"secret-id"}'
dcloud deploy apps deploy app-id --image ghcr.io/example/web:1.4.2 --wait
```

**API**
```http
PUT /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/registry-credentials
{ "credentials": [{ "registryHost": "ghcr.io", "username": "example-bot", "passwordSecretId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a" }] }
```

The call replaces the app's whole set of credentials.

**Terraform**
```hcl
resource "dcloud_app_registry_credentials" "web" {
  app_id = dcloud_app.web.id
  credentials = jsonencode([
    { registryHost = "ghcr.io", username = "example-bot", passwordSecretId = dcloud_secret.ghcr_token.id },
  ])
}
```

The resource owns the app's whole set: a credential added elsewhere is removed on the next apply.

## Result

On the next deployment the machine logs in to every registry the app holds a credential for, then
pulls. A refused credential shows in the deployment's activity as _Rollout attempt failed,
retrying: registry login to ghcr.io …_; the machine retries until the deployment times out.

The call is refused with `400` when a host is listed twice ("… is listed twice: one credential
per registry") or names your organization's own registry, and with `404` when a secret does not
exist.

Credentials that expire within hours, such as AWS ECR tokens, are not supported.

## Related

- [Troubleshooting](troubleshooting.md)
- `deploy.registry-credentials.replace` · `dcloud deploy registry-credentials replace` ·
  `dcloud_app_registry_credentials`
