How to host Github Runners for enterprise with Github App ?

[brandonfl]

🏷️ Discussion Type

Question

Body

Hello,

I am trying to figure out how to set up self-hosted runners for an enterprise with a GitHub App. The GitHub App permissions do not include "manage_runners:enterprise"; only the organization-level permission is available.

Does that mean I am forced to use a PAT to do this?

Thanks in advance for your help.
BrandonFL

[waqasulhaqqureshi]

Hey Brandon! To answer your question directly:

1. GitHub App Limitation: Yes, you hit the exact reason—enterprise-level GitHub Apps currently do not support a native manage_runners:enterprise permission scope (organization-level permissions exist, but enterprise ones do not).

2. Authentication Options: You aren't completely stuck, but you do have to pivot away from a GitHub App for enterprise scoping. You will need to use a Personal Access Token (PAT) (classic or fine-grained with enterprise runner scopes) or deploy via tools like Actions Runner Controller (ARC) using alternative credentials.

3. Organization-Level Workaround:** If enterprise-wide management isn't a strict requirement for your setup, dropping down to register the runners at the organization level will let you use a GitHub App smoothly since those permissions are fully supported there.

[brandonfl]

Thanks for the answer 😃

[PythonAlpha]

Yes — if you specifically need to manage enterprise-level self-hosted runners through the enterprise REST API, the limitation you’re seeing is real.

GitHub’s current documentation says the enterprise self-hosted-runner endpoints require the "manage_runners:enterprise" scope for OAuth apps or classic PATs, and those enterprise endpoints do not support GitHub App user or installation access tokens.

GitHub Apps can manage self-hosted runners at the organization level using the "Self-hosted runners" organization permission, including registering and managing organization runners.

So if your workflow requires the enterprise-level endpoints specifically, a GitHub App currently can't replace the "manage_runners:enterprise" credential for those operations. A classic PAT with the required enterprise scope would be one supported option.

If you only need runners within individual organizations, I'd use a GitHub App with the organization-level Self-hosted runners permission instead of giving the app broader credentials.

[arul637]

Directly using a GitHub App to host enterprise-level runners is not currently supported. Because GitHub App's permission system does not include enterprise-level manage_runners:enterprise permission.

🔑 Official Alternative Authentication Options

If you want to deploy enterprise-level self-hosted runners using Actions Runner Controller (ARC), you can only use a Personal Access Token (Classic) and must grant the manage_runners:enterprise permission.

💡 A Feasible Workaround

If you must use a GitHub App for authentication, you need to lower the registration level from enterprise to organization. At the organization level, GitHub App has complete Self-hosted runners (read and write) permission and can work normally.