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:
- As itself as described above
- 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.