GitHub API permission name for self-hosted GitHub Actions runners?

Question

At the end of the day, I'm trying to implement the solution linked from here: Reuse Github Actions self hosted runner on multiple repositories. But the tutorials walk you though setting up a GitHub app in the UI, and I'm trying to do it via the API.

---

Context:

1. Creating a new "GitHub App" (not "OAuth App") in GitHub Enterprise v3.0 (soon migrating to v3.1).

2. Trying to do it entirely over the API and explicitly NOT the UI, by creating an "app manifest" (https://docs.github.com/en/enterprise-server@3.0/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest).

3. Everything I've read about permissions on docs.github.com ends up pointing over to https://docs.github.com/en/enterprise-server@3.0/rest/reference/permissions-required-for-github-apps, which does not include the specific values that can be used with the API.

4. On a GHE instance, there is a large list of permissions available at a URL with this pattern:

   https://{HOSTNAME}/organizations/{ORG}/settings/apps/{APP}/permissions
   

5. The specific permission I'm trying set says:

   Self-hosted runners
   View and manage Actions self-hosted runners available to an organization.
   Access: Read & write

6. In the documentation (https://docs.github.com/en/enterprise-server@3.0/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest#github-app-manifest-parameters) there is a parameter called default_permissions.

   What is the identifier (key) to use for this permission, where the value is write?

   I've tried:

   • the documented Self-hosted runners
   • the guess self-hosted runners
   • the guess self-hosted_runners
   • the guess self_hosted_runners
   • the guess selfhosted_runners
   • the guess runners

   …but ultimately, the actual values which can be used here are (as far as I can tell after several hours of digging and guessing) undocumented.

   actions:read and checks:read appear to work. Those are also undocumented, but I was able to figure it out by looking at the URLs, making an educated guess, and testing.

7. All of the tutorials I can find on the internet, including those on docs.github.com, all walk you through creating a new GitHub app via the UI. I am very explicitly trying to do this over the API.

Any tips? Have I missed something? Is this not available in GHE yet?

---

Here is my app manifest, redacted.

{
  "public": true,
  "name": "My app",
  "description": "My app's description.",
  "url": "https://github.example.com/my-org/my-repo",
  "redirect_url": "http://localhost:9876/register/redirect",
  "default_events": [],
  "default_permissions": {
    "actions": "read",
    "checks": "read",
    "runners": "write"
  },
  "hook_attributes": {
    "url": "",
    "active": false
  }
}

WITH the "runners": "write" line, the error message I receive says:

Invalid GitHub App configuration
The configuration does not appear to be a valid GitHub App manifest.
× Error Default permission records resource is not included in the list

WITHOUT the "runners": "write" line, the submission is successful.

Answer 1

The GitHub team finally updated the documentation. The permission I was looking for was organization_self_hosted_runners.