Cloudflare Pages Deployment Guide
This guide covers deploying a static site or documentation project (e.g. Docusaurus) to Cloudflare Pages via GitHub integration.
Prerequisites
- A Cloudflare account with access to the dashboard
- A GitHub repository containing your project
- Appropriate permissions to install GitHub Apps in your organization
1. Create a New Cloudflare Pages Application
- Log in to the Cloudflare dashboard.
- Navigate to Build → Compute → Workers & Pages.
- Click Create Application.
- Under the Pages section, click Get started (next to "Looking to deploy Pages?").
- Select Import an existing Git repository → Get started.
2. Connect Your GitHub Repository
- Click Connect GitHub to authorize Cloudflare's GitHub App.
- Select your GitHub organization (e.g.
your-org). - Choose Only select repositories, then select the target repository (e.g.
your-org/your-repo). - Click Install and authorize to grant Cloudflare access.
3. Configure the Build Settings
After connecting your repository, click Begin setup and fill in the build configuration:
| Setting | Value |
|---|---|
| Project name | your-project-name |
| Production branch | main |
| Framework preset | e.g. Docusaurus (select as appropriate) |
| Build command | npm run build |
| Build output directory | /build |
Note: Adjust the framework preset, build command, and output directory to match your project. For example, Next.js uses
.next, and plain HTML projects may not require a build command at all.
Click Save and deploy to trigger the first deployment.
4. Custom Domains (Optional)
Once deployed, Cloudflare assigns a .pages.dev preview URL (e.g. your-project.pages.dev).
To add a custom domain:
- Go to Workers & Pages → your project → Custom Domains tab.
- Click Set up a custom domain.
- Enter your domain and follow the DNS configuration steps.
5. Environment Variables and Secrets
To configure runtime environment variables:
- Go to Workers & Pages → your project → Settings tab.
- Scroll down to Variables and Secrets.
- Add variables as needed:
| Type | Variable Name | Value |
|---|---|---|
| Secret | MY_SECRET_KEY | your-secret-value |
| Text | NODE_ENV | production |
Important: Secrets are encrypted and not visible after saving. Variables take effect on the next deployment — re-deploy if you add them after initial setup.
6. Subsequent Deployments
Cloudflare Pages automatically deploys on every push to the configured production branch (main). Pull requests generate isolated preview deployments with unique URLs, allowing you to review changes before merging.
Troubleshooting
- Build fails: Check the build log in the Deployments tab. Ensure your build command and output directory are correct.
- Missing environment variables: Variables added after a deployment require a re-deploy to take effect.
- GitHub connection issues: Re-authorize via Settings → Builds & deployments → Connected Git repository.