{"id":48648117,"url":"https://github.com/boringcache/one","last_synced_at":"2026-05-06T22:01:56.271Z","repository":{"id":343987338,"uuid":"1179793221","full_name":"boringcache/one","owner":"boringcache","description":"Main GitHub Action for BoringCache shared build cache workflows.","archived":false,"fork":false,"pushed_at":"2026-05-03T04:31:29.000Z","size":9134,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T06:36:48.328Z","etag":null,"topics":["build-cache","ci","docker","github-actions","remote-cache"],"latest_commit_sha":null,"homepage":"https://boringcache.com/docs#one-action","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boringcache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-12T11:41:15.000Z","updated_at":"2026-05-03T04:23:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/boringcache/one","commit_stats":null,"previous_names":["boringcache/one"],"tags_count":77,"template":false,"template_full_name":null,"purl":"pkg:github/boringcache/one","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boringcache%2Fone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boringcache%2Fone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boringcache%2Fone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boringcache%2Fone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boringcache","download_url":"https://codeload.github.com/boringcache/one/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boringcache%2Fone/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32713820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T19:35:05.142Z","status":"ssl_error","status_checked_at":"2026-05-06T19:35:03.996Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build-cache","ci","docker","github-actions","remote-cache"],"created_at":"2026-04-10T08:09:04.942Z","updated_at":"2026-05-06T22:01:56.264Z","avatar_url":"https://github.com/boringcache.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# boringcache/one\n\n`boringcache/one` is the main GitHub Actions entrypoint for BoringCache.\n\nIf you are starting fresh, the preferred path is:\n\n1. install the CLI locally\n2. run `boringcache onboard`\n3. commit `.boringcache.toml` when it helps\n4. use `boringcache/one@v1` in GitHub Actions\n\nThat keeps local runs, Docker builds, and GitHub Actions on the same workspace, cache names, and trust model.\n\nIf you are migrating an existing workflow and do not want repo config yet, raw `entries` plus `actions/cache` compatibility inputs such as `path`, `key`, and `restore-keys` still work.\n\n## Quick start\n\n```yaml\n- uses: boringcache/one@v1\n  with:\n    workspace: my-org/my-project\n    cache-profiles: bundle-install\n  env:\n    BORINGCACHE_RESTORE_TOKEN: ${{ secrets.BORINGCACHE_RESTORE_TOKEN }}\n    BORINGCACHE_SAVE_TOKEN: ${{ secrets.BORINGCACHE_SAVE_TOKEN }}\n```\n\nIf you do not have repo config yet, start with explicit entries:\n\n```yaml\n- uses: boringcache/one@v1\n  with:\n    workspace: my-org/my-project\n    entries: bundler:vendor/bundle,node:node_modules\n  env:\n    BORINGCACHE_RESTORE_TOKEN: ${{ secrets.BORINGCACHE_RESTORE_TOKEN }}\n    BORINGCACHE_SAVE_TOKEN: ${{ secrets.BORINGCACHE_SAVE_TOKEN }}\n```\n\nFor Docker or native remote-cache flows, set the mode you need and keep the same workspace:\n\n```yaml\n- uses: boringcache/one@v1\n  with:\n    mode: docker\n    workspace: my-org/my-project\n    image: ghcr.io/${{ github.repository }}\n    tags: latest,${{ github.sha }}\n  env:\n    BORINGCACHE_RESTORE_TOKEN: ${{ secrets.BORINGCACHE_RESTORE_TOKEN }}\n    BORINGCACHE_SAVE_TOKEN: ${{ secrets.BORINGCACHE_SAVE_TOKEN }}\n```\n\nIf you want dashboard sessions and misses grouped by an explicit low-cardinality label, pass `metadata-hints` on the action itself:\n\n```yaml\n- uses: boringcache/one@v1\n  with:\n    mode: bazel\n    workspace: my-org/my-project\n    cache-tag: bazel-main\n    metadata-hints: |\n      tool=bazel\n      phase=ci\n  env:\n    BORINGCACHE_RESTORE_TOKEN: ${{ secrets.BORINGCACHE_RESTORE_TOKEN }}\n    BORINGCACHE_SAVE_TOKEN: ${{ secrets.BORINGCACHE_SAVE_TOKEN }}\n```\n\nUse short stable labels such as `project=web`, `phase=seed`, `phase=warm`, `tool=gradle`, or `benchmark=grpc-bazel`. These hints are replayable proxy arguments, so keep them low-cardinality and avoid commit SHAs, run ids, or other per-run values.\n\nIf the repo already defines shared proxy labels in `.boringcache.toml`, `boringcache/one` inherits them through the CLI dry-run plan. Prefer repo config for durable defaults and use the action-level `metadata-hints` input only when a workflow needs an explicit override.\n\nDocker workflows should use `mode: docker` or `mode: buildkit`. The action follows the CLI dry-run plan and passes BuildKit registry cache refs to the build.\n\nFor Docker and BuildKit registry caches, the action follows the CLI's ref plan.\nPull request runs are restore-only by default, so a PR-scoped ref such as `/cache:pr-3208` may legitimately 404, especially on the first PR run.\nThat miss should not make the build cold: restore-only PRs continue with the CLI-planned base/default imports, while PR writes stay opt-in.\nIf a repo deliberately wants PR-scoped Docker cache writes, provide a save-capable token and set `save-on-pull-request: true`; the default derived promotion for a PR is the PR alias, while branch and default aliases remain trusted-branch outputs.\n\nArchive caches use the same trust model through the CLI. Default-branch runs\nread/write the default tag, trusted branch runs read branch then default and\nwrite branch, PRs read base/default and save nothing by default, and\n`save-on-pull-request: true` makes the PR read/write target isolated to that PR:\nthe action exports `BORINGCACHE_SAVE_ON_PULL_REQUEST=1` for its post-save phase\nand sets `BORINGCACHE_RESTORE_PR_CACHE=1` for CLI restore subprocesses.\nIf you build explicit tags from refs, slug branch names before passing them to\nthe action; explicit tags are not silently rewritten.\n\nFor Docker and BuildKit setup flows, `boringcache/one` now treats proxy readiness and OCI import readability as one contract.\nThe setup step waits for the started proxy to be reachable, probes each CLI-planned import ref through the proxy, and exposes both the requested and actually usable import refs.\nIf some planned refs are unreadable, the action keeps the build path fail-safe:\n\n- `cache-from` / `cache-to` stay the action-owned source of truth for the actual build command.\n- `docker-cache-from-refs` reports the readable refs that were actually used.\n- `docker-cache-requested-from-refs` reports the full CLI-planned ref set.\n- `docker-cache-unreadable-from-refs` reports the refs that were planned but not readable through the started proxy.\n- `docker-cache-import-ready` is `true` only when every planned import ref was readable.\n\nIf none of the planned refs are readable, the action treats that as a cold seed\nand continues without registry imports. If only some refs are readable, it keeps\na warning because the planned warm import set is degraded.\n\nSet `require-oci-import-ready: true` for benchmark or deployment phases where a\nwarm OCI import is mandatory. In that mode, the action fails setup when the CLI\nplan has no import refs, when no planned import ref is readable, or when only a\npartial planned import set is readable.\n\nWrite-capable Docker and BuildKit runs also include CLI-planned promotion refs\nin post-save verification, so branch/default OCI aliases are checked before the\naction finishes instead of only trusting proxy shutdown.\n\nWorkflow authors should consume those outputs instead of polling `/_boringcache/status` or probing `/v2/cache/manifests/*` themselves.\n\n## What it handles\n\n- archive caching for repeated directories\n- `mise`-based tool setup by default\n- Docker and BuildKit cache flows\n- Bazel, Go, Gradle, Maven, Turbo, and Rust plus `sccache` proxy-backed modes\n- repo-config-driven cache profiles after `boringcache onboard`\n\n## Maintainer model\n\n`boringcache/one` owns its GitHub Actions support code directly under `lib/core/`. Releases are self-contained: this action does not depend on the retired `@boringcache/action-core` npm package, and maintained behavior should not be split across a second package version.\n\n## Trust model\n\n- every job that should read cache gets `BORINGCACHE_RESTORE_TOKEN`\n- only trusted jobs get `BORINGCACHE_SAVE_TOKEN`\n- `pull_request` jobs stay restore-only by default; set `save-on-pull-request: true` only when the write scope is intentionally isolated\n- missing PR-scoped Docker refs on restore-only PRs are expected cache misses, not a reason to grant write access by themselves\n- new workflows should avoid broad `BORINGCACHE_API_TOKEN` use in CI\n\nFor bootstrap or setup-only steps that should never publish cache, set:\n\n```yaml\n- uses: boringcache/one@v1\n  with:\n    save-policy: off\n```\n\nThat keeps the step restore-only by configuration instead of emitting missing-save-token noise in the post step.\n\n## Mental model\n\n- `workspace` is the shared cache boundary\n- `entries` add archive caches, including optional hybrid local-state caches alongside remote modes\n- `cache-profiles` resolve repo-defined cache groups from `.boringcache.toml`\n- `preset` is for archive-oriented defaults plus tool detection\n- `mode` selects the primary adapter when you need Docker or a native remote-cache flow; proxy/build modes stay pure remote unless you also set `entries`\n- `setup` defaults to `mise`\n- `verify` defaults to `none`; set `check` for one-shot tag checks or `wait`/`warn` when you explicitly want polling\n\nIn most workflows, set `workspace` and then one of:\n\n- `cache-profiles`\n- `entries`\n- `preset`\n- a mode-specific input such as `image`\n\n`action.yml` is the source of truth for the full input and output surface.\n\n## Learn more\n\n- [GitHub Actions docs](https://boringcache.com/docs#one-action)\n- [GitHub Actions auth and trust model](https://boringcache.com/docs#actions-auth)\n- [CLI docs](https://github.com/boringcache/cli/tree/main/docs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboringcache%2Fone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboringcache%2Fone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboringcache%2Fone/lists"}