coderabbitai · karan925 · Jan 15, 2025 · Jan 14, 2025 · Jan 15, 2025 · Jan 15, 2025
diff --git a/docs/platforms/gitlab-com.md b/docs/platforms/gitlab-com.md
@@ -5,81 +5,141 @@ sidebar_label: GitLab.com
 sidebar_position: 2
 ---
 
-This guide will assist you in effectively integrating CodeRabbit with SaaS GitLab.
-
-## How it works
+CodeRabbit integrates with GitLab to enhance code review and collaboration by:
 
-For the CodeRabbit app to post reviews on merge requests, it needs to interact with the GitLab API, which requires a Personal Access Token. This token can be generated either by using our default CodeRabbit user or by creating a Personal Access Token from one of your existing users.
+- Automatically initiating code reviews for newly created merge requests.
+- Displaying review comments and suggestions directly on merge requests.
+- Enabling seamless interaction with the CodeRabbit bot for real-time feedback and assistance.
 
-The CodeRabbit default user, named "coderabbitai", is already set up in GitLab SaaS and will be added to your project when you install the CodeRabbit app. During installation, the necessary webhook for the project will also be created.
-
-If your organization prefers to use an organization user, you can create a new user in GitLab and generate a Personal Access Token for that user, following [our recommendations](#recommendations).
+This guide will assist you in effectively integrating CodeRabbit with SaaS GitLab.
 
-:::note
+## GitLab Access Tokens
 
-Keep in mind that if you want to change the review user, you can either disable the organization user or add a new user via the CodeRabbit UI. However, this will require manually removing the previous user from the projects and associated webhooks. Afterward, you will need to reinstall the CodeRabbit app for each project.
+To enable CodeRabbit to interact with your GitLab repositories, an access token is required. This token grants the necessary permissions for interacting with the Merge Requests and Discussions APIs.
 
-:::
+    1. Personal Access Token (PAT): You can create a new GitLab account specifically for CodeRabbit, name it “CodeRabbit” and treat it as a service account. Then generate a PAT from it where PAT will enable seamless integration between CodeRabbit and your GitLab repositories.
+    2. Group Access Token: If your organization uses GitLab Premium or Ultimate, you can generate a Group Access Token. This option automatically creates a bot user associated with the group for managing access and posting reviews.
 
-## GitLab Access Tokens
+### Personal Access Token
 
-To interact with the GitLab API, a **Personal Access Token** is required. This token can either be generated by using our default CodeRabbit user or by creating a **Personal Access Token** from one of your existing users.
+We recommend creating a new user as a service account, associating this user to the group you'd like to install CodeRabbit on, and providing CodeRabbit with the personal access token to allow access. During the installation process, CodeRabbit will automatically configure the required webhook for seamless integration.
 
-Upon first login to the application (immediately after the onboarding screen), you will need to choose based on your organization's requirements.
+<div class="center-image">
+ <img
+  src="/img/integrations/gitlab_user_choice.png"
+  alt="GitLab user modal choice"
+  width="1000"
+ />
+</div>
 
-![gitlab user modal choice](/img/integrations/gitlab_user_choice.png)
-
-**We recommend using the default CodeRabbit user** for most organizations, as it is pre-configured. However, we understand that some organizations may prefer more control over the user or have restrictions regarding user inclusion within their organization.
+:::note
 
-### Personal Access Tokens
+If you wish to change the review user, you must provide the access token for the new user who will post reviews and comments. However, this requires manually removing the previous user from the projects and associated webhooks. Once this is done, you will need to reinstall the CodeRabbit app for each project.
 
-If your organization opts to use another user within the organization, you can do so by [generating a personal access token](#generating-a-personal-access-token).
+:::
 
-![gitlab organization user modal choice](/img/integrations/gitlab_organization_user.png)
+<div class="center-image">
+ <img
+  src="/img/integrations/gitlab_organization_user.png"
+  alt="GitLab organization user modal
+choice"
+  width="1000"
+ />
+</div>
 
 #### Recommendations
 
 - **Create a dedicated user for CodeRabbit** - This ensures the user is exclusively for CodeRabbit, allowing better access control.
 - **Use "CodeRabbit" as the username** - This makes the user easily recognizable for future reference.
 - **Use a dedicated email address** - This helps in easy identification and management.
 - **Use the CodeRabbit logo as the profile picture** - This further ensures easy recognition. You can download our logo from [here](/img/integrations/logo.svg "download").
+- **Developer Access** Ensure the service account user has developer access to the group or projects that you wish to install CodeRabbit on.
 
 #### Key Points to Remember
 
-- Personal access tokens have expiration dates. Ensure the expiration date covers the duration of your intended use of the CodeRabbit app.
+- Personal access tokens have expiration dates. Ensure the expiration date **covers the duration** of your intended use of CodeRabbit.
 - Code reviews will be attributed to the owner of the personal access token.
 - If the personal access token expires, you can add a new one via the CodeRabbit UI:
-  - Navigate to the "GitLab User" page in the sidebar.
-  - Click the "Update" button on the displayed card to see the same modal as the initial login.
+  - Navigate to the **GitLab User** page in the sidebar.
+  - Enter the new Access token, and click the **Update** button on the page.
 
-### Generating a Personal Access Token
+#### Generating a Personal Access Token
 
 GitLab provides an option to generate a personal access token for a new user. Follow these steps to generate the token:
 
-1. Log in as the user intended for CodeRabbit reviews.
+1. Log in using the user designated for CodeRabbit reviews. This user serves as a service account for managing reviews and related activities.
 2. Select your avatar on the left sidebar.
-3. Choose "Edit Profile."
-4. Select "Access Tokens" from the left sidebar.
-5. [Click "Add New Token."](https://gitlab.com/-/user_settings/personal_access_tokens)
+3. Choose **Edit Profile**.
+4. Select **Access Tokens** from the left sidebar.
+5. Click [Add New Token.](https://gitlab.com/-/user_settings/personal_access_tokens)
 6. Enter a name and an expiry date for the token.
 7. If no expiry date is entered, it defaults to 365 days from the current date.
 8. Ensure the following scopes are selected: `api`, `read_api`, `read_user`.
-9. Click "Create Personal Access Token."
+9. Click **Create Personal Access Token**
 10. Note down the token as it will only be displayed once.
 
-![GitLab personal access token configuration page](/img/integrations/admin-access-token.png)
+<div class="center-image">
+ <img
+  src="/img/integrations/admin-access-token.png"
+  alt="GitLab personal access token configuration page"
+  width="1000"
+ />
+</div>
 
-### Installing CodeRabbit into your GitLab Repositories
+---
 
-1. Go to the [Repositories page](https://app.coderabbit.ai/settings/repositories) in the CodeRabbit app.
-2. Click the check box to the left of the repos you want to install CodeRabbit into. Click the box at the top to install onto all repos at once.
-3. Click **Install Repositories**.
+### Group Access Token
+
+Creating a Group Access Token in GitLab automatically generates a bot user. Ensure that the token is configured with Developer access. Once set up, you only need to provide this token for integration. Note that a Group Access Token is limited to the scope of the group where it was created. To configure additional groups, you will need to generate a separate Group Access Token for each group.
 
 ![GitLab repo Installation](/img/integrations/gitlab-repo-install.png)
+:::note
+
+By default, GitLab restricts this option to users on the Premium or Ultimate tiers.
+
+:::
+
+#### Generating a Group Access Token
+
+1. Navigate to the group you wish to install CodeRabbit on.
+2. Select **Settings** from the left sidebar.
+3. Select **Access Tokens** within the Settings heading.
+4. Create a Group Access Token.
+5. Ensure the following scopes are selected: `api`.
+6. Ensure Developer Access is provided.
+
+---
 
-The webhook `https://coderabbit.ai/gitlabHandler` will now be installed in your repositories.
+### Where to Provide CodeRabbit the Access Token
 
-![GitLab Webhook Example](/img/integrations/gitlab-webhook.png)
+By default, if no access token is provided, CodeRabbit will prompt you to provide one during the installation process. However, if you wish to provide the token beforehand, you can do so by navigating to the **Organization Settings** tab, and selecting the **GitLab User** tab on the sidebar. Once entering the token, the token will be validated and saved for future use.
+
+You can confirm the correct user is being selected by verifying the user ID shown on the UI with the user ID of the service account user you created.
+
+---
+
+### Installing CodeRabbit into your GitLab Repositories
+
+1. Go to the [Repositories page](https://app.coderabbit.ai/settings/repositories) in the CodeRabbit app.
+2. Select the checkbox next to the repositories where you want to install CodeRabbit. To install it on all repositories at once, select the checkbox at the top.
+3. Select **Install Repositories**.
+
+<div class="center-image">
+ <img
+  src="/img/integrations/gitlab-repo-install.png"
+  alt="GitLab Repo Install Modal"
+  width="1000"
+ />
+</div>
+
+The webhook `https://coderabbit.ai/gitlabHandler` will now be installed for the projects selected.
+
+<div class="center-image">
+ <img
+  src="/img/integrations/gitlab-webhook.png"
+  alt="GitLab Webhook Example"
+  width="1000"
+ />
+</div>
 
 ### Troubleshooting
 

diff --git a/src/css/custom.css b/src/css/custom.css
@@ -299,3 +299,7 @@ a[docid="docs"] > svg {
 		background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg' fill='%23fff'%3E%3Cpath d='M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z'/%3E%3C/svg%3E");
 	}
 }
+
+.center-image {
+	text-align: center;
+}