BuildKit Cache Dance

To use this action in a GitHub Actions workflow, you need to follow a specific sequence:

1. Use actions/cache to persist a directory (e.g., cache-mount).
2. Use reproducible-containers/buildkit-cache-dance@v3 to restore (inject) the cache before your build step. Use skip-extraction: ${{ steps.cache.outputs.cache-hit }} to avoid redundant extraction if the cache was already found.
3. Run your build (e.g., using docker/build-push-action).

Note: Your Dockerfile must use --mount=type=cache for the paths you wish to persist.

      - name: Cache
        uses: actions/cache@v4
        id: cache
        with:
          path: cache-mount
          key: cache-mount-${{ hashFiles('Dockerfile') }}

      - name: Restore Docker cache mounts
        uses: reproducible-containers/buildkit-cache-dance@v3
        with:
          builder: ${{ steps.setup-buildx.outputs.name }}
          cache-dir: cache-mount
          dockerfile: Dockerfile
          skip-extraction: ${{ steps.cache.outputs.cache-hit }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          cache-from: type=gha
          cache-to: type=gha,mode=max
          file: Dockerfile

By default, the action attempts to auto-discover cache mounts from your Dockerfile. If you need manual control, provide a cache-map as a JSON string.

Simple Mapping: Map a key (representing a path on the host/cache-dir) to the target path used in the Dockerfile.

Advanced Mapping: Provide a JSON object for each key to include additional BuildKit mount options like id. The target property is mandatory.

In GitHub Actions, use the cache-map input. In the CLI, use the --cache-map flag.

      - name: Restore Docker cache mounts
        uses: reproducible-containers/buildkit-cache-dance@v3
        with:
          builder: ${{ steps.setup-buildx.outputs.name }}
          cache-map: |
            {
              "var-cache-apt": {
                "target": "/var/cache/apt",
                "id": "1"
              },
              "var-lib-apt": "/var/lib/apt"
            }
          skip-extraction: ${{ steps.cache.outputs.cache-hit }}

The injectCaches function is the primary entrypoint for injecting BuildKit caches into a container image. It iterates through a cache map and performs a BuildKit build to copy cached files from a source directory into the target container image using --mount flags.

To use this, you must provide an Opts object containing:

• scratch-dir: A directory used to store temporary build files (like the generated Dancefile.inject).
• utility-image: The base container image used for the injection build.
• A cache map (retrieved via getCacheMap(opts)) which defines the source-to-target mapping and cache options.
• An optional builder name (retrieved via getBuilder(opts)).

import { injectCaches } from './src/inject-cache.js';

// Example usage (requires an implementation of Opts)
await injectCaches({
  'scratch-dir': './tmp',
  'utility-image': 'ubuntu:latest',
  // ... other options required by getCacheMap and getBuilder
});

The extractCaches function is the primary entrypoint for extracting BuildKit cache mounts from a container image and saving them to a local filesystem. It iterates through a mapping of cache sources and options, uses a temporary 'Dancefile' to mount the caches within a new container layer, and then unpacks those layers back to your host machine.

Workflow

1. Generates a Dancefile: Creates a temporary Dockerfile (Dancefile.extract) that uses --mount to access the specified cache paths.
2. Builds an Extraction Image: Uses docker buildx build to create a temporary image tagged dance:extract.
3. Unpacks Cache: Creates a container from the extraction image and pipes the contents of /var/dance-cache to the host using docker cp and tar.
4. Atomic Replacement: Removes the existing cacheSource directory and renames the newly extracted directory to the target cacheSource path.

Error Handling: Permission Issues

If the process fails to remove the existing cache directory due to permission errors (EACCES or EPERM), the function automatically falls back to using a Docker container with a bind mount to perform the rm -rf operation on the host path.

import { extractCaches } from './path-to-module';

// Example usage with an Opts object
await extractCaches({
  "skip-extraction": false,
  "scratch-dir": "./tmp/scratch",
  "utility-image": "debian:latest",
  // ... other Opts required by getCacheMap
} as any);

The following flags are available for the build-cache-dance command:

--extract      Extract the cache from the docker container (extract step). Otherwise, inject the cache (main step)
--cache-map    The map of actions source paths to container destination paths or mount arguments
--dockerfile   The Dockerfile to use for auto-discovery of the cache-map. Default: 'Dockerfile'
--cache-dir    The root directory where cache content is injected from/extracted to when using auto-discovery of the cache-map.
--scratch-dir  Where the action is stores some temporary files for its processing. Default: 'scratch'
--skip-extraction  Skip the extraction of the cache from the docker container
--utility-image  The container image to use for injecting and extracting the cache. Default: 'ghcr.io/containerd/busybox:latest'
--builder      The name of the buildx builder to use for the cache injection
--help         Show this help