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:
- HolyDocs builds the docs from the PR branch
- A unique preview URL is generated
- A comment is posted on the PR with the preview link
- 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-botauthor attribution - Changes are pushed to a new branch or directly to the default branch (configurable)
bash# Agent commits follow this formatAuthor: 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:
- Go to Settings > Git in the dashboard
- Click Reconnect GitHub
- 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:
- Go to Settings > Git
- Click Disconnect Repository
- 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.