Quickstart

​

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.

For more details

1. On GitHub.com, navigate to the main page of the organization.

2. Under your organization name, click Settings. If you cannot see the Settings tab, select the dropdown menu, then click Settings.

3. In the left sidebar, click Actions, then click Runner groups.

4. In the Runner groups section, click the Default group.

5. Under Workflow access, ensure that the repository that contains your workflow is selected.

5. (public repositories only): Under Repository access check the Allow public repositories box for all the repositories whose GitHub Actions you want to run on Blacksmith.

6. Click the Save button to save your changes.

​

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.

​

4. Use Blacksmith Cache to Speed Up Jobs (Recommended)

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 useblacksmith/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 }}-