clean: Create a dedicated section for the service account procedure DOCS-680

docs/assets/includes/service-account-integration.md

@@ -1,4 +1,2 @@
 !!! tip
-    Use a dedicated service account to integrate Codacy with your repositories. This prevents disruption of service if the user who originally enabled the integration loses access to the repositories, which may happen when a user leaves the team or the organization.
-
-    For more information and instructions on how to set up a dedicated service account see [Why did Codacy stop commenting on pull requests?](../../faq/troubleshooting/why-did-codacy-stop-commenting-on-pull-requests.md#outdated-permissions)
+    Use a [dedicated service account](../../faq/troubleshooting/why-did-codacy-stop-commenting-on-pull-requests.md#service-account) to integrate Codacy with your repositories. This prevents disruption of service if the user who originally enabled the integration loses access to the repositories, which may happen when a user leaves the team or the organization.

docs/faq/troubleshooting/why-did-codacy-stop-commenting-on-pull-requests.md

@@ -14,7 +14,15 @@ If you stopped receiving coverage summaries on your pull requests, please [revie
 
 Different reasons can cause Codacy to stop analyzing and commenting on pull requests, but the most common is that the user who initially enabled the GitLab or Bitbucket integration no longer has permissions on the repository or that the SSH key is no longer valid.
 
-To fix this issue and avoid future disruptions, refresh the GitLab or Bitbucket integration on Codacy using a dedicated service account on your Git provider:
+To fix this issue and avoid future disruptions, refresh the GitLab or Bitbucket integration on Codacy [using a dedicated service account](#service-account) on your Git provider.
+
+## Using a dedicated service account to integrate with your Git provider {: id="service-account"}
+
+!!! info "This section applies to GitLab and Bitbucket"
+
+Using a dedicated service account to integrate Codacy with your repositories prevents disruption of service if the user who originally enabled the integration loses access to the repositories.
+
+To integrate Codacy with GitLab or Bitbucket using a dedicated service account, do the following:
 
 1.  Create a service account on your Git provider exclusively dedicated to integrating Codacy with your repositories.
 

docs/repositories-configure/integrations/using-a-dedicated-service-account.md

@@ -0,0 +1,34 @@
+# Integrate with your Git provider using a service account
+
+!!! info "This page applies only to GitLab and Bitbucket"
+
+Using a dedicated service account to integrate Codacy with your repositories prevents disruption of service if the user who originally enabled the integration loses access to the repositories.
+
+To integrate Codacy with GitLab or Bitbucket using a dedicated service account, do the following:
+
+1.  Create a service account on your Git provider exclusively dedicated to integrating Codacy with your repositories.
+
+    !!! note
+        The service account must:
+
+        -   [Have administrator permissions](../../organizations/roles-and-permissions-for-organizations.md) on the repositories to integrate with Codacy
+        -   Not be shared by other systems to ensure that Codacy doesn't hit the API rate limits of the Git provider when using this account
+
+    !!! tip
+        Using a dedicated service account also has the advantage of any pull request comments made by Codacy appearing as authored by the service account instead of by a regular organization member. You can name this account "Codacy" and use [this Codacy logo](https://avatars.githubusercontent.com/u/1834093) as the account picture so that your pull request comments look like the following example:
+
+        ![Codacy comment on a GitLab merge request](images/gitlab-integration-pr-comment.png)
+
+1.  Log out of both your Git provider and of Codacy.
+
+1.  Log in to Codacy using the new service account.
+
+1.  Open your repository **Settings**, tab **Integrations**, and click the link **Refresh connection** to refresh the existing Git provider integration:
+
+    ![Refresh Git provider integration](images/gitlab-integration-refresh.png)
+
+1.  Make sure the Git provider integration is configured as needed:
+
+    -   [Configuring the GitLab integration](gitlab-integration.md#configuring)
+
+    -   [Configuring the Bitbucket integration](bitbucket-integration.md#configuring)

mkdocs.yml

@@ -579,6 +579,7 @@ nav:
                 - repositories-configure/integrations/github-integration.md
                 - repositories-configure/integrations/gitlab-integration.md
                 - repositories-configure/integrations/bitbucket-integration.md
+                - repositories-configure/integrations/using-a-dedicated-service-account.md
                 - repositories-configure/integrations/post-commit-hooks.md
           - repositories-configure/ignoring-files.md
           - repositories-configure/languages.md