Pants

Pants is an ergonomic build tool for codebases of all sizes and supports Python, Go, Java, Scala, Kotlin, Shell, and Docker. It is used in many large projects, including Coinbase, IBM, and Slack, and is optimized for fine-grained incremental builds with advanced local and remote cachin. Pants is highly configurable and can scale to codebases of any size.

Depot Cache provides a remote cache service that can be used with Pants, allowing you to incrementally cache and reuse parts of your builds. This cache is accessible from anywhere, both on your local machine and on CI/CD systems.

Configuring Pants to use Depot Cache

Depot Cache can be used with Pants from Depot's managed GitHub Actions runners, from your local machine, or from any CI/CD system.

From Depot-managed Actions runners

Depot GitHub Actions runners are pre-configured to use Depot Cache with Pants - each runner is launched with a pants.toml file that is pre-configured with the connection details for Depot Cache.

If this automatic configuration is incompatible with your specific setup, you can disable automatic configuration in your organization settings page and manually configure Pants to use Depot Cache as described below.

From your local machine or any CI/CD system

To manually configure Pants to use Depot Cache, you will need to enable remote caching in your pants.toml. Configure Pants to use the Depot Cache service endpoints and set your API token in the Authorization header:

pants.toml:

[GLOBAL]
# Enable remote caching
remote_cache_read = true
remote_cache_write = true

# Point remote caching to Depot Cache
remote_store_headers = { "Authorization" = "DEPOT_TOKEN" }
remote_store_address = "grpcs://cache.depot.dev"

If you are a member of multiple organizations, and you are authenticating with a user token, you must additionally specify which organization to use for cache storage using the x-depot-org header:

remote_store_headers = { "x-depot-org" = "DEPOT_ORG_ID" }

Once Pants is configured to use Depot Cache, you can then run your builds as you normally would. Pants will automatically communicate with Depot Cache to fetch and reuse any stored build artifacts from your previous builds.

Using Depot Cache with Pants in depot/build-push-action

When using depot/build-push-action to build Docker images that contain Pants projects, your build needs access to Pants' remote cache credentials to benefit from caching.

These credentials are not automatically available inside your Docker build environment. Unlike builds running directly on Depot-managed GitHub Actions runners (which have automatic access to Depot Cache environment variables), containerized builds execute in isolated VMs that require explicit configuration.

Follow these steps to securely pass your Pants credentials into your Docker build:

1. Store the Depot token in a GitHub Secret named DEPOT_TOKEN.

2. Update your pants.toml to read the Depot token from an environment variable:

[GLOBAL]
remote_cache_read = true
remote_cache_write = true
remote_store_address = "grpcs://cache.depot.dev"

[GLOBAL.remote_store_headers]
Authorization = "%(env.DEPOT_TOKEN)s"

3. Configure your GitHub Action to pass secrets to the container build:

- name: Build and push
  uses: depot/build-push-action@v1
  with:
    context: .
    file: ./Dockerfile
    push: true
    tags: your-image:tag
    secrets: |
      "DEPOT_TOKEN=${{ secrets.DEPOT_TOKEN }}"

4. Update your Dockerfile to mount the secret and run the build:

# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Copy pants.toml and run build with mounted secret
COPY pants.toml .
RUN --mount=type=secret,id=DEPOT_TOKEN,env=DEPOT_TOKEN \
    pants package ::

Adding # syntax=docker/dockerfile:1 as the first line of your Dockerfile enables mounting secrets as environment variables.