From 93a93df83cc22583ff4d466d46c53fe83e8a42ae Mon Sep 17 00:00:00 2001 From: Artemiy Date: Mon, 29 Jun 2026 16:39:35 +0100 Subject: [PATCH] Document GitLab service-account identity and per-user connections Lead the GitLab connect flow with a dedicated service account so write-backs (MR comments, fix MRs) are attributed to "Gecko" rather than the individual who provided the token, mirroring the GitHub gecko[bot] identity. Add a draft connect/personal-connections.mdx specifying the target per-user linking model (team service account + opt-in personal connections). Kept out of docs.json navigation until the feature ships. Co-Authored-By: Claude Opus 4.8 --- connect/gitlab.mdx | 37 ++++++++-- connect/personal-connections.mdx | 123 +++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 5 deletions(-) create mode 100644 connect/personal-connections.mdx diff --git a/connect/gitlab.mdx b/connect/gitlab.mdx index 522504f0e..9579b99cd 100644 --- a/connect/gitlab.mdx +++ b/connect/gitlab.mdx @@ -20,9 +20,32 @@ merge-request comments, and open fix merge requests. ## Connect - - In GitLab, create a personal, group, or service-account token on an account - that can access the repositories you want Gecko to scan: + + Create a **service account** in GitLab for Gecko instead of using a personal + account. Gecko writes back to GitLab — it posts merge-request comments and + opens fix merge requests — and **those actions are authored by whoever owns + the token you provide.** A service account makes that activity show up as + "Gecko" in your commit history, notifications, and audit log instead of under + an individual's name, and it keeps the connection working when that person + leaves or rotates their own credentials. + + On GitLab Premium and Ultimate, use the built-in + [Service accounts](https://docs.gitlab.com/user/profile/service_accounts/) + feature. On Free, create a standard account to act as the bot (for example, + `gecko-bot`). Either way, add it to the groups or projects you want Gecko to + scan with the **Developer** role or higher. + + + This mirrors how Gecko connects to GitHub, where the GitHub App acts under + its own `gecko[bot]` identity automatically. GitLab has no equivalent app + identity, so a service account is how you get the same clean separation + between Gecko's actions and your team's. + + + + + On the service account, create an access token that can reach the repositories + you want Gecko to scan: - **Name**: `Gecko Security` - **Expiration**: 1 year, or your team's standard rotation window @@ -145,9 +168,13 @@ with a valid token. GitLab.com needs none of this. - Clone repositories over HTTPS for scan workers - Post merge-request comments and open fix merge requests +Comments and fix MRs are authored by the GitLab account that owns the token, so +connecting with a [service account](#connect) keeps Gecko's activity clearly +attributed to "Gecko" rather than to an individual. + - Use a dedicated service account scoped only to the groups and projects Gecko - should scan, and rotate the token on a schedule. + Scope the service account to only the groups and projects Gecko should scan, + and rotate its token on a schedule. ## Export findings back to GitLab diff --git a/connect/personal-connections.mdx b/connect/personal-connections.mdx new file mode 100644 index 000000000..3a384b34a --- /dev/null +++ b/connect/personal-connections.mdx @@ -0,0 +1,123 @@ +--- +title: "Personal connections" +icon: "user-check" +description: "Link your own GitLab account so the actions you trigger are attributed to you, not the shared service account." +--- + +{/* DRAFT: documents target behavior for per-user GitLab identity linking. Not yet + implemented. Keep out of docs.json navigation until the feature ships. */} + +Gecko writes back to GitLab in two situations: it acts on its own (posting scan +findings as merge-request comments, opening fix MRs) and it acts on your behalf +when you trigger something (asking for a fix, running a `/gecko` command on an +MR). **Personal connections** let the second kind of action be authored under +**your** GitLab identity instead of the shared service account. + +## Two layers of identity + +Gecko separates the team's automated identity from each member's personal one: + +| Layer | Who it is | Used for | +| --- | --- | --- | +| **Service account** | The team's [GitLab service account](/connect/gitlab#connect) | Gecko's autonomous actions, and a fallback for any member who hasn't linked | +| **Personal connection** | Your own GitLab account | Actions you explicitly trigger, attributed to you | + +The service account is configured once for the whole team and is required. +Personal connections are optional and configured per member. + + + If no one links a personal account, Gecko behaves exactly as before: every + write is authored by the service account. Personal connections only change + attribution for the member who opts in. + + +## What gets attributed to whom + +| Action | Without a personal connection | With a personal connection | +| --- | --- | --- | +| Scan findings posted as MR comments | Service account | Service account (always — these aren't triggered by a person) | +| Fix MR opened automatically | Service account | Service account | +| Fix MR you requested from the dashboard | Service account | **You** | +| `/gecko` command you run on an MR | Service account | **You** | +| Commit pushed by a command you ran | Service account | **You** | + +The rule: **autonomous** actions stay on the service account; **member-initiated** +actions follow that member's personal connection when one exists, and fall back +to the service account when it doesn't. + +## Link your GitLab account + + + + Go to **Settings** > **Personal Connections** and click **Connect** on + GitLab. This is per-user: linking your account doesn't affect anyone else on + the team. + + + + + + Gecko redirects you to GitLab to authorize the connection over OAuth. + Approve the requested scopes and you'll be redirected back. + + + Create a personal access token on your own account with the `api` scope and + paste it in, along with the same instance URL your team uses. Self-managed + and Dedicated instances must already be reachable by Gecko — see + [Network & IP allowlist](/connect/network-allowlist). + + + + + + Gecko validates the connection with `GET /api/v4/user` and shows the GitLab + username it will act as for you. From now on, actions you trigger are authored + under that account. + + + + + Your personal connection only works on repositories **your** GitLab account + can already access with at least the **Developer** role. If you trigger an + action on a project you can't write to, it falls back to the service account + (or fails if the service account also lacks access). + + +## Requirements + +- A team-level [service account connection](/connect/gitlab) must already be set + up. Personal connections layer on top of it; they don't replace it. +- Each personal connection needs the `api` scope, the same as the service + account, so it can post comments and push commits. +- On self-managed and GitLab Dedicated, every member's traffic still arrives from + [Gecko's IP addresses](/connect/network-allowlist) — there's nothing extra to + allowlist per user. + +## Manage and revoke + +- **See who's linked**: team owners can view which members have a personal + connection in **Settings** > **GitLab**. +- **Unlink yourself**: remove your connection from **Settings** > **Personal + Connections** at any time. Your future actions revert to the service account. +- **Rotation**: if you used a token (self-managed), rotate it on your team's + normal schedule. An expired personal token falls back to the service account + until you re-link. + +## Troubleshooting + + + + Either you haven't linked a personal connection, or the action was an + autonomous one (scan findings, auto-opened fix MRs) that always uses the + service account. Only actions you explicitly trigger follow your personal + connection. + + + Your GitLab account needs at least the Developer role on that project. + Confirm your own access in GitLab; Gecko can't grant you more than you have. + + + Gecko falls back to the service account for your actions until you re-link + with a fresh token. Re-connect in **Settings** > **Personal Connections**. + +