Container registry
Push private images to the registry Guidal provides, and deploy from them.
Guidal runs container images. You can deploy from any registry your account can reach, or push to the private registry included with your plan.
Most applications do not need this page: guidal deploy builds the image on Guidal straight from your source directory — see Deploy from source. Use the registry when you already build your own images.
Get credentials
guidal registry credentialsThis prints the registry hostname, a username and a token. Each run creates new credentials and invalidates the previous ones for this project, so update your CI secret afterwards. Use them to log in with your container tool:
docker login <registry-host> -u <username> --password-stdinPipe the token, don't paste it
Passing a token as --password on the command line records it in your shell history and can be visible to other processes. --password-stdin reading from a pipe or a file avoids both.
Push an image
Every Guidal project has its own registry namespace, named <org-slug>.<project-slug>. Tag the image for it, then push:
docker tag my-app:latest <registry-host>/<org-slug>.<project-slug>/my-app:v1
docker push <registry-host>/<org-slug>.<project-slug>/my-app:v1The credentials from guidal registry credentials are scoped to the project you are currently in. They cannot push to another project's namespace — including another project in the same organisation.
Deploy from it
guidal services create --name api \
--image <registry-host>/<org-slug>.<project-slug>/my-app:v1 \
--port 8080Services in the same project pull from the registry without extra configuration.
Inspect what you have
guidal registry repos
guidal registry artifacts my-appBoth read the registry of your active project. Switch projects with guidal projects switch <project>, or pass --project for a one-off.
Storage limits
Registry storage counts against your plan:
| Plan | Registry storage |
|---|---|
| Starter | 5 GB |
| Pro | 25 GB |
| Team | 100 GB |
Image layers are shared between tags, so pushing v2 of an application that changed only its top layer costs far less than the full image size. Even so, tags accumulate — deleting old ones you no longer deploy is the simplest way to stay under the limit.
A push that would exceed the limit is refused. See Plans, billing and limits for the full table.
Using an external registry
Public images work with no setup:
guidal services create --name web --image nginxdemos/hello --port 80For a private external registry, store the pull credentials as a secret and reference them when creating the service. Guidal will use them to pull on each deploy.
Tagging
Prefer immutable tags — a commit SHA or a release version — over latest. With latest, two deploys of "the same" tag can run different code, which makes rollbacks unreliable and incidents hard to reason about:
guidal services deploy api --image <registry-host>/<org-slug>.<project-slug>/my-app:"$GIT_SHA"