Secu Platform Documentation

GitLab Integration

The GitLab integration connects your repositories to the platform using a Personal Access Token (PAT). It enables repository discovery, code cloning, and security scanning for projects hosted on GitLab.com.

Personal Access Token

A Personal Access Token (PAT) authenticates the platform as your GitLab user. This is the simplest setup and works well for individual accounts where your user already has access to the target projects.

Create a PAT for your account

  1. Open GitLab → User Settings → Access Tokens.
  2. Click Add new token.
  3. Give the token a descriptive name, for example secu-platform.
  4. Choose an expiration date. GitLab enforces a maximum of one year. Shorter lifetimes reduce risk - consider rotating every 90 days.
  5. Select the scopes listed below.
  6. Click Create personal access token.

Copy your token immediately. GitLab will never show it again.

Required scopes

read_api

Grants read access to the API, including all groups and projects, the container registry, and the package registry. Required for repository discovery and metadata sync.

read_repository

Grants read-only access to repositories using git clone over HTTPS. Required for the platform to clone source code before running scanners.

Group service account

For organizations and teams, GitLab recommends using a group service account instead of a personal token. A service account is a bot user that belongs to the group rather than an individual. If a team member leaves, the integration keeps working.

1. Create the service account

  1. Open your top-level group and navigate to Settings → General → Service accounts.
  2. Click Add service account.
  3. Enter a username, for example secu-bot, and an optional display name.
  4. Go to your group's Manage → Members page and click Invite members.
  5. Search for the service account you just created, assign the Reporter role, and click Invite. Reporter is the minimum role that grants read access to repositories.

2. Create a PAT for the service account

  1. In the same Service accounts panel, locate the account you created.
  2. Click the three-dot menu next to it and select Create personal access token.
  3. Give the token a descriptive name, for example secu-platform.
  4. Set the expiration date (maximum one year). Consider rotating every 90 days.
  5. Select the read_api and read_repository scopes.
  6. Click Create personal access token.

Copy your token immediately. GitLab will never show it again.

Required scopes

read_api

Grants read access to the API, including all groups and projects, the container registry, and the package registry. Required for repository discovery and metadata sync.

read_repository

Grants read-only access to repositories using git clone over HTTPS. Required for the platform to clone source code before running scanners.

Add the token to Secu

Once you have a PAT - from either your personal account or a group service account - add it to the platform from the Integrations page.

  1. Open the Integrations page in the Secu dashboard.
  2. Click New integration.
  3. Select GitLab as the provider and Git as the type.
  4. Paste the Personal Access Token into the token field.
  5. Optionally provide a friendly name for the integration, for example GitLab Production.
  6. Click Save. The platform encrypts the token at rest and verifies connectivity with GitLab immediately.

What happens next

After saving, the platform validates the token by calling the GitLab personal_access_tokens/self API. If the token is valid, the integration moves to Active status and the list of accessible repositories is synced in the background.

You can verify or re-verify the integration at any time from the Integrations page. When a token is close to expiration, rotate it by creating a new PAT and updating the integration.