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”- Register at Cloudflare. Follow Register a domain. The DNS zone is created for you.
- 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.
- 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.
3. Pick the hosting product first
Section titled “3. Pick the hosting product first”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:
- Add a
wrangler.jsonc(or.toml) with anameandcompatibility_date, and replacepages_build_output_dirwithassets.directory. - Set
not_found_handlingexplicitly if you serve a custom 404 page, and add an.assetsignorefile for things likenode_modules. - Swap Pages-specific adapters and
wrangler pagescommands for the Workers ones (wrangler deploy). Movefunctions/code as the guide describes. - 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.
4. Create the Astro site
Section titled “4. Create the Astro site”-
Create a separate private GitLab repository,
<product>-www. -
Run
npm create astro@latest. Keep the default static output. -
Set
siteinastro.config.mjstohttps://<product>.com, so the sitemap and canonical URLs are right. -
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} -
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. -
Use Blueprint’s conventions in this repository too:
maketargets for lint, build and test, a changelog fragment per change, and an MR for every change. Start it from its own/kickoff.
5. Deploy from GitLab: two options
Section titled “5. Deploy from GitLab: two options”| 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 asCLOUDFLARE_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.ymlinto the marketing repository. It is entirely commented out, so it changes nothing until you uncomment and adapt it.
6. Preview, then staging, then production
Section titled “6. Preview, then staging, then production”The template builds this shape:
- A preview per MR. A job uploads a version with
wrangler versions upload --preview-alias mr-<iid>, which returns a URL onworkers.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. maingoes to staging automatically, with the aliasstaging.- Production is a manual, protected job that runs
wrangler deployafter someone has looked at staging. Protect theproductionenvironment 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.
7. Attach the domain
Section titled “7. Attach the domain”- Add the apex
<product>.comas 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. - Redirect
wwwto the apex (or the reverse) with a single redirect, so there is one canonical address. Match it tositeinastro.config.mjs. - Serve HTTPS only: turn on Always Use HTTPS. Enable HSTS only after you have verified HTTPS works on every host, because browsers remember it.
- Keep the docs where they are.
docs.<product>.comstill points at GitLab Pages (A custom domain). Both sites share one Cloudflare DNS zone on different hosts. For the GitLab PagesCNAMEand itsTXTverification 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 tofullinstead offlexible.” So the proxied option works only with Cloudflare’s SSL/TLS mode on Full. Read that page before choosing it.
8. Free extras worth turning on
Section titled “8. Free extras worth turning on”- Web Analytics: privacy-friendly traffic numbers without a cookie banner.
- Email Routing: forward
hello@<product>.comto a real inbox. - A cache rule for fingerprinted assets, so the CDN keeps them (see Cache Rules).
Worked example: Visiban and TruePPM
Section titled “Worked example: Visiban and TruePPM”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.tomlusingpages_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
needthe build job and the OSV dependency scan (security:osv), and production also needs the staging job.astro checkruns in an earlier stage but is not in any deploy job’sneeds, 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/withwrangler pages deploy dist --branch staging, to astaging.<project>.pages.devaddress, registered as astagingGitLab environment. - Production: a manual job on the default branch,
wrangler pages deploy distwithout 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 builtdist/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.