Skip to main content

Merge Request Preview Environments

This guide explains how to use MR (Merge Request) preview environments to share and review documentation changes before merging to production.

Overview​

When you create a merge request, GitLab CI automatically builds and deploys a preview version of the documentation site. This preview:

  • Uses the same S3 bucket as production but in a separate subdirectory
  • Has a unique URL based on the MR ID: https://docs.mambu.com/mr-{ID}/
  • Automatically updates when you push new commits to the MR
  • Is automatically cleaned up when the MR is merged or closed
  • Keeps all internal links working within the preview environment

How to Use MR Previews​

1. Create a Merge Request​

Create your MR as usual through GitLab. The CI pipeline will automatically:

  1. Build the documentation with a special base URL
  2. Deploy to s3://docs-mambu-prod/mr-{ID}/
  3. Create a GitLab environment with the preview URL

2. Access the Preview​

Once the deploy_s3_review job completes:

  1. Go to your MR page in GitLab
  2. Look for the Environments section or click the View app button
  3. The preview URL will be: https://docs.mambu.com/mr-{ID}/

Example: MR #251 → https://docs.mambu.com/mr-251/

3. Share for Review​

Share the preview URL with stakeholders for review. All internal links will work correctly within the preview environment.

Clean URLs work: You can share URLs with or without .html extensions:

  • https://docs.mambu.com/mr-251/docs/navigating-in-mambu/ ✅
  • https://docs.mambu.com/mr-251/docs/navigating-in-mambu.html ✅

Both formats work thanks to CloudFront URL rewriting.

4. Update the Preview​

Push new commits to your MR branch, and the pipeline will automatically rebuild and redeploy the preview.

5. Cleanup​

The preview environment is automatically deleted when:

  • The MR is merged
  • The MR is closed

You can also manually stop the environment from:

  • GitLab → Deployments → Environments → Click the stop button for your review environment

How It Works​

Build Process​

When building for an MR preview, the CI pipeline:

  1. Detects CI_MERGE_REQUEST_IID environment variable
  2. Sets baseUrl to /mr-{ID}/ in docusaurus.config.ts
  3. Builds the site with all internal links prefixed with /mr-{ID}/
  4. Deploys to the S3 subdirectory

Relevant code in docusaurus.config.ts:

const isReviewBuild = process.env.CI_MERGE_REQUEST_IID !== undefined;
const baseUrl = isReviewBuild ? `/mr-${process.env.CI_MERGE_REQUEST_IID}/` : '/';

URL Rewriting​

A CloudFront Function handles URL rewriting to support clean URLs:

  • /mr-251/docs/guide/ → /mr-251/docs/guide/index.html
  • /mr-251/docs/intro → /mr-251/docs/intro.html

This is configured in infrastructure/cloudfront/url-rewrite-function.js and associated with the CloudFront distribution.

Environment Lifecycle​

GitLab CI uses dynamic environments with auto-stop:

deploy_s3_review:
  environment:
    name: review/mr-$CI_MERGE_REQUEST_IID
    url: https://docs.mambu.com/mr-$CI_MERGE_REQUEST_IID/
    on_stop: stop_s3_review

When the MR is closed/merged, GitLab automatically triggers stop_s3_review which deletes the S3 files.

Limitations​

  • No Security: MR previews are publicly accessible. Sensitive WIP content should not be pushed to MR branches.
    • Note: Security can be added via CloudFront Functions to restrict to VPN/Netskope. See infrastructure/cloudfront/ for implementation.
  • No CloudFront Invalidation: Changes may take up to 5 minutes to appear due to cache (cache-control is set to max-age=300)
  • S3 Costs: Each preview uses S3 storage. With auto-cleanup, costs are minimal.

Troubleshooting​

Preview URL returns 404​

Check deployment status:

# Check if files were deployed
aws s3 ls s3://docs-mambu-prod/mr-{ID}/ --recursive

Check CloudFront Function:

  • Ensure docs-mambu-url-rewrite function is deployed and associated with the distribution

This means the baseUrl wasn't set correctly during build:

  1. Check the build logs for: Building for MR preview with baseUrl: /mr-{ID}/
  2. Verify CI_MERGE_REQUEST_IID is available in the pipeline
  3. Rebuild the MR pipeline

Preview not cleaned up after merge​

Check the stop_s3_review job:

  1. Go to GitLab → Deployments → Environments
  2. Find the review/mr-{ID} environment
  3. Manually click the stop button

If it fails, manually delete from S3:

aws s3 rm s3://docs-mambu-prod/mr-{ID}/ --recursive
  • .gitlab-ci.yml - CI/CD pipeline configuration
  • docusaurus.config.ts - Dynamic baseUrl configuration
  • infrastructure/cloudfront/url-rewrite-function.js - CloudFront URL rewriting
  • infrastructure/cloudfront/SETUP.md - CloudFront Function setup instructions

Cost Estimate​

For typical usage (5-10 active MRs at a time):

  • S3 Storage: ~$0.50/month (assuming 100MB per preview × 10 MRs)
  • S3 Requests: ~$0.10/month
  • CloudFront Functions: ~$0.50/month (for URL rewriting)
  • Total: < $2/month

Costs are minimal since previews are automatically cleaned up.