Container registries
BetaCredentials for pulling private images, from GitHub Container Registry, Docker Hub, GitLab or anything self-hosted.
Settings -> Registries.
Beta
This feature is currently beta/experimental and subject to change. It is not recommended for production. Try it out and share your feedback on our GitHub.
How it works
One entry per registry, stored per team and encrypted. Every deploy of an app in that team carries the credentials to its server, which authenticates with them on every pull it makes:
- the image an app of source Docker image runs,
- every image a Compose stack brings up,
- the base image a Dockerfile build starts
FROM.
Nothing is set per app. Connect the registry once and every private image from that host pulls, on every server the team deploys to.
The password or token is write-only: it is never returned by the API and there is no reveal path.
The credential itself is not something Deplo issues, it is created on the registry provider's own site first, then pasted in here.
Add one
Open registries settings
Settings -> Registries, then Add registry.
Pick the type
Pick the Type: ghcr, dockerhub, gitlab or generic.
Create a credential on the provider, then fill in the form
Go to the provider's own site first and create a read-only credential. The exact steps, and what goes in Registry host, Username and Token, differ per provider:
- Registry host:
ghcr.io. - Username: your GitHub username.
- Token: a classic personal access token with the
read:packagesscope, created under GitHub's own Settings -> Developer settings -> Personal access tokens -> Tokens (classic). If the image belongs to an organization, the org may also need to grant that token access under its package settings.
Classic token, not fine-grained
GHCR does not work with a fine-grained personal access token: GitHub's
fine-grained tokens have no packages permission to grant, so a pull with
one fails with unauthorized even if the token looks valid. Use Tokens
(classic) and tick read:packages.
See GitHub's docs on authenticating to the Container registry for the exact steps.
Save
Save.
Use it by referencing the image in an app whose source is a Docker image, or as the base image of a Dockerfile build.
Limits and gotchas
- The server's agent has to be recent enough to authenticate a pull. An outdated one is flagged on the Servers page, where you update it.
- Registries are per team. Another team needs its own entry.
- Tokens expire. A pull that used to work and now fails with
unauthorizedis almost always this. - Scope the token to read-only on the provider's side. Deplo only ever pulls.
- Deplo pushes nothing. Images it builds stay on the server that built them, which is why rollbacks depend on local retention rather than a registry.
If it does not work
pull access denied: no credential matches that image's host, or the token cannot see that repository.- It works for one image and not another: same host, different repository permissions on the provider's side.
- Nothing changed after connecting the registry: the deploy that failed ran before it existed. Deploy again, the credentials are read at deploy time.
- A registry on a private address: the server pulls from it fine, it is on the same network. Only the image search box in the app form cannot reach it, so type the image reference in full.
See Deploys and builds for more.
See also
Did this page help you?