Worker secrets and vars

Status

Current

Reviewed

October 14, 2026

Cadence

Review after a Cloudflare deploy or secret-handling change

This page is the fleet source for Wrangler secrets and plain vars when Workers Builds owns production deploy.

Names only

This page lists secret names and ownership rules. It does not publish live values, dashboard inventories, or operator tokens.

Secrets vs plain vars

A secret is an encrypted Worker binding. A plain var is an unencrypted environment value. Do not put secret-looking keys in vars.

Build-time Packages auth (NODE_AUTH_TOKEN, NPM_CONFIG_USERCONFIG) lives on the Worker trigger under Settings → Build → Build variables and secrets. Those values are not Worker runtime secrets. Do not put NODE_AUTH_TOKEN in secrets.required. See docs/private-package-distribution.md.

Secrets

• Survive every deploy, with or without keep_vars.
• Commit names only, in secrets.required. Never values.
• Set production values in the Cloudflare dashboard or a documented break-glass operator path.

Plain vars

• Steady state: every non-secret plain var lives in committed config vars or env-specific blocks. Config is the source of truth.
• Default deploy deletes remote vars, then writes config vars.
• Dashboard-only plain vars are a migration smell, not the end state.
• keep_vars is short-lived. Use it only while you copy dashboard-only plain vars into config. Then remove keep_vars.
• Tests and local .dev.vars can supply examples.

secrets.required

Every Worker that uses secrets must declare those names in the current Wrangler schema. Commit names only.

{
  "secrets": {
    "required": ["EXAMPLE_API_TOKEN"],
  },
}

wrangler deploy and wrangler versions upload fail closed when a required secret is missing on the Worker. wrangler types uses secrets.required as the name source. It does not need a local .dev.vars file.

Fleet exemplar: botmail-worker pull request 6.

Config-owned plain vars

Put every non-secret plain var in committed Wrangler vars or env-specific blocks. On the cf path, put those keys in cloudflare.config.ts. Config is the source of truth.

Do not leave production plain vars only in the dashboard. Do not commit example or placeholder values for those keys. Example values in config overwrite production on the next deploy.

Transitional keep_vars

keep_vars and --keep-vars are deprecated as a fleet pattern. Use them only on transitional Wrangler configs while you copy dashboard-only plain vars into config. Then remove keep_vars.

keep_vars still writes every var that appears in config. Committed vars still overwrite dashboard values for those keys.

keep_vars does not protect secrets. Secrets survive every deploy. Do not set keep_vars because the Worker has secrets.

cf has no keep_vars. cf migrate does not convert it. Move plain vars into config instead of depending on keep_vars. Do not invent a cf deploy keep-vars flag.

Known fleet leftovers. Move these plain vars into config, then drop keep_vars:

• wkd-proxy-worker production DOMAINS
• zuricert testmail plain vars
• personal-finance processor Access dashboard vars

Local and examples

Add .dev.vars and any secrets-file to .gitignore. Never commit those files.

Commit .dev.vars.example with placeholders only:

EXAMPLE_API_TOKEN=

Do not put real values in comments, pull requests, or example files. Do not commit --secrets-file input.

When secrets.required is set, local wrangler dev loads only those names from .dev.vars. Missing names log a warning.

Workstation Keychain and direnv stay in docs/secrets-direnv-standard.md in MNPPI/org-standards. They do not replace Cloudflare Worker secrets.

Deploy ownership

Workers Builds owns production and staging Worker deploy. GitHub Actions validates the pull request. Merge is not deploy.

Do not run workstation wrangler deploy against production. Do not store routine Cloudflare deploy tokens in GitHub. Do not use GitHub Actions wrangler secret put as the normal path while Builds also deploys. That is dual ownership. Reserve wrangler secret put for a documented break-glass step.

See Cloudflare deployment and docs/workers-builds-migration-pattern.md in MNPPI/org-standards.

Anti-patterns

Do not

Using keep_vars because “we have secrets” is unnecessary. Secrets survive deploy. Do not treat keep_vars as the steady state for dashboard-only plain vars. Do not commit CMS_API_KEY-style values in vars. Do not run GitHub Actions wrangler secret put on every release while Workers Builds also deploys. Do not put example values of production plain vars into config. Do not recommend a fleet cutover to bare cf deploy from this page. Do not invent cf keep-vars flags. Discover commands with cf cli search.

Checklist

• Declare secrets.required names for every Worker that uses secrets.
• Put every non-secret plain var in committed config vars or env blocks.
• Confirm .dev.vars and secrets-file paths are gitignored and untracked.
• Commit .dev.vars.example with placeholders only.
• If keep_vars is still on, copy the dashboard-only plain vars into config, then remove keep_vars.
• Point Workers Builds at the production deploy script.
• Update the repository AGENTS.md forbidden list for secret files and workstation production deploys.

Pointers

• Cloudflare deployment — Builds owns production. Secret values stay out of git. Plain vars live in config.
• Workers Builds notify — WATCHDOG_WEBHOOK_SECRET is a Worker runtime secret for the tokenless GitHub push webhook.
• cf CLI and cloudflare.config.ts — cf has no keep_vars. Move vars into config. Wrangler stays transitional.
• docs/workers-builds-migration-pattern.md in MNPPI/org-standards — leftover keep_vars is a migrate follow-up, not the end state.
• docs/private-package-distribution.md in MNPPI/org-standards — Workers Builds NODE_AUTH_TOKEN is a trigger Build secret, not a Worker runtime secret.
• docs/secrets-direnv-standard.md in MNPPI/org-standards — workstation Keychain names and commit-safe .envrc.
• Repo runbook, not an org-standard: zuricert OPERATIONS-secret-management. Product repos may keep their own WORKER_SECRETS runbooks.