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

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

```
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

1. Go to **Deployments** in your project sidebar
2. Find the deployment you want to restore
3. Click the **Rollback to this deployment** button
4. 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.