relayrunner
Sign in Get started Open dashboard
← All integrations

RunsOn integration

Route jobs between RunsOn, your machines and GitHub.

RunsOn starts a runner for each job in your own AWS account. Jobs go to your machines first and to RunsOn when they're busy. You change the order from the dashboard, not your workflows.

Get started with GitHub

With routing

RunsOn on its own, or in your runner order

RunsOn on its own

  1. Each workflow names a RunsOn label, so every job runs on RunsOn.
  2. Your own machines sit idle while RunsOn bills you.
  3. Trying another host means editing every workflow again.
  4. Each host shows its own job times in its own dashboard.

In your runner order

  1. Jobs run on your machines first, and on RunsOn when your machines are busy.
  2. GitHub-hosted runners stay as the fallback after RunsOn.
  3. Move RunsOn up, down or out from the dashboard. No workflow edits.
  4. The Performance page compares RunsOn's job times with your machines and GitHub-hosted runners.

Setup

How to set up RunsOn

  1. Set up your RunsOn account

    Deploy RunsOn into your AWS account and install the GitHub App it creates.

  2. Add RunsOn to your runner order

    On the Router page, put RunsOn where you want it. A common order is your machines, then RunsOn, then GitHub-hosted.

  3. Add relays to your jobs

    Run npx relayrunner init in your repo. It adds a relay to each job you pick and keeps the label the job uses today as its fallback.

.github/workflows/ci.yml
jobs:
  relay-test:
    uses: relayrunner/actions/.github/workflows/relay.yml@v1
    with:
      machine: self-hosted
      runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
      github: ubuntu-latest
  test:
    needs: relay-test
    runs-on: ${{ needs.relay-test.outputs.runner }}

The relay

Name a RunsOn label in the relay.

The relay answers in about a second and uses no minutes. It returns the label of the first runner in your order that can take the job, and the job runs there.

Read how routing works →

Details

RunsOn at a glance

What it is
Runners started in your own AWS account.
Labels
runs-on=<run id>/runner=<type>
Example
runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
Relay input
runs-on
Links
RunsOn docs

Common questions

How is this different from using RunsOn directly?

Used directly, every job that names a RunsOn label runs on RunsOn. In a runner order, jobs go to your own machines first and to RunsOn only when they're busy, and you can move RunsOn up, down or out from the dashboard without editing workflows.

Do I have to change my workflows to use RunsOn?

Once. Run npx relayrunner init in your repo and it adds a relay to each job you pick. After that, you move RunsOn up or down in the dashboard.

Which jobs go to RunsOn?

Jobs whose relay names a RunsOn label, when nothing above RunsOn in your runner order is free.

Who bills me for RunsOn?

RunsOn does. Jobs run under your own RunsOn account, so your plan, credits and discounts still apply.

Do public repos run on RunsOn?

Yes. Your own machines skip public repos' jobs, but hosted providers like RunsOn run them.

Add RunsOn to your runner order.

Add relays once. After that, change the order in the dashboard.

  1. 1. In your repo, add relays to the jobs you want to route
    npx relayrunner init
  2. 2. Optionally, turn this computer into a runner
    npx relayrunner connect