How to Migrate from GitHub Actions to Blacksmith

Migrating your CI/CD workflows from GitHub-hosted runners to Blacksmith ↗ is highly straightforward. Because Blacksmith acts as a drop-in replacement, you do not need to rewrite your pipelines, switch platforms, or change your core workflow syntax.

This guide walks you through the core benefits, prerequisites, and the two simple methods to complete your migration in under five minutes.

The Problem with Standard GitHub-Hosted Runners#

As software projects grow, CI/CD pipeline execution times frequently become a major bottleneck. Standard GitHub-hosted runners (ubuntu-latest) often face resource constraints regarding vCPU performance and I/O throughput:

Slower Builds: Docker image layer caching relies on network transfers rather than fast local NVMe storage.
Higher Expenses: Compute minutes for high-spec runners on GitHub can accumulate significant costs.
Resource Bottlenecks: Large test suites stall due to limited vCPU availability.

flowchart LR
    A[Commit Code] --> B[GitHub Workflow Triggered]
    B --> C{Runner Selection}
    C -->|Standard| D[GitHub Standard Runner\n- Average Speed\n- Network Cache]
    C -->|Blacksmith Drop-in| E[Blacksmith High-Perf Runner\n- Higher vCPU\n- Local NVMe Cache]
    D --> F[Build Time: 10-15 mins]
    E --> G[Build Time: 3-5 mins]

Prerequisites#

Before you start, ensure you meet the infrastructure requirements:

Organization Accounts Only: Blacksmith is built strictly for GitHub Organizations and does not support personal user repositories.
Network Access (IP Allowlist): If your organization enforces strict IP allowlists, you must first allowlist Blacksmith’s control plane IPs.

Method 1: The Automated Migration Wizard (Recommended)#

The easiest way to migrate is using the built-in wizard, which automatically creates pull requests for your repositories.

Sign Up: Navigate to the Blacksmith Dashboard and create an account.
Link GitHub: Grant Blacksmith the required permissions to access your GitHub organization.
Run the Wizard: Select the repository you want to migrate inside the dashboard.
Review the PR: The wizard automatically scans your .github/workflows/ directory and opens a Pull Request.
Merge: Review the changes, merge the Pull Request, and your next commit will run on Blacksmith.

Method 2: Manual Migration (Single-Line Update)#

If you prefer to update your workflows manually, you only need to change the runs-on property in your YAML configuration files.

Open your workflow file (e.g., .github/workflows/ci.yml) and swap ubuntu-latest with a designated Blacksmith runner:

.github/workflows/ci.yml

# BEFORE: Using standard GitHub-hosted runners
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

# AFTER: Using Blacksmith high-performance runners
jobs:
  test:
    runs-on: blacksmith-4vcpu-ubuntu-2404 // [!code ++]
    steps:
      - uses: actions/checkout@v4

yaml

[!TIP] No step-level modifications are needed. All existing GitHub Action steps remain completely untouched.

Available Runner Sizes#

Pick the runner profile that best fits your job constraints:

blacksmith-4vcpu-ubuntu-2404: Standard workloads.
blacksmith-8vcpu-ubuntu-2404: Medium workloads or Docker builds.
blacksmith-16vcpu-ubuntu-2404: Heavy test suites and compilations.

[!NOTE] Blacksmith also provides identical flavor options for Ubuntu 22.04 and ARM64 architectures if your codebase requires them.

What to Expect After Migrating#

Native Caching: Your existing actions/cache blocks will continue to work out of the box without code modifications, leveraging Blacksmith’s local NVMe-backed filesystem for drastically quicker download speeds.
Docker Optimization: Heavy layers and docker/setup-buildx-action steps automatically benefit from optimized caching, often reducing image build runtimes significantly.
Analytics: Once jobs finish executing, you can log back into the Blacksmith Dashboard to view comparative run histories, speed improvements, and active cost saving data.

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant GH as GitHub Actions
    participant BS as Blacksmith Runner
    participant NVMe as Local NVMe Cache

    Dev->>GH: Push Commit / PR
    GH->>BS: Trigger Job (runs-on: blacksmith)
    BS->>NVMe: Fetch Cache from Local NVMe
    NVMe-->>BS: Return Cached Layers
    BS->>BS: Execute Build & Test
    BS-->>GH: Report Job Status