Routing
Change where jobs run without editing your workflows.
Add a relay to each job once. After that, you pick where jobs go from the dashboard: your machines, your self-hosted runners, a hosted provider or GitHub. A change applies from the next job.
How it works
Run one command, then manage routing in the dashboard.
-
Add relays with one command
npx relayrunner initputs a relay in front of each job. The relay lists where that job is allowed to run. -
Set your runner order
Each job goes to the first free runner in your order. Move a provider up or down, add a minutes limit, or take one out.
-
See where each job ran
The Activity page shows the runner each job got and why it skipped the runners above it.
jobs:
relay-test:
uses: relayrunner/actions/.github/workflows/relay.yml@v1
with:
machine: self-hosted
github: ubuntu-latest
blacksmith: blacksmith-4vcpu-ubuntu-2404
test:
needs: relay-test
runs-on: ${{ needs.relay-test.outputs.runner }}
The relay
Each job runs on the first free runner its relay allows.
The relay answers in about a second, needs no runner and uses no minutes. Leave a provider out of a job's relay and that job never runs there.
Read how routing works →Rules
Change routing rules in the dashboard.
-
Fall back when your machines are busy
When every machine is busy or offline, the job moves to the next step instead of waiting.
-
Stay under a minutes limit
Use GitHub while you're under a share of your included minutes, then switch to your own machines.
-
Try a new provider
Move a provider up for a day, compare job times on the Performance page, and move it back if it's slower.
Common questions
What if nothing in my order can take the job?
The relay fails right away with one line that says why each provider couldn't take it. Keep GitHub-hosted at the end of your order and a job always has somewhere to go.
Which providers can I route to?
Your own machines, the self-hosted runners your org already has, GitHub-hosted, and hosted providers like Blacksmith, Depot, Namespace, WarpBuild, Ubicloud and RunsOn. See all providers.
Do public repos run on my machines?
No. Jobs from public repos skip your machines, so code from a stranger's pull request never runs on your computer.
Who pays the hosted providers?
You do, directly. A routed job runs under your own account with each provider, so you keep your plans, credits and discounts.
Start routing your jobs.
Add relays once. After that, change the order in the dashboard.
-
1. In your repo, add relays to the jobs you want to route
npx relayrunner init -
2. Optionally, turn this computer into a runner
npx relayrunner connect
