Surface CMSDocs
Integration guide

Cloudflare

Connect Cloudflare when you want Surface to add provider-owned deployment evidence to your Git-backed publishing workflow. The integration is optional: your website remains fully usable in Surface without it.

What the integration does

Git and GitHub remain authoritative for repository content, branches, pull requests, merge history, and saved work. Cloudflare remains authoritative for its builds, deployments, and production serving state.

With a connection, Surface can enrich the Library, Publishing Timeline, and work-session status with bounded evidence for the configured target. Surface reads the target, build, and deployment information needed to determine status. It does not mutate the provider as part of this flow: no Cloudflare project or deployment is created, deleted, redeployed, or reconfigured.

Before you start

  • You must be a Surface account Owner or Admin to manage the durable account connection.
  • Open Account Integrations at/accounts/<accountSlug>/integrations.
  • Choose the target type you use: Cloudflare Pages orCloudflare Workers. They are distinct target types.
  • For Workers, create a user-scoped Cloudflare API token. Scope its account and resources as narrowly as Cloudflare permits.

The Workers permission recipe below does not apply automatically to Pages. For a Pages target, follow the permissions requested by Surface during in-product setup.

Cloudflare Workers permissions

For the currently supported Workers deployment-status contract, use auser-scoped Cloudflare API token and grant it exactly:

  • Workers Scripts — Read
  • Workers Builds Configuration — Edit

Scope the token as narrowly as Cloudflare permits. Cloudflare currently requires the broader Builds capability for the read contract Surface needs, so the provider credential is not literally read-only.

Surface itself uses the credential only for boundedGET/read-only requests. Surface does not expose Worker build, deployment, or configuration mutation merely because the token could authorize it.

Connect Cloudflare in Surface

  1. As an Owner or Admin, open Account Integrations at/accounts/<accountSlug>/integrations.
  2. Follow the Cloudflare setup and provide the appropriately scoped API token.
  3. Choose Cloudflare Pages or Cloudflare Workers, then identify the intended target.
  4. Bind that target to the appropriate Surface workspace.

Keep secrets out of URLs, screenshots, sample code, logs, and diagnostics.

How deployment status works

Saved or merged work is not automatically Live. Surface reports Live only when current production evidence supports that claim.

For Workers, Surface correlates the tracked repository, branch, root, and Worker identity to exact build evidence. It then joins the active serving Worker versions to their build and commit evidence. The tracked production commit must unambiguously account for 100% of non-zero serving traffic before Surface reports Live.

A successful build alone is not enough. Mixed rollouts, unrelated active commits, serving versions that cannot be mapped, and successful but inactive builds do not appear Live.

In pull-request workflows, an open PR head is not a production subject. After a merge, squash, or rebase, Surface uses GitHub's verified resulting merge commit as the publication subject.

When provider evidence is unavailable

No Cloudflare integration is a healthy, supported posture. If provider evidence is absent or temporarily unavailable, Surface's Git and GitHub publishing truth remains useful. Missing deployment evidence is not automatically a deployment failure, and Surface does not fabricate a Live state.

Unbind or disconnect

One account Cloudflare Integration can be shared by multiple workspace bindings. Unbinding one workspace removes that binding but does not revoke the shared account credential.

Account-level disconnect removes Surface-held authority and dependent bindings. It does not delete external Cloudflare projects, builds, deployments, or other provider resources.

Troubleshooting

  • If deployment evidence is missing, continue using Surface's Git-backed CMS workflow while checking the provider connection. An unavailable provider is not automatically a failed deployment.
  • If the token was revoked, expired, replaced, or no longer has the required scope, an Owner or Admin should return to Account Integrations and repair or replace the connection.
  • Never put the token or other secrets in URLs, screenshots, sample code, logs, or diagnostics.