I’m working on building a GitHub app and have run into two issues that I wanted to suggest could be clarified in the documentation. On the second item, I am not sure if I am misunderstanding the docs or not, so I’m happy to be corrected!
While building the OAuth flow for my GitHub App, I was mostly looking at the OAuth documentation under the OAuth App section of the docs. I spent quite a bit of time trying to debug and figure out why the scopes I was setting weren’t resulting in access tokens that had those permissions. It wasn’t until later that I came across the Identifying and authorizing users for GitHub Apps docs and the fine print:
Note: You don’t need to provide scopes in your authorization request. Unlike traditional OAuth, the authorization token is limited to the permissions associated with your GitHub App and those of the user.
My suggestion would be to include some call-outs in all of the OAuth flow docs, including those under OAuth Apps, that mention this and link to the specific documentation for Github Apps. A message like: “Building a Github App? Read about how scopes work.”
Accessing API as Github App versus an installation
Authentication options for GitHub Apps describes how to authenticate as a Github App, as well as how to get an installation access token with which to make API requests “as an installation”.
The page links out to:
However, this information seems to be a bit misleading. For example, I am NOT able to access the List pull requests endpoint using a Github App jwt token. It seems I can only access it using an installation access token?
If this is in fact the case, my suggestion would be to reorganize the docs a bit so that endpoints that require an installation access token are clearly indicated and organized as such.