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

• 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

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

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 for how engagements work.

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

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

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

• 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.