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:
- Go to Settings > Git and click Connect GitLab
- Authorize HolyDocs via GitLab OAuth
- Select your project and configure the branch/path
- 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:
- Fetches the repository content via the GitHub/GitLab API
- Parses the
docs.jsonconfiguration - Processes MDX files through the unified remark/rehype pipeline
- Resolves OpenAPI specs and generates API reference pages
- Uploads built pages and assets to edge object storage
- Purges the edge page cache for the project
- 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:
- Go to Settings > Git in the dashboard
- Click Reconnect GitHub
- 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.