Skip to content

Marketing site on Cloudflare (free plan)

The big picture: Your docs site says a marketing site belongs in its own private repository, on its own host, at the apex domain. This page is the walkthrough: from “I have a product name” to <product>.com serving an Astro site, every MR getting a preview, and production changing only when a person clicks a button.

Why it matters: The steps are short but the order matters. Decide the hosting product before you write any config. Decide the deploy path before you create the repository, or a failed lint will not stop a deploy. Domain and DNS choices are the hardest to undo.

How it works: Cloudflare holds the domain, DNS and hosting. GitLab holds the code and runs the gates. A GitLab CI job builds the site, then uploads it with Wrangler. The recommendation, with the reasons:

  • Hosting: Workers static assets for a new project. A Pages project stays on Pages until you choose to migrate.
  • Deploy path: GitLab CI with Wrangler, not Cloudflare’s Git integration.

1. What “free” covers, and what costs money

Section titled “1. What “free” covers, and what costs money”

Cloudflare’s Free plan covers DNS, the CDN, TLS certificates and static hosting at no cost. Compare the plans on Cloudflare’s plans page and read the hosting limits on the Workers limits and Pages limits pages. This guide quotes no numbers, because they change.

The domain is not free. Cloudflare Registrar sells domains at cost, with no markup, and you pay a yearly renewal at the registry’s price. Budget for that one line item. Everything else in this guide costs nothing on the Free plan, as far as the pages above say today. Check them again before relying on that.

2. Buy the domain and point DNS at Cloudflare

Section titled “2. Buy the domain and point DNS at Cloudflare”
  1. Register at Cloudflare. Follow Register a domain. The DNS zone is created for you.
  2. Or use another registrar. Add the domain to Cloudflare, then change the nameservers at your registrar to the two Cloudflare gives you. That is a full DNS setup. Workers custom domains need Cloudflare to manage the nameservers.
  3. Check three settings on the domain: auto-renew is on (Cloudflare’s Registrar page says domains are enrolled by default), WHOIS redaction is on (also the default there), and DNSSEC is enabled (one click in the dashboard). A lapsed domain takes the site and your email down together.

Checked 2026-10-27. This is moving; re-read the sources before you decide.

Recommendation: Workers static assets for a new project. Astro’s Cloudflare guide states that “Cloudflare recommends using Cloudflare Workers for new projects.” A static site needs no adapter: a Wrangler config points assets.directory at ./dist. Sources: Astro on Cloudflare, Workers static assets and Astro on Workers.

Cloudflare’s migration guide also says Workers has a broader feature set than Pages (Durable Objects, Cron Triggers) and that static asset requests are free on both. Pages keeps two advantages that matter here. It can attach a custom domain that is not in a Cloudflare zone, and it has Branch Deploy Controls. Neither applies if the zone is on Cloudflare, as step 2 sets up.

Visiban and TruePPM run on Pages (see the worked example below). They started there. Staying on Pages is a legitimate choice for them; the recommendation is for a site that doesn’t exist yet.

Migrating an existing Pages site is a config change plus a deploy, then a traffic move. The steps in Cloudflare’s guide, in order:

  1. Add a wrangler.jsonc (or .toml) with a name and compatibility_date, and replace pages_build_output_dir with assets.directory.
  2. Set not_found_handling explicitly if you serve a custom 404 page, and add an .assetsignore file for things like node_modules.
  3. Swap Pages-specific adapters and wrangler pages commands for the Workers ones (wrangler deploy). Move functions/ code as the guide describes.
  4. Deploy, check the Worker, attach the custom domain, then delete the Pages project once all traffic has moved.

Previews work differently: Workers uses preview_urls and version URLs on workers.dev rather than Pages’ <branch>.<project>.pages.dev. The guide above covers it.

  1. Create a separate private GitLab repository, <product>-www.

  2. Run npm create astro@latest. Keep the default static output.

  3. Set site in astro.config.mjs to https://<product>.com, so the sitemap and canonical URLs are right.

  4. Add the Wrangler config for the product you chose in step 3. For Workers:

    wrangler.jsonc
    {
    "name": "<product>-www",
    "compatibility_date": "<today's date>",
    "assets": { "directory": "./dist" },
    "preview_urls": true
    }
  5. Only if the site renders on demand (SSR), add the adapter with npx astro add cloudflare. The Astro guide says the adapter is for on-demand rendering.

  6. Use Blueprint’s conventions in this repository too: make targets for lint, build and test, a changelog fragment per change, and an MR for every change. Start it from its own /kickoff.

Cloudflare Git integration GitLab CI with Wrangler
Who builds Cloudflare, on push Your pipeline
Setup Simplest A token and a few jobs
A failed make lint or test Does not stop the deploy Stops it, if the job is in the deploy job’s needs
Credentials Cloudflare holds repo access A token in GitLab CI variables

Recommendation: deploy from GitLab CI with Wrangler. The Git integration builds outside your pipeline (Workers Builds and the Pages GitLab integration both do), so the gates Blueprint relies on, a green pipeline before anything ships, don’t guard the deploy. Deploying from CI keeps that rule, with one catch: needs bypasses stage order, so a gate stops a deploy only if it is listed in the deploy job’s needs. A lint or test job that is merely in an earlier stage does not hold back a deploy job that needs only build. It costs one token and one template.

How it is set up, following Cloudflare’s GitLab CI/CD guide:

  • Create a custom API token (how) with the Edit Cloudflare Workers permission, scoped to the one account you deploy to. On Pages, the direct-upload guide asks for Account > Cloudflare Pages > Edit.
  • Store it as CLOUDFLARE_API_TOKEN, and the account ID as CLOUDFLARE_ACCOUNT_ID, in GitLab Settings > CI/CD > Variables. Mark both masked. Mark the token protected, so only pipelines on protected refs (main) can read it. Never commit either value.
  • Previews need their own token. A protected variable is invisible to an MR pipeline on an unprotected branch. Recommended: a second, narrowly scoped token for the preview job only (masked, not protected, same single account), and never unprotect the production token. The cost: any MR author can read that token, so keep MR pipelines to people you trust. The alternative is a protected branch pattern for previews, which keeps one token but means previews exist only for those branches.
  • Copy ci/cloudflare-deploy.yml into the marketing repository. It is entirely commented out, so it changes nothing until you uncomment and adapt it.

The template builds this shape:

  1. A preview per MR. A job uploads a version with wrangler versions upload --preview-alias mr-<iid>, which returns a URL on workers.dev (previews). The job registers it as a GitLab environment, so the URL appears on the MR. It uses the separate preview token from step 5.
  2. main goes to staging automatically, with the alias staging.
  3. Production is a manual, protected job that runs wrangler deploy after someone has looked at staging. Protect the production environment so only the right people can run it.

Version URLs are public unless protected. To keep unreleased copy private, put previews and staging behind Cloudflare Access. Visiban and TruePPM don’t, from what their pipelines show.

  1. Add the apex <product>.com as a custom domain on the Worker (or the Pages project). Cloudflare creates the DNS record and certificate. See Pages custom domains or Workers custom domains.
  2. Redirect www to the apex (or the reverse) with a single redirect, so there is one canonical address. Match it to site in astro.config.mjs.
  3. Serve HTTPS only: turn on Always Use HTTPS. Enable HSTS only after you have verified HTTPS works on every host, because browsers remember it.
  4. Keep the docs where they are. docs.<product>.com still points at GitLab Pages (A custom domain). Both sites share one Cloudflare DNS zone on different hosts. For the GitLab Pages CNAME and its TXT verification record, a safe default is DNS only (grey cloud) while GitLab verifies the domain and issues its own certificate. GitLab’s Pages TLS documentation covers Cloudflare in front of Pages: “If you use Cloudflare CDN in front of GitLab Pages, set the SSL connection setting to full instead of flexible.” So the proxied option works only with Cloudflare’s SSL/TLS mode on Full. Read that page before choosing it.
  • Web Analytics: privacy-friendly traffic numbers without a cookie banner.
  • Email Routing: forward hello@<product>.com to a real inbox.
  • A cache rule for fingerprinted assets, so the CDN keeps them (see Cache Rules).

Both marketing sites were read from their repositories (visiban-www and trueppm-web) on 2026-10-27. Both run the same setup:

  • Hosting: Cloudflare Pages, an Astro site with wrangler.toml using pages_build_output_dir = "dist". Neither has moved to Workers.
  • Deploy path: GitLab CI with Wrangler direct upload, not the Git integration. The token and account ID are two CI/CD variables.
  • What gates a deploy: the deploy jobs need the build job and the OSV dependency scan (security:osv), and production also needs the staging job. astro check runs in an earlier stage but is not in any deploy job’s needs, so a failed type check does not hold back a deploy. This is the catch described in step 5.
  • Token protection: not visible from the pipelines. Whether the variables are masked or protected is a project setting, so the guide does not claim either.
  • Staging: every push to the default branch deploys dist/ with wrangler pages deploy dist --branch staging, to a staging.<project>.pages.dev address, registered as a staging GitLab environment.
  • Production: a manual job on the default branch, wrangler pages deploy dist without a branch, needing the staging job first. Its environment URL is the apex domain.
  • Previews: TruePPM has a job per non-default branch that deploys with --branch "$CI_COMMIT_REF_SLUG" to <branch>.<project>.pages.dev. Both sites also expose the built dist/ as a downloadable MR artifact (expose_as: "Site preview").

What differs from the recommendation: they use Pages instead of Workers, and as far as the pipelines show, nothing puts the preview or staging addresses behind Access. The template here uses MR aliases and wrangler deploy as the Workers equivalents.