> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Try the fastest way to run your GitHub Actions in under 5 minutes

<Steps>
  <Step title="Set up our GitHub integration">
    Start by going to [app.blacksmith.sh](https://app.blacksmith.sh) and follow the steps to grant Blacksmith the necessary permissions to execute your GitHub Action jobs on Blacksmith's infrastructure.

    <Note> Blacksmith is limited to GitHub organizations and not available for personal repositories.</Note>

    <Note>
      If your GitHub organization uses **IP allowlists** or network restrictions, you may need to allowlist
      Blacksmith's control plane IPs so we can communicate with GitHub.
      See [Network & IP Allowlisting](/blacksmith-administration/network-allowlisting) for details.
    </Note>
  </Step>

  <Step title="Use our Migration Wizard to update your GitHub Actions workflow files">
    <div
      style={{
    position: "relative",
    width: "100%",
    paddingTop: "64.67%",
    marginTop: "2rem",
    marginBottom: "4rem",
    margin: "2rem 0 4rem 0",
  }}
    >
      <video
        src="https://mintcdn.com/blacksmith/RMBIa5U5GnHQ2Ykn/images/migwiz.mp4?fit=max&auto=format&n=RMBIa5U5GnHQ2Ykn&q=85&s=93ce81c8766004918d14be6ddba5cb09"
        style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
      display: "block",
    }}
        autoPlay
        loop
        muted
        playsInline
        controls
        data-path="images/migwiz.mp4"
      />
    </div>

    <Accordion title="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](mailto:support@blacksmith.sh).
    </Accordion>

    If you've chosen to ignore the Migration Wizard (don't, really), continue reading this step. To switch to a Blacksmith runner, just manually replace the current tag with the appropriate [Blacksmith runner tag](/blacksmith-runners/overview#runner-tags).

    Common mappings:

    | GitHub-hosted tag | Blacksmith tag                  |
    | :---------------- | :------------------------------ |
    | `ubuntu-latest`   | `blacksmith-2vcpu-ubuntu-2404`  |
    | `windows-latest`  | `blacksmith-2vcpu-windows-2025` |
    | `macos-latest`    | `blacksmith-6vcpu-macos-latest` |

    ```yml Diff Example icon="code" lines theme={"system"}
    jobs:
      build:
        runs-on: ubuntu-latest # [!code --]
        runs-on: blacksmith-2vcpu-ubuntu-2404 # [!code ++]
    ```

    If you want a pinned macOS image instead of `macos-latest`, use `blacksmith-6vcpu-macos-15` or `blacksmith-6vcpu-macos-26`.

    <Note>Workflow files may contain multiple jobs. Ensure you update all `runs-on` fields to utilize Blacksmith runners.</Note>
  </Step>

  <Step title="Cache dependencies and build outputs to run even faster (recommended)">
    When you run jobs on Blacksmith, all official GitHub and popular third-party cache actions transparently interact
    with our 4x faster, colocated cache, instead of GitHub's backend. Plus, enjoy **25GB** of free storage per repository each week, 2.5x what GitHub offers.

    ```yml Diff Example icon="code" lines theme={"system"}
    # If it's running on Blacksmith, it will use our cache
    name: Cache Cargo dependencies
    uses: actions/cache@v5
    ```

    To learn more about how we achieve this, checkout our [dependencies cache page](/blacksmith-caching/dependencies-actions).
  </Step>

  <Step title="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.

    ```yml Diff Example icon="code" lines theme={"system"}
    name: Set up Docker Buildx
    uses: docker/setup-buildx-action@v4 # [!code --]
    uses: useblacksmith/setup-docker-builder@v1 # [!code ++]

    name: Build and Push Docker Image
    uses: docker/build-push-action@v7 # [!code --]
    uses: useblacksmith/build-push-action@v2 # [!code ++]
    with:
      push: true
      tags: user/app:latest
      cache-from: type=registry,ref=user/app:latest # [!code --]
      cache-to: type=inline # [!code --]
    ```

    To learn more about how we achieve this, checkout our [Docker builds cache page](/blacksmith-caching/docker-builds).
  </Step>

  <Step title="Debug your CI pipeline using our observability features">
    We fill the gap GitHub left: quickly seeing what's happening in your CI pipeline when something goes wrong.

    <Columns cols={2}>
      <Card title="Run History" icon="rectangle-history" href="/blacksmith-observability/history">
        Search, filter, and debug past CI runs
      </Card>

      <Card title="Logs" icon="magnifying-glass" href="/blacksmith-observability/logs">
        Search and filter logs across your entire CI/CD pipeline
      </Card>

      <Card title="SSH Access" icon="terminal" href="/blacksmith-observability/ssh-access">
        Debug running jobs and inspect VM state
      </Card>

      <Card title="Test Analytics" icon="vial" href="/blacksmith-observability/test-analytics">
        Quickly identify test failures and fix them
      </Card>

      <Card title="CI Analytics" icon="chart-line-up" href="/blacksmith-observability/dashboard">
        Monitor your GitHub Actions across your team
      </Card>
    </Columns>
  </Step>
</Steps>