The ephemeral registry is a temporary registry for your Depot builds. It allows you to easily save your build, then pull it back later, without needing to push to another registry. Additionally you can choose to push your build directly from the ephemeral registry to your own registry.
Builds saved in the ephemeral registry are currently persisted for 7 days, after which time they are deleted. The cost of ephemeral registry storage is part of our the $0.20/GB storage pricing (see pricing).
To save a Depot build in the ephemeral registry, use the --save
flag when running depot build
:
The --metadata-file
flag is optional, but it's useful for capturing the metadata about the build, such as the build ID and project ID. You can use build ID property in that file to pull or push the build later.
For example, you could pull the image by the build ID in the metadata file via the depot pull
command:
If you are using GitHub Actions with the depot/build-push-action
, you can add save: true
as an input:
To pull the image back or push it to another registry, you will need the build ID. The build ID is printed in the output of depot build
and is automatically set as an output of the depot/build-push-action
:
To pull a build that has been saved in the ephemeral registry, you can use the depot pull
command with the build ID, and the -t
flag to choose the image name/tag:
You can also omit the <build-id>
argument to display an interactive list of builds to choose for pulling.
To pull a build from the ephemeral registry using the Docker CLI, you must first authenticate with the Depot registry. You can do this by running the docker login
command or by using any of the other authentication methods.
Learn more about Depot authentication tokens in the authentication guide.
After authenticating, you can pull the build using the docker pull
command:
To pull a build from the ephemeral registry in a Kubernetes cluster, you can use the kubectl
command to create a secret with the Docker registry credentials, then create a Kubernetes deployment that uses the secret to pull the image.
To push a build that has been saved in the ephemeral registry to your own registry, you can use the depot push
command with the build ID, and the -t
flag to choose the image name/tag:
Some notes:
Like adding the --push
flag to depot build
, the depot push
command uses registry credentials stored in Docker when pushing to registries. If you have not already authenticated with your registry, you should do so with docker login
before running depot push
.
Similar to depot pull
, you can omit the <build-id>
argument to display an interactive list of builds to choose from.
depot push
will push the image to the target registry directly from the remote infrastructure, without downloading it to the CLI first, to avoid unnecessary data transfer.
There are a few common use-cases for the ephemeral registry:
depot pull
. This distribution mechanism makes it much faster to quickly pull and push large images.