# GitLab (/docs/integrations/gitlab) Trace reads code from GitLab.com through a **service account** it creates in your top-level group. You approve Trace once in GitLab, pick the repositories pentests can read, and Trace adds the service account to them with read-only access. After that, Trace keeps only the service account's token and gives up your approval. Before you start [#before-you-start] * You need the **Owner** role on the top-level GitLab.com group you want to connect. Trace connects one top-level group at a time; its subgroups come with it. * You need to be an admin of your Trace organization. How it works [#how-it-works] 1. **Approve Trace in GitLab.** On the GitLab page in Trace, click **Connect group**. GitLab asks you to approve the Trace application. The approval carries the `api` scope because creating a service account needs it. Trace uses it only for the next few steps and revokes it when the connection is set up. 2. **Pick the group and repositories.** Back in Trace, choose the group (if you own more than one) and either: * **All repositories**: the service account joins the group as a Reporter, which covers every project in it and its subgroups, including projects added later. * **Selected projects**: the service account joins each project you tick as a Reporter, up to 500 projects. 3. **Trace sets up access.** Trace creates a service account named `trace-` followed by a few random characters in your group, adds it where you chose, and mints a token for it with only `read_api` and `read_repository`. Trace checks that the token belongs to a bot account and has no other scope before keeping it. 4. **Repositories sync.** The repositories the service account can read appear on the GitLab page and in your dashboard. To add a project later, invite the Trace service account to it as a Reporter in GitLab, then use **Re-sync repositories** on the group. Using GitLab repositories [#using-gitlab-repositories] Connected repositories are available as sources for penetration tests, the same as GitHub and Bitbucket repositories. Before each session, Trace checks the token with GitLab, so a revoked or expired token stops the session with a reason instead of a failed clone. See the [Pentest overview](/docs/pentest/overview) for how engagements work. What Trace can access [#what-trace-can-access] * **The service account's token**: `read_api` and `read_repository`, on the projects the account is a member of, with the Reporter role. It can't push code, change settings, or see projects it isn't a member of. * **Your approval**: held only while Trace sets up the connection, then revoked. If GitLab doesn't confirm the revoke, Trace tells you, and the approval expires on its own within 2 hours. You can also revoke it yourself in GitLab under **Edit profile → Applications → Authorized applications**. Trace stores the token encrypted with AWS KMS and never stores your own GitLab credentials. Token expiry [#token-expiry] The service account's token lasts about a year (or 90 days if your group limits token lifetimes). The GitLab page warns you 30 days before it expires. Trace doesn't rotate the token yet: before it expires, disconnect the group and connect it again. Disconnecting [#disconnecting] On the GitLab page, click **Disconnect** on the group. Trace revokes the token, deletes its copy, and pentests can't read the group's repositories anymore. The service account stays in your GitLab group; remove it from the group's members if you don't need it. If a group shows **Revoked** or **Expired**, GitLab no longer accepts the token. Disconnect the group, then connect it again. Current limitations [#current-limitations] * **GitLab.com only.** GitLab Self-Managed and GitLab Dedicated aren't supported yet. * **Pentests only.** GitLab repositories aren't scanned yet, and Trace doesn't post merge request checks. * **No automatic token rotation.** Reconnect the group before the token expires.