Deployment options comparison

Compare different deployment and hosting options for your Mintlify documentation

This guide compares deployment methods and hosting configurations to help you choose the right setup.

Deployment methods

GitHub integration (recommended)

Best for: Most teams

Automatic deployments triggered by Git pushes.

Pros:

• Automatic deployments on push
• Preview deployments for pull requests
• Full Git history and version control
• Team collaboration through PRs
• No manual deployment steps

Cons:

• Requires GitHub account
• Deployment depends on GitHub availability

Setup:

1. Connect repository in dashboard
2. Install GitHub App
3. Push changes to deploy

GitLab integration

Best for: Teams using GitLab

Similar to GitHub with GitLab-specific features.

Pros:

• Automatic deployments on push
• Works with self-hosted GitLab
• GitLab CI/CD integration
• Team collaboration

Cons:

• Requires GitLab account
• Fewer integrations than GitHub

Setup:

1. Connect repository in dashboard
2. Configure GitLab integration
3. Push changes to deploy

CI/CD deployment

Best for: Custom workflows, monorepos

Deploy from any CI/CD system using the API.

Pros:

• Works with any Git provider
• Custom deployment logic
• Integration with existing CI/CD
• Monorepo support

Cons:

• Requires API key management
• Manual CI/CD configuration
• No automatic preview deployments

Setup:

1. Generate API key in dashboard
2. Configure CI/CD pipeline
3. Call deployment API

Example (GitHub Actions):

name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Trigger deployment
        run: |
          curl -X POST https://api.mintlify.com/v1/project/update/${{ secrets.PROJECT_ID }} \
            -H "Authorization: Bearer ${{ secrets.MINTLIFY_API_KEY }}"

Hosting configurations

Mintlify subdomain

Best for: Quick setup, testing

Your docs at your-project.mintlify.app.

Pros:

• Instant setup
• Free SSL certificate
• No DNS configuration
• Automatic CDN

Cons:

• Mintlify branding in URL
• Can’t customize domain

Setup: Automatic during onboarding.

Custom domain

Best for: Production documentation

Your docs at docs.yourcompany.com.

Pros:

• Professional appearance
• Your branding
• SEO benefits
• Custom SSL certificate

Cons:

• Requires DNS configuration
• 24-48 hour DNS propagation

Setup:

1. Add domain in dashboard
2. Update DNS records (CNAME)
3. Wait for SSL certificate

Subpath hosting

Best for: Unified domain structure

Your docs at yourcompany.com/docs.

Pros:

• Unified domain
• Consistent branding
• SEO consolidation
• Existing domain authority

Cons:

• More complex setup
• Requires reverse proxy or CDN
• Additional configuration

Options:

• Cloudflare
• AWS CloudFront
• Vercel
• Reverse proxy

Comparison table

Feature	GitHub	GitLab	CI/CD	Mintlify Domain	Custom Domain	Subpath
Setup time	5 min	5 min	15 min	Instant	24-48 hrs	1-2 hrs
Auto deploy	✓	✓	✓	N/A	N/A	N/A
Preview deploys	✓	✓	Custom	N/A	N/A	N/A
Custom domain	N/A	N/A	N/A	✗	✓	✓
SSL certificate	Auto	Auto	Auto	Auto	Auto	Manual
CDN	✓	✓	✓	✓	✓	Depends
Cost	Free	Free	Free	Free	Free	Varies

Choosing the right setup

For startups and small teams

Recommended:

• GitHub integration
• Mintlify subdomain initially
• Custom domain when ready

Why:

• Fastest setup
• Minimal configuration
• Easy to upgrade later

For enterprises

Recommended:

• GitLab/GitHub integration
• Custom domain
• Subpath hosting (optional)

Why:

• Professional appearance
• Brand consistency
• Advanced security options

For monorepos

Recommended:

• CI/CD deployment
• Custom domain
• Monorepo configuration

Why:

• Flexible deployment
• Works with existing setup
• Multiple docs in one repo

For agencies

Recommended:

• GitHub integration
• Custom domains for each client
• Preview deployments

Why:

• Client branding
• Easy client handoff
• Professional workflow

Migration paths

From Mintlify subdomain to custom domain

1. Add custom domain in dashboard
2. Update DNS records
3. Wait for SSL certificate
4. Test custom domain
5. Update links (optional)

Downtime: None (both domains work during transition)

From custom domain to subpath

1. Set up reverse proxy/CDN
2. Configure subpath routing
3. Update DNS records
4. Test subpath access
5. Set up redirects

Downtime: Minimal (during DNS propagation)

From one Git provider to another

1. Push code to new repository
2. Connect new repository in dashboard
3. Disconnect old repository
4. Update team access

Downtime: None (deployment continues)

Advanced configurations

Multiple environments

Deploy different branches to different domains:

Branch	Domain	Purpose
main	docs.example.com	Production
staging	staging-docs.example.com	Staging
dev	dev-docs.example.com	Development

Geographic distribution

Use CDN for global performance:

• Automatic with Mintlify hosting
• Configure with custom CDN for subpath
• Edge caching for faster loads

Authentication

Add authentication to protect docs:

Method	Best For	Setup
Password	Simple protection	Dashboard config
JWT	Custom auth	API integration
OAuth	SSO integration	OAuth provider

Performance considerations

Deployment speed

Method	Typical Deploy Time
GitHub	2-3 minutes
GitLab	2-3 minutes
CI/CD	3-5 minutes

Build optimization

• Use preview deployments for testing
• Deploy only changed files
• Optimize images before committing
• Minimize custom scripts

Security best practices

For all deployments

• Use HTTPS (automatic with Mintlify)
• Keep API keys secret
• Rotate keys regularly
• Use environment variables

For custom domains

• Enable HSTS
• Configure CSP headers
• Use CAA DNS records
• Monitor SSL certificate expiration

For CI/CD

• Store API keys in secrets
• Limit API key permissions
• Use separate keys per environment
• Audit deployment logs

Troubleshooting

Deployment not triggering

GitHub/GitLab:

• Check webhook configuration
• Verify branch name matches
• Review GitHub App permissions

CI/CD:

• Verify API key is valid
• Check CI/CD logs
• Ensure correct project ID

Custom domain not working

• Verify DNS records
• Wait 24-48 hours for propagation
• Check SSL certificate status
• Clear browser cache

Slow deployments

• Optimize image sizes
• Reduce number of pages
• Check for large files
• Review custom scripts

Getting help

For deployment issues:

• Check troubleshooting guide
• Review deployment documentation
• Contact support