What is the meaning and purpose of the "Enabled For GitHub Apps" tag in some API endpoints?


#1

In the REST API v3 there seems to be certain endpoints tagged with “Enabled for GitHub Apps”. What does this tag mean exactly? What is its purpose?

Does this mean the endpoints which do not have this tag cannot be used by GitHub Apps? Is a GitHub App limited when compared with an OAuth App?

The distinction between GitHub Apps and OAuth Apps is not very clear in some points.

Any help would be appreciated!


Api request with access_token return 404
#2

The distinction between GitHub Apps and OAuth Apps is not very clear in some points.

Yes, it can be confusing—and because it’s still in progress, that only makes it more confusing.

I’ll try to clarify, but I’m not sure exactly what parts are not clear, so I’m going to take a big step backwards and start at the beginning (apologies if I’m covering territory that you’re familiar with).

The big difference between OAuth Apps and GitHub Apps is that an OAuth app acts as a GitHub user. It is not scoped to a particular organization or repository, it’s scoped to very broad categories of things, like “repositories”, or “deploy keys”. That means that if an OAuth app is authorized for deploy keys, it can manage deploy keys in any repository where the user is allowed to manage deploy keys, in any organization. If it has repo scope, then it has read and write access to public and private repositories in all organizations and user accounts that the user has commit access to.

This works well if the OAuth app is used as an identity provider (“log in via GitHub”), or if the OAuth app is about something that is not scoped to repositories—e.g. Octobox is notifications. It’s important that this is across all the activity that you’re involved in on GitHub, not just a particular organization or repository. So OAuth makes sense here.

A GitHub App is something that is installed on a given organization, or specific repositories within an organization. It provides much more granular permissions. So if you have a CI service that is a GitHub App, then you could go ahead and install it for a single repository. It would not have access to any other repositories. Since it doesn’t need to change code, the app would probably have read-only access to the code base, and it would only have write-access to the pull request status (green checkmark, link to broken builds, that sort of thing). Any actions taken would be taken as the app not as a particular user. So it wouldn’t say that @sashaafm kicked off the build, it would say that the app kicked off the build.

This is really great for things that are typically scoped to a repo or an org.

The bit where it gets sticky is this. GitHub Apps are production ready in the sense that they’re stable and they perform well, however we have hundreds of API endpoints, and we’re still in the process of enabling them for GitHub Apps to access.

It’s taking a while, because the permissions stuff is pretty hairy. It can be a bit slow going to make sure we don’t accidentally expose data that shouldn’t be exposed.

We’re working on a full audit of all the endpoints in order to be able to provide a proper timeline of when we’ll be able to get to each of the remaining endpoints. In the meanwhile, we use the “enabled for GitHub Apps” notation in the documentation to mark when something has been enabled.

There’s a complicating factor to all of this… there are two ways that GitHub Apps can act:

  1. As itself as described above
  2. On behalf of a user, but with the permissions scoped down to the intersection of what the user can see and do and what the app can see and do.

We call the first “server-to-server”, and the second “user-to-server”. So a user could authenticate inside of the app, and then the app has a token and can act on behalf of a user, to a limited extent.

The “enabled for GitHub Apps” notation in the docs is for the server-to-server requests, not the user-to-server requests.

I think the user-to-server stuff has been documented somewhere, but I can’t find it right now. I’ll try to dig that up.


General questions about integration
#3

Great explanation!

I think user-to-server stuff can be found here: identifying-users-for-github-apps/#user-to-server-requests


#4

Yes, that’s what I was thinking of. Thank you @andreash92


#5

This is a much clearer (for me) top-level explanation than the ones found at the following two pages:

I have a follow-on question. You’ve covered authenticating as a GitHub App to act as itself (server-to-server) and to act as a user (user-to-server). What, then, is the relationship to “authenticating as an installation”?

Some more specific questions:

  • After each installation of my GitHub App, is its access token (the JWT I sign with my private key, server-to-server) transparently augmented with access to (potentially) more repositories? Would that mean that for any single repository my GitHub App can access, there may be N installations through which that access is granted? Does this further imply that listening for the installation events on my Webhook URL is optional, because my GitHub App will instantly gain access to the new repositories without any change to how its access token is generated?

  • What does it mean to list installations that a user can access (acting as the user with a user-to-server access token)? I guess a user can create more than one installation of my GitHub App to incrementally give my app access to more repositories, but why bother dealing with them as separate installations? How would I use this information?


#6

What, then, is the relationship to “authenticating as an installation”?

For the most part, the app (authenticated with the jwt) only has access to a few things related to metadata about the app itself, like listing installations. In order to do anything with the permissions your app has requested, you have to authenticate as a specific installation.

After each installation of my GitHub App, is its access token (the JWT I sign with my private key, server-to-server) transparently augmented with access to (potentially) more repositories?

Not quite. The jwt token has access to fetch an installation token. Installation tokens are augmented with access as more repositories are added. Keep in mind that installation tokens only last an hour, and you have to have the private key to request a new token.

Would that mean that for any single repository my GitHub App can access, there may be N installations through which that access is granted?

I’m not sure I understand this question, so let me know if I’m off the mark: Apps are installed on accounts (user or organization), and given access to repositories, but each account only has one installation of an app. An account admin can add/remove repositories to that installation, and any active installation tokens will have access as it’s updated, but it’s still the same installation.

Does this further imply that listening for the installation events on my Webhook URL is optional, because my GitHub App will instantly gain access to the new repositories without any change to how its access token is generated?

Correct, you don’t need to listen to the installation event for access purposes, only for record keeping and triggering behavior when access is granted or revoked for an installation.

What does it mean to list installations that a user can access (acting as the user with a user-to-server access token)? I guess a user can create more than one installation of my GitHub App to incrementally give my app access to more repositories, but why bother dealing with them as separate installations? How would I use this information?

Since a user can be a member of multiple organizations (and each organization could have an installation of your app), there are times when your app may want to get a list of installations that a user can access. For example, [this app] allows admins to generate an link to share with anyone they want to invite to an organization. It uses this endpoint to get a list of the organizations that the user is a member of and have the app installed.

Let me know if that clears anything up, and feel free to ask followup questions.