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:
- During the OAuth setup, select Self-Managed instead of GitLab.com
- Enter your GitLab instance URL (e.g.,
https://gitlab.yourcompany.com) - 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
- 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
repoPathpoints to the correct directory - Verify the branch name matches your GitLab project's default branch