API permission name for self-hosted runners?

[skyzyx]

Apparently I have too many links to GitHub documentation. I’ve replaced https with httpx in the links below.

---

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” (httpx://docs.github.com/en/[email protected]/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 httpx://docs.github.com/en/[email protected]/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 (httpx://docs.github.com/en/[email protected]/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.

[skyzyx]

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

[icj217]

I too ran into this issue where it was unclear what the proper permissions were. I ended up creating the app by hand and adding the permissions I needed for it to function, then I used the GH API to see what permissions it had using this command:

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /apps/<slug>

I was specifically interested in the custom_property_values event, which ended up needing the organization_custom_properties and repository_custom_properties permissions. It looks like permission names can be plural and can also be prefixed with organization_ or repository_.

If only GitHub could provide a public list of these permissions.

[theELITEbes]