Caching

How caching works

The runner's local disk is destroyed when the job finishes, so files do not carry over automatically. actions/cache works normally: on jobs with FlareRunner dependency caching enabled, FlareRunner routes cache traffic to its own private Cloudflare R2 storage. Archives persist independently of the runner and can be restored by later jobs with a matching key, version, and permitted branch scope. GitHub artifact uploads continue to use GitHub's artifact service. Jobs without FlareRunner dependency caching use GitHub's cache service. The FlareRunner Cache page lists only FlareRunner-managed archives; it is not an inventory of GitHub caches or artifacts.

Cache dependencies

Build a key from the operating system, package manager, and lockfile. A broader restore key can reuse the closest available cache when the exact lockfile has changed.

- name: Restore npm cache
  uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- name: Install dependencies
  run: npm ci

When a setup action offers a built-in cache option, such as actions/setup-node, that is often the simplest choice.

Read the cache inventory

Open the repository's Runs menu and select Cache to see archives stored by FlareRunner. The page shows repository and workspace capacity, archive sizes, expiration, and the last matching lookup. A lookup match does not confirm that a job finished downloading or restoring the archive.

• Key and version: the key identifies reusable inputs. The action also supplies a version derived from the cached paths and archive format. Expand Version to inspect it; matching a key alone does not make different versions interchangeable.
• Branch and writer: identify the source scope and job that wrote the archive. Workflow restores remain limited to the branch scopes permitted for that job.
• Size and capacity: archive bytes count toward both repository and workspace limits. An unfinished upload reserves capacity before its final size is verified. Limits and usage are shown in binary units such as MiB and GiB.
• Last matched: the last recorded successful lookup, updated at most once per minute. It is not a download completion timestamp and does not extend the archive's expiry.

Retention and deletion

Entries expire seven days after the archive is verified and may be evicted sooner when capacity is needed. A restore does not restart this period. Repository admins can delete entries before expiry. Deletion releases capacity when removal finishes, so a deleting entry can still appear in the capacity totals briefly. Caches are disposable: every job must be able to rebuild its dependencies after a miss.

Download an archive

Repository members can download a ready, unexpired archive. Downloads preserve the original bytes and compression produced by the caching action; the .cache filename does not convert it to a ZIP. Use an archive tool that supports the original format. Access is checked again when the download starts; an expired, deleted, or inaccessible archive cannot be downloaded from an old inventory page. Downloading does not renew retention. Use GitHub artifacts for release files and other outputs that need a longer, deliberate retention period.

Cache billing and usage

Cache archives are stored in FlareRunner's private Cloudflare R2 Standard bucket. Cache billing applies automatically to all workspaces. Storage, writes and reads draw from service credit at the rates below. View usage and charges under Billing → Usage.

Standard storage transfer and retrieval are included. Rate card: storage-2026-10-10.

Storage uses the compressed archive's actual byte count, prorated to milliseconds with a decimal GB (1,000,000,000 bytes) and a 30-day month. Time starts when the verified archive is published and ends at expiry or a deletion request, whichever comes first. A capacity reservation is not a stored archive. Failed/unpublished uploads and delayed cleanup do not extend your storage bill.

Writes and reads are separate line items for successful R2 Class A and Class B operations initiated by your cache requests. Multipart uploads can use several operations. Downloading from the Cache page is a read; it does not start a runner or extend retention. Verification, metadata, cleanup and uncertain provider outcomes are covered by service prices. The activity table is diagnostic evidence, not an invoice.

Before new work begins, FlareRunner reserves sufficient prepaid service credit for its maximum exposure. Storage settles when an archive is deleted or expires; requests settle after completion. Unused credit is released. Small charges accumulate at sub-micro-dollar precision, rather than rounding each request up. Workspace spending limits apply to compute and storage together. Already-funded work can finish when the balance runs low.

Billing shows storage, writes and reads separately by workspace and repository. Compute remains separate and includes time spent uploading/restoring. Run log and resource trace retention currently have no separate charge. Shared infrastructure and payment processing are included in service prices. Workspace invoices separately show plan fees, credits, refunds and applicable taxes; credit purchases are not counted twice as service usage.

Example: 10 GB retained for 30 days, 10,000 writes and 100,000 reads cost $0.46 before discounts, in addition to compute and the workspace fee. Use the pricing calculator to include all three.

GitHub caches and artifacts remain separate GitHub services. Their charges do not appear in FlareRunner's capacity or service-credit totals.

Understand a run's cache activity

Open a job's Dependency cache section to inspect its observed lookups, uploads, downloads, and publication. A miss means no permitted archive matched; it is a normal outcome. The table records individual calls, so an upload that retries can have failed calls followed by a successful publication. A failed call is not, by itself, a failed job or proof that the final archive is missing. Use the job logs and the ready entry in the inventory to check the final result. GitHub cache traffic is not included in this section.

Keep caches safe and useful

• Never cache secrets, tokens, credentials, or other sensitive files.
• Prefer dependencies and compiler caches over the entire workspace.
• Change the key when the cached inputs or tool versions change.
• Use artifacts, not caches, for files people or later jobs must reliably download.

Check whether it helps

Restoring and saving a cache takes runner time. Start with expensive, repeatable downloads, then compare job duration and cache hit rate. A large cache with few hits may be slower than rebuilding it.