The Deploy button flow - what a deploy builds, deploy statuses, when a redeploy is required, and how the first deploy differs from updates.
Loading the guide...
Help us make the guides more useful.
0 helpful · 0 not helpful
A deploy rebuilds one client site as fast static pages and ships it to that client's Cloudflare Pages project. Deploys are always manual: nothing you publish, save, or schedule reaches the live site until someone presses Deploy. (If that surprises you, read Preview, Publish, and Deploy first.)
The clip above tours one deployed site end to end - hero, services, gallery, testimonials, estimate form, and blog roll, all real content shipped as static pages.
Every site's portal sidebar has a Deploy button. It reflects the site's current state:
| Button state | Meaning |
|---|---|
| Deploy (highlighted) | There are published changes newer than the last deploy - the live site is behind |
| Deploying... (disabled) | A deploy is running right now |
| Deploy failed - retry | The last deploy did not finish; press to try again |
| Up to date (disabled) | Nothing has been published since the last successful deploy |
The portal tracks whether anything changed since the last successful deploy, so a highlighted Deploy button is your "the live site is stale" signal.
Deploy permission is a per-user, per-site setting, independent of content roles - see Users and Roles. The operator can always deploy. If a site's billing is past due with enforcement active, client deploys are blocked until billing is resolved (the operator can still deploy).
Pressing Deploy dispatches the site's build pipeline. In order, it:
[AI-PROMPT] placeholder, stops the deploy before anything is built, and the run's log names each page and the problem. Blocks you have switched off in the builder are skipped. Drafts are not checked, so a fix counts only once you publish it.robots.txt, your configured redirects, and the 404 handling for the site.Each client site has its own Cloudflare Pages project (created automatically when the site is created), so one client's deploy never touches another client's site.
Each site carries a deploy status you can see in the portal:
| Status | Meaning |
|---|---|
| Pending | Created but never deployed |
| Building | A deploy is in progress |
| Live | The last deploy succeeded |
| Failed | The last deploy errored - fix and retry |
A successful deploy also stamps the site's last deployed time, which is what the Deploy button compares against to decide whether the site needs a redeploy.
A deploy that reports Building forever has usually lost its status callback rather than actually still running. Once a build has been sitting there long enough that it cannot plausibly still be in progress, the Deploy button becomes available again so you can retry, instead of the site being wedged until someone intervenes in the database.
If a deploy's status callback fails outright, you get a warning rather than silence, so a build whose result never came back is visible instead of looking like it is still going.
Any change that should show on the live site requires a deploy after it. That includes:
A good habit: batch your edits, publish everything, then do one deploy at the end of the session.
First deploy. A brand-new site deploys to its Cloudflare Pages preview address (<project>.pages.dev). That address is intentionally kept out of search engines until the site has a real domain, so you can review a not-yet-launched site safely. See Hosting and Domains.
Go-live. Set the site's custom domain and deploy. From then on the preview address permanently redirects to the real domain.
Updates. Every later deploy replaces the whole static artifact atomically. There is no partial state: visitors see the old site until the new build ships, then the new one.
| Problem | Likely cause |
|---|---|
| "The live site doesn't show my change" | The change was published but not deployed, or the deploy is still building |
| Deploy says the site has no Cloudflare Pages project | Pressing Deploy retries creating it, and the message names the cause, usually CF_API_TOKEN or CF_ACCOUNT_ID missing or wrong on the cms service. Fix it, redeploy the cms service, and press Deploy again |
| Deploy failed - retry | Open the deploy workflow logs (linked from the portal after dispatch) to see the build error, fix, and retry |
| The run failed with Deploy BLOCKED in its log | A published page has a content error, and the log lists each page with a reason code. Fix it in the builder, publish the page, and deploy again. Switched-off blocks are not checked |
| The Deploy button says Up to date after you set a custom domain | Saving the domain is not a content change. Open a page that is already published and has no unpublished edits, open its three-dot menu, choose Settings, and click Save & deploy. Save & deploy publishes the page it is on, so never use it on a draft |
| Stuck at Building and never finishing | The status callback was lost. Wait for the Deploy button to free up, then retry - see above |
| A client cannot press Deploy | Their per-site deploy permission is off, or billing enforcement is active |