https://github.com/boringcache/buildkit-action
Cache BuildKit layers with BoringCache for raw buildctl builds.
https://github.com/boringcache/buildkit-action
caching ci cicd dependency-management github-actions utilities
Last synced: 3 months ago
JSON representation
Cache BuildKit layers with BoringCache for raw buildctl builds.
- Host: GitHub
- URL: https://github.com/boringcache/buildkit-action
- Owner: boringcache
- Created: 2026-01-12T17:01:30.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T13:04:47.000Z (4 months ago)
- Last Synced: 2026-03-05T13:45:33.937Z (4 months ago)
- Topics: caching, ci, cicd, dependency-management, github-actions, utilities
- Language: TypeScript
- Homepage: https://boringcache.com
- Size: 2.49 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# boringcache/buildkit-action
Cache BuildKit layers with BoringCache for raw `buildctl` builds. Runs a local OCI registry proxy for lazy layer restore.
Layers are fetched on demand during `buildctl build` and pushed through the proxy — no bulk restore/save steps needed. Caches are content-addressed — identical content is never re-uploaded.
## Quick start
```yaml
- uses: boringcache/buildkit-action@v1
with:
buildkit-host: tcp://127.0.0.1:1234
workspace: my-org/my-project
image: ghcr.io/${{ github.repository }}
tags: latest,${{ github.sha }}
env:
BORINGCACHE_API_TOKEN: ${{ secrets.BORINGCACHE_API_TOKEN }}
```
Cache is automatically restored before build and saved after.
## Mental model
By default, this action runs a local OCI registry proxy (`boringcache serve`) that BuildKit talks to via `type=registry` cache flags. Layers are fetched lazily on cache hit and pushed through the proxy during the build — no bulk restore/save steps needed.
You still control your Dockerfile, build args, and output settings.
Notes:
- TLS inputs accept either file paths or raw PEM strings.
- Set `output` for custom buildctl outputs (for example, `type=local,dest=./out`).
- Set `cache-backend: local` to fall back to the older bulk restore/save flow with `type=local` cache flags.
- For Docker buildx builds, use `boringcache/docker-action` instead.
## Common patterns
### Simple buildctl build
```yaml
- uses: boringcache/buildkit-action@v1
with:
buildkit-host: tcp://127.0.0.1:1234
workspace: my-org/my-project
image: ghcr.io/${{ github.repository }}
tags: latest,${{ github.sha }}
env:
BORINGCACHE_API_TOKEN: ${{ secrets.BORINGCACHE_API_TOKEN }}
```
### Separate restore/save actions (advanced)
```yaml
- uses: boringcache/buildkit-action/restore@v1
id: cache
with:
workspace: my-org/my-project
- name: Build with buildctl
run: |
buildctl --addr $BUILDKIT_HOST build \
--frontend dockerfile.v0 \
--local context=. \
--local dockerfile=. \
--import-cache ${{ steps.cache.outputs.import-cache }} \
--export-cache ${{ steps.cache.outputs.export-cache }} \
--output type=image,name=my-app:latest,push=false
- uses: boringcache/buildkit-action/save@v1
with:
workspace: my-org/my-project
cache-tag: ${{ steps.cache.outputs.cache-tag }}
```
## Inputs
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `buildkit-host` | Yes | - | BuildKit address (e.g., `tcp://buildkit:1234`). |
| `image` | Yes | - | Base image name (e.g., `ghcr.io/org/app`). |
| `workspace` | No | repo name | Workspace in `org/repo` form. Defaults to `BORINGCACHE_DEFAULT_WORKSPACE` or repo name. |
| `context` | No | `.` | Build context path. |
| `dockerfile` | No | `Dockerfile` | Dockerfile path. |
| `tags` | No | `latest` | Image tags (comma or newline separated). |
| `push` | No | `false` | Push image to registry. |
| `output` | No | - | Custom `buildctl --output` string. When set, `image`, `tags`, and `push` are ignored. |
| `build-args` | No | - | Build arguments (newline-separated `KEY=VALUE`). |
| `secrets` | No | - | BuildKit secrets (newline separated). |
| `ssh` | No | - | SSH specs for BuildKit (newline separated). |
| `target` | No | - | Target build stage. |
| `platforms` | No | - | Target platforms (e.g., `linux/amd64,linux/arm64`). |
| `no-cache` | No | `false` | Build without cache. |
| `cache-mode` | No | `max` | BuildKit cache mode (`min` or `max`). |
| `cache-tag` | No | slugified image name | Cache tag for BoringCache. |
| `cli-version` | No | `v1.7.2` | BoringCache CLI version. Set to `skip` to disable installation. |
| `buildkit-tls-ca` | No | - | TLS CA certificate (path or PEM). |
| `buildkit-tls-cert` | No | - | TLS client certificate (path or PEM). |
| `buildkit-tls-key` | No | - | TLS client key (path or PEM). |
| `buildkit-tls-skip-verify` | No | `false` | Skip TLS verification. |
| `cache-backend` | No | `registry` | Cache backend: `registry` (lazy proxy) or `local` (bulk restore/save). |
| `proxy-port` | No | `5000` | Port for the BoringCache registry proxy. |
| `registry-tag` | No | - | Optional human-readable alias tag passed to `boringcache docker-registry`. |
| `proxy-no-git` | No | `false` | Pass `--no-git` to `boringcache docker-registry`. |
| `proxy-no-platform` | No | `false` | Pass `--no-platform` to `boringcache docker-registry`. |
| `verbose` | No | `false` | Enable verbose CLI output. |
| `exclude` | No | - | Glob pattern to exclude files from cache. |
## Outputs
| Output | Description |
|--------|-------------|
| `digest` | Image digest from buildctl metadata |
## Platform behavior
Platform scoping is what makes it safe to reuse caches across machines.
By default, caches are isolated by OS and architecture. This action uses your existing BuildKit daemon, so ensure it supports the target platforms you specify.
## Environment variables
| Variable | Description |
|----------|-------------|
| `BORINGCACHE_API_TOKEN` | API token for BoringCache authentication |
| `BORINGCACHE_DEFAULT_WORKSPACE` | Default workspace if not specified in inputs |
## Troubleshooting
- Cache not restored: ensure `BORINGCACHE_API_TOKEN` is set and the workspace exists.
- TLS connection failures: verify `buildkit-tls-*` values and `buildkit-tls-skip-verify`.
- buildctl output missing: check `output` and `push` settings.
## Release notes
See https://github.com/boringcache/buildkit-action/releases.
## License
MIT