Build and use custom images

Build a reusable custom image from the Depot base image that includes your tools and dependencies.

How it works

You build a custom image in Depot CI using a job that runs only your setup steps on the Depot base image. After your setup steps complete, a Depot snapshot action captures the state of the sandbox environment and pushes it to the Depot registry as a reusable image. Any job can then use that snapshot as its starting image, skipping the setup steps entirely.

Snapshot a sandbox to build a custom image

Create a job that runs on a standard Depot sandbox and installs the tools and dependencies you want to bake in. This is a separate workflow that only creates your custom image and pushes it to the Depot Registry. You'll need to run this workflow initially to create the image and then only when dependencies change.

To create the build image workflow:

• Add depot/snapshot-action as a step (after your setup steps). It captures the full state of the sandbox environment and pushes it to the Depot registry as a reusable image.

• Include image (required) as the input for the depot/snapshot-action in the format:

  <org-id>.registry.depot.dev/<repo>:<tag>

  Copy code

  This URL is the path in the Depot registry where the image will be stored and how you'll reference the image in your CI workflows.

  You can copy your organization ID from the Depot dashboard or use the depot org list command.

Example build image job:

jobs:
  build-image:
    runs-on: depot-ubuntu-latest
    steps:
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y your-tool-here
      - uses: depot/snapshot-action@v1
        with:
          image: <org-id>.registry.depot.dev/my-ci-image:latest

Use a custom image in a job

Any job in any workflow on Depot CI can specify your custom image. The custom image is in the Depot registry (registry.depot.dev). Images from external registries aren't supported.

To run a job on a custom image, specify runs-on with size and image keys (both required).

• size: the size of the sandbox
• image: is the Depot registry URL you specified in the build image workflow

Example specifying a custom image in a job:

jobs:
  use-image:
    runs-on:
      size: 2x8
      image: xk7m4hnp2q.registry.depot.dev/my-ci-image:latest
    steps:
      - uses: actions/checkout@v4
      - run: your-tool-here do-the-thing

Available values for size:

For sandbox information and pricing, see Depot CI sandboxes.

Environment variable changes don't persist in custom images

For actions that set or change environment variables, you need to include the steps in both the image build workflow and the workflows that use the custom image.

Snapshots capture only the sandbox filesystem. Environment variables exist only in the running process (not the filesystem) so they aren't included in the snapshot.

For example, some actions (like actions/setup-node) download tools and configure PATH to find them. The downloaded tools persist in the snapshot, but the PATH changes don't. When a new job starts from the custom image, it's a fresh environment with default environment variables. The tools are present but can't be found without the PATH updates.

To restore the environment variables, include the action in both workflows:

• In the image build workflow, the action downloads the tool and bakes it into the filesystem.
• In the workflow that uses the custom image, the action detects the tool is already on disk, skips the download, and only sets up the environment variables.

Steps that install tools with apt-get install don't need to be in both workflows because they install to system paths that are already on PATH by default.

Full example

Build the image once in a dedicated workflow. Run the workflow again whenever dependencies change. Reference the custom image in your regular CI workflows.

For example, create .depot/workflows/build-ci-image.yml:

on:
  workflow_dispatch:

jobs:
  build-image:
    runs-on: depot-ubuntu-latest
    steps:
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            python3 python3-pip \
            nodejs npm \
            postgresql-client
      - name: Install Python packages
        run: pip3 install pytest boto3 requests
      - uses: depot/snapshot-action@v1
        with:
          image: xk7m4hnp2q.registry.depot.dev/my-ci-image:latest

Merge the new workflow into your default branch. Run .depot/workflows/build-ci-image.yml once to build the custom image.

Reference the image in your regular CI workflow. For example, in .depot/workflows/ci.yml:

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on:
      size: 2x8
      image: xk7m4hnp2q.registry.depot.dev/my-ci-image:latest
    steps:
      - uses: actions/checkout@v4
      - run: pytest tests/
      - run: npm test

Run .depot/workflows/build-ci-image.yml whenever dependencies change to keep the custom image up-to-date.

Best practices

Snapshot slow-to-install software: Include software that is slow to install, such as system packages, browser binaries, and language toolchains, in your snapshot. Installing Chrome for Playwright tests and MySQL from apt are good candidates. A package directory can easily be cached, but the system changes an installer makes cannot.

Pre-pull container images: Run docker pull in the snapshot job to include those layers in the custom image, so jobs using service containers or docker compose start without pulling from a registry. Containers still need to start and pass their health checks, as normal.

Set clean: false when pre-cloning a repository: If your custom image includes a pre-cloned copy of your repository, set clean: false on actions/checkout so it skips running git clean -ffdx before fetching. Without clean: false, checkout removes untracked files from the pre-cloned repo (like installed dependencies or build artifacts), negating the benefit of pre-cloning.

steps:
  - uses: actions/checkout@v4
    with:
      clean: false