​
1. Install the blacksmith.sh GitHub App

Start by adding Blacksmith to your GitHub organization. Simply navigate to the Blacksmith app and follow the prompts to install Blacksmith. This grants Blacksmith the necessary permissions to execute your GitHub Action jobs on Blacksmith’s infrastructure.

Please Note: Blacksmith is currently limited to GitHub organizations and not available for personal repositories at this time.

​
2. Ensure Blacksmith runners have the correct permissions

For Blacksmith to be able to run GitHub Actions in your repository, you must ensure that the runners have the correct permissions. To do this, navigate to your Organization settings and click into Actions -> Runner groups -> Default to make sure that the repository is selected.

For public repositories, you will additionally need to check the Allow public repositories box under Repository access.

​
3. Switching to Blacksmith Runners in Workflow Files

GitHub Action workflows are found in .github/workflows, where the runs-on property specifies the runner tag. To switch to a Blacksmith runner, simply replace the current runner tag with the appropriate Blacksmith runner tag. Blacksmith is a drop-in replacement for GitHub runners, so no other changes are required.

For a comprehensive list of available Blacksmith runners, refer to our runners configuration page.

To switch from the default ubuntu-latest runner to a Blacksmith runner with 2 vCPUs, modify your workflow as shown:

jobs:
  build:
-    runs-on: ubuntu-latest
+    runs-on: blacksmith-2vcpu-ubuntu-2204
    steps:

Blacksmith runners are available in 2, 4, 8, 16 and 32 vCPU configurations.

Important: Workflow files may contain multiple jobs. Ensure you update all runs-on fields to utilize Blacksmith runners.

Blacksmith’s caching solution useblacksmith/cache can significantly reduce job times by accelerating cache download and upload speeds.

While the default GitHub cache actions/cache@v3 operates at speeds up to 100MB/s, our useblacksmith/cache dramatically increases this to over 400MB/s. To learn more about how we achieve this, checkout our Blacksmith cache page.

useblacksmith/cache is a drop-in replacement for actions/cache and offers 25GB of free storage per repository each week, a substantial increase from GitHub’s 10GB.

Switching is straightforward - replace the GitHub cache action in your workflow file with Blacksmith cache:

    name: Cache Cargo dependencies
-    uses: actions/cache@v3
+    uses: useblacksmith/cache@v5
    with:
      path: |
        ~/.cargo/registry
        ~/.cargo/git
        target
      key: ${{ matrix.rust }}-${{ hashFiles('**/Cargo.lock') }}
      restore-keys: |
        ${{ runner.labels }}-rust-${{ matrix.rust }}-
Why Blacksmith?Blacksmith Cache