feat: Installation access tokens for Git operations on GH PLUTO-772

docs/faq/troubleshooting/we-no-longer-have-access-to-this-repository.md

@@ -17,7 +17,7 @@ If you renamed the repository or moved it to a different account on the Git prov
 
 !!! info "This section applies only to GitLab and Bitbucket"
 
-Codacy uses SSH keys to clone your private repositories. Depending on the level of access that the user configuring the repository on Codacy has on the remote Git provider, an SSH key can be added either:
+On GitLab and Bitbucket organizations, Codacy uses SSH keys to clone your private repositories. Depending on the level of access that the user configuring the repository on Codacy has on the remote Git provider, an SSH key can be added either:
 
 -   Directly to the repository itself, if the user has permissions to add SSH keys to the repository
 -   To the user account, if the user only has read or commit permissions on the repository
@@ -30,7 +30,7 @@ If the user that initially configured the repository on Codacy was using a user
     This is only possible if the user configuring the integration with the remote Git provider has administrator access to the repository. Otherwise, this operation will fail. Alternatively, you can do this process manually by copying the SSH key.
 
     !!! note
-        If [your repository is using submodules on Codacy](../../repositories-configure/using-submodules.md), add a new SSH user key to your git provider account instead.
+        If [your repository is using submodules on Codacy](../../repositories-configure/using-submodules.md), add a new SSH user key to your Git provider account instead.
 
     ![Generate new key](images/we-no-longer-have-access-to-this-repository-new-key.png)
 

docs/getting-started/which-permissions-does-codacy-need-from-my-account.md

@@ -63,15 +63,15 @@ If you log in with GitHub, Codacy requires the following [app permissions](https
       <td>Read & Write</td>
       <td>Codacy sets the status of commits according to the result of code analysis.</td>
     </tr>
-    <tr>
-      <td>Administration</td>
-      <td>Read & Write</td>
-      <td><a href="#why-does-codacy-ask-for-permission-to-create-ssh-keys">Codacy creates an SSH key</a> on the repository to allow cloning and integrating with your repository.</td>
-    </tr>
     <tr>
       <td>Contents</td>
       <td>Read-Only</td>
-      <td>Codacy accesses repository contents to provide faster code coverage analysis and as part of an initiative to use GitHub App tokens instead of SSH keys when cloning repositories for code quality analysis.</td>
+      <td>Codacy retrieves repository contents to get installation access tokens when integrating with your repositories and clone them, and for code coverage analysis.<br/><strong>Codacy requests this permission since September 2023.</strong> Make sure an organization owner <a href="https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps">approves Codacy GitHub App updated permissions</a> on your GitHub organization.</td>
+    </tr>
+    <tr>
+      <td>Administration</td>
+      <td>Read & Write</td>
+      <td>This permission <strong>will soon be removed</strong> and is currently used as a fallback mechanism when the Contents permission isn't available. In this case, Codacy <a href="#why-does-codacy-ask-for-permission-to-create-ssh-keys">creates an SSH key on the repository</a> to allow cloning and integrating with your repository.<br/>To ensure Codacy keeps working correctly, make sure an organization owner <a href="https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps">approves Codacy GitHub App updated permissions</a> on your GitHub organization.</td>
     </tr>
     <tr>
       <td colspan="3"><strong>Organization permissions:</strong></td>
@@ -206,8 +206,16 @@ If you need to use an integration that you have previously revoked, log in again
 
 ## Why does Codacy ask for permission to create SSH keys?
 
+!!! note
+    **GitHub only:** Codacy will soon start using [installation access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app#about-installation-access-tokens) instead of SSH keys to integrate with your GitHub repositories and clone them. SSH keys are currently used as a fallback mechanism when the [Contents permission](#github-cloud) isn't available.
+
+    To ensure Codacy keeps working correctly, make sure an organization owner [approves Codacy GitHub App updated permissions](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps) on your GitHub organization.
+
 When you add a private repository to Codacy, Codacy uses the integration with your Git provider to create a new SSH key on the repository. Codacy then uses that SSH key every time it needs to clone the repository.
 
-**Codacy only adds read-only SSH keys** and can't access any of your existing SSH keys. You have full control over which organizations and repositories Codacy is authorized to access, and you can also [revoke the keys created by Codacy at any time](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-deploy-keys). Codacy doesn't change the contents or member privileges of any repository you authorize it to analyze.<!--NOTE Even though this section applies to all Git providers, we're only providing a link to the GitHub docs for the sake of simplicity.-->
+**Codacy only adds read-only SSH keys** and can't access any of your existing SSH keys. You have full control over which organizations and repositories Codacy is authorized to access. Codacy doesn't change the contents or member privileges of any repository you authorize it to analyze.
 
 We understand the desire for security and privacy and find that the SSH protocol is preferable to HTTPS as it separates Codacy's access rights from the one of the users.
+
+!!! tip
+    You can revoke the keys created by Codacy at any time. See [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/reviewing-your-deploy-keys), [GitLab](https://docs.gitlab.com/ee/user/project/deploy_keys/), or [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-repository-settings/) documentation for further details.

docs/repositories-configure/removing-your-repository.md

@@ -16,4 +16,7 @@ To delete your repository from Codacy:
     ![Removing your repository](images/repository-remove.png)
 
     !!! note
-        For added security, after you remove the repository from Codacy you can delete the webhooks and SSH keys related to this Codacy repository from your Git provider to prevent their reuse.
+        For added security, after you remove the repository from Codacy you can delete from your Git provider the resources related to this Codacy repository to prevent their reuse:
+
+        -   Webhooks
+        -   SSH keys <!--TODO PLUTO-811 Add "(GitLab and Bitbucket only)"-->

docs/repositories-configure/using-submodules.md

@@ -4,35 +4,54 @@
 
 By default, Codacy does normal Git clones that **don't include submodules** to ensure that we only clone necessary repositories. If your organization needs to use submodules, you can request Codacy to enable this feature for you.
 
+!!! important
+    **GitHub only:**
+
+    -   To clone repositories, the Codacy GitHub App [requires the Contents permission](../getting-started/which-permissions-does-codacy-need-from-my-account.md#github-cloud). Make sure an organization owner [approves Codacy GitHub App updated permissions](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps) on your GitHub organization.
+    -   Your repository and the repositories that you add as submodules must belong to the same GitHub organization.
+
 ## Prerequisites for using submodules
 
 1.  Contact us at <mailto:[email protected]> asking to enable submodules on Codacy.
 
 1.  **If you're using Codacy Self-hosted**, [update your license](../chart/maintenance/license.md).
 
-1.  If your submodules are:
-    -   **Public repositories**, make sure that your Git URL uses the HTTPS protocol.
-    -   **Private repositories**, make sure that your Git URL uses the SSH protocol.
+1.  Make sure that your **Git URL** uses the correct protocol:
+    -   **GitHub:** HTTPS protocol
+    -   **GitLab and Bitbucket:**
+        -   HTTPS protocol, if your submodules are **public repositories**
+        -   SSH protocol, if your submodules are **private repositories**
 
 ## Enabling submodules on a repository
 
 When using submodules, you must do the following for all your existing and new repositories:
 
-1.  Open the repository **Settings**, tab **General**. In the **Danger zone** area, you have the **SSH Key** generated by Codacy to access your repository. Take note of this key.
+1.  **GitLab and Bitbucket only:** [Update the public SSH key](#update-key) that Codacy uses to access your repository.
 
-    Codacy generates this repository key when you add a repository to Codacy and uses it to clone that repository. When you're using submodules, Codacy needs to clone additional repositories it may not have access to. To overcome this, Codacy must use an SSH key of your user account to have access to the same repositories as your user.
+1.  If you're using submodules to share an analysis tool configuration file across your repositories, check if your tool recursively searches the subdirectories of your repositories for configuration files.
 
-1.  For GitHub and Bitbucket, remove this Codacy key from the repository settings on your Git provider.
+    If your tool doesn't detect the configuration files in the submodule directories, you must include a configuration file directly in the root of your repositories referencing the configuration files in the submodule directories.
 
-1.  Add a new SSH key to your git provider account by clicking the link **Add new user key** or the button **Generate New User Key**, depending on your Git provider.
+## Updating the public SSH key to access the repository {: id="update-key"}
 
-    For GitHub and Bitbucket, this takes you to the Git provider page where you can manage your user account SSH keys. For GitLab, Codacy removes the existing repository key and creates the new SSH key on your user account automatically.
+!!! info "This section applies only to GitLab and Bitbucket"
 
-    ![Generate new user key](images/using-submodules-generate-new-user-key.png)
+On GitLab and Bitbucket organizations, Codacy generates a repository key when you add a repository to Codacy and uses it to clone that repository. When you're using submodules, Codacy needs to clone additional repositories it may not have access to. To overcome this, Codacy must use an SSH key of your user account to have access to the same repositories as your user.
 
-1.  If you're using submodules to share an analysis tool configuration file across your repositories, check if your tool recursively searches the subdirectories of your repositories for configuration files.
+To update your GitLab or Bitbucket public SSH key that Codacy uses to access your repository, do the following:
 
-    If your tool doesn't detect the configuration files in the submodule directories, you must include a configuration file directly in the root of your repositories referencing the configuration files in the submodule directories.
+1.  Open the repository **Settings**, tab **General**. In the **Danger zone** area, you have the **SSH Key** generated by Codacy to access your repository.
+
+1.  Depending on your Git provider, do the following to update the key:
+
+    -   For GitLab, click the button **Generate New User Key**. Codacy removes the existing repository key and creates the new SSH key on your user account automatically.
+
+    -   For Bitbucket:
+        1.  Remove the existing Codacy key from the repository settings on your Git provider.
+        1.  Click the link **Add new user key**. This takes you to the Git provider page where you can manage your user account SSH keys.
+        1.  Add a new SSH key to your Git provider account.
+
+    ![Generate new user key](images/using-submodules-generate-new-user-key.png)
 
 ## Automating user keys for new repositories
 
@@ -47,7 +66,5 @@ You can set Codacy to automatically add the new SSH key to your Git provider acc
 
 ## See also
 
--   [Managing deploy keys in GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys)
--   [Add an SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
 -   [Configure repository settings in Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-repository-settings/)
 -   [Add an SSH key to your Bitbucket account](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/)