> ## 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.

# Git Integration

Connect your GitHub or GitLab repository to HolyDocs for automatic deployments on every push.

## Overview

HolyDocs integrates directly with **GitHub** and **GitLab** to pull documentation content from your repository. When you push changes to your configured branch, HolyDocs automatically triggers a build and deploys the updated docs to the edge.

## Connecting GitHub

**Authorize GitHub**

Go to **Settings > Git** in your project dashboard and click **Connect GitHub**. This initiates an OAuth flow where you grant HolyDocs read access to your repositories.
  **Select a repository**

Choose the repository containing your documentation. You can select any repo your GitHub account has access to, including organization repos.
  **Configure branch and path**

Specify the branch to watch (default: `main`) and the directory path where your `docs.json` lives (default: `/`).

    ```json
    {
      "repoProvider": "github",
      "repoOwner": "your-org",
      "repoName": "documentation",
      "repoBranch": "main",
      "repoPath": "/docs"
    }
    ```
  **Install the webhook**

HolyDocs automatically installs a webhook on your repository. This webhook fires on `push` events to trigger builds, and on `pull_request` events for preview deployments.

## Connecting GitLab

The GitLab integration follows the same pattern:

1. Go to **Settings > Git** and click **Connect GitLab**
2. Authorize HolyDocs via GitLab OAuth
3. Select your project and configure the branch/path
4. A webhook is automatically installed for push events

GitLab integration supports both gitlab.com and self-managed GitLab instances. For self-managed, provide your instance URL during the OAuth setup.

## Webhook Events

HolyDocs listens for these webhook events:

| Event | Action |
|---|---|
| `push` to default branch | Full production build and deployment |
| `push` to other branches | Preview deployment (Pro plan and above) |
| `pull_request` opened/updated | Preview deployment with PR comment |
| `pull_request` closed | Preview deployment cleanup |

Webhook endpoints:
- GitHub: `https://api.holydocs.com/api/v1/webhooks/github`
- GitLab: `https://api.holydocs.com/api/v1/webhooks/gitlab`

## Preview Deployments

On Pro plans and above, every pull request gets its own preview deployment:

- Unique preview URL: `preview-{sha}.your-project.holydocs.com`
- A comment is posted on the PR with the preview link
- Preview deployments are automatically cleaned up when the PR is closed

## Build Pipeline

When a webhook fires, the build pipeline:

1. **Fetches** the repository content via the GitHub/GitLab API
2. **Parses** the `docs.json` configuration
3. **Processes** MDX files through the unified remark/rehype pipeline
4. **Resolves** OpenAPI specs and generates API reference pages
5. **Uploads** built pages and assets to edge object storage
6. **Purges** the edge page cache for the project
7. **Queues** AI content indexing for updated pages

Builds are processed one at a time per project (queue batch size of 1) to prevent concurrent builds from competing for resources. Subsequent pushes are queued and processed in order.

## Token Expiry

GitHub OAuth tokens can expire. If a build fails with "Bad credentials," the repository owner needs to re-authenticate:

1. Go to **Settings > Git** in the dashboard
2. Click **Reconnect GitHub**
3. Re-authorize access

## Monorepo Support

If your docs live in a subdirectory of a larger repository, set the `repoPath` to point to the directory containing your `docs.json`:

```json
{
  "repoPath": "/packages/docs"
}
```

HolyDocs only processes files within this path, so changes outside the docs directory will not trigger unnecessary builds.