boringcache/BoringCache One
Maintained GitHub Action entrypoint for the BoringCache suite across archive caches, proxy-backed modes, and build adapters.
View on GitHubTrust Signals
- Scorecard Score
- not yet scored
- Maintenance Recency
- Activelast commit Jul 9, 2026
- License
- MIT
Pinned Snippet
uses: boringcache/one@d39427a8c278c17670e2fbb1b2ba9a699b61075f # v1.13.92tags can be moved; commit SHAs can't. why a SHA?
Inputs
| name | description | required | default |
|---|---|---|---|
| cli-version | Version of BoringCache CLI to install (e.g., v1.0.1). Set to "skip" to disable automatic CLI setup. | no | v1.13.102 |
| cli-platform | Optional CLI target/platform override for advanced diagnostics and compatibility cases (for example linux-amd64 or linux-musl-amd64). Legacy distro aliases are normalized to the generic release asset names. | no | — |
| setup | Runtime setup owner: mise, external, or none. mise auto-detects project tools from mise.toml, .tool-versions, and common version files. | no | mise |
| mode | Primary cache behavior: auto or archive for portable caches, or a proxy/build adapter mode such as docker, buildkit, bazel, go, gradle, maven, nx-proxy, rust-sccache, or turbo-proxy. Proxy/build modes are pure remote by default; add entries when you want explicit local archive caches too. | no | auto |
| preset | Workflow preset for archive-oriented defaults and tool detection: none, rails, ruby, node, node-turbo, python-uv, go, or php-composer. Presets add archive caches; use mode for pure remote adapter flows. | no | none |
| workspace | Workspace identifier in format namespace/workspace (e.g., my-org/my-project). If not provided, uses repo config workspace or BORINGCACHE_DEFAULT_WORKSPACE/CLI defaults. | no | — |
| cache-tag | Human-readable cache tag or prefix. Generated archive entries, runtime caches, and proxy tags derive deterministic names from this when you do not set exact overrides. | no | — |
| runtime-cache-tag | Optional exact tag for the mise installs cache. Use this when you want the same runtime cache tag across GitHub Actions, local CLI, and Docker workflows. | no | — |
| working-directory | Project root used for tool detection and relative cache paths. | no | . |
| tools | Explicit mise tools to install, one per line (for example ruby@3.3, node@22). Overrides auto-detected project tools for the same names. | no | — |
| tool-version-scope | How generated runtime and archive tags encode tool versions: patch, minor, or major. | no | patch |
| cache-runtime | Cache mise tool installs when setup is mise. Shims are regenerated after restore. | no | true |
| read-only | Proxy-backed modes: run without writes when supported. | no | false |
| save-policy | Whether boringcache/one should publish cache updates in the post step: auto (default) saves when event policy and tokens allow it, off keeps the step restore-only by configuration. | no | auto |
| save-on-pull-request | Allow save-capable tokens to publish cache updates on pull_request events. Defaults to false so pull requests stay restore-only; missing PR-scoped Docker cache refs should fall back to CLI-planned base/default imports, not require PR writes. | no | false |
| verify | Optional internal verification for resolved tags: none, check, wait, or warn. check is one-shot; wait and warn poll explicitly. Save-capable tags verify in the post step after save completes. | no | none |
| verify-timeout-seconds | Timeout in seconds for verify=wait/warn tag checks and managed Docker/BuildKit cache promotion checks. Values above 900 are clamped to keep verification bounded. | no | 180 |
| verify-require-server-signature | Require signed cache hits during verification. | no | false |
| trusted-workspace-signing-key-fingerprint | Optional ed25519-sha256 workspace signing key fingerprint. When set, the CLI only accepts signed cache hits from this workspace key. | no | — |
| diagnostics | Action-level diagnostics: auto follows ACTIONS_STEP_DEBUG, off disables grouped diagnostics, summary emits grouped state, and verbose also tails proxy logs. | no | auto |
| diagnostics-log-lines | When diagnostics includes logs, tail up to this many proxy log lines. Values above 500 are clamped to keep diagnostics bounded. | no | 40 |
| metadata-hints | Low-cardinality proxy session labels as KEY=VALUE pairs, comma-separated or newline-separated. Use this for grouping hints such as phase=seed, project=web, tool=bazel, or benchmark=grpc-bazel. | no | — |
| proxy-port | Proxy-backed modes: explicit TCP port from 1 to 65535. Leave blank to use the mode default or an automatically selected port. | no | — |
| proxy-no-git | Proxy-backed modes: disable git scoping. | no | false |
| proxy-no-platform | Proxy-backed modes: disable platform scoping. | no | false |
| context | Docker or BuildKit build context path. | no | . |
| dockerfile | Dockerfile path relative to the working directory or build context. | no | Dockerfile |
| image | Docker or BuildKit image name (for example ghcr.io/org/app). | no | — |
| tags | Image tags, comma-separated or newline-separated. | no | latest |
| build-args | Build arguments as newline-separated KEY=VALUE pairs. | no | — |
| target | Target build stage. | no | — |
| platforms | Target platforms for multi-arch builds. | no | — |
| push | Whether to push image output to the registry. Must be true or false. | no | false |
| load | Whether to load Docker image output into the local daemon when supported. Must be true or false. | no | true |
| no-cache | Whether to disable cache usage for Docker or BuildKit builds. Must be true or false. | no | false |
| provenance | Docker mode only: pass --provenance=true to docker buildx build. Must be true or false. | no | false |
| sbom | Docker mode only: pass --sbom=true to docker buildx build. Must be true or false. | no | false |
| secrets | Docker or BuildKit secrets, newline-separated. | no | — |
| docker-tool-cache | Docker mode only: expose session-only BoringCache remote-cache config for Turbo, Nx, Bazel, Gradle, Maven, sccache, or Go inside matching Dockerfile RUN steps. Accepts comma- or newline-separated TOOL:TAG values, or plain tool names backed by [adapters.<tool>].tag. | no | — |
| driver | Buildx driver for Docker mode. | no | docker-container |
| docker-command | Docker mode behavior: build (default) runs docker buildx build; setup prepares the managed BuildKit builder. Must be build or setup. | no | build |
| driver-opts | Additional buildx driver options, newline-separated. | no | — |
| buildkitd-config-inline | Inline BuildKit daemon TOML config for Docker mode. | no | — |
| managed-buildkit-image | Managed BoringCache BuildKit image. Defaults to the signed release digest; pass an explicit digest for canaries. | no | ghcr.io/boringcache/buildkit@sha256:2f6ddc6319f598180955e89e3a846b259b216458d528912c1477700670c96869 |
| cache-mode | Build cache mode for Docker or BuildKit. Must be min or max. | no | max |
| buildkit-host | BuildKit address for buildctl mode, for example tcp://host:1234 or unix:///run/buildkit/buildkitd.sock. | no | — |
| buildkit-tls-ca | TLS CA certificate path or PEM contents for BuildKit. | no | — |
| buildkit-tls-cert | TLS client certificate path or PEM contents for BuildKit. | no | — |
| buildkit-tls-key | TLS client key path or PEM contents for BuildKit. | no | — |
| buildkit-tls-skip-verify | Whether to skip TLS verification for BuildKit. Must be true or false. | no | false |
| output | Custom buildctl output. When set, image, tags, and push are ignored in BuildKit mode. | no | — |
| ssh | BuildKit SSH specs, newline-separated. | no | — |
| bazel-version | Bazel version for Bazelisk. Sets USE_BAZEL_VERSION when provided or auto-detected via mise. | no | — |
| bazelrc-lines | Additional newline-separated Bazel rc lines appended after boringcache/one writes the remote cache block. | no | — |
| gradle-home | Gradle user home directory. | no | ~/.gradle |
| enable-build-cache | Whether to set org.gradle.caching=true in gradle.properties. Must be true or false. | no | true |
| maven-version | Maven version to install when setup=mise and the project does not already pin it. | no | 3.9.9 |
| uv-version | uv version to install for preset=python-uv when the project does not already pin it through mise. | no | 0.9.21 |
| composer-version | Composer version to install for preset=php-composer when the project does not already pin it through mise. | no | 2.9.5 |
| maven-local-repo | Local Maven repository path. Used for archive defaults in Maven mode. | no | ~/.m2/repository |
| maven-extensions-path | Path to .mvn/extensions.xml. Maven mode ensures the build-cache extension is present here. | no | .mvn/extensions.xml |
| maven-build-cache-config-path | Path to .mvn/maven-build-cache-config.xml written by Maven mode. | no | .mvn/maven-build-cache-config.xml |
| maven-build-cache-extension-version | Version of org.apache.maven.extensions:maven-build-cache-extension to configure in Maven mode. | no | 1.2.3 |
| maven-build-cache-id | Logical Maven remote build-cache id for the generated config. | no | boringcache |
| rust-version | Rust version or channel to install when not handled by mise. | no | — |
| toolchain | Alias for rust-version. | no | — |
| targets | Rust target triples to install, comma-separated. | no | — |
| components | Rust components to install, comma-separated. | no | — |
| profile | Rustup profile. Must be minimal, default, or complete. | no | minimal |
| cache-cargo | Whether to cache cargo registry and git directories. Must be true or false. | no | true |
| cache-cargo-bin | Whether to cache cargo bin directory. Must be true or false. | no | false |
| cache-target | Whether to cache the Rust target directory. Must be true or false. | no | true |
| sccache | Whether to enable sccache for Rust builds. Must be true or false. | no | false |
| sccache-version | sccache version to install when the binary is not already available. Explicit versions require the matching publisher .sha256 release asset. | no | 0.16.0 |
| sccache-cache-size | Maximum local sccache cache size. | no | 5G |
| sccache-mode | sccache storage mode. Must be local or proxy. | no | local |
| turbo-api-url | Explicit Turbo remote cache endpoint. When omitted, boringcache/one starts a local proxy. | no | — |
| turbo-token | Turbo remote cache token. | no | — |
| turbo-team | Turbo remote cache team slug. | no | — |
| turbo-port | Preferred TCP port for a local Turbo proxy, from 1 to 65535. | no | — |
| nx-access-token | Nx self-hosted remote cache access token. Defaults to the proxy-internal token. | no | — |
| nx-port | Preferred TCP port for a local Nx self-hosted remote cache proxy, from 1 to 65535. | no | — |
| cache-profiles | Optional repo cache profile names from .boringcache.toml or boringcache.toml (comma-separated or newline-separated). These resolve through the CLI source of truth before any extra raw entries are appended. | no | — |
| entries | Optional archive entries. Accepts repo/built-in entry ids such as bundler or node_modules, or raw tag:path pairs (one per line; legacy comma lists remain supported and literal commas can be written as \,). Semantic entries resolve through the CLI source of truth. Use this to opt into hybrid local archive caches alongside proxy/build modes. | no | — |
| path | Newline-separated exact paths and deterministic directory/** roots (actions/cache migration compatibility). Lines use actions/glob trimming and # remains a literal path prefix. Leading-! exclusions support only literal !directory/subdirectory/** subtrees under one directory/** root and cannot share a save with cache-runtime. Commas and internal spaces are literal. | no | — |
| key | An explicit key for restoring and saving the cache (actions/cache compatible) | no | — |
| restore-keys | An ordered list of prefix-matched keys for restoring stale cache if no cache hit occurred | no | — |
| enableCrossOsArchive | Share one tag across operating systems by disabling platform suffixes and forcing canonical tar archive transport. Equivalent representable content can reuse one tar root; BoringCache does not translate filesystem semantics. Requires CLI v1.13.100+. | no | false |
| save-always | Run the post step to save the cache even if another step fails. Supports the same true spellings as GitHub boolean inputs. | no | false |
| no-platform | Disable automatic platform suffix for tags (CLI --no-platform flag) | no | false |
| fail-on-cache-miss | Fail the workflow if cache entry is not found (CLI --fail-on-cache-miss flag) | no | false |
| fail-on-cache-error | Fail the workflow when cache restore, save, or proxy work fails. Defaults to false so a successful build remains successful; GitHub continue-on-error may still soften an explicitly strict step. | no | false |
| require-oci-import-ready | Deprecated v1 compatibility input. Fail Docker or BuildKit setup when any planned managed cache ref is unreadable. | no | false |
| lookup-only | Check if a cache entry exists without downloading (CLI --lookup-only flag) | no | false |
| force | Force save even if cache entry already exists on server (CLI --force flag) | no | false |
| verbose | Enable detailed output (CLI --verbose flag) | no | false |
| exclude | Legacy comma-separated glob patterns to exclude from cache (for example "*.out,*.log"). | no | — |
| exclude-patterns | Tar exclusion patterns, one per line. Preserves commas and significant whitespace. Requires CLI v1.13.100+ for writable steps. | no | — |
| allow-external-symlinks | Allow external symlinks in content-addressed layouts (CLI --allow-external-symlinks flag). Tar archive transport leaves symlink handling to tar. Requires CLI v1.13.100+. | no | false |
Outputs
| name | description |
|---|---|
| cache-hit | A boolean value indicating an archive or mode-specific cache hit was found |
| runtime-cache-hit | A boolean value indicating the mise runtime cache was restored |
| diagnostics-level | Effective diagnostics level used by the action: off, summary, or verbose |
| evidence-path | Path to the local boringcache/one JSON evidence file with restore and post-step state |
| resolved-mode | The effective cache mode used by the action |
| resolved-tools | Resolved mise tools as a newline-separated list |
| workspace | Resolved BoringCache workspace |
| cache-tag | Resolved cache tag or prefix |
| runtime-cache-tag | Resolved mise runtime cache tag |
| resolved-entries | Resolved archive cache entries after deterministic tool scoping |
| resolved-tags | Resolved exact cache tags used by boringcache/one for verification and follow-up checks |
| proxy-port | Resolved proxy port for proxy-backed modes |
| proxy-log-path | Proxy log file path for proxy-backed modes |
| cache-ref | Resolved managed Docker or BuildKit cache ref. |
| cache-from | Resolved Docker --cache-from or BuildKit --import-cache values for Docker or BuildKit modes, newline-separated when the CLI plan includes multiple import refs. PR-scoped refs may be absent on restore-only PR runs. |
| cache-to | Resolved Docker --cache-to or BuildKit --export-cache value for Docker or BuildKit modes |
| docker-cache-run-ref | Provider-neutral immutable Docker or BuildKit cache run ref tag when CI run-ref derivation is active |
| docker-cache-from-refs | Newline-separated managed Docker or BuildKit cache ref tags that were actually readable and used for restore |
| docker-cache-requested-from-refs | Newline-separated managed Docker or BuildKit cache ref tags requested from the CLI plan before readability filtering |
| docker-cache-unreadable-from-refs | Newline-separated managed Docker or BuildKit cache ref tags that were requested but not readable |
| docker-cache-import-ready | Whether every requested managed Docker or BuildKit cache ref was readable before the build began |
| docker-cache-promotion-refs | Newline-separated managed Docker or BuildKit cache alias ref tags requested for promotion |
| docker-ci-provider | Provider-neutral CI provider name used for Docker or BuildKit cache run-ref derivation |
| docker-ci-run-id | Provider-neutral CI run id used for Docker or BuildKit cache run-ref derivation |
| docker-ci-run-attempt | Provider-neutral CI run attempt used for Docker or BuildKit cache run-ref derivation |
| docker-ci-ref-type | Provider-neutral CI ref type used for Docker or BuildKit cache run-ref derivation |
| docker-ci-ref-name | Provider-neutral CI ref name used for Docker or BuildKit cache run-ref derivation |
| docker-ci-run-started-at | Provider-neutral CI run start timestamp used for Docker or BuildKit alias promotion ordering when available |
| cache-dir | Resolved local cache import directory for Docker or BuildKit local backend |
| save-cache-dir | Resolved local cache export directory for Docker or BuildKit local backend |
| image-id | Built Docker image ID when available |
| digest | Built image digest when available |
| buildx-name | Docker buildx builder name |
| buildx-platforms | Available platforms for the Docker buildx builder |
| rust-version | Resolved Rust version |
| cargo-tag | Resolved cargo registry cache tag |
| cargo-git-tag | Resolved cargo git cache tag |
| target-tag | Resolved Rust target cache tag |
| cargo-bin-tag | Resolved cargo bin cache tag |
| sccache-tag | Resolved sccache cache tag |
| sccache-hit | Whether the sccache cache was restored |
| package-manager | Detected Node.js package manager for Turbo mode |
| package-manager-cache-dir | Resolved package-manager cache directory exported by Turbo mode |
| maven-extensions-path | Resolved Maven extensions.xml path |
| maven-build-cache-config-path | Resolved Maven build-cache config path |
| maven-local-repo | Resolved Maven local repository path |