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

# GitLab

> Set up the Zenable GitLab Reviewer for GitLab.com

<Note>
  **Using Self-managed GitLab?** See our [Self-managed GitLab guide](/integrations/vcs-reviewers/gitlab-on-prem) for self-hosted GitLab installations (version 17+).
</Note>

## Installation

### Prerequisites

To use Zenable with GitLab, you'll need to create a Personal Access Token (PAT) or Group Access Token with the appropriate permissions.

#### Option 1: Personal Access Token (Recommended for individual users)

<Note>
  **Best Practice**: Create a dedicated service account for Zenable rather than using your personal account. The reviews will be easier to attribute to the bot
  user and it provides better security, easier management, and clearer audit trails.
</Note>

##### Creating a Service Account (Recommended)

<Steps>
  <Step title="Create Dedicated GitLab User">
    Create a new GitLab user for Zenable:

    * **Username**: `zenable-bot` or `zenable-reviewer`
    * **Email**: Use a dedicated email (e.g., `zenable-bot@yourcompany.com`)
    * **Profile picture**: Consider using zenable's logo ([here](https://www.zenable.app/zenable_dark.svg) or [here](https://www.zenable.app/zenable_light.svg)) as profile picture so its easier to understand that the reviews are coming from Zenable.
    * **Access level**: Ensure this user has at least **Developer** access to the groups or projects where you want Zenable to review code
  </Step>

  <Step title="Generate Personal Access Token">
    Log in as the service account and navigate to access tokens:

    1. Click on your **avatar** in the top-right corner
    2. Select **Edit Profile**
    3. Click **Access Tokens** in the left sidebar
    4. Click **[Add new token](https://gitlab.com/-/user_settings/personal_access_tokens)**
  </Step>

  <Step title="Configure Token Settings">
    **Token name**: `zenable-integration` (or any descriptive name)

    **Expiration date**: Set according to your security policy (recommended: Long enough so you don't have to rotate it often). Remember to update/rotate this token before it expires.

    **Select scopes**: Enable the following permissions:

    * ✅ `api` - Full API access (required for reading MRs, posting comments, and listing projects to manage webhooks)
    * ✅ `read_user` - Read user information
  </Step>

  <Step title="Generate and Save Token">
    1. Click **Create personal access token**
    2. **Critical**: Copy the token immediately - it will only be displayed once
  </Step>
</Steps>

<Warning>
  Keep your Personal Access Token secure. Anyone with this token can access your GitLab account with the permissions you've granted. Never commit tokens to
  version control or share them in plain text.
</Warning>

#### Option 2: Group Access Token (GitLab Premium/Ultimate)

<Note>
  If you have GitLab Premium or Ultimate, you can use Group Access Tokens which automatically create a dedicated bot user.
</Note>

<Steps>
  <Step title="Navigate to Group Settings">
    1. Go to your GitLab group
    2. Select **Settings** from the left sidebar
    3. Select **Access Tokens** within the Settings section
  </Step>

  <Step title="Create Group Access Token">
    1. Click **Create a Group Access Token**
    2. Enter a descriptive name (e.g., `zenable-reviewer`)
    3. Set an expiration date
    4. Select the **`api`** scope
    5. Ensure **Developer** access is provided
    6. Click **Create group access token**
  </Step>

  <Step title="Save the Token">
    GitLab will automatically create a bot user (e.g., `group_123_bot_456...`) and display the token. Copy and store it securely immediately.
  </Step>
</Steps>

### Step 2: Configure Zenable

<Steps>
  <Step title="Navigate to Integrations">
    Go to [zenable.app/integrations](https://www.zenable.app/integrations?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=setup) and select the **GitLab** tab
  </Step>

  <Step title="Add GitLab Token">
    1. Click **Connect GitLab**
    2. Paste your Personal Access Token or Group Access Token in the **Access Token** field
    3. Click **Add Server**

    Zenable will automatically discover all accessible projects from your GitLab account.
  </Step>

  <Step title="Enable Projects for Review">
    After the installation is registered, your projects appear inline on the integrations page:

    1. Toggle **MR Reviews** on for each project you want Zenable to review
    2. Click **Save Changes** in the sticky bar at the bottom to apply your configuration
    3. If you have multiple GitLab installations, each appears as an expandable accordion section identified by its GitLab URL

    You can also use **Resync** to refresh the project list from GitLab, or **Delete** to remove an installation entirely.

    <Note>
      Only enabled projects will receive automated merge request reviews from Zenable.
    </Note>
  </Step>
</Steps>

## How It Works

The Zenable GitLab Reviewer automatically reviews merge requests in your repository, providing valuable feedback on code quality, security, and best practices.
It leverages any Policy as Code or context you've configured in your tenant on [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=tenant-config), ensuring consistent enforcement across
your entire development workflow.

Once configured, it will:

1. **Monitor MR events** - Responds to merge request opens, updates, and review requests
2. **Analyze code changes** - Reviews modified files against your custom policies and organizational context
3. **Provide inline feedback** - Adds comments directly on the code with specific suggestions
4. **Maintain standards** - Ensures consistent code quality across your team

### Re-requesting a Review

You can trigger a new review at any time by commenting `/zenable` on your merge request. This is useful when:

* You've made changes and want fresh feedback
* You want to re-run the review after updating your policies
* The initial review was skipped due to rate limits or other conditions

Simply add a comment with `/zenable` anywhere in the MR, and Zenable will perform a complete review of the current state of the merge request.

### Unified Context Across All Integration Points

All Zenable integration points (GitLab, GitHub, MCP, API) share the same context and policies from your Zenable tenant. This provides continuous enforcement
throughout the entire SDLC - consistently reinforced and fully automated. Whether developers are using AI tools locally, committing code, or creating merge
requests, the same standards and policies apply everywhere.

## Security Best Practices

<AccordionGroup>
  <Accordion title="Use Service Accounts">
    **Always use a dedicated service account** instead of personal accounts:

    * Create a separate GitLab user specifically for Zenable (e.g., `zenable-bot`)
    * Use a dedicated email address for easy identification
    * Provides clear audit trails and easier access management
    * Makes it obvious in MR comments that it's an automated review
  </Accordion>

  <Accordion title="Token Rotation">
    Regularly rotate your Personal Access Tokens:

    * Set expiration dates on all tokens
    * Create new tokens before old ones expire
    * Update the token in Zenable settings promptly
    * Revoke tokens that are no longer needed
    * Document token renewal dates in your team calendar
  </Accordion>

  <Accordion title="Minimum Permissions">
    Only grant the minimum required scopes:

    * **Required**: `api` scope (provides all necessary access)
    * **Required**: `read_user` scope (for user information)
    * Ensure the service account has **Developer** access level
  </Accordion>
</AccordionGroup>

## Next Steps

After installation, you can:

* [Configure the reviewer](/integrations/vcs-reviewers/configuration) to match your team's standards
* Set up [pre-commit hooks](/integrations/pre-commit/getting-started) for developer-side enforcement
* Install the [MCP server](/integrations/mcp/getting-started) for real-time IDE feedback
* Define [custom policies](/use-cases/policy-as-code) specific to your organization
* Review our [deployment guide](/deployment-adoption) for team adoption strategies
* Explore [supply chain security](/use-cases/supply-chain-security) to protect your dependencies
* Check our [Roadmap](https://zenable.io/feedback?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=roadmap) to see what's coming next

## Troubleshooting

<AccordionGroup>
  <Accordion title="Reviews not appearing">
    * Verify your PAT has the [correct scopes](#prerequisites)
    * Check that the token hasn't expired — [create a new one](#prerequisites) if needed
    * Ensure the repository is selected in Zenable settings
    * Check GitLab webhook logs for errors
  </Accordion>

  <Accordion title="Permission errors">
    * Confirm the PAT has `api` and `read_user` scopes — see [Prerequisites](#prerequisites) for how to create one
    * Verify the token owner has access to the repository
    * Check if branch protection rules are blocking comments
  </Accordion>

  <Accordion title="Token expired">
    * [Create a new PAT](#prerequisites) following the setup steps
    * Update the token in Zenable settings
  </Accordion>

  <Accordion title="Connection or URL errors">
    * Make sure you are entering the **base URL** of your GitLab instance (e.g. `https://gitlab.com`), not a project or group page URL
  </Accordion>
</AccordionGroup>

For additional support, please submit feedback at [zenable.io/feedback](https://zenable.io/feedback?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=support).