> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

# Connect to Self-Hosted GitLab

## Overview

**You can connect to a self-hosted GitLab instance to setup Git remotes.**

You can use your own GitLab server, and you can connect to as many as you like.
This requires adding a custom integration with your server's URL and credentials.

**Self-hosted GitLab supports both OAuth and Personal Access Token (PAT) authentication.**

OAuth requires a GitLab administrator to configure an OAuth application on the server first.
PAT only requires you to create a token and specify the server URL.

**Self-hosted GitLab servers must use HTTPS with trusted certificates.**

HTTP connections are not supported.
If using a self-signed certificate, install it as a trusted root CA on all machines running AI Workbench.

## Key Concepts

**Self-Hosted GitLab**

Private GitLab instance your organization controls and operates.
Provides the same functionality as GitLab.com but on your own infrastructure.

**OAuth Application**

Server-side configuration that enables OAuth authentication for AI Workbench.
Must be created by a GitLab administrator before users can connect with OAuth.

**Custom Integration**

User-configured connection to a platform not in the default integration list.
Requires manually entering server details and credentials.

**Redirect URL**

OAuth callback URL where the authentication flow returns after login.
Must be set to `http://localhost:9999/callback` for AI Workbench.

## Configure OAuth Application (Administrator)

**GitLab administrators must complete this procedure before users can connect with OAuth.**

Users connecting with PAT can skip this section.

**Step One: Create an OAuth2 application on the GitLab server.**

1. Follow the [GitLab OAuth provider instructions](https://docs.gitlab.com/ee/integration/oauth_provider.html) to create the application
2. Name the application (e.g., "AI Workbench")

**Step Two: Configure the OAuth application settings.**

1. Set **Redirect URI** to `http://localhost:9999/callback`
2. Set **Scopes** to `api`
3. Save the application

**Step Three: Record the Client ID and Client Secret.**

1. Copy the **Application ID** (Client ID)
2. Copy the **Secret** (Client Secret)
3. Distribute these values to users who need to connect

**Success: The OAuth application is configured and users can add the integration.**

## Connect Using OAuth

**You must have the Client ID and Client Secret from your GitLab administrator.**

**Step One: Open Settings and start adding a custom integration.**

1. Select **Gear Icon (Top Right) > Settings**
2. Select **Settings > Integrations > Add Integration (Top Right)**
3. Select **Self-Hosted GitLab**

**Step Two: Enter the server details and OAuth credentials.**

1. Enter **Hostname** (e.g., `gitlab.company.com`)
2. Enter **Port** (typically `443` for HTTPS)
3. Enter **Client ID** provided by your administrator
4. Enter **Client Secret** provided by your administrator
5. Select **OAuth** as the authentication method

**Step Three: Complete the authentication flow.**

1. Select **Connect**
2. Click through the prompts to authenticate with your GitLab account
3. Authorize AI Workbench to access your GitLab resources

**Success: The custom GitLab integration appears in your integrations list.**

## Connect Using PAT

**Step One: Create a Personal Access Token on your self-hosted GitLab.**

1. Log into your self-hosted GitLab instance
2. Go to **User Settings > Access Tokens**
3. Create a new token with the `api` scope
4. Copy the generated token

**Step Two: Open Settings and start adding a custom integration.**

1. Select **Gear Icon (Top Right) > Settings**
2. Select **Settings > Integrations > Add Integration (Top Right)**
3. Select **Self-Hosted GitLab**

**Step Three: Enter the server details and PAT.**

1. Enter **Hostname** (e.g., `gitlab.company.com`)
2. Enter **Port** (typically `443` for HTTPS)
3. Select **Personal Access Token** as the authentication method
4. Paste your PAT into the token field
5. Select **Connect**

**Success: The custom GitLab integration appears in your integrations list.**

<Note title="HTTPS and certificate requirements">

Self-hosted GitLab servers must use HTTPS.
HTTP connections are not supported for security reasons.
If your server uses a self-signed certificate, install it as a trusted root CA on every machine running AI Workbench, including all remote locations.

</Note>

<Note title="Distributing integration configuration to teams">

When you create a custom integration, AI Workbench writes a configuration file to disk.
You can distribute this file to team members so they don't have to manually enter server details and OAuth credentials.

**File locations:**

- **macOS/Linux:** `~/.nvwb/integrations/<INTEGRATION_NAME>-integration.json`
- **Windows:** `C:\Users\<username>\AppData\Local\NVIDIA Corporation\AI Workbench\integrations\<INTEGRATION_NAME>-integration.json`

Copy this file to the same location on team members' machines.

</Note>