# Configure moonrepo to use Depot Cache (https://depot.dev/docs/cache/integrations/moonrepo)

[**moonrepo**](https://moonrepo.dev/) is a repository management, organization, orchestration, and notification tool for the web ecosystem, written in Rust. Many of the concepts within moon are heavily inspired from Bazel and other popular build systems.

[**Depot Cache**](/docs/cache/overview) provides a remote cache service that works with moonrepo, 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.

**Note:** You need a [Depot API token](/docs/cli/authentication) to authenticate with the cache service.

## Local workstation

Set a `DEPOT_TOKEN` environment variable with an organization or user token and add the following to your `.moon/workspace.yml` file:

```yaml
unstable_remote:
  host: 'grpcs://cache.depot.dev'
  auth:
    token: 'DEPOT_TOKEN'
```

If you are using a user token and are a member of more than one organization, you additionally need to set an `X-Depot-Org` header to your Depot organization ID:

```yaml
unstable_remote:
  host: 'grpcs://cache.depot.dev'
  auth:
    token: 'DEPOT_TOKEN'
    headers:
      'X-Depot-Org': '<your-org-id>'
```

See [moonrepo's remote cache documentation](https://moonrepo.dev/docs/guides/remote-cache#cloud-hosted-depot) for more details.

After you configure moonrepo to use Depot Cache, run your builds as you normally would. moonrepo automatically communicates with Depot Cache to fetch and reuse any stored build artifacts from your previous builds.

## Local workstation with containerized builds

When building Docker images that contain moonrepo workspaces locally, your build needs access to moonrepo's remote cache credentials to benefit from caching. Containerized builds execute in isolated environments that require explicit configuration.

### Moonrepo configuration

Configure moonrepo to read the Depot token from an environment variable in `.moon/workspace.yml`:

```yaml
unstable_remote:
  host: 'grpcs://cache.depot.dev'
  auth:
    token: 'DEPOT_TOKEN'
```

### Dockerfile configuration

Update your Dockerfile to copy the workspace configuration and mount the secret:

```dockerfile
# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Copy moonrepo workspace configuration
COPY .moon/workspace.yml .moon/workspace.yml

# Mount secret as environment variable and run build
RUN --mount=type=secret,id=DEPOT_TOKEN,env=DEPOT_TOKEN \
    moon run build
```

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

### Depot CLI

```shell
depot build --secret id=DEPOT_TOKEN,env=DEPOT_TOKEN -t your-image:tag .
```

### Docker buildx

```shell
docker buildx build --secret id=DEPOT_TOKEN,env=DEPOT_TOKEN -t your-image:tag .
```

### Bake

Define the secret in your `docker-bake.hcl` file:

```hcl
target "default" {
  context    = "."
  dockerfile = "Dockerfile"
  tags       = ["your-image:tag"]
  secret = [
    {
      type = "env"
      id   = "DEPOT_TOKEN"
    }
  ]
}
```

Then run the build:

```shell
DEPOT_TOKEN=your_token depot bake
```

## Depot GitHub Actions runners

[Depot GitHub Actions runners](/docs/github-actions/overview) are pre-configured to use Depot Cache with moonrepo. Each runner launches with the necessary environment variables for accessing Depot Cache.

You don't need additional configuration. Run your moonrepo builds as normal:

```yaml
jobs:
  build:
    runs-on: depot-ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - run: moon run build
```

To disable automatic configuration, turn off **Allow Actions jobs to automatically connect to Depot Cache** in your organization settings page. You can then manually configure moonrepo as described in the Local workstation section.

## Depot GitHub Actions runners with containerized builds

When running containerized builds on Depot GitHub Actions runners, your build needs access to moonrepo's remote cache credentials. These credentials aren't automatically available inside your Docker build environment.

### Moonrepo configuration

Configure moonrepo to read the Depot token from an environment variable in `.moon/workspace.yml`:

```yaml
unstable_remote:
  host: 'grpcs://cache.depot.dev'
  auth:
    token: 'DEPOT_TOKEN'
```

### Dockerfile configuration

Update your Dockerfile to copy the workspace configuration and run the build with mounted secret:

```dockerfile
# syntax=docker/dockerfile:1

# ... other Dockerfile instructions

# Copy moonrepo workspace configuration
COPY .moon/workspace.yml .moon/workspace.yml

# Mount secret as environment variable and run build
RUN --mount=type=secret,id=DEPOT_TOKEN,env=DEPOT_TOKEN \
    moon run build
```

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

### `depot/build-push-action`

Store the Depot token in a GitHub Secret named `DEPOT_TOKEN`, then configure your workflow:

```yaml
- 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 }}"
```

### `depot/bake-action`

Define the secret in your `docker-bake.hcl` file:

```hcl
target "default" {
  context    = "."
  dockerfile = "Dockerfile"
  tags       = ["your-image:tag"]
  secret = [
    {
      type = "env"
      id   = "DEPOT_TOKEN"
    }
  ]
}
```

Then configure your workflow:

```yaml
- name: Bake
  uses: depot/bake-action@v1
  with:
    files: docker-bake.hcl
  env:
    DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}
```

### Docker CLI

Store the Depot token in a GitHub Secret named `DEPOT_TOKEN`, then configure your workflow:

```yaml
- name: Build
  run: |
    docker buildx build \
      --secret id=DEPOT_TOKEN,env=DEPOT_TOKEN \
      -t your-image:tag .
  env:
    DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}
```

## For AI Agents

The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.