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

# GitLab Integration

> Connect your GitLab projects to CodeThreat

Connect GitLab to scan your projects for security vulnerabilities. Works with both GitLab.com and self-hosted GitLab instances.

## Connection Methods

<Tabs>
  <Tab title="OAuth (Recommended)">
    **Best for**: GitLab.com users

    * One-click authorization
    * Automatic token management
    * Works with GitLab Cloud

    **Requirements**: GitLab.com account
  </Tab>

  <Tab title="Personal Access Token">
    **Best for**: Self-hosted GitLab, automation

    * Works with self-hosted GitLab
    * Fine-grained permissions
    * No browser redirect needed

    **Requirements**: Ability to create tokens
  </Tab>
</Tabs>

***

## OAuth Setup (GitLab.com)

<Steps>
  <Step title="Navigate to Integrations">
    **Settings** → **Integrations** → **GitLab** → **Connect with OAuth**
  </Step>

  <Step title="Authorize CodeThreat">
    You'll be redirected to GitLab. Click **Authorize** to grant access
  </Step>

  <Step title="Import Projects">
    Select projects to scan and click **Import**
  </Step>
</Steps>

### OAuth Permissions

CodeThreat requests:

* `read_user`: Read user profile
* `read_repository`: Read repository content
* `read_api`: Access GitLab API (read-only)
* `api`: Webhook management

***

## Personal Access Token Setup

<Steps>
  <Step title="Open GitLab Settings">
    GitLab → **Preferences** → **Access Tokens**
  </Step>

  <Step title="Create New Token">
    Fill in token details:

    **Token name**: `CodeThreat Security Scanner`
    **Expiration date**: Choose expiration (optional)
    **Scopes**: Select:

    * ✅ `read_api`: Read-only API access
    * ✅ `read_repository`: Read repository content
    * ✅ `write_repository`: Webhook management
  </Step>

  <Step title="Generate and Copy">
    Click **Create personal access token** and copy immediately
  </Step>

  <Step title="Add Token to CodeThreat">
    **Settings** → **Integrations** → **GitLab** → Select **Personal Access Token**

    Paste token and for self-hosted GitLab, enter base URL (e.g., `https://gitlab.company.com`)
  </Step>

  <Step title="Import Projects">
    Select projects to scan and import them
  </Step>
</Steps>

***

## Self-Hosted GitLab

CodeThreat supports self-hosted GitLab instances (GitLab CE and EE).

### Requirements

* GitLab 13.0 or later
* Network connectivity from CodeThreat to your GitLab instance
* Valid SSL certificate

When adding a Personal Access Token, enter your GitLab base URL:

```
https://gitlab.company.com
```

Ensure no trailing slash, includes protocol (https\://), and is accessible from CodeThreat.

***

## Webhook Configuration

CodeThreat automatically creates webhooks for automated scanning.

### Webhook Events

* **Push events**: Trigger scans on commits
* **Merge request events**: Scan MRs automatically
* **Tag events**: Scan tagged releases

### Verify Webhooks

1. In GitLab: Project → **Settings** → **Webhooks**
2. Find webhook pointing to: `https://app.codethreat.com/webhooks/gitlab`
3. Click **Test** → **Push events** to verify delivery

***

## Merge Request Integration

Get security feedback directly in GitLab merge requests.

### Enable MR Scanning

In CodeThreat repository settings:

* Auto-scan on MR: ✓ Enabled
* AI MR reviews: ✓ Enabled
* Post MR comments: ✓ Enabled

### MR Comments

CodeThreat posts:

* Summary comment with overall security status
* Inline comments on specific vulnerabilities
* AI-generated security suggestions

***

## Best Practices

* Use OAuth for GitLab.com
* Rotate PATs periodically (every 90 days)
* Enable merge request scanning
* Monitor webhook delivery

***

## Troubleshooting

**Connection failed**:

* Verify token has correct scopes
* Check base URL for self-hosted GitLab
* Ensure GitLab instance is reachable

**Projects not showing**:

* Verify you have at least Developer access
* Check project visibility
* Re-authorize the connection

**Webhook not triggering**:

* Check webhook delivery in GitLab project settings
* Verify webhook is active
* Ensure firewall allows outbound HTTPS

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Run Your First Scan" icon="play" href="/scanning/running-scans">
    Start scanning your GitLab projects
  </Card>

  <Card title="PR Scanning" icon="code-pull-request" href="/scanning/pr-scanning">
    Get security feedback on merge requests
  </Card>
</CardGroup>