Ephemeral Registry

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).

Saving

To save a Depot build in the ephemeral registry, use the --save flag when running depot build:

depot build --save --metadata-file=build.json ...

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.

{
  "depot.build": {
    "buildID": "your-build-id",
    "projectID": "your-project-id"
  }
}

For example, you could pull the image by the build ID in the metadata file via the depot pull command:

depot pull $(cat build.json | jq -r .\[\"depot.build\"\].buildID)

If you are using GitHub Actions with the depot/build-push-action, you can add save: true as an input:

- uses: depot/build-push-action@v1
  with:
    save: true
    project: <your-project-id>

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:

- uses: depot/build-push-action@v1
  id: build
  with:
    save: true
    project: <your-project-id>
 
- name: Print build ID
  run: echo ${{ steps.build.outputs.build-id }}

Pulling

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:

depot pull <build-id> -t <image-name>:<tag>

You can also omit the <build-id> argument to display an interactive list of builds to choose for pulling.

Pulling with Docker

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.

docker login registry.depot.dev -u x-token -p <any project, org, or user access token>

Learn more about Depot authentication tokens in the authentication guide.

After authenticating, you can pull the build using the docker pull command:

docker pull registry.depot.dev/PROJECT_ID:BUILD_ID

Pulling with Kubernetes

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.

kubectl create secret depot-registry regcred --docker-server=registry.depot.dev --docker-username=x-token --docker-password=<any project, org, or user access token>

Pushing

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:

depot push <build-id> -t <image-name>:<tag>

Some notes:

1. 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.

2. Similar to depot pull, you can omit the <build-id> argument to display an interactive list of builds to choose from.

3. 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.

Example use-cases

There are a few common use-cases for the ephemeral registry:

• Pulling a build to your local machine - If you are building an image on Depot, but want to test it locally before pushing it to a registry, you can save the build in the ephemeral registry, then pull it down to your local machine to test it without having to rerun a build.
• Integration testing a built image - If you are running a set of matrix integration tests on your final image across multiple CI workflows, ephemeral registries can save you needing to run a build for each workflow. Instead, you can run a single build, save it in the ephemeral registry, then pull it down to each workflow to run the integration tests.
• Working with large images - The layer blobs in a Docker image can be quite large when working with large images. It can be time consuming to pull and push them down from a single builder. The ephemeral registry leverages a global CDN to distribute layer blobs to registries and when you run depot pull. This distribution mechanism makes it much faster to quickly pull and push large images.