1
1
Connecting Your Account
2
- -----------------------
2
+ =======================
3
3
4
4
If you are going to import repositories from GitHub, Bitbucket, or GitLab,
5
5
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
18
18
From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
19
19
account. This process will ask you to authorize a connection to Read the Docs,
20
20
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