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

# GitHub Integration

Connect your GitHub repository to HolyDocs for automatic deployments, PR preview builds, and AI-powered code sync.

## Overview

The GitHub integration is the primary way to connect your documentation source code to HolyDocs. Once connected, every push to your repository triggers an automatic build and deployment.

## Setting Up

**Navigate to Git Settings**

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

Click **Connect GitHub**. You will be redirected to GitHub to authorize the HolyDocs OAuth app. Grant access to the repositories you want to use.
  **Select Repository**

Choose the repository containing your documentation files. Configure:
    - **Branch**: The branch to deploy from (default: `main`)
    - **Path**: Directory containing `docs.json` (default: `/`)
  **Webhook Installation**

HolyDocs automatically installs a webhook on the selected repository to listen for push and pull request events.

## Webhook Events

The GitHub webhook listens for:

| Event | Trigger | Action |
|---|---|---|
| `push` (default branch) | Commit to main/master | Production deployment |
| `push` (other branches) | Commit to feature branch | Preview deployment (Pro+) |
| `pull_request.opened` | New PR created | Preview deployment |
| `pull_request.synchronize` | PR updated with new commits | Preview deployment update |
| `pull_request.closed` | PR merged or closed | Preview cleanup |

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

## PR Preview Deployments

On Pro plans and above, every pull request gets an automatic preview deployment:

1. HolyDocs builds the docs from the PR branch
2. A unique preview URL is generated
3. A comment is posted on the PR with the preview link
4. Reviewers can view the documentation changes before merging

Preview deployments do not trigger AI content indexing. Only production deployments (merges to the default branch) update the search index.

## Permissions Required

The HolyDocs GitHub OAuth app requests these permissions:

| Permission | Scope | Purpose |
|---|---|---|
| Repository contents | Read | Fetch documentation files during builds |
| Webhooks | Read/Write | Install and manage deployment webhooks |
| Pull requests | Write | Post preview deployment comments |
| Metadata | Read | List repositories during setup |

## Code Sync

The code-sync feature allows the AI agent to commit documentation changes back to your repository:

- Agent suggestions are committed as new commits
- Commits use a `holydocs-bot` author attribution
- Changes are pushed to a new branch or directly to the default branch (configurable)

```bash
# Agent commits follow this format
Author: holydocs-bot <bot@holydocs.com>
Message: docs: update API reference for /users endpoint
```

## Monorepo Support

If your docs are in a subdirectory of a monorepo, set the `repoPath`:

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

HolyDocs filters webhook events to only trigger builds when files within the configured path change.

## Token Refresh

GitHub OAuth tokens can expire or be revoked. If builds fail with authentication errors:

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

If you see "Bad credentials" in your deployment logs, the OAuth token has expired. The repository owner needs to re-authenticate through the dashboard.

## Disconnecting

To disconnect GitHub:

1. Go to **Settings > Git**
2. Click **Disconnect Repository**
3. Optionally revoke the HolyDocs OAuth app in GitHub Settings > Applications

Disconnecting removes the webhook and stops automatic deployments, but does not delete existing deployments or content.