Skip to content

Commit 6905051

Browse files
authored
Merge pull request #6172 from readthedocs/davidfischer/connected-account-perms
Document connected account permissions
2 parents 3f3488f + 4c8a35f commit 6905051

File tree

1 file changed

+67
-1
lines changed

1 file changed

+67
-1
lines changed

docs/connected-accounts.rst

Lines changed: 67 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
Connecting Your Account
2-
-----------------------
2+
=======================
33

44
If you are going to import repositories from GitHub, Bitbucket, or GitLab,
55
you should connect your Read the Docs account to your repository host first.
@@ -18,3 +18,69 @@ and select `Connected Services <https://readthedocs.org/accounts/social/connecti
1818
From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
1919
account. This process will ask you to authorize a connection to Read the Docs,
2020
that allows us to read information about and clone your repositories.
21+
22+
23+
Permissions for connected accounts
24+
----------------------------------
25+
26+
Read the Docs does not generally ask for write permission to your repositories' code
27+
(with one exception detailed below)
28+
and since we only connect to public repositories we don't need special permissions to read them.
29+
However, we do need permissions for authorizing your account
30+
so that you can login to Read the Docs with your connected account credentials
31+
and to setup :doc:`webhooks`
32+
which allow us to build your documentation on every change to your repository.
33+
34+
35+
GitHub
36+
~~~~~~
37+
38+
Read the Docs requests the following permissions (more precisely, `OAuth scopes`_)
39+
when connecting your Read the Docs account to GitHub.
40+
41+
.. _OAuth scopes: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/
42+
43+
Read access to your email address (``user:email``)
44+
We ask for this so you can create a Read the Docs account and login with your GitHub credentials.
45+
46+
Administering webhooks (``admin:repo_hook``)
47+
We ask for this so we can create webhooks on your repositories when you import them into Read the Docs.
48+
This allows us to build the docs when you push new commits.
49+
50+
Read access to your organizations (``read:org``)
51+
We ask for this so we know which organizations you have access to.
52+
This allows you to filter repositories by organization when importing repositories.
53+
54+
Repository status (``repo:status``)
55+
Repository statuses allow Read the Docs to report the status
56+
(eg. passed, failed, pending) of pull requests to GitHub.
57+
This is used for a feature currently in beta testing
58+
that builds documentation on each pull request similar to a continuous integration service.
59+
60+
.. note::
61+
62+
:doc:`Read the Docs for Business </commercial/index>`
63+
asks for one additional permission (``repo``) to allow access to private repositories
64+
and to allow us to setup SSH keys to clone your private repositories.
65+
Unfortunately, this is the permission for read/write control of the repository
66+
but there isn't a more granular permission
67+
that only allows setting up SSH keys for read access.
68+
69+
70+
Bitbucket
71+
~~~~~~~~~
72+
73+
For similar reasons to those above for GitHub, we request permissions for:
74+
75+
* Reading your account information including your email address
76+
* Read access to your team memberships
77+
* Read access to your repositories
78+
* Read and write access to webhooks
79+
80+
GitLab
81+
~~~~~~
82+
83+
Like the others, we request permissions for:
84+
85+
* Reading your account information (``read_user``)
86+
* API access (``api``) which is needed to create webhooks in GitLab

0 commit comments

Comments
 (0)