english/.opencode/skills/mintlify/references/deployment-and-continuous-integration-reference.md

Deployment and Continuous Integration Reference

Complete guide for deploying Mintlify documentation with various hosting platforms and CI/CD pipelines.

Auto-Deploy from Git

Mintlify automatically deploys from connected Git repositories.

GitHub Integration

1. Connect Repository:

   • Go to Mintlify dashboard
   • Click "Connect Repository"
   • Authorize GitHub access
   • Select repository

2. Configure Branch:

   • Set main branch (e.g., main, master)
   • Optionally enable preview deployments for PRs

3. Auto-Deploy:

   • Push to main branch triggers production deployment
   • Pull requests trigger preview deployments
   • Deployment status shows in GitHub checks

GitLab Integration

1. Connect Repository:

   • Go to Mintlify dashboard
   • Select GitLab integration
   • Authorize GitLab access
   • Choose repository and branch

2. Deploy on Push:

   • Commits to configured branch auto-deploy
   • Merge requests can trigger previews

GitHub Enterprise Server

For self-hosted GitHub instances:

1. Configuration:

   • Provide GitHub Enterprise Server URL
   • Generate personal access token with repo permissions
   • Add webhook URL to repository

2. Webhook Setup:

   Payload URL: https://api.mintlify.com/webhook/github-enterprise
   Content type: application/json
   Events: Push, Pull request
   

Preview Deployments

Preview documentation changes before merging.

Pull Request Previews

Automatically generate preview deployments for PRs:

1. Enable in Dashboard:

   • Navigate to Settings > Deployments
   • Enable "Preview Deployments"
   • Choose PR branches to deploy

2. Access Previews:

   • Preview URL appears in PR checks
   • Format: https://preview-{pr-number}.mintlify.app
   • Auto-updates on new commits

3. Cleanup:

   • Previews auto-delete after PR merge/close
   • Configurable retention period

Branch Previews

Deploy specific branches for testing:

1. Configure Branch Patterns:

   {
     "deployments": {
       "preview": {
         "branches": ["staging", "dev", "feature/*"]
       }
     }
   }
   

2. Access:

   • URL format: https://{branch-name}.mintlify.app
   • Auto-deploy on branch push

Custom Domain

Connect custom domain to documentation.

DNS Configuration

1. Add DNS Records:

   Apex domain (example.com):

   Type: TXT
   Name: @
   Value: mintlify-domain-verification={verification-code}
   
   Type: CNAME (or ALIAS/ANAME)
   Name: @
   Value: mintlify-dns.com
   

   Subdomain (docs.example.com):

   Type: TXT
   Name: docs
   Value: mintlify-domain-verification={verification-code}
   
   Type: CNAME
   Name: docs
   Value: mintlify-dns.com
   

2. Verify in Dashboard:

   • Go to Settings > Custom Domain
   • Enter domain name
   • Click "Verify DNS"
   • Wait for SSL certificate provisioning (5-15 minutes)

Multiple Domains

Point multiple domains to same documentation:

docs.example.com → Primary domain
documentation.example.com → Redirect to primary
help.example.com → Redirect to primary

Configure redirects in dashboard or via DNS.

Subpath Hosting

Host documentation on subpath (e.g., example.com/docs).

Reverse Proxy Configuration

Nginx:

location /docs {
    proxy_pass https://your-site.mintlify.app;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # Rewrite path
    rewrite ^/docs(/.*)?$ $1 break;
}

Apache:

<Location /docs>
    ProxyPass https://your-site.mintlify.app
    ProxyPassReverse https://your-site.mintlify.app
    ProxyPreserveHost On

    # Rewrite
    RewriteEngine On
    RewriteRule ^/docs(/.*)?$ $1 [PT]
</Location>

Cloudflare Workers:

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const url = new URL(request.url)

  if (url.pathname.startsWith('/docs')) {
    const newUrl = url.pathname.replace(/^\/docs/, '')
    return fetch(`https://your-site.mintlify.app${newUrl}`, {
      headers: request.headers
    })
  }

  return fetch(request)
}

Base Path Configuration

Configure base path in docs.json:

{
  "basePath": "/docs"
}

All routes prefixed with /ck:docs:

• /ck:docs/introduction
• /ck:docs/api/users
• /ck:docs/guides/quickstart

Platform-Specific Deployment

Vercel

Deploy Mintlify docs alongside Next.js app.

1. Install Mintlify:

   npm install -D mintlify
   

2. Add Build Script:

   {
     "scripts": {
       "docs:build": "mintlify build",
       "docs:dev": "mintlify dev"
     }
   }
   

3. Configure Vercel:

   {
     "buildCommand": "npm run docs:build",
     "outputDirectory": ".mintlify/out",
     "routes": [
       {
         "src": "/docs/(.*)",
         "dest": "/.mintlify/out/$1"
       }
     ]
   }
   

4. Deploy:

   vercel
   

Cloudflare Pages

1. Build Settings:

   • Build command: mintlify build
   • Build output directory: .mintlify/out
   • Root directory: / (or docs subfolder)

2. Environment Variables:

   • Set NODE_VERSION=18 or higher

3. Deploy:

   • Connect GitHub repository
   • Configure branch: main
   • Cloudflare auto-builds on push

AWS (Route 53 + CloudFront)

Host static Mintlify build on AWS.

1. Build Docs:

   mintlify build
   

2. Upload to S3:

   aws s3 sync .mintlify/out s3://docs-bucket/ \
     --delete \
     --cache-control "public, max-age=3600"
   

3. CloudFront Distribution:

   • Origin: S3 bucket
   • Default root object: index.html
   • Error pages: Route 404 to /404.html

4. Route 53:

   • Create A record (alias to CloudFront distribution)
   • Enable IPv6 (AAAA record)

5. SSL Certificate:

   • Request certificate in AWS Certificate Manager
   • Validate domain ownership
   • Attach to CloudFront distribution

Monorepo Setup

Deploy documentation from monorepo structure.

Directory Structure

monorepo/
├── packages/
│   ├── app/
│   ├── api/
│   └── docs/           # Mintlify documentation
│       ├── docs.json
│       ├── introduction.mdx
│       └── api/
└── package.json

Configuration

Root package.json:

{
  "workspaces": ["packages/*"],
  "scripts": {
    "docs:dev": "npm run dev --workspace=packages/docs",
    "docs:build": "npm run build --workspace=packages/docs"
  }
}

packages/docs/package.json:

{
  "name": "docs",
  "version": "1.0.0",
  "scripts": {
    "dev": "mintlify dev",
    "build": "mintlify build"
  },
  "devDependencies": {
    "mintlify": "latest"
  }
}

CI/CD for Monorepo

GitHub Actions:

name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'packages/docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Build docs
        run: npm run docs:build

      - name: Deploy
        run: npx mintlify deploy
        env:
          MINTLIFY_TOKEN: ${{ secrets.MINTLIFY_TOKEN }}

CI/CD Validation

Validate documentation in CI pipeline.

GitHub Actions

name: Validate Docs

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'docs.json'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install Mintlify
        run: npm install -g mintlify

      - name: Validate config
        run: mint validate

      - name: Check broken links
        run: mint broken-links

      - name: Check accessibility
        run: mint a11y

      - name: Validate OpenAPI
        run: mint openapi-check

GitLab CI

validate-docs:
  image: node:18
  stage: test
  only:
    changes:
      - docs/**
      - docs.json
  script:
    - npm install -g mintlify
    - mint validate
    - mint broken-links
    - mint openapi-check

CircleCI

version: 2.1

jobs:
  validate:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run:
          name: Install Mintlify
          command: npm install -g mintlify
      - run:
          name: Validate
          command: |
            mint validate
            mint broken-links
            mint a11y

workflows:
  docs:
    jobs:
      - validate:
          filters:
            branches:
              only:
                - main
                - develop

Authentication

Protect documentation with authentication.

Mintlify Auth (Built-in)

1. Enable in Dashboard:

   • Go to Settings > Authentication
   • Enable "Require Authentication"
   • Choose auth method

2. Auth Methods:

   • Email allowlist
   • Google OAuth
   • GitHub OAuth
   • Custom SSO (SAML)

3. Configure:

   {
     "auth": {
       "enabled": true,
       "method": "google",
       "allowedDomains": ["company.com"]
     }
   }
   

Custom Authentication

Integrate with existing auth system:

1. Reverse Proxy:

   • Place auth layer before Mintlify
   • Validate session/token
   • Proxy authenticated requests

2. Example (Nginx + OAuth2 Proxy):

   location /docs {
       auth_request /oauth2/auth;
       error_page 401 = /oauth2/sign_in;
   
       proxy_pass https://your-site.mintlify.app;
   }
   

Content Security Policy (CSP)

Configure CSP headers for security.

Required CSP Directives

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-inline' 'unsafe-eval' https://mintlify.com;
  style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
  font-src 'self' https://fonts.gstatic.com;
  img-src 'self' data: https:;
  connect-src 'self' https://api.mintlify.com;
  frame-src 'self' https://mintlify.com;

Cloudflare Configuration

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const response = await fetch(request)
  const newHeaders = new Headers(response.headers)

  newHeaders.set(
    'Content-Security-Policy',
    "default-src 'self'; script-src 'self' 'unsafe-inline' https://mintlify.com"
  )

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: newHeaders
  })
}

Environment-Specific Configuration

Manage configurations per environment.

Multiple Config Files

docs/
├── docs.json              # Production config
├── docs.staging.json      # Staging config
├── docs.development.json  # Development config

Build with Environment Config

# Development
MINTLIFY_CONFIG=docs.development.json mint dev

# Staging
MINTLIFY_CONFIG=docs.staging.json mint build

# Production
mint build  # Uses docs.json by default

Environment Variables

Inject environment-specific values:

{
  "name": "${DOCS_SITE_NAME}",
  "api": {
    "playground": {
      "proxy": "${API_BASE_URL}"
    }
  },
  "integrations": {
    "ga4": {
      "measurementId": "${GA4_MEASUREMENT_ID}"
    }
  }
}

GitHub Actions:

- name: Build docs
  run: mint build
  env:
    DOCS_SITE_NAME: "My Docs"
    API_BASE_URL: "https://api.example.com"
    GA4_MEASUREMENT_ID: "G-XXXXXXXXXX"

Cache Configuration

Optimize caching for better performance.

CDN Cache Headers

Cache-Control: public, max-age=3600, s-maxage=86400

Cloudflare Page Rules

URL: docs.example.com/*
Settings:
  - Cache Level: Standard
  - Edge Cache TTL: 1 day
  - Browser Cache TTL: 1 hour

Invalidation

Invalidate cache after deployment:

Cloudflare:

curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/purge_cache" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"purge_everything":true}'

AWS CloudFront:

aws cloudfront create-invalidation \
  --distribution-id ${DISTRIBUTION_ID} \
  --paths "/*"

Deployment Checklist

Pre-deployment validation:

• Run mint validate - Check configuration
• Run mint broken-links - Verify all links work
• Run mint a11y - Check accessibility
• Run mint openapi-check - Validate API specs
• Test preview deployment
• Verify custom domain DNS
• Check SSL certificate
• Test authentication (if enabled)
• Validate CSP headers
• Review analytics integration
• Check mobile responsiveness
• Test search functionality
• Verify social preview images