From 17314394b076243913e55ac6be73767d9487f2ea Mon Sep 17 00:00:00 2001
From: David Fischer <david@readthedocs.org>
Date: Wed, 11 Sep 2019 19:38:37 -0700
Subject: [PATCH 1/2] Document connected account permissions

---
 docs/connected-accounts.rst | 63 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst
index 3db7ed6ca51..bacca099b32 100644
--- a/docs/connected-accounts.rst
+++ b/docs/connected-accounts.rst
@@ -1,5 +1,5 @@
 Connecting Your Account
------------------------
+=======================
 
 If you are going to import repositories from GitHub, Bitbucket, or GitLab,
 you should connect your Read the Docs account to your repository host first.
@@ -18,3 +18,64 @@ and select `Connected Services <https://readthedocs.org/accounts/social/connecti
 From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
 account. This process will ask you to authorize a connection to Read the Docs,
 that allows us to read information about and clone your repositories.
+
+
+Permissions for connected accounts
+----------------------------------
+
+Read the Docs does **not** ask for write permission to your repositories' code
+and since we only connect to public repositories we don't need special permissions to read them.
+However, we do need permissions for authorizing your account
+so that you can login to Read the Docs with your connected account credentials
+and to setup :doc:`webhooks`
+which allow us to build your documentation on every change to your repository.
+
+
+GitHub
+~~~~~~
+
+Read the Docs requests the following permissions (more precisely, `OAuth scopes`_)
+when connecting your Read the Docs account to GitHub.
+
+.. _OAuth scopes: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/
+
+Read access to your email address (``user:email``)
+    We ask for this so you can create a Read the Docs account and login with your GitHub credentials.
+
+Administering webhooks (``admin:repo_hook``)
+    We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
+    This allows us to build the docs when you push new commits.
+
+Read access to your organizations (``read:org``)
+    We ask for this so we know which organizations you have access to.
+    This allows you to filter repositories by organization when importing repositories.
+
+Repository status (``repo:status``)
+    Repository statuses allow Read the Docs to report the status
+    (eg. passed, failed, pending) of pull requests to GitHub.
+    This is used for a feature currently in beta testing
+    that builds documentation on each pull request similar to a continuous integration service.
+
+.. note::
+
+    :doc:`Read the Docs for Business </commercial/index>`
+    asks for one additional permission (``repo``) to allow access to private repositories
+    and to allow us to setup SSH keys to clone your private repositories.
+
+Bitbucket
+~~~~~~~~~
+
+For similar reasons to those above for GitHub, we request permissions for:
+
+* Reading your account information including your email address
+* Read access to your team memberships
+* Read access to your repositories
+* Read and write access to webhooks
+
+GitLab
+~~~~~~
+
+Like the others, we request permissions for:
+
+* Reading your account information (``read_user``)
+* API access (``api``) which is needed to create webhooks in GitLab

From 4c8a35fbd81fc8eb91951875727a7d3d3e5ed4b5 Mon Sep 17 00:00:00 2001
From: David Fischer <david@readthedocs.org>
Date: Thu, 26 Sep 2019 12:22:06 -0700
Subject: [PATCH 2/2] Note that RTD for Business does ask for write permissions

---
 docs/connected-accounts.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst
index bacca099b32..3a913b46e42 100644
--- a/docs/connected-accounts.rst
+++ b/docs/connected-accounts.rst
@@ -23,7 +23,8 @@ that allows us to read information about and clone your repositories.
 Permissions for connected accounts
 ----------------------------------
 
-Read the Docs does **not** ask for write permission to your repositories' code
+Read the Docs does not generally ask for write permission to your repositories' code
+(with one exception detailed below)
 and since we only connect to public repositories we don't need special permissions to read them.
 However, we do need permissions for authorizing your account
 so that you can login to Read the Docs with your connected account credentials
@@ -61,6 +62,10 @@ Repository status (``repo:status``)
     :doc:`Read the Docs for Business </commercial/index>`
     asks for one additional permission (``repo``) to allow access to private repositories
     and to allow us to setup SSH keys to clone your private repositories.
+    Unfortunately, this is the permission for read/write control of the repository
+    but there isn't a more granular permission
+    that only allows setting up SSH keys for read access.
+
 
 Bitbucket
 ~~~~~~~~~