RelayRunner docs: Move your workflows over
Page: https://relayrunner.app/docs/get-started/move-over
Markdown: https://relayrunner.app/docs/get-started/move-over.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 (this page)
- 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
- 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

---

# 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

Inside a checkout of the repo:

```sh
npx relayrunner init
```

It 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 as `blacksmith-*` or `depot-*`. 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.

## What it writes

For a job like this:

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps: ...
```

`init` writes:

```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 }}
    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

- **Deploy jobs.** Jobs that use secrets or a deploy environment. Running one on a machine gives that machine those secrets, so it's your call. You can route one by hand with the same change.
- **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 already on a self-hosted runner.

## Public repos

`init` refuses public repositories, since their jobs [never run on your machines](/docs/concepts/principles#public-repositories-never-run-on-your-machines).

## Undo

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.