Deployment Guide

This guide walks you through setting up automated deployment for your documentation site using GitLab CI/CD and Cloudflare Pages.

Prerequisites

• A GitLab repository with this template
• A Cloudflare account
• Admin access to your GitLab project settings

Step 1: Cloudflare Setup

1.1 Create a Pages Project

1. Log into Cloudflare Dashboard
2. Navigate to Pages in the left sidebar
3. Click Create a project
4. Select Upload assets (not Connect to Git)
   • This creates an empty project that we’ll deploy to via CI/CD
   • You don’t need to upload any files at this step
5. Enter a project name that matches what you’ll use for CLOUDFLARE_PAGES_PROJECT
   • Use a descriptive name like my-docs or project-documentation
   • Remember this exact name - it must match your environment variable
6. Click Create project - after this the page is created. No need to upload anything. You can leave the page
7. Note your Account ID from the dashboard URL or sidebar
   • It looks like: https://dash.cloudflare.com/[ACCOUNT_ID]/pages
   • You’ll need this for the CLOUDFLARE_ACCOUNT_ID variable

1.2 Generate API Token

1. Go to Cloudflare API Tokens
2. Click Create Token
3. Use the Custom token template
4. Configure permissions:
   • Zone:Zone:Read (if using custom domains)
   • Zone:Page Rules:Edit (if using custom domains)
   • Account:Cloudflare Pages:Edit
   • Acount:Worker:Edit (add everything related to workers)
5. Copy the generated token

Step 2: GitLab Configuration

2.1 Set Environment Variables

Go to your GitLab project: Settings > CI/CD > Variables

Add these variables (mark as Protected and Masked where appropriate):

Variable	Value	Type	Protected	Masked
CLOUDFLARE_PAGES_PROJECT	Your Pages project name	Variable	✅	❌
CLOUDFLARE_API_TOKEN	Your API token	Variable	✅	✅
CLOUDFLARE_ACCOUNT_ID	Your account ID	Variable	✅	✅
WEBSITE_PASSWORD	Your site password (optional)	Variable	✅	✅

2.2 Verify CI/CD Configuration

The .gitlab-ci.yml file should already be configured. It includes:

• Build Stage: Installs dependencies and builds the site
• Deploy Stage: Deploys to Cloudflare Pages using Wrangler

Step 3: Deploy

1. Commit and Push: Any push to your repository will trigger deployment
2. Monitor Progress: Check the CI/CD pipeline in GitLab
3. Access Your Site: Visit https://your-project-name.pages.dev

Password Protection

If you set the WEBSITE_PASSWORD variable, your site will be protected with a login page.

How It Works

• Users see a login page before accessing content
• Correct password sets a secure cookie valid for 1 day
• Authentication is handled by Cloudflare Functions

Important Notes

• Password Changes: Require redeployment to take effect
• Security: Passwords are hashed using SHA-256
• Sessions: Login persists across browser sessions

Changing the Password

1. Update the WEBSITE_PASSWORD variable in GitLab
2. Trigger a new deployment (push a commit or manual pipeline)
3. The new password will be active after deployment completes

Troubleshooting

Common Issues

Build Failures

Error: Failed to install dependencies

Solution: Check that pnpm-lock.yaml is committed to the repository.

Deployment Failures

Error: Authentication failed

Solutions:

• Verify CLOUDFLARE_API_TOKEN has correct permissions
• Ensure CLOUDFLARE_ACCOUNT_ID is correct
• Check that the Pages project exists

Password Not Working

Solution: Redeploy the project after changing WEBSITE_PASSWORD.

Page Not Found (404)

Solutions:

• Verify CLOUDFLARE_PAGES_PROJECT matches your actual project name
• Check that the deployment completed successfully
• Wait a few minutes for DNS propagation

Checking Deployment Status

1. GitLab: Go to CI/CD > Pipelines to see build status
2. Cloudflare: Check Pages dashboard for deployment history
3. Logs: View detailed logs in both GitLab and Cloudflare

Advanced Configuration

Custom Domains

1. Add your domain in Cloudflare Pages settings
2. Update DNS records as instructed
3. Modify environment variables if needed

Branch Deployments

The CI/CD is configured to deploy all branches, creating preview URLs for each branch automatically.