RelayRunner docs: GitHub App Page: https://relayrunner.app/docs/reference/github-app Markdown: https://relayrunner.app/docs/reference/github-app.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 (this page) - 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 --- # GitHub App > What the RelayRunner GitHub App can do, and why it asks for each permission. RelayRunner reaches GitHub through one GitHub App, [RelayRunner](https://github.com/apps/relayrunner). It signs you in, receives workflow events, and registers the one-job runners that answer relays and run jobs on your machines. Install it on each organization or personal account you want to route. ## Repository permissions | Permission | Access | Why | | -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Administration | Read & write | Registers one-job runners on the job's own repo, so only that repo's jobs can reach them. Lists and labels repo runners you add. | | Actions | Read & write | Workflow job and run events, and checking whether a relay job is still queued. Write re-runs jobs for automatic retries and is reserved for cancelling jobs. | | Checks | Read & write | The PR title check, a check run that explains a relay that can't be answered, and reading why a job's runner failed. | | Contents | Read & write, `relayrunner.yml` only | Reads [repo config](/docs/reference/repo-config). Write is reserved for saving it from the dashboard. It can't touch any other file. | | Pull requests | Read | Pull request events for the PR title check. | | Metadata | Read | Required by GitHub for every App. | ## Organization permissions | Permission | Access | Why | | ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Self-hosted runners | Read & write | Registers one-job runners in the org when a repo runner isn't allowed, and lists and labels [existing runners](/docs/runners/self-hosted#runners-your-org-already-has) you add. | | Administration | Read | Reads your plan, Actions usage and budget for the [minutes limit](/docs/concepts/runner-order#the-minutes-limit). It can't change any setting. | ## Enterprise permissions | Permission | Access | Why | | ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Enterprise billing | Read | Your enterprise's shared Actions minutes, for the minutes limit. Only used if an enterprise owner [installs it on the enterprise](#enterprises). | ## Account permissions | Permission | Access | Why | | --------------- | ------ | ---------------------------------------------------------- | | Email addresses | Read | Your email at sign-in. | | Plan | Read | A personal account's Actions usage, for the minutes limit. | ## Enterprises An org in a GitHub enterprise shares the enterprise's Actions minutes, and GitHub only reports those to the enterprise. To use a minutes limit there, an enterprise owner installs the App on the enterprise too: open [the install page](https://github.com/apps/relayrunner/installations/new) and pick the enterprise. Settings > GitHub links there when it's needed. That install only reads the enterprise's billing. It sees no repos, and your org installs keep doing the routing. Each org in the enterprise is then judged against the shared minutes. ## What it never gets The App can't read your code, beyond `relayrunner.yml`. It doesn't receive job logs or repository secrets. Jobs that run on your machines use GitHub's own runner, which talks to GitHub directly. ## Runner groups If your org's runner group settings block RelayRunner's runners, it posts a failed `RelayRunner` check on the commit that says what to change. ## RelayRunner Checks Lint uses a second, optional App, **RelayRunner Checks**, with Contents read, Checks write and Pull requests read. It lints each commit in a sandbox with no internet access, then discards it. Install it only if you want lint. ## RelayRunner Spend An optional App, [RelayRunner Spend](https://github.com/apps/relayrunner-spend), reads billing on its own. Its only permission is Organization administration (read). You don't need it unless the dashboard asks for it. ## When permissions change When the App asks for a new permission, GitHub asks each account to accept it under **Settings → GitHub Apps**. Features that need it start working once it's accepted.