---
name: github-cloudflare-pages
description: Deploy static websites and serverless Functions to Cloudflare Pages via GitHub. Use to set up automated publishing from private/public GitHub repositories, configure build settings, create edge Functions, and manage deployments. Covers Cloudflare Pages API operations, Git integration, path-watching configurations, and automatic branch deployments.
---

# GitHub + Cloudflare Pages

This skill enables deployment of static sites and serverless Functions to Cloudflare Pages using Git integration with GitHub. It automates Pages project creation, configures automatic deployments from GitHub branches, and manages Function routing.

## When to Use

- Setting up Cloudflare Pages projects connected to GitHub repositories
- Configuring automatic deployments when code is pushed to GitHub
- Adding or modifying Cloudflare Pages Functions (edge serverless functions)
- Managing build configurations, path watching, and environment variables
- Automating the initial setup for static sites, React apps, or custom HTML with edge logic

## Core Workflow

### 1. Prepare GitHub Repository

1. Create or identify a GitHub repository (public or private)
2. Push initial site content (`index.html`, static assets, etc.)
3. Ensure the `main` (or desired production) branch exists and contains your latest code
4. Note: Cloudflare will require you to authorize the GitHub App on your account (happens via browser during first connection)

### 2. Enable Cloudflare Connector

Use `manus-config connector ensure Cloudflare` to verify your Cloudflare account is connected. If not already enabled, run:

```bash
manus-config connector enable Cloudflare
```

### 3. Create Pages Project and Connect GitHub

Use the Cloudflare API to:
- Create a new Pages project
- Connect a GitHub repository as the source
- Configure build settings (build command, output directory)
- Set production branch (usually `main`)
- Configure path watching (which file changes trigger deployments)

See **Automated Setup** below for script-based approach.

### 4. Push to GitHub and Verify Deployment

After connecting:

1. Make a change to your repository on the production branch
2. Push to GitHub
3. Cloudflare will automatically detect the push and deploy your changes
4. Check the deployment status in Cloudflare dashboard or via API

## Automated Setup

**Script**: `scripts/setup_github_pages.py`

This Python script automates the Pages project creation and GitHub connection. It requires:

- Cloudflare API token (in environment or via `manus-config`)
- GitHub repository owner and name
- GitHub repository ID (obtain via `gh api repos/<owner>/<repo> --jq '.id'`)
- Desired project name (defaults to repository name)

**Usage:**

```bash
python scripts/setup_github_pages.py \
  --account-id YOUR_ACCOUNT_ID \
  --repo-owner github-username \
  --repo-name my-repo \
  --repo-id NUMERIC_ID \
  --project-name my-pages-project
```

The script:
- Creates a Cloudflare Pages project
- Connects the GitHub repository as a source
- Configures standard build settings (static HTML at repo root)
- Enables production deployments on the `main` branch
- Disables preview branch deployments by default

## Manual Configuration via Cloudflare Dashboard

1. Go to [Cloudflare Dashboard](https://dash.cloudflare.com/) → **Workers & Pages**
2. Click **Create application** → **Pages** → **Connect to Git**
3. Authorize and select your GitHub repository
4. Configure:
   - **Project name**: Used for your Pages URL (`{project-name}.pages.dev`)
   - **Production branch**: Usually `main`
   - **Build command**: Leave blank for static HTML, or specify for frameworks
   - **Build output directory**: `.` for static files at root, `/dist` for build output
5. Click **Save and Deploy**

## Build Watch Paths

By default, all files in the repository trigger a deployment. To limit deployments to specific directories (e.g., monorepo):

- Go to **Settings** → **Build** → **Build watch paths**
- **Include paths**: Glob patterns to watch (e.g., `src/*`, `*.md`)
- **Exclude paths**: Patterns to ignore (e.g., `docs/*`, `*.test.js`)

**Glob syntax**: `*` matches zero or more characters, including `/`. Examples:
- `src/*` matches `src/index.js` and nested `src/app/config.ts`
- `*.md` matches `README.md` and `docs/GUIDE.md`
- `*` (alone) matches all files

**Important**: If you programmatically set `path_includes: []`, all pushes will be skipped. Use `path_includes: ["*"]` to watch all files.

## Environment Variables

Set environment variables for your build or runtime:

1. **Dashboard**: Pages project → **Settings** → **Environment variables**
2. **API**: Use the Cloudflare API to configure environment variables for production/preview deployments

Example (via API):
```json
{
  "env_vars": {
    "API_URL": "https://api.example.com",
    "DEBUG": "false"
  }
}
```

## Functions (Edge Serverless)

Add serverless Functions to handle dynamic routes:

**File structure:**
```
functions/
├── api/
│   ├── users.js        → Handles requests to /api/users
│   └── posts/[id].js   → Handles /api/posts/:id
└── middleware.js        → Middleware for all routes (optional)
```

**Function example:**
```javascript
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    return new Response(`Hello from ${url.pathname}`);
  }
};
```

Functions have access to:
- `request` — The incoming HTTP request
- `env` — Environment variables and bindings (KV, D1, R2, etc.)
- `ctx` — Execution context (for background tasks)

For more details, see **References: Cloudflare Functions** below.

## Troubleshooting

**Deployment is skipped:**
- Check **Build watch paths** are correctly configured (include paths should include the files you changed)
- Verify `path_includes` is not empty (`[]`); use `["*"]` to watch all files

**Function not responding:**
- Ensure Functions are in the `functions/` directory with correct file structure
- Check file exports a default object with a `fetch` method
- Verify file extensions are `.js` or `.ts`

**Build fails:**
- Check build command is correct for your framework (or leave blank for static HTML)
- Verify build output directory is correct (e.g., `/dist` for most frameworks, `.` for static files)
- Check build logs in Cloudflare dashboard

**GitHub connection lost:**
- Re-authorize the Cloudflare GitHub App through the dashboard
- Or disconnect and reconnect the Pages project source

## Key Differences: GitHub Pages vs. Cloudflare Pages

| Feature | GitHub Pages | Cloudflare Pages |
|---------|---|---|
| **Hosting** | GitHub servers | Cloudflare global network |
| **Custom Functions** | No (static only) | Yes, via Functions |
| **Environment variables** | No | Yes |
| **Build command** | Jekyll only | Any build tool |
| **Edge execution** | No | Yes (Cloudflare Workers runtime) |
| **Custom domains** | Supported | Supported |

## References

- **[Cloudflare Setup & API Details](references/cloudflare-setup.md)** — API endpoints, authentication, detailed configuration examples
- **[Function Routing & Bindings](references/functions-reference.md)** — Function file structure, routing syntax, accessing bindings

## Templates

- `templates/index.html` — Minimal HTML starter for static sites
- `templates/function-api.js` — Template for a Functions endpoint
- `templates/README.md` — Boilerplate README for your Pages project

Use these as starting points when creating a new site or Function.