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

# GitLab Integration

Connect your GitLab repository to HolyDocs for automatic documentation deployments.

## Overview

HolyDocs supports GitLab as an alternative to GitHub for hosting your documentation source code. The integration works with both GitLab.com and self-managed GitLab instances.

## Setting Up

**Navigate to Git Settings**

In your project dashboard, go to **Settings > Git**.
  **Connect GitLab**

Click **Connect GitLab**. You will be redirected to GitLab to authorize the HolyDocs application.
  **Select Project**

Choose the GitLab project containing your documentation. Configure the branch and directory path.
  **Webhook Setup**

A webhook is automatically installed on your GitLab project to listen for push events.

## Self-Managed GitLab

For self-managed GitLab instances:

1. During the OAuth setup, select **Self-Managed** instead of **GitLab.com**
2. Enter your GitLab instance URL (e.g., `https://gitlab.yourcompany.com`)
3. Complete the authorization flow on your instance

Self-managed GitLab instances must be accessible from the internet for webhooks to function. Instances behind a corporate firewall will need webhook forwarding or a public proxy.

## Webhook Events

The GitLab webhook listens for:

| Event | Action |
|---|---|
| Push to default branch | Production deployment |
| Push to other branches | Preview deployment (Pro+) |
| Merge request opened/updated | Preview deployment |
| Merge request merged/closed | Preview cleanup |

Webhook endpoint: `https://api.holydocs.com/api/v1/webhooks/gitlab`

## Configuration

The GitLab connection stores these settings:

```json
{
  "repoProvider": "gitlab",
  "repoOwner": "your-group",
  "repoName": "documentation",
  "repoBranch": "main",
  "repoPath": "/"
}
```

## Content Fetching

During builds, HolyDocs uses the GitLab API to fetch repository contents:

- Files are fetched via the [Repository Files API](https://docs.gitlab.com/ee/api/repository_files.html)
- Binary files (images, fonts) are fetched with binary encoding to preserve byte integrity
- The tree API is used to discover all files in the docs directory

## Differences from GitHub

| Feature | GitHub | GitLab |
|---|---|---|
| OAuth setup | GitHub OAuth App | GitLab Application |
| Webhook events | push, pull_request | push, merge_request |
| PR comments | Supported | Supported via MR notes |
| Monorepo filtering | Path-based | Path-based |
| Code sync (agent) | Supported | Supported |
| Self-managed | N/A | Supported |

## Troubleshooting

### Builds not triggering

- Verify the webhook is installed: **GitLab Project > Settings > Webhooks**
- Check that the webhook URL is `https://api.holydocs.com/api/v1/webhooks/gitlab`
- Ensure push events are enabled for the webhook

### Authentication errors

- Re-authenticate via **Settings > Git > Reconnect GitLab** in the dashboard
- For self-managed instances, verify the instance URL is correct and accessible

### Missing files in build

- Check that `repoPath` points to the correct directory
- Verify the branch name matches your GitLab project's default branch