repomatic.cloudflare.pages module¶

Reconcile a Cloudflare Pages project against the state its repository declares.

A Direct Upload project is not reproducible from anything committed: wrangler.toml only describes what a build would need, and these projects are never built by Cloudflare. Everything that actually shapes the live site (the compatibility date, Smart Placement, the build image, whether a git source got attached) lives server-side in the project’s deployment_configs and is invisible to anyone reading the repository. One project’s compatibility date sat three years behind the live value with nothing noticing. This module makes that state explicit, diffable and re-applicable, from the [tool.repomatic] site.* keys.

Backs the cloudflare-pages command, in the modes of PagesMode. repomatic.cloudflare.api resolves the credential and the account.

repomatic.cloudflare.pages.MISSING: Final = <object object>¶

What a lookup in the live project answers when the path names nothing.

repomatic.cloudflare.pages.SECRET_KEYS: Final = frozenset({'api_token', 'oauth_token', 'refresh_token', 'secret'})¶

Response keys whose values must never be printed.

class repomatic.cloudflare.pages.PagesMode(*values)[source]¶

Bases: StrEnum

What one run of cloudflare-pages does, named after its flag.

APPLY = 'apply'¶

Write every managed drifted setting back to its declared value.

ATTACH_DOMAIN = 'attach-domain'¶

Serve the project at a custom domain, DNS record included.

CHECK = 'check'¶

Diff the live project against the declared state.

CREATE = 'create'¶

Create the project when missing, then apply the declared settings.

DUMP = 'dump'¶

Print the live project state as JSON, secrets redacted.

property writes: bool¶

Whether the mode writes the declared settings to the live project.

class repomatic.cloudflare.pages.Setting(path, desired, default, why, verified=False, managed=True)[source]¶

Bases: object

One server-side setting, with enough context to justify its value.

Where the stock default is quoted from Cloudflare’s documentation, verified is true. Where it is inferred from how the product behaves, it is false and the diff labels it as such: an unverified default is a reasonable guess, not a fact, and this module should not launder one into the other.

path: tuple[str, ...]¶

Keys leading to the value in the project object.

desired: Any¶

The value the repository declares.

default: Any¶

What a stock Cloudflare Pages project reports for this key.

why: str¶

Why the value matters, printed beside a drift.

verified: bool = False¶

Whether default is quoted from Cloudflare’s documentation.

managed: bool = True¶

Whether --apply writes the value, or only reports its drift.

describe()[source]¶

Name the setting, its scope and how sure its stock default is.

Return type:

str

repomatic.cloudflare.pages.desired_settings(compatibility_date='', placement='')[source]¶

The settings to enforce, from the repository’s site.* declarations.

Only what the repository declares is managed, plus one documented floor: the build image major version, which Cloudflare auto-migrates old projects onto (v1 on 2026-09-15, v2 on 2027-02-23) and then freezes, so asserting 3 requests nothing from a current project and names the stragglers.

Pages supports exactly production and preview, so the two environments are enumerated rather than globbed, and every managed setting applies identically to both.

Parameters:

  • compatibility_date (str) – site.cloudflare-compatibility-date, empty to leave the live value unmanaged.

  • placement (str) – site.cloudflare-placement, empty to leave the live value unmanaged.

Return type:

tuple[Setting, ...]

repomatic.cloudflare.pages.run_cloudflare_pages(project, mode, *, domain='', compatibility_date='', placement='')[source]¶

Drive one mode of the Pages reconciliation against project project.

--create makes the project when it does not exist yet (Direct Upload, main as its production branch), then applies the declared settings to it like --apply does. Read-only drift is reported by every mode, and keeps the exit code non-zero.

Parameters:

  • project (str) – Cloudflare Pages project name to reconcile.

  • mode (PagesMode) – What to do with the project.

  • domain (str) – The hostname PagesMode.ATTACH_DOMAIN serves the project at, creating the DNS record it needs when the credential can.

  • compatibility_date (str) – Declared Workers runtime date, empty for unmanaged.

  • placement (str) – Declared Smart Placement mode, empty for unmanaged.

Return type:

int

Returns:

Exit code: 0 clean, 1 drift found (or left, for the read-only settings no write can change).