Pages Deployment

Deploying static sites with wrangler pages deploy

Creating a Pages Project

Before your first deploy, create the project:

npx wrangler@4 pages project create zudo-cloudflare --production-branch=main

Pass --production-branch explicitly — without it, project create needs a production branch and would normally prompt for one interactively. In CI there's no TTY to prompt against, so it doesn't hang: it fails immediately with Must specify a production branch.

For CI pipelines, make the create step idempotent so re-runs don't fail once the project already exists:

set +e
create_output=$(npx wrangler@4 pages project create zudo-cloudflare \
  --production-branch=main 2>&1)
create_exit=$?
set -e

if [ "$create_exit" -ne 0 ]; then
  if echo "$create_output" | grep -qiE "already exists|8000077|duplicate"; then
    echo "Project already exists, continuing."
  else
    echo "$create_output" >&2
    exit "$create_exit"
  fi
fi

Only tolerate the "already exists" family of signatures (already exists, the 8000077 API error code, duplicate). Any other failure — an auth error, a rate limit, a typo'd account ID — should still fail the pipeline instead of being silently swallowed.

Deploy Command

The core deploy command:

npx wrangler@4 pages deploy <directory> \
  --project-name=<project-name> \
  --branch=<branch> \
  --commit-hash="${GITHUB_SHA}" \
  --commit-message="Production deploy: ${GITHUB_SHA}"

Parameters

Environment Variables

The deploy command needs these environment variables:

CLOUDFLARE_API_TOKEN=<your-token>
CLOUDFLARE_ACCOUNT_ID=<your-account-id>

Production vs Preview

• Production: Deploy with --branch=main. This updates the primary URL.

• Preview: Deploy with any other branch name (e.g., --branch=pr-42). This creates a preview URL.

Deploy Directory Structure

The deploy directory must contain the final files as they should be served. If your site uses a base path (e.g., /pj/my-site/), you need to nest files accordingly:

mkdir -p deploy/pj/my-site
cp -r dist/* deploy/pj/my-site/
echo '/ /pj/my-site/ 302' > deploy/_redirects
npx wrangler@4 pages deploy deploy --project-name=my-site --branch=main

See Base Path Pattern for details.

Pages CI Troubleshooting

Common failure signatures when running pages project create / pages deploy in CI, and what actually causes them: