Skip to main content

​
Overview

useblacksmith/checkout is a drop-in replacement for actions/checkout that caches git repositories on Blacksmith’s sticky disks. Instead of cloning your entire repository from GitHub on every workflow run, the action maintains a persistent git mirror that is updated incrementally, only fetching new commits and refs since the last run.
Git checkout caching is currently in beta. We encourage users to stay on the latest published release as we are rapidly fixing bugs and incorporating feedback.

​
Why use this

Large repositories that are slow to clone. If your repo is multiple gigabytes and git clone adds minutes to the start of every job, checkout caching cuts that time down by keeping a local mirror on the runner. After the first run, only new commits are fetched, turning a multi-minute clone into a sub-second operation. Fewer failures from intermittent GitHub outages. Every object you pull from GitHub is a chance for a transient network error or rate limit to stall your pipeline. Caching the repository locally and only fetching the delta on each run means fewer objects transferred, and fewer chances for something to go wrong.

​
How it works

Git checkout caching uses sticky disks to persist a bare git mirror across workflow runs. The checkout process has three phases:
  1. First run (hydration): The action creates a full git clone --mirror of your repository on a sticky disk. This initial clone takes the same time as a regular clone, but it only happens once.
  2. Incremental updates: On subsequent runs, the mirror is updated with git fetch --prune to pull only new refs and objects. The workspace checkout then uses git’s alternates mechanism to reference objects from the mirror without copying them, so checkout time stays flat no matter how big the repo gets.
  3. Concurrent job handling: If a hydration is still in progress when another job starts, the action automatically falls back to a standard actions/checkout clone. Once the mirror is ready, all subsequent jobs use it.
Cache failures are always safe. If the mirror or sticky disk is unavailable for any reason, the action falls back to a standard clone from GitHub and your workflow continues normally.

​
Usage

Swap actions/checkout for useblacksmith/checkout. All existing inputs work the same. The only additions are dissociate and verbose. 
steps:
  - uses: useblacksmith/checkout@v1
    with:
      # All standard actions/checkout inputs are supported.
      # For example:
      fetch-depth: 0

​
The dissociate option

By default, the workspace references objects from the mirror via git alternates. This is fast, but means the checkout depends on the mirror mount being accessible. If you’re running Docker-based actions that won’t have access to the mount, set dissociate: true to copy objects into the workspace: 
steps:
  - uses: useblacksmith/checkout@v1
    with:
      dissociate: true
This makes the checkout self-contained at the cost of a slightly longer checkout time and larger workspace.

​
Monitoring usage

You can see storage usage for your git mirror sticky disk on the Sticky Disks page in the Blacksmith dashboard.

​
Pricing

Git checkout caching is powered by sticky disks and charged at $0.50/GB/mo. For details, see our pricing page.

​
FAQ

Git mirror caches are stored on sticky disks and are automatically evicted after 7 days of inactivity. Each time a workflow uses the cached mirror, the “last used” timestamp resets. As long as your workflows run at least once within 7 days, the mirror stays available.
Yes. The mirror always stores a complete clone, but your workspace respects the fetch-depth input. Git’s alternates mechanism lets a shallow workspace reference objects from the full mirror without downloading them again.
The action falls back to a standard clone from GitHub. Cache failures never break your workflow. They just mean that particular run won’t benefit from caching.
No. Garbage collection (git gc --prune=now) runs in the post-job cleanup phase, after all your workflow steps have completed. This keeps checkout fast and avoids impacting your build.