From 682225c3f5b4cc1ef13d0b0b1963e9f2cffb43fb Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 30 Jun 2021 16:33:27 -0700 Subject: [PATCH 1/7] Add docs about setting up permissions for GH apps & orgs This is a common issue, so now we at least have a link to point users to. --- docs/connected-accounts.rst | 34 ++++++++++++++++++++++++++++++++-- docs/pull-requests.rst | 8 +++----- 2 files changed, 35 insertions(+), 7 deletions(-) diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index c25d6dbf76f..c91b4b6328a 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -13,8 +13,7 @@ Connecting your account allows for: If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials, you're all done. Your account is connected. -To connect your unconnected account, go to your *Settings* dashboard -and select `Connected Services `_. +To connect a social account, go to your :guilabel:`Username dropdown > Settings > Connected Services`. 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. @@ -66,6 +65,37 @@ Repository status (``repo:status``) but there isn't a more granular permission that only allows setting up SSH keys for read access. +.. _github-permission-troubleshooting: + +GitHub Permission Troubleshooting +````````````````````````````````` + +A common issue with importing a GitHub project to Read the Docs is OAuth permissions. +Many organizations require approval for each OAuth application that is used, +or you might have disabled it in the past for your personal account. +This can happen at the personal or organization level, +depending on where the project you are trying to access has permissions from. + +.. tabs:: + + .. tab:: Personal Account + + You need to make sure that you have granted access to the Read the Docs `OAuth App`_ to your **personal GitHub account**. + If you do not see Read the Docs in the `OAuth App`_ settings, you might need to disconnect and reconnect the GitHub service. + + GitHub has docs on `requesting access to your personal OAuth`_ for more information. + + .. _OAuth App: https://github.com/settings/applications + .. _requesting access to your personal OAuth: https://docs.github.com/en/organizations/restricting-access-to-your-organizations-data/approving-oauth-apps-for-your-organization + + .. tab:: Organization Account + + You need to make sure that you have granted access to the Read the Docs OAuth App to your **organization GitHub account**. + If you don't see |com_brand| listed, then you might need to connect GitHub in your social accounts as noted above. + + GitHub has docs on `requesting access to your organization OAuth`_ for step-by-step instructions. + + .. _requesting access to your organization OAuth: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps Bitbucket ~~~~~~~~~ diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index b9798e26cbb..071fba303d3 100644 --- a/docs/pull-requests.rst +++ b/docs/pull-requests.rst @@ -59,17 +59,15 @@ Troubleshooting #. **Pull Requests builds are not triggered**. We only support GitHub and GitLab currently. You need to make sure that your Read the Docs account is connected with that provider. - You can check this by going to your `profile settings`_. + You can check this by going to your :guilabel:`Username dropdown > Settings > Connected Services`. #. **Build status is not being reported to your VCS provider**. You need to make sure that you have granted access to the Read the Docs - `OAuth App`_ to your personal or organization GitHub account. - If you do not see "Read the Docs" in the `OAuth App`_ settings, - you might need to disconnect and reconnect to GitHub service. + OAuth App to your personal or organization GitHub account. + Learn more about this in our :ref:`github-permission-troubleshooting` section. Also make sure your webhook is properly setup to handle events related to pull requests. You can setup or ``re-sync`` the webhook from your projects admin dashboard. Learn more about setting up webhooks from our :doc:`Webhook Documentation `. -.. _profile settings: https://readthedocs.org/accounts/social/connections/ .. _OAuth App: https://github.com/settings/applications From 887935c49bcb74fc53e05393359498e142750c4c Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 30 Jun 2021 17:13:12 -0700 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: Anthony --- docs/connected-accounts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index c91b4b6328a..66783e0dd17 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -13,7 +13,7 @@ Connecting your account allows for: If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials, you're all done. Your account is connected. -To connect a social account, go to your :guilabel:`Username dropdown > Settings > Connected Services`. +To connect a social account, go to your :guilabel:`Username dropdown` > :guilabel:`Settings` > :guilabel:`Connected Services`. 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. @@ -67,7 +67,7 @@ Repository status (``repo:status``) .. _github-permission-troubleshooting: -GitHub Permission Troubleshooting +GitHub permission troubleshooting ````````````````````````````````` A common issue with importing a GitHub project to Read the Docs is OAuth permissions. From 8c518fe1b53bfc22a411402462c4005a57bd170c Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 30 Jun 2021 17:13:25 -0700 Subject: [PATCH 3/7] Use seealso links --- docs/connected-accounts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index 66783e0dd17..a9bfecaa7c4 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -83,7 +83,7 @@ depending on where the project you are trying to access has permissions from. You need to make sure that you have granted access to the Read the Docs `OAuth App`_ to your **personal GitHub account**. If you do not see Read the Docs in the `OAuth App`_ settings, you might need to disconnect and reconnect the GitHub service. - GitHub has docs on `requesting access to your personal OAuth`_ for more information. + .. seealso:: GitHub docs on `requesting access to your personal OAuth`_ for step-by-step instructions. .. _OAuth App: https://github.com/settings/applications .. _requesting access to your personal OAuth: https://docs.github.com/en/organizations/restricting-access-to-your-organizations-data/approving-oauth-apps-for-your-organization @@ -93,7 +93,7 @@ depending on where the project you are trying to access has permissions from. You need to make sure that you have granted access to the Read the Docs OAuth App to your **organization GitHub account**. If you don't see |com_brand| listed, then you might need to connect GitHub in your social accounts as noted above. - GitHub has docs on `requesting access to your organization OAuth`_ for step-by-step instructions. + .. seealso:: GitHub doc on `requesting access to your organization OAuth`_ for step-by-step instructions. .. _requesting access to your organization OAuth: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/managing-your-membership-in-organizations/requesting-organization-approval-for-oauth-apps From c6c77008679dd817a12f6b10ebee4570dd4bf2f2 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 30 Jun 2021 17:17:56 -0700 Subject: [PATCH 4/7] Add question to be answered. --- docs/connected-accounts.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index a9bfecaa7c4..8bc62aee72c 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -70,7 +70,8 @@ Repository status (``repo:status``) GitHub permission troubleshooting ````````````````````````````````` -A common issue with importing a GitHub project to Read the Docs is OAuth permissions. +**Repositories not in your list of repositories to import**. + Many organizations require approval for each OAuth application that is used, or you might have disabled it in the past for your personal account. This can happen at the personal or organization level, From b3baa7a7a90b78d0c4f730d88b54fdb20ee72805 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 30 Jun 2021 17:20:13 -0700 Subject: [PATCH 5/7] A bit more cleanup in language --- docs/connected-accounts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index 8bc62aee72c..dc3e1fcd804 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -70,7 +70,7 @@ Repository status (``repo:status``) GitHub permission troubleshooting ````````````````````````````````` -**Repositories not in your list of repositories to import**. +**Repositories not in your list to import**. Many organizations require approval for each OAuth application that is used, or you might have disabled it in the past for your personal account. From 52c98d56ccf975fda05f97b3fefadd73fa728dcb Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Tue, 6 Jul 2021 14:23:39 -0700 Subject: [PATCH 6/7] Update docs/pull-requests.rst Co-authored-by: Manuel Kaufmann --- docs/pull-requests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index 071fba303d3..c72d0c59f45 100644 --- a/docs/pull-requests.rst +++ b/docs/pull-requests.rst @@ -59,7 +59,7 @@ Troubleshooting #. **Pull Requests builds are not triggered**. We only support GitHub and GitLab currently. You need to make sure that your Read the Docs account is connected with that provider. - You can check this by going to your :guilabel:`Username dropdown > Settings > Connected Services`. + You can check this by going to your :guilabel:`Username dropdown` > :guilabel:`Settings` > :guilabel:`Connected Services`. #. **Build status is not being reported to your VCS provider**. You need to make sure that you have granted access to the Read the Docs From f554e5d9fbe36955162354a46d828e7c24cf4382 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Tue, 6 Jul 2021 14:23:46 -0700 Subject: [PATCH 7/7] Update docs/connected-accounts.rst Co-authored-by: Manuel Kaufmann --- docs/connected-accounts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index dc3e1fcd804..4ac43024cfa 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -92,7 +92,7 @@ depending on where the project you are trying to access has permissions from. .. tab:: Organization Account You need to make sure that you have granted access to the Read the Docs OAuth App to your **organization GitHub account**. - If you don't see |com_brand| listed, then you might need to connect GitHub in your social accounts as noted above. + If you don't see "Read the Docs" listed, then you might need to connect GitHub to your social accounts as noted above. .. seealso:: GitHub doc on `requesting access to your organization OAuth`_ for step-by-step instructions.