GitHub App: add docs

docs/user/guides/connecting-git-account.rst

@@ -40,7 +40,7 @@ You will now see the account appear in the list of connected services.
    :align: center
    :alt: Screenshot of Read the Docs "Connected Services" page with multiple services connected
 
-   Connected Services [#f1]_ [#f2]_ shows the list of Git providers that
+   Connected Services [#f1]_ [#f2]_ shows the list of Git providers that are connected to your Read the Docs account.
 
 Now your connection is ready and you will be able to import and configure Git repositories with just a few clicks.
 
@@ -57,11 +57,11 @@ You may at any time delete the connection from Read the Docs.
 Delete the connection makes Read the Docs forget the immediate access,
 but you should also disable our OAuth Application from your Git provider.
 
-* On GitHub, navigate to `Authorized OAuth Apps`_.
+* On GitHub, navigate to `Authorized GitHub Apps`_.
 * On Bitbucket, navigate to `Application Authorizations`_.
 * On GitLab, navigat to `Applications`_
 
-.. _Authorized OAuth Apps: https://github.com/settings/applications
+.. _Authorized GitHub Apps: https://github.com/settings/apps/authorizations
 .. _Application Authorizations: https://bitbucket.org/account/settings/app-authorizations/
 .. _Applications: https://gitlab.com/-/profile/applications
 

docs/user/guides/private-submodules.rst

@@ -8,9 +8,12 @@ How to use private Git submodules
 If you are using private Git repositories and they also contain private Git submodules,
 you need to follow a few special steps.
 
-Read the Docs uses SSH keys (with read only permissions) in order to clone private repositories.
-A SSH key is automatically generated and added to your main repository, but not to your submodules.
-In order to give Read the Docs access to clone your submodules you'll need to add the public SSH key to each repository of your submodules.
+Read the Docs uses SSH keys (with read only permissions) for GitLab and Bitbucket in order to clone private repositories,
+this key is added to your main repository, but not to your submodules.
+For GitHub we make use of a temporary token generated using our :ref:`GitHub App <reference/git-integration:GitHub App>`.
+
+When a project is created, a SSH key is automatically generated.
+You can use this SSH key to give Read the Docs access to clone your private submodules.
 
 .. note::
 
@@ -33,13 +36,6 @@ Since GitHub doesn't allow you to reuse a deploy key across different repositori
 you'll need to use `machine users <https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users>`__
 to give read access to several repositories using only one SSH key.
 
-#. Remove the SSH deploy key that was added to the main repository on GitHub
-
-   #. Go to your project on GitHub
-   #. Click on :guilabel:`Settings`
-   #. Click on :guilabel:`Deploy Keys`
-   #. Delete the key added by ``Read the Docs Commercial (readthedocs.com)``
-
 #. Create a GitHub user and give it read only permissions to all the necessary repositories.
    You can do this by adding the account as:
 

docs/user/guides/pull-requests.rst

@@ -4,15 +4,15 @@ How to configure pull request builds
 In this section, you can learn how to configure :doc:`pull request builds </pull-requests>`.
 
 To enable pull request builds for your project,
-your Read the Docs account needs to be connected to an account with a supported Git provider.
+your Read the Docs project needs to be connected to a repository from a supported Git provider.
 See `Limitations`_ for more information.
 
-If your account is already connected:
+If your project is already connected:
 
 #. Go to your project dashboard
-#. Go to :guilabel:`Admin`, then :guilabel:`Settings`
+#. Go to :guilabel:`Settings`, then :guilabel:`Pull request builds`
 #. Enable the :guilabel:`Build pull requests for this project` option
-#. Click on :guilabel:`Save`
+#. Click on :guilabel:`Update`
 
 .. tip::
 
@@ -44,18 +44,17 @@ while private previews are only available to users with access to the Read the D
 To change the privacy level:
 
 #. Go to your project dashboard
-#. Go to :guilabel:`Admin`, then :guilabel:`Settings`
-#. Select your option in :guilabel:`Privacy level of builds from pull requests`
-#. Click on :guilabel:`Save`
+#. Go to :guilabel:`Settings`, then :guilabel:`Pull request builds`
+#. Select your option in :guilabel:`Privacy level of builds of Pull Requests`
+#. Click on :guilabel:`Update`
 
 Privacy levels work the same way as :ref:`normal versions <versions:Version states>`.
 
 Limitations
 -----------
 
 - Pull requests are only available for **GitHub** and **GitLab** currently. Bitbucket is not yet supported.
-- To enable this feature, your Read the Docs account needs to be connected to an
-  account with your Git provider.
+- To enable this feature, your Read the Docs project needs to be connected to a repository from a supported Git provider.
 - Builds from pull requests have the same memory and time limitations
   :doc:`as regular builds </builds>`.
 - Additional formats like PDF aren't built in order to reduce build time.
@@ -66,7 +65,10 @@ Troubleshooting
 ---------------
 
 No new builds are started when I open a pull request
-   The most common cause is that your repository's webhook is not configured to
+   The most common cause when using GitHub is that your Read the Docs project is not
+   connected to the corresponding repository on GitHub.
+
+   The most common cause for GitLab and Bitbucket is that your repository's webhook is not configured to
    send Read the Docs pull request events. You'll need to re-sync your project's
    webhook integration to reconfigure the Read the Docs webhook.
 
@@ -85,11 +87,6 @@ Build status is not being reported to your Git provider
    being updated with your Git provider, then your connected account may have out
    dated or insufficient permissions.
 
-   Make sure that you have granted access to the Read the Docs `GitHub OAuth App`_ for
-   your personal or organization GitHub account.
-
 .. seealso::
    - :ref:`guides/setup/git-repo-manual:Debugging webhooks`
    - :ref:`github-permission-troubleshooting`
-
-.. _GitHub OAuth App: https://github.com/settings/applications

docs/user/guides/setup/git-repo-manual.rst

@@ -205,13 +205,7 @@ Webhook activation failed. Make sure you have the necessary permissions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you find this error,
-make sure your user has permissions over the repository.
-In case of GitHub,
-check that you have granted access to the Read the Docs `OAuth App`_ to your organization.
-A similar workflow is required for other supported providers.
-
-.. _OAuth App: https://github.com/settings/applications
-
+make sure your user has admin permissions over the repository.
 
 My project isn't automatically building
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/user/intro/add-project.rst

@@ -16,6 +16,7 @@ Automatically add your project
 #. Go to your :term:`dashboard`.
 #. Click on :guilabel:`Add project`.
 #. Type the name of the repository you want to add and click on it.
+   If you are using GitHub, make sure you have installed the :ref:`Read the Docs GitHub App <reference/git-integration:GitHub App>` in your repository.
 #. Click on :guilabel:`Continue`.
 #. Edit any of the pre-filled fields with information of the repository.
 #. Click on :guilabel:`Next`.

docs/user/reference/git-integration.rst

@@ -12,8 +12,9 @@ Connecting your account provides the following features:
   See: :doc:`/intro/add-project`.
 
 ⚙️ Automatic configuration
-  Have your Git repository automatically configured with your Read the Docs :term:`webhook`,
-  which allows Read the Docs to build your docs on every change to your repository.
+  Have Read the Docs subscribe to your repository's events,
+  allowing us to build your docs on every change to your repository,
+  and keep in sync with your tags and branches.
 
 🚥️ Commit status
   See your documentation build status as a commit status indicator on :doc:`pull request builds </pull-requests>`.
@@ -46,10 +47,17 @@ you can follow the :doc:`/intro/add-project` guide to actually add your project
 How automatic configuration works
 ---------------------------------
 
-When your Read the Docs account is connected to |git_providers_or| and you :doc:`add a new Read the Docs project </intro/add-project>`:
+When your Read the Docs account is connected to GitHub, and you :doc:`add a new Read the Docs project </intro/add-project>`:
+
+* Read the Docs automatically connects your project with the GitHub repository,
+  and subscribes to the repository's events.
+* Read the Docs makes use of its :ref:`GitHub App <reference/git-integration:GitHub App>` to interact with your repository.
+
+When your Read the Docs account is connected to GitLab or Bitbucket, and you :doc:`add a new Read the Docs project </intro/add-project>`:
 
 * Read the Docs automatically creates a Read the Docs Integration that matches your Git provider.
 * Read the Docs creates an incoming webhook with your Git provider, which is automatically added to your Git repository's settings using the account connection.
+* Read the Docs creates an SSH key, which is automatically added to your Git repository (when adding private repositories on |com_brand|).
 
 After project creation,
 you can continue to configure the project.
@@ -64,7 +72,12 @@ including the ones that were automatically created.
 Read the Docs incoming webhook
 ------------------------------
 
-Accounts with |git_providers_and| integration automatically have Read the Docs' incoming :term:`webhook` configured on all Git repositories that are imported.
+.. note::
+
+   When using GitHub, Read the Docs uses a GitHub App that subscribes to all required events.
+   You don't need to create a webhook on your repository.
+
+Accounts with GitLab and Bitbucket integrations automatically have Read the Docs' incoming :term:`webhook` configured on all repositories that are imported.
 Other setups can set up the webhook through :doc:`manual configuration </guides/setup/git-repo-manual>`.
 
 When an incoming webhook notification is received,
@@ -97,24 +110,30 @@ Read the Docs uses `OAuth`_ to connect to your account at |git_providers_or|.
 You are asked to grant permissions for Read the Docs to perform a number of actions on your behalf.
 
 At the same time, we use this process for authentication (login)
-since we trust that |git_providers_or| have verified your user account and email address.
+since we trust that the user who connects the account is the owner of Git provider account.
 
 By granting Read the Docs the requested permissions,
 we are issued a secret OAuth token from your Git provider.
-Using the secret token,
-we can automatically configure repositories during :doc:`project creation </intro/add-project>`.
-We also use the token to send back build statuses and preview URLs for :doc:`pull requests </pull-requests>`.
+In the case of GitLab and Bitbucket, we can use the secret token
+to automatically configure repositories during :doc:`project creation </intro/add-project>`.
+For GitHub, you need to install our :ref:`GitHub App <reference/git-integration:GitHub App>` in the repository you want to add.
 
 .. _OAuth: https://en.wikipedia.org/wiki/OAuth
 
 .. note::
 
-  Access granted to Read the Docs can always be revoked.
-  This is a function offered by all Git providers.
+   Access granted to Read the Docs can always be revoked.
+   This is a function offered by all Git providers.
 
 Git provider integrations
 -------------------------
 
+.. note::
+
+   When using GitHub, Read the Docs uses a GitHub App to interact with your repositories.
+   If the original user who connected the repository to Read the Docs loses access to the project or repository,
+   the GitHub App will still have access to the repository, and the integrations will continue to work.
+
 If your project is using :doc:`Organizations </commercial/organizations>` (|com_brand|) or :term:`maintainers <maintainer>` (|org_brand|),
 then you need to be aware of *who* is setting up the integration for the project.
 
@@ -136,6 +155,40 @@ so that you can log in to Read the Docs with your connected account credentials.
 
    .. tab:: GitHub
 
+      Read the Docs requests the following permissions when connecting your Read the Docs account to GitHub.
+
+      Account email addresses (read only)
+          We ask for this so we can verify your email address and create a Read the Docs account.
+
+      When installing the Read the Docs GitHub App in a repository, you will be asked to grant the following permissions:
+
+      Repository permissions
+        Commit statuses (read and write)
+          This allows Read the Docs to report the status of the build to GitHub.
+        Contents (read only)
+          This allows Read the Docs to clone the repository and build the documentation.
+        Metadata (read only)
+          This allows Read the Docs to read the repository collaborators and the permissions they have on the repository.
+          This is used to determine if the user can connect a repository to a Read the Docs project.
+        Pull requests (read and write)
+          This allows Read the Docs to subscribe to pull request events,
+          and to create a comment on the pull request with information about the build.
+
+      Organization permissions
+        Members (read only)
+          This allows Read the Docs to read the organization members.
+
+
+   .. tab:: GitHub (old OAuth app integration)
+
+      .. note::
+
+         Read the Docs used to use a GitHub OAuth application for integration,
+         which is being deprecated and replaced by a `GitHub App <https://docs.github.com/en/apps/overview>`__.
+         If you haven't migrated your projects to the new GitHub App,
+         we will still use the OAuth application to interact with your repositories for now,
+         but we recommend migrating to the GitHub App for a better experience and more granular permissions.
+
       Read the Docs requests the following permissions (more precisely, `OAuth scopes`_)
       when connecting your Read the Docs account to GitHub.
 
@@ -197,35 +250,90 @@ so that you can log in to Read the Docs with your connected account credentials.
       * API access (``api``) which is needed to create webhooks in GitLab
 
 
-.. _github-permission-troubleshooting:
+GitHub App
+----------
 
-GitHub permission troubleshooting
----------------------------------
+Read the Docs used to use a GitHub OAuth application for integration,
+which has been replaced by a `GitHub App <https://docs.github.com/en/apps/overview>`__.
+If you haven't migrated your projects to the new GitHub App,
+we will still use the OAuth application similar to the other Git providers to interact with your repositories,
+we recommend migrating to the GitHub App for a better experience and more granular permissions.
 
-**Repositories not in your list to import**.
+We have two GitHub Apps, one for each of our platforms:
 
-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.
+- `Read the Docs Community <https://github.com/apps/read-the-docs-community>`__.
+- `Read the Docs for Business <https://github.com/apps/read-the-docs-business>`__.
 
-.. tabs::
+Features
+~~~~~~~~
+
+When using GitHub, Read the Docs uses a GitHub App to interact with your repositories.
+This has the following benefits over using an OAuth application (like the other Git providers):
+
+- More control over which repositories Read the Docs can access.
+  You don't need to grant access to all your repositories in order to create an account or import a single repository.
+- No need to create webhooks on your repositories.
+  The GitHub App subscribes to all required events when you install it.
+- No need to create a deploy key on your repository (|com_brand| only).
+  The GitHub App can clone your private repositories using a temporal token.
+- If the original user who connected the repository to Read the Docs loses access to the project or repository,
+  the GitHub App will still have access to the repository.
+- You can revoke access to the GitHub App at any time from your GitHub settings.
+- Never out of sync with changes on your repository.
+  The GitHub App subscribes to all required events and will always keep your project up to date with your repository.
+
+Revoking access
+~~~~~~~~~~~~~~~
+
+You can revoke access to the Read the Docs GitHub App at any time from your GitHub settings.
+
+- `Read the Docs Community <https://github.com/apps/read-the-docs-community/installations/new/>`__.
+- `Read the Docs for Business <https://github.com/apps/read-the-docs-business/installations/new/>`__.
+
+There are three ways to revoke access to the Read the Docs GitHub App:
+
+Revoke access to one or more repositories:
+  Remove the repositories from the list of repositories that the GitHub App has access to.
+Suspend the GitHub App:
+  This will suspend the GitHub App and revoke access to all repositories.
+  The installation and configuration will still be available,
+  and you can re-enable the GitHub App at any time.
+Uninstall the GitHub App:
+  This will uninstall the GitHub App and revoke access to all repositories.
+  The installation and configuration will be removed,
+  and you will need to re-install the GitHub App and reconfigure it to use it again.
+
+.. warning::
+
+   If you revoke access to the GitHub App with any of the above methods,
+   all projects linked to that repository will stop working,
+   but the projects and its documentation will still be available.
+   If you grant access to the repository again,
+   you will need to manually connect your project to the repository.
+
+.. _github-permission-troubleshooting:
 
-   .. tab:: Personal Account
+Troubleshooting
+~~~~~~~~~~~~~~~
 
-      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.
+**Repository not in the list to import**
 
-      .. seealso:: GitHub docs on `requesting access to your personal OAuth`_ for step-by-step instructions.
+Make sure you have installed the corresponding GitHub App in your GitHub account or organization,
+and have granted access to the repository you want to import.
 
-      .. _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
+- `Read the Docs Community <https://github.com/apps/read-the-docs-community/installations/new/>`__.
+- `Read the Docs for Business <https://github.com/apps/read-the-docs-business/installations/new/>`__.
 
-   .. tab:: Organization Account
+If you still can't see the repository in the list,
+you may need to wait a couple of minutes and refresh the page,
+or click on the "Refresh your repositories" button in the import page.
 
-      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 "Read the Docs" listed, then you might need to connect GitHub to your social accounts as noted above.
+**Repository is in the list, but can't be imported**
 
-      .. seealso:: GitHub doc on `requesting access to your organization OAuth`_ for step-by-step instructions.
+Make sure you have admin access to the repository you are trying to import.
+If you are using |org_brand|, make sure your project is public,
+or use |com_brand| to import private repositories.
 
-      .. _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
+If you still can't import the repository,
+you may need to wait a couple of minutes and refresh the page,
+or click on the "Refresh your repositories" button in the import page.