Document connected account permissions

[davidfischer]

This is a documentation only pull request that just documents why we ask for the permissions from GitHub, Bitbucket, and GitLab. We've had a few questions about this in the past.

There is a meta question of whether this is the right place for this information. Another question is whether we should link to this from the login and signup screens so users are prepared for permission prompts.

[saadmk11]

Should we talk about the GitLab Event we are accessing (e.g: merge_requests_events) ?

readthedocs.org/readthedocs/oauth/services/gitlab.py

Lines 261 to 267 in e50345c

	# Optional
	'issues_events': False,
	'merge_requests_events': True,
	'note_events': False,
	'job_events': False,
	'pipeline_events': False,
	'wiki_events': False,

[stsewd]

@saadmk11 webhooks are part of the API. That is only the list of events we subscribe when creating the webhook (that list of events are in this same page if I remember correctly).

[stsewd]

There is a meta question of whether this is the right place for this information.

I think it is 👍

we should link to this from the login and signup screens so users are prepared for permission prompts.

I think this is a good idea. We should put this on https://readthedocs.org/accounts/social/connections/ too.

[davidfischer]

If we're good with this change, let's go forward with it. Once this has "been released" an is available in the stable version, we'll add those links to it.

[agjohnson]

It's good to have this explicitly stated, there have been questions here in the past. Mostly from commercial accounts wondering why we require admin repo permissions. Hopefully the move to a GitHub App, instead of the OAuth app, will give us more permission granularity and we can avoid asking for admin access.

[agjohnson]

Unfortunately, the commercial side does ask for admin (and therefore write) permissions, as this is the lowest granularity that GitHub has/had in order to add private ssh keys. Moving to a GitHub App instead does probably give us finer permission control, if i remember correctly.