RelayRunner docs: How it works with GitHub Actions
Page: https://relayrunner.app/docs/get-started/github-actions
Markdown: https://relayrunner.app/docs/get-started/github-actions.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 (this page)
- 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
- 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

---

# How it works with GitHub Actions

> What changes in your GitHub Actions workflows, what stays the same, and which jobs you can route.

Every routed job still runs on GitHub Actions. The only thing that changes is which runner picks it up.

## What changes

Each job you route gets a relay job in front of it, and its `runs-on` reads the relay's answer. Here's a complete workflow with `test` routed and `lint` left as it was:

```yaml title=".github/workflows/ci.yml" {9-14,17-18}
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  # Picks a runner for the test job: your machines first, then ubuntu-latest.
  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:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm test

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint
```

`npx relayrunner init` makes this change for you. See [Move your workflows over](/docs/get-started/move-over).

## What stays the same

- Your workflow files, the events that start them, and your steps.
- Check names, so required checks and branch protection keep working.
- Logs, artifacts and re-runs, which all stay in GitHub.
- Secrets, which go from GitHub straight to the runner.

## Minutes

The relay job finishes in about a second without a runner, so it uses no minutes. Jobs on your own machines don't use GitHub minutes either. Jobs that go to GitHub-hosted runners use your included minutes as usual. See [Spend controls](/docs/guides/spend-controls).

## What you can't route yet

- **Matrix jobs.** One relay routes one job.
- **Reusable workflows.** They choose their own runner.
- **Windows jobs**, and GitHub Enterprise Server.
- **Public repos on your machines.** Public repos can still route between hosted providers.

## Next

- [Quickstart](/docs/get-started/quickstart): connect a machine and route your first job.
- [How routing works](/docs/concepts/routing): how the relay picks a runner.