The Blacksmith cache is a drop-in replacement for GitHub’s cache action. The Blacksmith cache co-locates cache artifacts in the same datacenter park as the bare metal instances running our VMs, and can almost saturate the NIC on our runners. GitHub’s cache action stores cache artifacts in Azure Blob Storage, which generally performs poorly when the action runner is not co-located in the same AZ as the storage. This results in ~4x faster cache download speeds compared to GitHub’s cache.

Migrating from the actions/cache to the Blacksmith cache is a one line change. Simply replace the actions/cache@v3 line in your workflow files with useblacksmith/cache@v5.

    name: Cache dependencies
-   uses: actions/cache@v3
+   uses: useblacksmith/cache@v5

If you’re using actions/cache/save and actions/cache/restore, you can migrate them to useblacksmith/cache/save and useblacksmith/cache/restore respectively.

For more information, refer to GitHub’s official documentation, since the Blacksmith cache is fully compatible with GitHub’s cache.

Cache Size and Pricing

There is no cost for using the Blacksmith cache. The Blacksmith cache provides 25GB of free storage per repo per week, a substantial increase from GitHub’s 10GB to maximize your cache hits. Like GitHub, our cache also evicts the least recently used cache entries that were last accessed more than 7 days ago. Contact us at [email protected] if you’d like us to increase the allowed cache size for your organization.

Language specific cache actions

In addition to the useblacksmith/cache, Blacksmith also provides drop-in replacements for GitHub’s official actions/setup-* actions. These replacements have the same semantics as the official setup actions, but they are backed by Blacksmith’s much faster and more reliable cache.

        name: Setup go
-       uses: actions/setup-go@v4
+       uses: useblacksmith/setup-go@v6
        with:
          go-version: '>=1.17.0'

Please refer to the README of each setup action for detailed instructions on how to configure them. For languages that we don’t have a setup action for, you can still leverage the useblacksmith/cache action to cache dependencies by following these guidelines.

Some languages have popular cache actions that are not maintained by GitHub. Blacksmith offers drop-in replacements for these actions too so that you can leverage our faster cache.

Blacksmith offers a drop-in replacement for Swatinem/rust-cache@v2. Once you make the changes outlined below, you can configure the action using these guidelines.

        name: Setup rust cache
-       uses: Swatinem/rust-cache@v2
+       uses: useblacksmith/rust-cache@v3

As our customers migrate to Blacksmith, we keep growing our list of cache actions that are compatible with Blacksmith’s cache.

        name: Run lint
-       uses: golangci/golangci-lint-action@v6
+       uses: useblacksmith/golangci-lint-action@v6

Using the Blacksmith cache inside a container

If your GitHub Actions job runs inside a container, you will need to ensure that the container is hydrated with certain Blacksmith specific environment variables. These environment variables allow the container to upload and download artifacts from Blacksmith’s cache.

To do this, you can add an env section to your container definition as shown below.

   container:
      image: mcr.microsoft.com/playwright:v1.41.1
+     env:
+       BLACKSMITH_CACHE_TOKEN: ${{ env.BLACKSMITH_CACHE_TOKEN }}
+       BLACKSMITH_CACHE_URL: ${{ env.BLACKSMITH_CACHE_URL }}
+       GITHUB_REPO_NAME: ${{ env.GITHUB_REPO_NAME }}

If the container image does not have tar installed, you will need to install it as a step inside the container. tar is required to extract the artifacts downloaded from Blacksmith’s cache.

   steps:
      - name: Install GNU tar
        run: |
          apk add --no-cache tar

Without these steps, you will see a 401 error or an Unauthenticated error when restoring or saving to the Blacksmith cache.