From 676c59d392818f2a6cd08ca36be311556bc7c1d8 Mon Sep 17 00:00:00 2001
From: Piyush Gupta <piyushguptaa2z123@gmail.com>
Date: Tue, 28 Oct 2025 18:11:27 +0530
Subject: [PATCH] docs: clarify GitLab access token requirements and update
 setup instructions

---
 docs/integrations/app-connections/gitlab.mdx | 98 ++++++++++++--------
 1 file changed, 58 insertions(+), 40 deletions(-)

diff --git a/docs/integrations/app-connections/gitlab.mdx b/docs/integrations/app-connections/gitlab.mdx
index 009ca040e..c9af952a7 100644
--- a/docs/integrations/app-connections/gitlab.mdx
+++ b/docs/integrations/app-connections/gitlab.mdx
@@ -204,57 +204,75 @@ Infisical supports two methods for connecting to GitLab: **OAuth** and **Access
 
             <Tabs>
                 <Tab title="Secret Sync">
-                  For Secret Syncs, your token will require the `api` scope and at least a **Maintainer** role or higher.
+                  For Secret Syncs, the required role depends on your sync destination:
+                  - **Project variables**: Requires **Maintainer** role or higher
+                  - **Group variables**: Requires **Owner** role
+
+                  Your token will require the `api` scope.
+
                   ![GitLab Create Group Token](/images/app-connections/gitlab/gitlab-group-access-token-form-secret-sync.png)
 
                   Click **Create group access token** to create the token.
+
+                  <Note>
+                    Use the **Owner** role if you need to sync to group-level variables. The **Maintainer** role is sufficient only for project-level variables.
+                  </Note>
                 </Tab>
                 <Tab title="Secret Scanning">
-                    For Secret Scanning, your token will require the `api` scope and at least a **Maintainer** role or higher.
-                    ![GitLab Create Group Token](/images/app-connections/gitlab/gitlab-group-access-token-form-secret-sync.png)
+                     To set up Secret Scanning, the required permissions depend on the data source level:
+                      - **Project-level data source:** Requires **Maintainer** role or higher
+                      - **Group-level data source:** Requires **Owner** role
 
-                    Click **Create group access token** to create the token.
-                </Tab>
-            </Tabs>
+                    Your token will require the `api` scope.
 
-            <Info>
-              Group Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.
-            </Info>
-          </Step>
-          <Step title="Copy Token">
-            Copy the generated token immediately as it won't be shown again.
-            ![GitLab Group Token Created](/images/app-connections/gitlab/gitlab-group-access-token-created.png)
-            <Warning>
-              Keep your access token secure and do not share it. Anyone with access to this token can access all projects within your GitLab group.
-            </Warning>
-          </Step>
-        </Steps>
-      </Tab>
-    </Tabs>
+                  ![GitLab Create Group Token](/images/app-connections/gitlab/gitlab-group-access-token-form-secret-sync.png)
 
-    ## Setup GitLab Access Token Connection in Infisical
+                  Click **Create group access token** to create the token.
+              </Tab>
+          </Tabs>
 
-    <Steps>
-      <Step title="Navigate to App Connections">
-        Navigate to the **App Connections** page in the desired project.
-        ![App Connections Tab](/images/app-connections/general/add-connection.png)
-      </Step>
-      <Step title="Add Connection">
-        Select the **GitLab Connection** option from the connection options modal.
-        ![Select GitLab Connection](/images/app-connections/gitlab/select-gitlab-connection.png)
-      </Step>
-      <Step title="Configure Access Token">
-        Select the **Access Token** method, paste your GitLab access token in the provided field, and select the appropriate token type.
+          <Info>
+            Group Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.
+          </Info>
+        </Step>
+        <Step title="Copy Token">
+          Copy the generated token immediately as it won't be shown again.
+          ![GitLab Group Token Created](/images/app-connections/gitlab/gitlab-group-access-token-created.png)
+          <Warning>
+            Keep your access token secure and do not share it. Anyone with access to this token can access all projects within your GitLab group.
+          </Warning>
+        </Step>
+      </Steps>
 
-        ![Configure Access Token](/images/app-connections/gitlab/create-gitlab-access-token-connection.png)
+    </Tab>
 
-        Click **Connect** to establish the connection.
-      </Step>
-      <Step title="Connection Created">
-        Your **GitLab Connection** is now available for use.
-        ![GitLab Access Token Connection](/images/app-connections/gitlab/gitlab-access-token-connection.png)
-      </Step>
-    </Steps>
+</Tabs>
+
+## Setup GitLab Access Token Connection in Infisical
+
+  <Steps>
+  <Step title="Navigate to App Connections">
+    Navigate to the **App Connections** page in the desired project.
+    ![App Connections Tab](/images/app-connections/general/add-connection.png)
+  </Step>
+  <Step title="Add Connection">
+    Select the **GitLab Connection** option from the connection options modal.
+    ![Select GitLab Connection](/images/app-connections/gitlab/select-gitlab-connection.png)
+  </Step>
+  <Step title="Configure Access Token">
+    Select the **Access Token** method, paste your GitLab access token in the provided field, and select the appropriate token type.
+
+      ![Configure Access Token](/images/app-connections/gitlab/create-gitlab-access-token-connection.png)
+
+      Click **Connect** to establish the connection.
+
+    </Step>
+
+  <Step title="Connection Created">
+    Your **GitLab Connection** is now available for use.
+    ![GitLab Access Token Connection](/images/app-connections/gitlab/gitlab-access-token-connection.png)
+  </Step>
+</Steps>
 
   </Tab>
 </Tabs>