Cloudflare Pages Deployment Guide

Prerequisites

1. A Cloudflare account (the free tier is enough)
2. GitHub repository: xy111a/gtm-knowledge-base

Step 1: Get a Cloudflare API Token

1. Sign in to the Cloudflare Dashboard
2. Click the avatar in the top-right corner → My Profile → API Tokens
3. Click Create Token
4. Select the Cloudflare Pages template
5. Configure permissions:
   • Account → Cloudflare Pages → Edit
   • Zone → Zone → Read (if you need a custom domain)
6. Click Continue to summary → Create Token
7. Copy the generated token

Step 2: Get the Account ID

1. The Account ID is shown in the right-hand sidebar of the Cloudflare Dashboard
2. Alternatively, open the Overview page of any domain and the Account ID appears on the right
3. Copy this ID

Step 3: Configure GitHub Secrets

1. Open the GitHub repository (private; ask an admin for access): xy111a/gtm-knowledge-base
2. Go to Settings → Secrets and variables → Actions
3. Click New repository secret
4. Add the following secrets:

Name	Value
CLOUDFLARE_API_TOKEN	The token obtained in Step 1
CLOUDFLARE_ACCOUNT_ID	The Account ID obtained in Step 2

Step 4: Create the Cloudflare Pages Project

Method A: Via the Cloudflare Dashboard (recommended)

1. Sign in to the Cloudflare Dashboard
2. Click Workers & Pages in the left sidebar
3. Click Create → Pages → Connect to Git
4. Select GitHub → select the gtm-knowledge-base repository
5. Configure the build settings:
   • Production branch: main
   • Build command: pnpm install && pnpm run build
   • Build output directory: docs/.vitepress/dist
   • Node.js version: 20
6. Click Save and Deploy

Method B: Via the Wrangler CLI

# Install Wrangler
npm install -g wrangler

# Log in
wrangler login

# Create the Pages project
wrangler pages project create gtm-knowledge-base

# Manual deployment (optional, for testing)
cd gtm-site
pnpm install && pnpm run build
wrangler pages deploy docs/.vitepress/dist --project-name=gtm-knowledge-base

Step 5: Configure Automatic Deployment

Once the Cloudflare Pages project is linked to the GitHub repository, every push to the main branch automatically triggers a deployment.

Deployment Flow

Push code → GitHub Actions build → Cloudflare Pages deployment
    ↑
    └── Feishu (Lark) sync (every 15 minutes) → automatic commit → triggers deployment

Step 6: Configure a Custom Domain (optional)

1. Click Custom domains in the Cloudflare Pages project settings
2. Enter your domain (e.g. gtm.yourcompany.com)
3. Configure the DNS records as prompted
4. The SSL certificate is provisioned automatically

Verify the Deployment

1. Visit the default domain provided by Cloudflare Pages: https://gtm-knowledge-base.pages.dev
2. Check that the site loads correctly
3. Test the search function
4. Test the interactive components (the P&L calculator, the Gantt chart, etc.)

Troubleshooting

The Build Fails

Check the GitHub Actions log:

1. Open the repository Actions page (sign-in required for a private repo)
2. Click the failed workflow
3. Review the detailed error message

Feishu (Lark) Sync Fails

You need to configure the Feishu-related secrets:

Name	Value
FEISHU_APP_ID	Feishu Open Platform App ID
FEISHU_APP_SECRET	Feishu Open Platform App Secret
FEISHU_USER_ACCESS_TOKEN	User access token (optional)

Search Does Not Work

VitePress generates the local-search index at build time, so make sure that:

1. The documents have sufficient frontmatter (title, description)
2. The build completed without errors

Monitoring

• Cloudflare Analytics: View traffic statistics in the Pages project
• GitHub Actions: View build status on the Actions page
• Cloudflare Status: https://www.cloudflarestatus.com/

Cost

Service	Free Allowance	Estimated Cost for This Project
Cloudflare Pages	500 builds/month, unlimited requests	$0
GitHub Actions	2000 minutes/month	$0
Feishu API	Free	$0
Total		$0/month