Docs: update docs to mention GitHub app (#12452)

Mostly extracted from
#12114

Closes #12129

Author: stsewd

docs/user/guides/private-submodules.rst

@@ -8,9 +8,8 @@ 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.
+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::
 
@@ -35,6 +34,11 @@ 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
 
+   .. note::
+
+      If you are using our :ref:`reference/git-integration:GitHub App` to connect your repository to Read the Docs,
+      you can skip this step, because access to your repository is controlled through the App instead of a deploy key.
+
    #. Go to your project on GitHub
    #. Click on :guilabel:`Settings`
    #. Click on :guilabel:`Deploy Keys`

docs/user/guides/pull-requests.rst

@@ -4,15 +4,13 @@ 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, with a webhook configured to send information on pull requests for your repository.
+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:
-
 #. 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 +42,19 @@ 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`
+#. Go to :guilabel:`Settings`, then :guilabel:`Pull request builds`
 #. Select your option in :guilabel:`Privacy level of builds from pull requests`
-#. Click on :guilabel:`Save`
+#. 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, *and* the connecting webhook must be configured to send on creation of a pull request, not just on pushes to your main branch.
+- To enable this feature, your Read the Docs project needs to be connected to a repository from a supported Git provider.
+- If your project is using our :ref:`reference/git-integration:GitHub App`, you don't need to configure a webhook.
+  For GitLab, and projects using our old GitHub integration, you need to make sure that your webhook is configured to send pull request events, not just push events.
 - 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.
@@ -67,8 +66,12 @@ 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
-   send Read the Docs pull request events. You'll need to re-sync your project's
+   The most common cause when using GitHub is that your Read the Docs project is not
+   :ref:`connected to the corresponding repository on GitHub <reference/git-integration:Connect a repository to an existing project>`.
+
+   If you are using our old GitHub integration,
+   make sure that your repository's webhook is configured to
+   send pull request events. You can re-sync your project's
    webhook integration to reconfigure the Read the Docs webhook.
 
    To re-sync your project's webhook, go to your project's admin dashboard,

docs/user/intro/add-project.rst

@@ -16,6 +16,8 @@ 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 our :ref:`reference/git-integration:GitHub App`,
+   make sure you have installed the :ref:`Read the Docs GitHub App <reference/git-integration:Troubleshooting>` 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

@@ -64,6 +64,11 @@ including the ones that were automatically created.
 Read the Docs incoming webhook
 ------------------------------
 
+.. note::
+
+   When using our :ref:`reference/git-integration:GitHub App`, Read the Docs subscribes to all required events.
+   You don't need to create a webhook on your repository.
+
 Accounts with |git_providers_and| integration automatically have Read the Docs' incoming :term:`webhook` configured on all Git repositories that are imported.
 Other setups can set up the webhook through :doc:`manual configuration </guides/setup/git-repo-manual>`.
 
@@ -109,8 +114,8 @@ We also use the token to send back build statuses and preview URLs for :doc:`pul
 
 .. 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
 -------------------------
@@ -124,6 +129,12 @@ A Git provider integration is active through the authentication of the user that
 If this user is removed,
 make sure to verify and potentially recreate all Git integrations for the project.
 
+.. note::
+
+   When using our :ref:`reference/git-integration:GitHub App`,
+   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.
+
 Permissions for connected accounts
 ----------------------------------
 
@@ -165,6 +176,31 @@ so that you can log in to Read the Docs with your connected account credentials.
           but there isn't a more granular permission
           that only allows setting up SSH keys for read access.
 
+   .. tab:: GitHub App
+
+      Read the Docs requests the following permissions when connecting your Read the Docs account to our :ref:`GitHub App <reference/git-integration:GitHub App>`.
+
+      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:: Bitbucket
 
       We request permissions for: