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

# GitLab

> Authenticate users via GitLab OAuth 2.0, including self-hosted instances. Register a public application and configure `read_user` and `email` scopes.

## Get credentials

<Steps>
  <Step>
    ### Create an application

    For **gitlab.com**: Go to [gitlab.com/-/profile/applications](https://gitlab.com/-/profile/applications).

    For a **self-hosted instance**: Go to your instance URL, then **User Settings > Applications**.

    * **Name**: your app name
    * **Redirect URI**: `https://auth.example.com/auth/oauth/gitlab/callback`
    * **Scopes**: check `read_user` and `email`
  </Step>

  <Step>
    ### Copy credentials

    After saving, copy the **Application ID** and **Secret**.
  </Step>
</Steps>

## Configuration

<Tabs>
  <Tab title="gitlab.com">
    ```typescript title="lib/kavach.ts" theme={"system"}
    import { createKavach } from 'kavachos';
    import { oauth } from 'kavachos/auth';

    const kavach = await createKavach({
      database: { provider: 'postgres', url: process.env.DATABASE_URL! },
      secret: process.env.KAVACH_SECRET!,
      baseUrl: 'https://auth.example.com',
      plugins: [
        oauth({
          providers: [
            {
              id: 'gitlab', // [!code highlight]
              clientId: process.env.GITLAB_CLIENT_ID!, // [!code highlight]
              clientSecret: process.env.GITLAB_CLIENT_SECRET!, // [!code highlight]
            },
          ],
        }),
      ],
    });
    ```
  </Tab>

  <Tab title="Self-hosted">
    ```typescript title="lib/kavach.ts" theme={"system"}
    oauth({
      providers: [
        {
          id: 'gitlab',
          clientId: process.env.GITLAB_CLIENT_ID!,
          clientSecret: process.env.GITLAB_CLIENT_SECRET!,
          // Point to your GitLab instance
          authorizationUrl: 'https://gitlab.yourcompany.com/oauth/authorize', // [!code highlight]
          tokenUrl: 'https://gitlab.yourcompany.com/oauth/token', // [!code highlight]
          userInfoUrl: 'https://gitlab.yourcompany.com/api/v4/user', // [!code highlight]
        },
      ],
    })
    ```
  </Tab>
</Tabs>

```bash theme={"system"}
GITLAB_CLIENT_ID=...
GITLAB_CLIENT_SECRET=...
```

## Scopes

Default scopes: `read_user email`

| Scope             | What it unlocks               |
| ----------------- | ----------------------------- |
| `read_user`       | Read the user's profile       |
| `email`           | Read the user's primary email |
| `read_api`        | Read access to the API        |
| `read_repository` | Read repository data          |

## User data returned

| Field   | Source             | Notes                         |
| ------- | ------------------ | ----------------------------- |
| `id`    | `id` field         | Stable numeric GitLab user ID |
| `email` | `email` field      | Primary email                 |
| `name`  | `name` field       | Display name                  |
| `image` | `avatar_url` field | Profile picture URL           |

<Info>
  For self-hosted GitLab instances, make sure your KavachOS server can reach the GitLab API. If you are behind a VPN or firewall, the token exchange and user info calls will fail if the instance is not reachable from your server.
</Info>