Move your workflows over
What relayrunner init changes in your GitHub Actions workflows, and which jobs it leaves alone.
Routing a job through RelayRunner is one change: a relay job in front of it, and a runs-on that points at the relay’s answer. relayrunner init makes that change for you.
Run init
Section titled “Run init”Inside a checkout of the repo:
npx relayrunner initIt sorts every job into three groups and lets you pick from the first:
- Ready. The job uses a plain GitHub-hosted label (
ubuntu-*,macos-*) or a hosted provider’s label, such asblacksmith-*ordepot-*. Warnings flag what to check first, such as a job that needs Docker or installs Linux packages when your machine runs jobs on itself and not in a VM. - Already routed. The job already runs where a relay sends it.
- Skipped, with the reason. See below.
To see the list without changing anything, run relayrunner init --plan. To route jobs without prompts, run relayrunner init --apply test,lint, or --apply all for every ready job. Add --auto to set Linux x64 jobs’ sizes on the Router page instead of in the file.
Route repos from the dashboard
Section titled “Route repos from the dashboard”On the dashboard’s Router page, Route a repo takes you through one repo at a time:
- Pick a repo. Repos your org’s Default runner group leaves out are marked, with the fix.
- Pick its jobs from recent runs, and a size for each if you want one other than the default.
- Copy a prompt for your coding agent, which runs
initand opens a PR, or copy theinitcommand.
After you copy, the sheet waits for the repo’s first routed run and says when it’s routed. Next repo moves on, and from the second repo one prompt can cover the rest.
What it writes
Section titled “What it writes”For a job like this:
jobs: test: runs-on: ubuntu-latest steps: ...init writes:
jobs: relay-test: uses: relayrunner/actions/.github/workflows/relay.yml@v1 with: machine: self-hosted github: ubuntu-latest
test: needs: relay-test runs-on: ${{ needs.relay-test.outputs.runner }} steps: ...The old label moves to the relay’s github input (or the provider’s own input, such as depot, for a hosted provider’s label), so the job still runs there when no machine is free. A macos-* job gets machine: macOS, so it only goes to Macs. init keeps your comments and formatting, and never commits.
Push the change. The check keeps its name in GitHub, so required checks and branch protection keep working.
Jobs it skips
Section titled “Jobs it skips”- Deploy jobs. Jobs that use secrets, a deploy environment, or an OIDC token to sign in to a cloud or publish a package. Running one on a machine gives that machine those secrets, so it’s your call. To route one anyway, add
--allow-deploy <job>. A job that only requests an OIDC token, such as for a remote cache, isn’t skipped. - Jobs pinned to a label list or runner group, such as
runs-on: [self-hosted, m1, macmini]. The relay falls back to one label, so to route one by hand, pick what kind of machine may take it (machine: macOS, ARM64) and a hosted label for when none is free. - Matrix jobs. One relay answers one job, so it can’t serve every leg of a matrix.
- Reusable workflows. They choose their own runner.
- Windows jobs, and jobs on a single
self-hostedlabel.
Public repos
Section titled “Public repos”init refuses public repositories, since their jobs never run on your machines.
Delete the relay job and put the old label back in runs-on. Or leave the change in place: with no machine online and GitHub in your runner order, jobs run on their old label anyway.