1

Install the Blacksmith GitHub app

Start by going to app.blacksmith.sh and follow the steps to grant 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

Use our Migration Wizard to update your GitHub Actions workflow files

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.

If you’ve chosen to ignore the Migration Wizard (don’t, really), continue reading this step. You can manually update your GitHub Actions workflows one by one like a caveman. These are located in .github/workflows, and the runs-on property specifies the runner tag.

To switch to a Blacksmith runner, just replace the current tag with the appropriate Blacksmith runner tag. Done!

jobs:
  build:
-    runs-on: ubuntu-latest
+    runs-on: blacksmith-2vcpu-ubuntu-2204
Workflow files may contain multiple jobs. Ensure you update all runs-on fields to utilize Blacksmith runners.
3

Cache dependencies and build outputs to run even faster (recommended)

Blacksmith’s useblacksmith/cache is a drop-in replacement for GitHub’s actions/cache, speeding up cache speeds from 100MB/s to over 400MB/s by co-locating cache artifacts with your Blacksmith runners. Plus, enjoy 25GB of free storage per repository each week, 2.5x what GitHub offers.

To learn more about how we achieve this, checkout our Dependencies cache page.

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

Cache Docker layers to make your Docker builds even faster (recommended)

Blacksmith lets your Docker builds in GitHub Actions reuse cached layers, rebuilding only what’s changed and speeding up your builds by up to 40x.

To learn more about how we achieve this, checkout our Docker builds cache page.

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

​
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 [email protected].