Environments

Overview

HolyDocs environments let you deploy different versions of your documentation from different Git branches. Each environment has its own URL, access controls, and variable overrides -- so your staging docs stay private while production docs are public.

Every project starts with a production environment. You can add additional environments for staging, development, feature previews, or any other workflow.

Default Environments

A newly created project has one environment:

Creating an Environment

Dashboard

API

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/environments" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "staging",    "branchPattern": "staging/*",    "accessLevel": "org"  }'

Environment Properties

Branch Pattern Matching

Branch patterns use glob syntax to match Git branches:

When a push arrives, HolyDocs matches the branch name against all environment patterns (in order of specificity) and deploys to the first matching environment.

If a branch matches multiple environment patterns, the most specific pattern wins. Exact matches take priority over wildcards.

Access Levels

Each environment has an access level that controls who can view the deployed documentation:

json
{ "accessLevel": "public" }

json
{ "accessLevel": "org" }

json
{ "accessLevel": "creator" }

Environment-Specific Domains

Each environment can have its own domain or subdomain:

json
{  "name": "staging",  "branchPattern": "staging/*",  "domain": "staging-docs.yourcompany.com"}

If no custom domain is set, the environment is accessible via a subdomain of your project:

• Production: docs.yourcompany.com
• Staging: staging.docs.yourcompany.com
• Development: dev.docs.yourcompany.com

Configure custom domains in Settings > Domain and then assign them to environments. Each environment can have one custom domain.

Variable Overrides

Override template variable defaults for each environment. This is the recommended way to manage environment-specific configuration like API endpoints, feature flags, or version numbers:

json
{  "name": "staging",  "branchPattern": "staging/*",  "variableOverrides": {    "api_base": "https://staging-api.example.com",    "environment_badge": "STAGING",    "feature_new_auth": "true"  }}

Variable overrides take priority over the defaultValue in your docs.json but are lower priority than reader selections and URL parameters. See Template Variables for the full resolution order.

Example Multi-Environment Setup

A typical project might have three environments:

json
[  {    "name": "production",    "branchPattern": "main",    "accessLevel": "public",    "domain": "docs.yourcompany.com",    "variableOverrides": {      "api_base": "https://api.yourcompany.com",      "environment_badge": ""    }  },  {    "name": "staging",    "branchPattern": "staging",    "accessLevel": "org",    "domain": "staging-docs.yourcompany.com",    "variableOverrides": {      "api_base": "https://staging-api.yourcompany.com",      "environment_badge": "STAGING"    }  },  {    "name": "development",    "branchPattern": "develop",    "accessLevel": "org",    "variableOverrides": {      "api_base": "https://dev-api.yourcompany.com",      "environment_badge": "DEV"    }  }]

Promoting Between Environments

You can promote a deployment from one environment to another directly from the dashboard. This copies the built output without re-running the build pipeline:

Promoting a deployment copies the built assets but applies the target environment's variable overrides. If the content relies on environment-specific variables, verify the output after promoting.

Managing Environments

List Environments

bash
curl "https://api.holydocs.com/api/v1/projects/PROJECT_ID/environments" \  -H "Authorization: Bearer YOUR_API_KEY"

Update an Environment

bash
curl -X PATCH "https://api.holydocs.com/api/v1/projects/PROJECT_ID/environments/ENV_ID" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "accessLevel": "public",    "variableOverrides": {      "api_base": "https://api.yourcompany.com"    }  }'

Delete an Environment

bash
curl -X DELETE "https://api.holydocs.com/api/v1/projects/PROJECT_ID/environments/ENV_ID" \  -H "Authorization: Bearer YOUR_API_KEY"

The production environment cannot be deleted. You can change its branch pattern and settings, but every project must have at least one environment.

Best Practices