How to deploy a GitHub website to Cloudflare

Before you start

You need the site’s code in a GitHub repository you control and a Cloudflare account of your own. If the repository isn’t yours, start with putting your website’s code in GitHub. Keep the current host running; DNS changes last.

One thing that’s different about Cloudflare: it’s also a DNS provider and a registrar, and its Workers platform expects your domain’s DNS to be at Cloudflare before a custom domain can be attached. If your DNS is elsewhere, that shapes the choice below.

Workers or Pages?

Cloudflare has two ways to host a site from a repository. Workers is its main platform, and Cloudflare’s documentation says to start new projects there: it serves static files and runs server code, and it has the broader feature set. Pages is the older, simpler static-site product, still available. For an owner, the practical difference is the domain:

If your DNS is already on Cloudflare, use Workers. If it isn’t, be clear-eyed: serving the bare domain from Cloudflare, on either product, means the domain’s DNS moves to Cloudflare. Pages lets you avoid that only if www is enough, with a CNAME at your current provider. If you do need to move DNS, do it as its own job with the DNS guide before starting here, not as a step in the domain wizard.

Step 1: Know what kind of site it is

Cloudflare has framework-specific guides rather than a single detector, so it helps to know the framework’s name. Read package.json on GitHub: the dependencies name it (next, vite, astro and so on). A plain Vite or static site is a folder of files after building; a Next.js site with server features needs Cloudflare’s Next.js adapter, which is a developer task. Cloudflare’s framework guides say which case you’re in and what settings each needs. Also find the environment variables, per the secrets guide.

Step 2: Connect the repository

1. In the Cloudflare dashboard, open Workers & Pages, choose Create application, and select Get started next to Import a repository (for Workers), or the Pages tab’s Git connection.
2. Connect GitHub. Cloudflare installs its Workers & Pages GitHub App; when asked, choose Only select repositories and pick the ones it should see.
3. Select the repository and the production branch.

Cloudflare’s documentation says a GitHub account should point to only one Cloudflare account, and doesn’t allow the same repository to be connected from two. If a previous developer already connected it from theirs, that connection has to go first.

Step 3: Build settings and root directory

Cloudflare asks for a build command and, for Workers, a deploy command; for Pages, a build output directory. Pick the framework preset if one is offered, otherwise use the values from Cloudflare’s guide for the framework. If the repository holds more than one app, set the root directory to the folder that contains the website’s package.json.

Workers projects also carry a small configuration file in the repository, wrangler.jsonc or wrangler.toml, that names the Worker and, for static sites, the folder of built files to serve; a site that does its own routing also needs a single-page-application setting in it. The name in that file must match the Worker’s name in the dashboard or the build fails. If the repository doesn’t have one, Cloudflare’s framework guide shows what it needs; a developer or coding agent can write it in a minute. Pages doesn’t need it.

Step 4: Variables and secrets

Cloudflare separates build-time variables, used while the site is being built, from runtime variables and secrets, which the running site reads. Enter values in the place the framework guide says. For anything sensitive, use a secret rather than a plain variable: secrets are encrypted and can’t be viewed again after you save them. On Pages, the equivalent is the Encrypt option when adding a variable.

Step 5: Deploy and test on the provider address

Run the first build. Workers gives the site a workers.dev address and Pages a pages.dev one; Cloudflare recommends running production on a custom domain, but the provider address is exactly right for testing:

From now on, commits to the production branch build and deploy; other branches can produce preview addresses if you enable non-production builds.

Step 6: Add the domain

Workers

In the Worker’s settings, under Domains & Routes, add a custom domain. The domain must already be a zone in this Cloudflare account, and the name can’t already have a CNAME record on it. Cloudflare creates the DNS records and issues the certificate itself; you don’t add records by hand. Add both the bare domain and www if you want both to work.

Pages

In the Pages project, under Custom domains, add the domain. If the domain’s DNS is on Cloudflare, it’s handled automatically. If it’s elsewhere, Cloudflare tells you to add a CNAME pointing at project.pages.dev at your DNS provider, which works for www or any other subdomain. The bare domain is the exception: Cloudflare’s Pages documentation says an apex custom domain must be a zone on your Cloudflare account. Detaching a domain later is done by changing the DNS records, not in the project.

In both cases, add or edit only the website records and leave everything else. The guide to connecting a domain without breaking email covers the capture, the TTLs and the email checks.

Step 7: HTTPS and the proxy

Cloudflare issues certificates automatically for domains on its DNS; it quotes 15 minutes to 24 hours after a domain becomes active. Website records for a Cloudflare-hosted site are proxied, shown with an orange cloud, which is normal and means visitors reach Cloudflare’s network and it serves the site. Verify the bare domain and www load over https, then run the email checks.

Later: pushes, rollbacks and leaving

• Every push to the production branch builds and deploys.
• If a push doesn’t show up on the site, the guide to a website not updating after a deploy traces the change from the edit to the browser; for domain and certificate problems after step 6, see website not showing after a DNS change and HTTPS not working.
• Rolling back: Workers keeps previous versions, up to the last hundred, and rolling back makes one of them the active deployment immediately without changing connected resources. Pages has a “Rollback to this deployment” action on earlier production deployments; previews can’t be rolled back to.
• Adding people: account members with roles; a Super Administrator invites, and there are narrower roles. See the access guide.
• Leaving: follow the host move guide. If your DNS stays at Cloudflare, you edit the website records there to point at the new host and can keep the proxy or turn it off as the new host advises. Then remove the custom domain and delete the project; Pages documents this under the project’s Settings. Moving DNS away from Cloudflare afterwards is a separate nameserver change with the DNS guide’s full-zone procedure.

Checklist

Sources

The rules and product behaviour described above were checked against these pages when the guide was last updated. If something here has changed, these are the places to look.

• Workers Builds · Cloudflare
• Workers Builds: build configuration · Cloudflare
• Workers Builds: GitHub integration · Cloudflare
• Static assets: single-page applications · Cloudflare
• Pages build configuration · Cloudflare
• Pages rollbacks · Cloudflare
• Pages bindings: secrets · Cloudflare
• Proxy status · Cloudflare
• Framework guides · Cloudflare
• Static assets · Cloudflare
• Pages: Git integration · Cloudflare
• Are you sure you want to use Pages? · Cloudflare
• Environment variables · Cloudflare
• Secrets · Cloudflare
• workers.dev · Cloudflare
• Custom domains for Workers · Cloudflare
• Custom domains for Pages · Cloudflare
• Enable Universal SSL · Cloudflare
• Rollbacks · Cloudflare
• Pages Git integration troubleshooting · Cloudflare
• Manage account members · Cloudflare