> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rad.security/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Connect GitLab to RAD Security for application security scanning and vulnerability management.

# GitLab Integration Setup

This guide walks you through connecting GitLab to RAD Security, enabling application security scanning and vulnerability findings across your GitLab instance or groups.

## Prerequisites

Before you begin, ensure you have:

<Check>Access to the web interface of your GitLab instance</Check>
<Check>GitLab instance administrator access or an account with the **Owner** role (recommended)</Check>
<Check>Access to RAD Security workspace with integration permissions</Check>

***

## Required Token Scopes

The GitLab integration requires the following API token scope:

| Operation                              | Required Scope |
| -------------------------------------- | -------------- |
| Query Applications                     | `read_api`     |
| Query Application Findings             | `read_api`     |
| Query findings across all applications | `read_api`     |
| Get Application Finding Details        | `read_api`     |

<Note>
  Only the `read_api` scope is required. This provides read-only access to the API, including all groups and projects, the container registry, and the package registry.
</Note>

***

## Generating an API Access Token

GitLab supports three methods for creating API access tokens. **The recommended method is using a service account**, but service accounts are not available on GitLab Free instances. If you're using GitLab Free, use a group access token instead.

<Tabs>
  <Tab title="Service Account (Recommended)">
    Service accounts provide the most secure option for integrations as they are not tied to individual users.

    ### Instance-Wide Service Account

    <Steps>
      <Step title="Access Admin Settings">
        Log into your GitLab instance and select **Admin** from the left sidebar.
      </Step>

      <Step title="Navigate to Service Accounts">
        Select **Settings > Service accounts**.
      </Step>

      <Step title="Create Service Account">
        Click **Add service account** and fill out the required fields to create a new instance-wide service account.
      </Step>

      <Step title="Manage Access Tokens">
        Click the vertical ellipsis (⋮) to the right of the new service account and select **Manage access tokens**.
      </Step>

      <Step title="Create the Token">
        Proceed to [Creating the Access Token](#creating-the-access-token) below.
      </Step>
    </Steps>

    ### Group Service Account

    <Steps>
      <Step title="Navigate to Your Group">
        Go to the group where you want to create the service account.
      </Step>

      <Step title="Access Service Account Settings">
        Select **Settings > Service accounts** from the left sidebar.
      </Step>

      <Step title="Create Service Account">
        Click **Add service account** and fill out the required fields.
      </Step>

      <Step title="Manage Access Tokens">
        Click the vertical ellipsis (⋮) to the right of the new service account and select **Manage access tokens**.
      </Step>

      <Step title="Create the Token">
        Proceed to [Creating the Access Token](#creating-the-access-token) below.
      </Step>
    </Steps>

    For more information, see the [GitLab service accounts documentation](https://docs.gitlab.com/user/profile/service_accounts/).
  </Tab>

  <Tab title="Group Access Token">
    Group access tokens are ideal for GitLab Free users who need to scope access to a specific group.

    <Steps>
      <Step title="Navigate to Your Group">
        Go to the group where you want to create the access token.
      </Step>

      <Step title="Access Token Settings">
        Select **Settings > Access tokens** from the left sidebar.
      </Step>

      <Step title="Add New Token">
        Click **Add new token** in the *Active group access tokens* section.
      </Step>

      <Step title="Create the Token">
        Proceed to [Creating the Access Token](#creating-the-access-token) below.
      </Step>
    </Steps>

    For more information, see the [GitLab group access tokens documentation](https://docs.gitlab.com/user/group/settings/group_access_tokens/).
  </Tab>

  <Tab title="Personal Access Token">
    Personal access tokens are tied to your user account and inherit your permissions.

    <Warning>
      Personal access tokens are tied to individual users. If the user is removed or leaves the organization, the integration will stop working. Consider using service accounts or group access tokens for production integrations.
    </Warning>

    <Steps>
      <Step title="Access Your Profile">
        Click your avatar in the left sidebar and select **Edit profile**.
      </Step>

      <Step title="Navigate to Access Tokens">
        Select **Access tokens** from the left sidebar.
      </Step>

      <Step title="Add New Token">
        Click **Add new token**.
      </Step>

      <Step title="Create the Token">
        Proceed to [Creating the Access Token](#creating-the-access-token) below.
      </Step>
    </Steps>

    For more information, see the [GitLab personal access tokens documentation](https://docs.gitlab.com/user/profile/personal_access_tokens/).
  </Tab>
</Tabs>

***

## Creating the Access Token

Once you're on the new API access token creation screen:

<Steps>
  <Step title="Configure Token Details">
    Fill out the following fields:

    * **Token name**: A descriptive name (e.g., "RAD Security Integration")
    * **Description** (optional): Purpose of the token
    * **Expiration date**: Set according to your security policies
  </Step>

  <Step title="Select Scopes">
    Under the *Select scopes* section, check the box next to:

    * `read_api`
  </Step>

  <Step title="Create Token">
    Click **Create token**.
  </Step>

  <Step title="Save Token">
    **Copy the token immediately** — it will not be shown again.

    <Warning>
      Store your token securely. If you lose it, you'll need to generate a new one.
    </Warning>
  </Step>
</Steps>

Also take note of your **GitLab instance URL** (e.g., `https://gitlab.com` or `https://gitlab.yourcompany.com`). You'll need this when configuring the integration.

***

## Configure in RAD Security

Once you have your token, configure the integration in RAD Security:

<Steps>
  <Step title="Navigate to Integrations">
    Go to your RAD Security workspace and navigate to **Integrations**.
  </Step>

  <Step title="Add GitLab Integration">
    Click **Add Integration** and select **GitLab** from the available options.
  </Step>

  <Step title="Enter Configuration">
    Fill in the required fields:

    | Parameter            | Description                             | Example              |
    | -------------------- | --------------------------------------- | -------------------- |
    | **Integration Name** | A descriptive name for this integration | `GitLab Production`  |
    | **Secret**           | The API access token you generated      | `glpat-xxxxxxxxxxxx` |
    | **Base URL**         | The URL of your GitLab instance         | `https://gitlab.com` |
  </Step>

  <Step title="Save and Test">
    Click **Save** to create the integration. RAD Security will validate the connection.
  </Step>
</Steps>

<Note>
  Your token is encrypted and stored securely by RAD Security.
</Note>

***

## Verify Integration

After completing the setup, verify your integration is working:

1. Navigate to **Integrations** in your RAD Security workspace
2. Locate your GitLab integration
3. Check the connection status shows as **Active**
4. Verify applications and findings are being discovered

<Check>
  Your GitLab integration is now configured! RAD Security will begin syncing application security data from your GitLab instance.
</Check>

***

## What Data is Synced

<AccordionGroup>
  <Accordion title="Applications" icon="grid-2">
    * Projects and repositories within your GitLab instance or group
    * Application metadata and configurations
  </Accordion>

  <Accordion title="Security Findings" icon="shield-exclamation">
    * SAST (Static Application Security Testing) findings
    * DAST (Dynamic Application Security Testing) findings
    * Dependency scanning results
    * Container scanning results
    * Secret detection findings
  </Accordion>

  <Accordion title="Finding Details" icon="magnifying-glass">
    * Vulnerability severity and classification
    * Affected files and line numbers
    * Remediation guidance
    * Finding status (detected, confirmed, dismissed)
  </Accordion>
</AccordionGroup>

***

## Use Cases

<CardGroup cols={2}>
  <Card title="Centralized Vulnerability View" icon="eye">
    Aggregate security findings from GitLab alongside other security tools for a unified view.
  </Card>

  <Card title="Security Posture Tracking" icon="chart-line">
    Track application security trends over time across all GitLab projects.
  </Card>

  <Card title="Compliance Reporting" icon="file-certificate">
    Generate compliance reports that include GitLab security scanning results.
  </Card>

  <Card title="Risk Prioritization" icon="list-ol">
    Correlate GitLab findings with other data sources to prioritize remediation efforts.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed" icon="triangle-exclamation">
    * Verify your access token is correct and hasn't expired
    * Ensure the token has the `read_api` scope
    * Check that the Base URL is correct and accessible
    * For self-hosted GitLab, verify network connectivity from RAD Security
  </Accordion>

  <Accordion title="No Applications Found" icon="folder-xmark">
    * Confirm the token has access to the groups/projects you expect
    * For group tokens, verify the token is scoped to the correct group
    * Check that the service account or user has appropriate role assignments
  </Accordion>

  <Accordion title="Missing Security Findings" icon="shield-xmark">
    * Verify that GitLab security scanning is enabled for your projects
    * Check that CI/CD pipelines with security jobs have run successfully
    * Ensure the token user/service account has access to security reports
  </Accordion>

  <Accordion title="Token Expired" icon="clock">
    * Generate a new token following the steps above
    * Update the integration in RAD Security with the new token
    * Consider setting longer expiration dates or using calendar reminders for rotation
  </Accordion>
</AccordionGroup>

***

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Service Accounts" icon="user-gear">
    Create dedicated service accounts rather than using personal tokens to avoid disruption when team members leave.
  </Card>

  <Card title="Minimal Scope" icon="minimize">
    Only grant the `read_api` scope required for the integration. Avoid granting write permissions.
  </Card>

  <Card title="Rotate Tokens Regularly" icon="rotate">
    Set appropriate expiration dates and rotate tokens according to your security policies.
  </Card>

  <Card title="Audit Token Usage" icon="clipboard-list">
    Regularly review service account and token activity in GitLab's audit logs.
  </Card>
</CardGroup>

***

## Token Rotation

To rotate your GitLab access token:

<Steps>
  <Step title="Generate New Token">
    Create a new token following the steps above with the same scope.
  </Step>

  <Step title="Update RAD Security">
    Edit your GitLab integration in RAD Security and update the **Secret** field.
  </Step>

  <Step title="Verify Connection">
    Confirm the integration status remains **Active** after the update.
  </Step>

  <Step title="Revoke Old Token">
    Delete the old token from GitLab to complete the rotation.
  </Step>
</Steps>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="AppSec Integrations Overview" icon="shield-check" href="/rad-security/integrations/appsec/overview">
    Learn about other application security integrations
  </Card>

  <Card title="Evidence Room" icon="vault" href="/rad-security/platform/evidence-room">
    View and analyze collected security data
  </Card>
</CardGroup>