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

# Environments

Configure multiple deployment environments with branch patterns, custom domains, and access controls.

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

| Environment | Branch Pattern | Access | Description |
|---|---|---|---|
| Production | `main` | Public | Your live documentation site |

## Creating an Environment

### Dashboard

**Open Environments**

Navigate to your project and click **Environments** in the sidebar.
  **Click Create Environment**

Click the **New Environment** button in the top-right corner.
  **Configure the environment**

Set the environment name, branch pattern, and access level.
  **Save**

Click **Create** to save the environment. The next push to a matching branch will trigger a deployment to this environment.

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

| Property | Type | Description |
|---|---|---|
| `name` | string | Display name (e.g., "Staging", "Development") |
| `branchPattern` | string | Git branch glob pattern that triggers deployments |
| `accessLevel` | `public` \| `org` \| `creator` | Who can view this environment |
| `domain` | string (optional) | Custom domain or subdomain for this environment |
| `variableOverrides` | object (optional) | Template variable values specific to this environment |

## Branch Pattern Matching

Branch patterns use glob syntax to match Git branches:

| Pattern | Matches | Does Not Match |
|---|---|---|
| `main` | `main` | `main-v2`, `hotfix/main` |
| `staging/*` | `staging/v2`, `staging/hotfix` | `staging`, `pre-staging/v1` |
| `release/**` | `release/v1`, `release/v1.2/rc1` | `pre-release/v1` |
| `feature/*` | `feature/dark-mode`, `feature/auth` | `feature/auth/oauth` |
| `develop` | `develop` | `development`, `dev` |

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:

**Public**

Anyone with the URL can view the documentation. This is the default for production environments.

    ```json
    { "accessLevel": "public" }
    ```
  **Org Members**

Only authenticated members of your organization can view the documentation. Visitors are redirected to the login page.

    ```json
    { "accessLevel": "org" }
    ```
  **Creator Only**

Only the environment creator (and org owners) can view the documentation. Useful for personal feature previews.

    ```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](/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:

**Select the source deployment**

Open the **Environments** page and find the deployment you want to promote.
  **Click Promote**

Click the arrow icon next to the deployment. Select the target environment.
  **Confirm**

Review the changes and confirm. The deployment is copied to the target environment and the CDN cache is purged automatically.

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

**Keep staging access restricted**

Set staging and development environments to `org` or `creator` access. This prevents draft documentation from being indexed by search engines or seen by customers.
  **Use variable overrides for API URLs**

Rather than hardcoding API endpoints in your MDX, define them as template variables and override per environment. This keeps your content portable.
  **Match your Git workflow**

Align environment branch patterns with your team's branching strategy. If you use GitFlow, map `release/*` to staging and `main` to production.
  **Test promotions before going live**

Promote staging deployments to production rather than deploying directly from `main`. This gives you a verified preview before readers see changes.