Deployments

Understand the HolyDocs build pipeline, deployment statuses, and how to manage production and preview deployments.

Overview

A deployment in HolyDocs is a snapshot of your documentation at a specific commit. Every push to your connected repository triggers a new deployment. Deployments are immutable — once built, the content is served from the edge until the next deployment replaces it.

Deployment Lifecycle

Each deployment goes through these stages:

Queued

The build job is placed in the build queue. Builds are processed one at a time per project to prevent resource contention.

Building

The build worker fetches your repository content, parses docs.json, processes all MDX files through the rendering pipeline, and resolves any OpenAPI specifications.

Uploading

Built HTML pages and static assets are uploaded to edge object storage. Page content is also cached on the edge for fast retrieval.

Indexing

After a successful build, an async job chunks your content and updates the vector index for AI-powered search and the assistant.

Live

The deployment is marked as active. All incoming requests to your docs domain serve the new content.

Build Pipeline (Detailed)

The build worker processes your documentation through several stages:

1. Repository Fetch

The worker fetches your repository content using the connected GitHub or GitLab integration. For GitHub, installation tokens are used (1-hour auto-refresh). The entire docs directory is downloaded as a tarball for efficiency.

2. Configuration Parse

The docs.json file is parsed and validated against the configuration schema. Dashboard overrides (theme, colors, navigation changes made in the UI) are merged with the file-based configuration. Dashboard settings take precedence.

3. MDX Processing

Each MDX file is processed through the unified pipeline: remark-parse, remark-mdx, remark-gfm, remark-toc, remark-images, remark-rehype, rehype-raw, rehype-slug, rehype-code-blocks, and rehype-stringify. This converts MDX to optimized HTML.

4. OpenAPI Resolution

If your configuration references OpenAPI specifications, they are fetched, parsed, and used to generate API reference pages. Code samples are generated in 7 languages automatically.

5. Asset Upload

Built HTML pages, images, and static assets are uploaded to edge object storage. Pages are also cached on the edge for sub-millisecond retrieval.

6. CDN Purge

After a successful upload, the CDN cache for your domain is purged to ensure readers see the latest content immediately.

Build Logs

Every deployment produces detailed build logs accessible from the deployment detail page in the dashboard. Logs include:

Repository fetch timing and file count
Configuration validation results
Per-page MDX processing status (success, warning, or error)
OpenAPI spec resolution results
Asset upload progress
Total build time breakdown

Logs are retained for 30 days on Pro plans and 90 days on Business/Enterprise plans.

If a build seems slow, check the build logs for the time breakdown. The most common bottleneck is OpenAPI spec fetching — if your spec URL is slow to respond, consider hosting the spec file in your repository instead.

Deployment Statuses

Status	Description
`queued`	Waiting in the build queue
`building`	Build in progress
`success`	Deployed successfully and serving traffic
`failed`	Build failed — check logs for details
`cancelled`	Manually cancelled before completion

Viewing Deployments

Dashboard

Navigate to Deployments in your project sidebar to see a list of all deployments with their status, commit SHA, branch, and timestamp.

API

bash
curl "https://api.holydocs.com/api/v1/deployments?projectId=PROJECT_ID" \  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{  "data": [    {      "id": "dep_abc123",      "projectId": "proj_xyz",      "status": "success",      "commitSha": "a1b2c3d",      "branch": "main",      "createdAt": 1708200000000,      "completedAt": 1708200015000    }  ],  "meta": {    "total": 42,    "page": 1,    "perPage": 20  }}

Triggering Manual Deployments

You can trigger a deployment without pushing to Git:

From the Dashboard

Click the Deploy button on your project overview page.

From the CLI

bash
holydocs deploy

Via the API

bash
curl -X POST https://api.holydocs.com/api/v1/deployments \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "projectId": "PROJECT_ID" }'

Preview Deployments

Preview deployments are created for non-default branches and pull requests. They provide a unique URL so you can review documentation changes before merging.

Preview deployments are available on the Pro plan and above. Free and Starter plans only support production deployments.

Preview URLs follow the pattern:

text
preview-{short-sha}.your-project.holydocs.com

Preview deployments:

Are automatically created when a PR webhook fires
Include a comment on the GitHub/GitLab PR with the preview link
Are cleaned up when the PR is closed or merged
Do not trigger AI content indexing (only production deployments do)

Build Limits

Deployment frequency is limited by your plan:

Plan	Builds per Day
Free	10
Starter	30
Pro	100
Business	500
Enterprise	Unlimited

If you exceed your daily build limit, subsequent pushes will be queued but will fail with a LIMIT_EXCEEDED error. Upgrade your plan or wait until the limit resets at midnight UTC.

Rollback

If a deployment introduces issues, you can instantly rollback to any previous successful deployment:

From the Dashboard

Go to Deployments in your project sidebar
Find the deployment you want to restore
Click the Rollback to this deployment button
The selected deployment's assets become active immediately

Via the API

bash
curl -X POST "https://api.holydocs.com/api/v1/deployments/DEPLOYMENT_ID/rollback" \  -H "Authorization: Bearer YOUR_API_KEY"

Rollback is instant because previous deployment assets are retained in storage. The rollback simply updates which deployment is marked as active — no rebuild is required.

Rollback does not affect the AI search index. If you need the search index to match the rolled-back content, trigger a manual reindex from AI Features > Reindex Content.

Build Performance Tips

Keep your docs directory focused

Only include files needed for documentation. Large binary files, test fixtures, or unrelated code in the docs directory slow down the repository fetch step.

Host OpenAPI specs locally

If your OpenAPI spec is fetched from a remote URL, network latency adds to build time. Hosting the spec file in your repository (e.g., openapi.yaml) eliminates this latency.

Use incremental builds

HolyDocs builds are incremental by default — only changed pages are re-processed. Avoid touching docs.json unnecessarily, as configuration changes trigger a full rebuild of all pages.

Optimize images before committing

Large images are uploaded to edge storage during each build. Pre-optimize images (compress PNGs, use WebP where possible) to reduce upload time and improve page load speed for readers.

Failed Deployments

When a build fails, the previous successful deployment continues serving traffic. Common failure reasons and solutions:

Error	Cause	Solution
Invalid docs.json	Schema validation errors in configuration	Run `holydocs check` locally to validate the config before pushing
MDX parse errors	Syntax errors in MDX files	Check the build log for the specific file and line number
Token expiry	GitHub/GitLab OAuth token expired	Reconnect your repository in Settings > Git
Missing files	Pages in navigation not found in repo	Verify file paths match navigation slugs exactly
OpenAPI parse errors	Invalid or unreachable spec URL	Test the spec URL directly; validate with an OpenAPI linter
LIMIT_EXCEEDED	Daily build limit reached	Wait until midnight UTC or upgrade your plan
TIMEOUT	Build exceeded the 120-second limit	Reduce docs directory size or split into multiple projects

Check the deployment logs in the dashboard for specific error messages and stack traces.

Was this page helpful?

Previous Environments

Next Custom Domains