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

# GitLab

> Configure a GitLab OAuth application in the runtime environment and authorize one account.

Towbar supports one GitLab OAuth authorization per workspace. OAuth application identity, client secret, webhook secret, base URL, and private-network policy live only in the API runtime environment. PostgreSQL stores the encrypted OAuth grant and account metadata needed to refresh it.

## Configure OAuth

Create an OAuth application in GitLab with the `api` and `read_repository` scopes. Set its callback to the exact API callback URL, then configure:

```dotenv theme={"system"}
TOWBAR_GITLAB_ENABLED=true
TOWBAR_GITLAB_BASE_URL=https://gitlab.com
TOWBAR_GITLAB_ALLOW_PRIVATE_NETWORK=false
TOWBAR_GITLAB_OAUTH_CLIENT_ID=<application-id>
TOWBAR_GITLAB_OAUTH_CLIENT_SECRET=<application-secret>
TOWBAR_GITLAB_OAUTH_REDIRECT_URI=https://api.towbar.example/v1/core/gitlab/oauth/callback
TOWBAR_GITLAB_WEBHOOK_SECRET=<shared-webhook-secret>
```

Private-network access must be enabled deliberately for an internal self-managed GitLab instance. Restart the API after changing these values.

## Authorize and connect repositories

Open **Manage → Integrations → GitLab** and choose **Connect GitLab**. Towbar uses Authorization Code with PKCE, verifies the callback state for the signed-in Admin, and stores only encrypted access and refresh tokens. Reauthorizing replaces the single grant. Disconnecting deletes the encrypted grant and stops new GitLab repository work.

When adding a Repository, select GitLab, then the project and branch. Towbar reads immutable commit archives, processes push and merge-request webhooks idempotently, and reports deployment results without making provider feedback part of deployment success.