Guide
Worker secrets and variables
Where the secrets and variables of the worker templates are set, and which
names each template reads. Secrets never go in .ssg.yaml; the build only
wires the code in (WORKERS-CONFIGURATION).
Which template does what is in WORKERS.
Where they are set
Secrets never live in .ssg.yaml or in the Function source — set them per Pages
project with wrangler:
1wrangler pages secret put STRIPE_SECRET_KEY
2wrangler pages secret put CONTACT_TURNSTILE_SECRET
The Function reads them from its env binding at runtime.
One project, one environment: prefix your secrets
Cloudflare Pages gives a project one set of variables and secrets, and every
worker merged into that project's functions/ tree reads all of it. A secret
set for one template is therefore visible to every other — and a template that
reads an unprefixed name picks up a value meant for someone else.
That is how a shared TURNSTILE_SECRET used to break the cookie-consent audit
log: set for contact-form or comments, it switched Turnstile verification on
in cookie-consent too, whose banner never sends a token, so every consent
record was dropped with {"ok":true,"stored":false} (#325).
Each template now reads its own prefixed name first:
| Template | Turnstile secret | Falls back to TURNSTILE_SECRET? |
|---|---|---|
contact-form |
CONTACT_TURNSTILE_SECRET |
yes — existing projects keep working |
comments |
COMMENTS_TURNSTILE_SECRET |
yes — existing projects keep working |
newsletter |
NEWSLETTER_TURNSTILE_SECRET |
yes |
auth |
AUTH_TURNSTILE_SECRET (after repeated failed logins) |
yes |
cookie-consent |
CONSENT_TURNSTILE_SECRET (opt-in, audit log only) |
no — the shared name is ignored |
The fallback means nothing changes for a project that already sets
TURNSTILE_SECRET for its contact form or comments, except that the consent log
starts storing records again. New projects should set the prefixed names. The
same rule applies to anything that switches behaviour on: the newsletter's
double opt-in keys (NEWSLETTER_RESEND_API_KEY, NEWSLETTER_MAILCHANNELS_API_KEY)
deliberately have no unprefixed fallback.
newsletter-ui is a separate Worker, so it has its own environment: set its
secrets with wrangler secret put (not wrangler pages secret put) from
workers/newsletter-ui/. It reads the same names as the newsletter
admin, so one set of values serves both:
| Template | Secret / variable | Purpose |
|---|---|---|
newsletter-ui |
NEWSLETTER_ADMIN_PASSWORD (secret) |
HTTP Basic admin password, when Access is not used |
newsletter-ui |
NEWSLETTER_ACCESS_TEAM + NEWSLETTER_ACCESS_AUD (vars) |
Cloudflare Access instead of a password |
newsletter, newsletter-ui |
NEWSLETTER_AUTH_ISSUER, _LOGIN_URL, _PUBLIC_KEY or _JWKS_URL, _AUDIENCE (vars) |
accounts of the auth worker with per-action permissions (newsletter:read, :edit, :send, …) and, in newsletter-ui, an audit trail; checked after Access, before the password, which is then not accepted |
newsletter-ui |
NEWSLETTER_AUDIT_RETENTION_DAYS (var) |
days the admin audit trail keeps a row, default 365, 0 = forever |
newsletter-ui |
NEWSLETTER_HASH_SALT (secret, optional) |
salts the short-lived failed-login records |
newsletter-ui |
NEWSLETTER_UI_BASE (var) |
path prefix, default /newsletter-admin |
newsletter, newsletter-ui |
NEWSLETTER_SMTP_PASSWORD (secret) + NEWSLETTER_SMTP_HOST, _PORT, _USER, _HELO (vars) |
your own SMTP server as the mail transport, used when neither provider key is set (order: Resend → MailChannels → SMTP); port 465 or 587, never 25 |
newsletter-ui |
NEWSLETTER_RESEND_WEBHOOK_SECRET, NEWSLETTER_MAILCHANNELS_WEBHOOK_KEY (secrets) |
verify the bounce/complaint webhooks |
The full list of newsletter-ui variables (send rate, batch size, click
counting, feed URL, …) is the "Configuration" table in
its README.
The admin sign-in settings of the other templates, and the secrets of auth
and core (both Pages Functions: wrangler pages secret put):
| Template | Secret / variable | Purpose |
|---|---|---|
comments |
COMMENTS_ADMIN_PASSWORD (secret) |
shared-password moderation |
comments |
COMMENTS_ACCESS_TEAM + COMMENTS_ACCESS_AUD (vars) |
Cloudflare Access |
comments |
COMMENTS_AUTH_ISSUER, _LOGIN_URL, _PUBLIC_KEY or _JWKS_URL, _AUDIENCE (vars) |
auth accounts: comments:read, :moderate, :delete, :import |
newsletter |
NEWSLETTER_ADMIN_PASSWORD (secret), NEWSLETTER_ACCESS_TEAM + _AUD, NEWSLETTER_AUTH_* (vars) |
the same three modes, the same names as newsletter-ui |
core |
CORE_ADMIN_PASSWORD (secret) |
shared password, with a per-IP lockout (CORE_LOGIN_MAX_FAILURES, CORE_LOGIN_WINDOW_MINUTES) |
core |
CORE_ACCESS_TEAM + CORE_ACCESS_AUD, CORE_AUTH_ISSUER, _LOGIN_URL, _PUBLIC_KEY or _JWKS_URL, _AUDIENCE (vars) |
Cloudflare Access; auth accounts, each seeing only the modules it may open |
core |
CORE_DB (D1), CORE_LOGIN_LIMITER (rate limit) (optional bindings) |
module management and a lockout shared by all isolates; a ceiling on password attempts |
web-push |
PUSH_AUTH_ISSUER, _LOGIN_URL, _PUBLIC_KEY or _JWKS_URL, _AUDIENCE (vars) |
accept auth service tokens holding web-push:notify; PUSH_KEY keeps working |
republish-trigger |
REPUBLISH_AUTH_ISSUER, _LOGIN_URL, _PUBLIC_KEY or _JWKS_URL, _AUDIENCE (vars) |
accept auth service tokens holding republish-trigger:run; REPUBLISH_KEY keeps working |
auth |
AUTH_SIGNING_KEY (secret, required) |
the private signing key from node workers/auth/scripts/auth-keys.mjs |
auth |
AUTH_BOOTSTRAP_TOKEN (secret) |
creates the first owner once; delete it afterwards |
auth |
AUTH_MFA_KEY (secret) |
switches the second factor on and encrypts the authenticator secrets; AUTH_MFA_KEY_PREVIOUS during a rotation, AUTH_MFA_RESET_TOKEN for a sole owner's break-glass |
auth |
AUTH_HASH_SALT, AUTH_TURNSTILE_SECRET (secrets) |
salted IP/User-Agent hashes; Turnstile after repeated failures |
auth |
AUTH_<PROVIDER>_CLIENT_SECRET, AUTH_APPLE_PRIVATE_KEY (secrets) with AUTH_<PROVIDER>_CLIENT_ID (vars) |
sign-in through Google, Microsoft, GitHub, Facebook, Apple |
auth |
AUTH_RESEND_API_KEY, AUTH_MAILCHANNELS_API_KEY or AUTH_SMTP_PASSWORD (secrets) with AUTH_MAIL_FROM |
invitation and reset mail; without a transport the link is shown to the administrator |
Every auth variable is in the "Configuration" section of
its README and in its
wrangler.snippet.toml; core's in its README.