Quickstart

Install the App, add a Mac, route a workflow.

1. Install the GitHub App

Go to Install and pick your organization. If you are not an owner, GitHub asks one to approve.

You get:

• Runner labels hive, hive-4cpu, hive-8cpu
• A hive
• A balance, starting with a trial credit

2. Add a machine

On an Apple Silicon Mac:

curl -fsSL https://get.hiveworkr.thecomputerplumbers.com/install.sh | sh

It installs under your home directory and asks for no password. See Download for what it installs.

A browser window opens. Sign in with GitHub and approve the machine. It runs a short benchmark and shows as online.

3. Route a workflow

Macs come and go. Check for a free machine before each run, and fall back when there is none:

jobs:
  route:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    outputs:
      runner: ${{ steps.hive.outputs.runner }}
    steps:
      - id: hive
        uses: thecomputerplumbers/hive-route@v1
        with:
          label: hive
          fallback: ubuntu-latest

  test:
    needs: route
    runs-on: ${{ needs.route.outputs.runner }}
    steps:
      - uses: actions/checkout@v7
      - uses: oven-sh/setup-bun@v2
      - run: bun test

Set label to a size and fallback to your current runner. Add needs: route and the runs-on line to each job you want routed. The step is one short file you can read: it asks whether a machine is free, waits up to fifteen seconds for one, and never fails your workflow. Routing and fallback has its inputs and what it checks.

Good to know

• hive is arm64 and ubuntu-latest is x64. If a job needs one architecture, fall back to ubuntu-24.04-arm.
• The check does not reserve a machine. If it leaves before the job starts, the job waits in GitHub's queue.
• For jobs that can wait, skip route and set runs-on: hive.