RelayRunner docs: relay.yml inputs
Page: https://relayrunner.app/docs/reference/relay-inputs
Markdown: https://relayrunner.app/docs/reference/relay-inputs.md
All pages: https://relayrunner.app/docs/llms.txt

Other pages (Markdown):
- Changelog: https://relayrunner.app/docs/changelog.md
- CLI changelog: https://relayrunner.app/docs/changelog/cli.md
- CI traces in your observability tool: https://relayrunner.app/docs/changelog/opentelemetry-traces.md
- Platform changelog: https://relayrunner.app/docs/changelog/platform.md
- Retries, queueing and provider usage: https://relayrunner.app/docs/changelog/retries-queueing-and-provider-usage.md
- Optimized checks: https://relayrunner.app/docs/concepts/optimized-checks.md
- Principles: https://relayrunner.app/docs/concepts/principles.md
- Routing: https://relayrunner.app/docs/concepts/routing.md
- Runner order: https://relayrunner.app/docs/concepts/runner-order.md
- Add a provider: https://relayrunner.app/docs/contribute/add-provider.md
- Feedback: https://relayrunner.app/docs/contribute/feedback.md
- Activity and history: https://relayrunner.app/docs/dashboard/activity.md
- Performance: https://relayrunner.app/docs/dashboard/performance.md
- Remove RelayRunner: https://relayrunner.app/docs/dashboard/remove.md
- Signals: https://relayrunner.app/docs/dashboard/signals.md
- Telemetry: https://relayrunner.app/docs/dashboard/telemetry.md
- Usage and savings: https://relayrunner.app/docs/dashboard/usage.md
- Workspaces and members: https://relayrunner.app/docs/dashboard/workspaces.md
- Set up with an agent: https://relayrunner.app/docs/get-started/agents.md
- How it works with GitHub Actions: https://relayrunner.app/docs/get-started/github-actions.md
- Install the CLI: https://relayrunner.app/docs/get-started/install.md
- Move your workflows over: https://relayrunner.app/docs/get-started/move-over.md
- Route GitHub Actions jobs to any runner: https://relayrunner.app/docs/get-started/overview.md
- Quickstart: https://relayrunner.app/docs/get-started/quickstart.md
- Keep up with coding agents: https://relayrunner.app/docs/guides/agent-surge.md
- Run CI on your laptop while you work: https://relayrunner.app/docs/guides/laptop-ci.md
- macOS and iOS builds on your Mac: https://relayrunner.app/docs/guides/mac-builds.md
- Spend controls: https://relayrunner.app/docs/guides/spend-controls.md
- Share your team's machines: https://relayrunner.app/docs/guides/team-machines.md
- RelayRunner API: https://relayrunner.app/docs/reference/api.md
- CLI: https://relayrunner.app/docs/reference/cli.md
- Errors: https://relayrunner.app/docs/reference/errors.md
- FAQ: https://relayrunner.app/docs/reference/faq.md
- GitHub App: https://relayrunner.app/docs/reference/github-app.md
- Runner labels: https://relayrunner.app/docs/reference/labels.md
- MCP server: https://relayrunner.app/docs/reference/mcp.md
- Data and privacy: https://relayrunner.app/docs/reference/privacy.md
- relay.yml inputs: https://relayrunner.app/docs/reference/relay-inputs.md (this page)
- Repo config: https://relayrunner.app/docs/reference/repo-config.md
- Security: https://relayrunner.app/docs/reference/security.md
- Troubleshooting: https://relayrunner.app/docs/reference/troubleshooting.md
- GitHub-hosted: https://relayrunner.app/docs/runners/github.md
- Hosted providers: https://relayrunner.app/docs/runners/hosted.md
- Providers: https://relayrunner.app/docs/runners/providers.md
- Your machines: https://relayrunner.app/docs/runners/self-hosted.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.

| 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`.                                                                                                                                                           |
| `runs-on`    | none    | One RunsOn label, such as `runs-on=${{ github.run_id }}/runner=2cpu-linux-x64`.                                                                                                                              |

## 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-<job> / 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.