Merge pull request #96 from DataRecce/feature/drc-3041-gitlab-service-account

docs: add GitLab service account guidance for bot identity

Author: gcko

docs/setup-guides/connect-git.md

@@ -50,22 +50,44 @@ Then select the repository containing your dbt project. This becomes your Cloud
 
 ## Connect GitLab
 
-GitLab uses Personal Access Tokens (PAT) instead of OAuth.
+GitLab uses Personal Access Tokens (PAT) instead of OAuth. Unlike GitHub, where the Recce GitHub App posts comments as itself, GitLab API comments appear as the token owner. We recommend creating a dedicated service account so that PR comments appear as a bot rather than your personal account.
 
-### 1. Create a Personal Access Token
+!!! tip "Use a shared team email"
+    When creating the service account, use a shared team email (e.g., `data@yourcompany.com`) so it isn't tied to any individual.
 
-In GitLab: User Settings → Access Tokens → Add new token.
+### 1. Create a Dedicated Service Account (Recommended)
 
-**Required scopes:**
+If you use your personal token, your teammates see PR comments from *you* rather than from Recce Cloud. To avoid this, create a **GitLab service account** for Recce Cloud:
 
-- `api` - Full access (required for PR comments)
-- `read_api` - Read-only alternative (limited functionality)
+1. In GitLab, navigate to your **group → Settings → Service Accounts**
+2. Click **Add service account**
+3. Set the name to **Recce Cloud** (username auto-generates)
+4. Click **Create service account**
+5. (Optional) Edit the account to customize the username and upload a Recce avatar
 
-**Expected result:** Token string displayed (copy immediately).
+**Expected result:** Service account appears in the group's member list with a "service account" badge.
 
-### 2. Add Token to Cloud
+Add the service account as a **Developer** member to the projects you want Recce Cloud to access.
 
-Navigate to Settings → Git Provider. Select GitLab, paste token.
+!!! info "Availability"
+    GitLab service accounts are available on GitLab.com Free (up to 100 per group), Premium, and Ultimate. For Self-Managed Free instances where service accounts are unavailable, create a dedicated GitLab user (e.g., `recce-cloud-bot`) instead.
+
+If you don't have group admin access, you can skip this step and use a personal access token directly. Note that PR comments will appear as your user account.
+
+### 2. Create a Personal Access Token
+
+Generate a PAT for the service account (or your personal account if you skipped Step 1):
+
+1. For a **service account**: navigate to your **group → Settings → Service Accounts**, select the account, and click **Create token**
+2. For a **personal token**: navigate to **User Settings → Access Tokens → Add new token**
+3. Set a descriptive name (e.g., "Recce Cloud integration")
+4. Select the **`api`** scope (required for posting PR comments). The `read_api` scope is not sufficient.
+5. Set an expiration date and click **Create**
+6. Copy the token immediately (it cannot be viewed again)
+
+### 3. Add Token to Cloud
+
+Navigate to **Settings → Git Provider** in Recce Cloud. Select GitLab and paste the token.
 
 ## Verify Success
 
@@ -84,6 +106,7 @@ In Cloud, navigate to your repository. You should see:
 | Repository not found | Ensure proper permissions are granted (GitLab: token access, GitHub: app authorized) |
 | Invalid token (GitLab) | Generate new token with `api` scope |
 | Cannot post PR comments (GitLab) | Regenerate token with `api` scope instead of `read_api` |
+| PR comments show as personal user (GitLab) | Create a [service account](#1-create-a-dedicated-service-account-recommended) and use its token instead of your personal token |
 
 ## Next Steps