Visualstudio-docs: Why does MicrosoftDocs require GitHub "Resources" permissions?

[patrikhuber]

Hello,
This is not related to visualstudio-docs per-se but I didn't find an appropriate or better place for this, so hopefully someone can help and/or answer here. It is related to the VS docs after all (which I've been browsing).
The new docs commenting system is awesome, but why does it require the GitHub permission "Resources: Determine what resources both you and docs.microsoft.com can access"? I tried to find information about it on GitHub and information is scarce but it seems this allows reading what repos (public and private) and organisations a user has access to. This seems very excessive to me and a permission that I'd not like to give to Microsoft by default, just for commenting on their docs.
Am I misunderstanding something?

Thanks!

[gewarren]

@jdanyow are you the appropriate person to address this concern? If not can you tag the correct person? Thanks!

[jdanyow]

Sure, I can provide more info on this.

During the oauth flow, GitHub will display an authorization page that looks something like this:

docs.microsoft.com by MicrosoftDocs
would like access to:

Your Account
Verify your GitHub account

Resources
Determine what resources both you and docs.microsoft.com can access

Actions
Enable you to trigger actions on GitHub from within docs.microsoft.com

I believe the question here is what does "determine what resources both you and docs.microsoft.com can access" mean? First some info on our app...

GitHub has two types of apps: "OAuth Apps" and "GitHub Apps". docs.microsoft.com uses the second kind, a "GitHub App". These types of apps can only act on repos where they are installed. They also have a more granular permission scheme than OAuth Apps. Here's the page where you would configure the permissions: https://github.com/settings/apps/new. We've installed our app on the MicrosoftDocs and Azure GitHub organizations and configured the app with read/write permissions on issues only.

Ultimately the permissions the authorization will grant our app is the intersection of your personal permissions and our GitHub App's permissions. This means we'll only be able to read/write issues on repos in the MicrosoftDocs and Azure orgs via the docs.microsoft.com app.

Hope this helps! More reading here if you'd like:

• https://developer.github.com/apps/building-github-apps/authentication-options-for-github-apps/
• https://developer.github.com/apps/differences-between-apps/#what-can-github-apps-and-oauth-apps-access

[jdanyow]

cc @tysonn @ShevaDas @DuncanmaMSFT @adkinn ^^^

[patrikhuber]

@jdanyow Okay, cool! Thank you very much for this explanation.
If I understand correctly, the important part is:

Determine what resources both you and docs.microsoft.com can access

Ultimately the permissions the authorization will grant our app is the intersection of your personal permissions and our GitHub App's permissions

So this is an "and" in the literal sense. That sounds great and nothing to worry about in terms of giving MS access to anything.
It's a bit of a shame that GitHub doesn't make this more clear. Now that I know, I understand, but I am pretty sure that few people will really understand when they're clicking to give their permission.

Thank you!