relay.yml inputs
Every input and output of the relay, a reusable GitHub Actions workflow.
The relay is a reusable workflow in relayrunner/actions. Add one in front of each job you want routed.
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 }}Inputs
Section titled “Inputs”Give one input per provider the job may use. A provider you leave out is never used for this job, even if it’s in your runner order.
Any input can say auto instead of a label. The Router then picks that provider’s label for the job’s size, which you set on the dashboard’s Router page. See Auto sizes.
| Input | Default | What it is |
|---|---|---|
machine |
none | Comma-separated labels a self-hosted machine must have, all of them. self-hosted accepts any machine. Narrow it with macOS, Linux, ARM64 or X64, such as macOS, ARM64. Ignored for public repos. |
github |
none | One GitHub-hosted label, such as ubuntu-latest or macos-latest. |
blacksmith |
none | One Blacksmith label, such as blacksmith-4vcpu-ubuntu-2404. |
depot |
none | One Depot label, such as depot-ubuntu-24.04. |
namespace |
none | One Namespace label, such as namespace-profile-default. |
warpbuild |
none | One WarpBuild label, such as warp-ubuntu-latest-x64-2x. |
ubicloud |
none | One Ubicloud label, such as ubicloud-standard-2. |
boat |
none | One Boat label, such as boat or boat-large. |
starsling |
none | One StarSling label, such as starsling-ubuntu-24.04-2. Organizations’ repos only. |
monkci |
none | One Monk CI label, such as monkci-ubuntu-24.04-2. Organizations’ repos only. |
runloft |
none | One Runloft label, such as runloft-ubuntu-24.04. |
latchkey |
none | One Latchkey label, such as latchkey-small. Organizations’ repos only. |
berrybox |
none | One BerryBox label, such as berrybox-2vcpu-ubuntu-2404. Organizations’ private repos only. |
celesto |
none | One Celesto label, such as celesto-standard. |
instabox |
none | One InstaBox label, such as instabox-medium. |
lizard |
none | One Lizard label, such as lizard-medium-ubuntu-2404. Organizations’ repos only. |
runs-on |
none | One RunsOn label, such as runs-on=${{ github.run_id }}/runner=2cpu-linux-x64. |
Auto sizes
Section titled “Auto sizes”With auto, you change a job’s size on the dashboard instead of in the workflow file:
jobs: relay-test: uses: relayrunner/actions/.github/workflows/relay.yml@v1 with: machine: auto blacksmith: auto github: auto| Input | What the job gets |
|---|---|
blacksmith: auto |
Blacksmith’s runner for the job’s size |
blacksmith: blacksmith-4vcpu-ubuntu-2404 |
That label, as written |
machine: auto |
Any of your machines, at its own size |
| No inputs at all | Every provider in your runner order, at the job’s size |
- The size is the one you picked for the job on the Router page, or the workspace’s Default size under Settings there. It starts at 2 vCPU. To pick one, find the workflow under Workflows and click its auto jobs. For a repo that isn’t routed yet, pick sizes in Route a repo on the same page; they apply from the first run.
- A provider without that size uses its next size up. If it has nothing that big, the job skips it, and the Activity page says why. GitHub-hosted has standard runners up to 2 vCPU.
- Try first, next to the size, sends one job to a provider before the rest of your runner order.
- A workflow whose relays all name their labels shows as Pinned under Workflows. Its sizes stay in the file.
- Auto sizes are for Linux x64. For macOS, Windows or Arm, write the label.
Output
Section titled “Output”| Output | What it is |
|---|---|
runner |
The label to put in the next job’s runs-on. |
Requirements
Section titled “Requirements”- The RelayRunner GitHub App is installed on the repo’s owner and connected to a workspace.
- If your organization limits which actions and reusable workflows can run, allow
relayrunner/actions/*.
Versions
Section titled “Versions”@v1 gets fixes and new features without breaking changes. See releases.
Good to know
Section titled “Good to know”- One relay per job. Jobs that share one relay’s output won’t all run. Give each job its own relay.
- It shows as
relay-<job> / RelayRunnerin the workflow run, and finishes in about a second. - No minutes. The relay runs on
runs-on: relayrunner, which needs no runner. Don’t give any runner of your own therelayrunnerlabel, or it may take relays instead.