RelayRunner docs: relay.yml inputs Page: https://relayrunner.dev/docs/reference/relay-inputs Markdown: https://relayrunner.dev/docs/reference/relay-inputs.md All pages: https://relayrunner.dev/docs/llms.txt Other pages (Markdown): - Route GitHub Actions jobs to any runner: https://relayrunner.dev/docs/get-started/overview.md - How it works with GitHub Actions: https://relayrunner.dev/docs/get-started/github-actions.md - Quickstart: https://relayrunner.dev/docs/get-started/quickstart.md - Install the CLI: https://relayrunner.dev/docs/get-started/install.md - RelayRunner for Mac: https://relayrunner.dev/docs/get-started/mac-app.md - Set up with an agent: https://relayrunner.dev/docs/get-started/agents.md - Move your workflows over: https://relayrunner.dev/docs/get-started/move-over.md - Principles: https://relayrunner.dev/docs/concepts/principles.md - Routing: https://relayrunner.dev/docs/concepts/routing.md - Runner order: https://relayrunner.dev/docs/concepts/runner-order.md - Optimized checks: https://relayrunner.dev/docs/concepts/optimized-checks.md - Spend controls: https://relayrunner.dev/docs/guides/spend-controls.md - Providers: https://relayrunner.dev/docs/runners/providers.md - Your machines: https://relayrunner.dev/docs/runners/self-hosted.md - GitHub-hosted: https://relayrunner.dev/docs/runners/github.md - Hosted providers: https://relayrunner.dev/docs/runners/hosted.md - Runner labels: https://relayrunner.dev/docs/reference/labels.md - Add a provider: https://relayrunner.dev/docs/contribute/add-provider.md - Run CI on your laptop while you work: https://relayrunner.dev/docs/guides/laptop-ci.md - macOS and iOS builds on your Mac: https://relayrunner.dev/docs/guides/mac-builds.md - Share your team's machines: https://relayrunner.dev/docs/guides/team-machines.md - Keep up with coding agents: https://relayrunner.dev/docs/guides/agent-surge.md - Activity and history: https://relayrunner.dev/docs/dashboard/activity.md - Signals: https://relayrunner.dev/docs/dashboard/signals.md - Performance: https://relayrunner.dev/docs/dashboard/performance.md - Usage and savings: https://relayrunner.dev/docs/dashboard/usage.md - Telemetry: https://relayrunner.dev/docs/dashboard/telemetry.md - AI: https://relayrunner.dev/docs/dashboard/ai.md - CLI: https://relayrunner.dev/docs/reference/cli.md - relay.yml inputs: https://relayrunner.dev/docs/reference/relay-inputs.md (this page) - Repo config: https://relayrunner.dev/docs/reference/repo-config.md - MCP server: https://relayrunner.dev/docs/reference/mcp.md - RelayRunner API: https://relayrunner.dev/docs/reference/api.md - Workspaces and members: https://relayrunner.dev/docs/dashboard/workspaces.md - GitHub App: https://relayrunner.dev/docs/reference/github-app.md - Security: https://relayrunner.dev/docs/reference/security.md - Data and privacy: https://relayrunner.dev/docs/reference/privacy.md - Remove RelayRunner: https://relayrunner.dev/docs/dashboard/remove.md - Troubleshooting: https://relayrunner.dev/docs/reference/troubleshooting.md - Errors: https://relayrunner.dev/docs/reference/errors.md - FAQ: https://relayrunner.dev/docs/reference/faq.md - Feedback: https://relayrunner.dev/docs/contribute/feedback.md - Changelog: https://relayrunner.dev/docs/changelog.md - Agents can change your routing: https://relayrunner.dev/docs/changelog/agent-changes.md - Pick runner sizes on the dashboard: https://relayrunner.dev/docs/changelog/auto-runner-sizes.md - CLI changelog: https://relayrunner.dev/docs/changelog/cli.md - Send job logs to your tools or your own bucket: https://relayrunner.dev/docs/changelog/job-log-export.md - Mac app changelog: https://relayrunner.dev/docs/changelog/mac.md - RelayRunner for Mac: https://relayrunner.dev/docs/changelog/mac-app.md - CI traces in your observability tool: https://relayrunner.dev/docs/changelog/opentelemetry-traces.md - Platform changelog: https://relayrunner.dev/docs/changelog/platform.md - Retries, queueing and provider usage: https://relayrunner.dev/docs/changelog/retries-queueing-and-provider-usage.md - Route a repo from the dashboard: https://relayrunner.dev/docs/changelog/route-a-repo.md - Clearer run times and job sizes for members: https://relayrunner.dev/docs/changelog/run-times.md - Usual times, job history and the Mac queue: https://relayrunner.dev/docs/changelog/usual-times-and-mac-queue.md --- # relay.yml inputs > Every input and output of the relay, a reusable GitHub Actions workflow. The relay is a reusable workflow in [relayrunner/actions](https://github.com/relayrunner/actions). Add one in front of each job you want routed. ```yaml 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 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](#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 With `auto`, you change a job's size on the dashboard instead of in the workflow file: ```yaml 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 | Output | What it is | | -------- | --------------------------------------------- | | `runner` | The label to put in the next job's `runs-on`. | ## Requirements - The [RelayRunner GitHub App](https://github.com/apps/relayrunner) 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 `@v1` gets fixes and new features without breaking changes. See [releases](https://github.com/relayrunner/actions/releases). ## 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- / RelayRunner`** in 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 the `relayrunner` label, or it may take relays instead.