​
1. Install the Blacksmith GitHub app

Start by going to the app.blacksmith.sh and follow the prompts to install Blacksmith’s GitHub app. This grants Blacksmith the necessary permissions to execute your GitHub Action jobs on Blacksmith’s infrastructure.

Blacksmith is limited to GitHub organizations and not available for personal repositories.

​
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 your 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.

The easiest way to get started with Blacksmith is through our migration wizard, which creates a PR with all required changes to use Blacksmith runners in three clicks.

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

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

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 co-locating your cache artifacts with your Blacksmith runners.

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

​
5. Make Docker builds incremental on Blacksmith runners (Optional)

Blacksmith supports incremental Docker builds with a one-line code change. This feature allows Docker builds in your GitHub Action workflows to reuse cached layers from previous runs, and only rebuild the layers that have changed.

To enable incremental Docker builds with Blacksmith runners, all you need to do is change the following line in your GitHub Actions workflow file:

   name: Build and Push Docker Image
-  uses: docker/build-push-action@v3
+  uses: useblacksmith/build-push-action@v1

Read more about incremental Docker builds here.

​
Troubleshooting

Don’t see your organization in the Blacksmith dashboard? This could be because of a few reasons:

  1. The GitHub organization has SSO enabled, but the current session is not authenticated. Make sure you authenticate with the SSO provider within GitHub and then refresh the Blacksmith dashboard.

  2. The GitHub organization does not have the Blacksmith app installed. Verify that the Blacksmith app is correctly installed in the organization.

  3. The GitHub user is not a member of the organization. Double-check that the user is a member of the organization.

If you are still having issues, reach out to us at support@blacksmith.sh.