# GitLab Setup (Self-Hosted)

Configure GitLab integration for your self-hosted PullApprove5 deployment. This works with both GitLab.com and self-managed GitLab instances.

For the access token, webhooks, and general GitLab setup steps, see the [GitLab setup guide](/docs/gitlab/). This page covers the additional configuration needed for self-hosted deployments.

## 1. Create an OAuth Application

PullApprove uses OAuth to authenticate users via their GitLab account. This is only used for user login — repository access and merge request interactions are handled by the API token.

> **Note**: The OAuth scopes (`read_api`, `read_user`) are read-only. PullApprove cannot perform actions on behalf of the logged-in user (e.g. submitting approvals). All write operations use the group API token.

**For self-managed GitLab** (recommended: instance-wide application):

1. Go to **Admin Area → Applications** (`/admin/applications`)
2. Click **New application**
3. Fill in:
   - **Name**: `PullApprove5 Login`
   - **Redirect URI**: `https://your-pullapprove-url.example.com/oauth/gitlab/callback/`
   - **Trusted**: Yes (skips user approval screen)
   - **Confidential**: Yes
   - **Scopes**: `read_api`, `read_user`
4. Click **Save application**
5. Copy the **Application ID** and **Secret**

**For GitLab.com** (group-level application):

1. Go to your group → **Settings → Applications**
2. Click **New application**
3. Fill in the same details as above (Redirect URI, Confidential, Scopes)
4. Copy the **Application ID** and **Secret**

## 2. Environment Variables

Set the following environment variables in your [deployment](/docs/self-hosted/deploy/).

```bash
GITLAB_CLIENT_ID=your-application-id
GITLAB_CLIENT_SECRET=your-application-secret
GITLAB_URL=https://gitlab.example.com
```

Optional settings:

```bash
# Custom name for commit statuses (default: "pullapprove5")
GITLAB_STATUS_NAME=pullapprove5

# Comma-separated list of GitLab usernames whose webhook events should be ignored.
# Useful for reducing unnecessary processing from other bots or CI systems.
GITLAB_WEBHOOK_SENDER_BLOCKLIST=other-bot,ci-service-account
```

## 3. Continue Setup

Once your environment variables are configured, continue with the [main GitLab setup guide](/docs/gitlab/) to create an access token, connect your group, configure webhooks, and enable repos.