Environments

Environments are where a project deploys, declared in wrktr.json under environments. Each one runs its steps, in order, in a fresh container, to deploy one commit of the default branch.

{
  "environments": {
    "dev": {
      "on": "land",
      "url": "https://dev.example.com",
      "secrets": ["CLOUDFLARE_API_TOKEN"],
      "steps": [
        { "name": "api", "run": "pnpm deploy:api" },
        { "name": "web", "run": "pnpm deploy:web" }
      ],
      "verify": { "check": "/api/health" }
    },
    "production": {
      "on": "promote",
      "from": "dev",
      "url": "https://example.com",
      "secrets": ["CLOUDFLARE_API_TOKEN"],
      "steps": [{ "name": "deploy", "run": "pnpm deploy" }]
    }
  }
}

• An on: "land" environment deploys every land by itself. changed limits it to lands that touch certain paths (globs).
• An on: "promote" environment deploys the commit a person promotes. With from, by default that’s what the from environment has live. Promoting an older commit than what’s live is a rollback.

See the wrktr.json reference for every field.

wrktr env ls                              # what's live where, what's running, what production is behind
wrktr env promote production              # ship what dev has
wrktr env logs dev 4 --follow             # stream run #4's steps
wrktr env rerun dev 4                     # run the newest run again
wrktr env cancel dev 5

Secrets

Steps get the project’s secrets without ever holding them: a deploy’s requests to the Cloudflare API go through wrktr’s deploy gateway, which adds the secret. Set them from stdin, so they never land in your shell history:

pbpaste | wrktr secret set CLOUDFLARE_API_TOKEN
wrktr secret ls

An environment whose secrets aren’t all set isn’t set up: a land doesn’t run it, and promoting it is refused with what’s missing. A fork starts that way, since secrets aren’t copied.

Each step also gets WRKTR_PROJECT, WRKTR_ENVIRONMENT, WRKTR_COMMIT, WRKTR_RUN, WRKTR_TRIGGER and WRKTR_URL, for deploy scripts that want them.

Every deploy says what it is

The deploy gateway adds a small manifest to every Worker a run uploads, served at /.well-known/wrktr.json: the project, environment, commit and run (a private project’s names only the environment, commit and run). Nothing to configure.

After a run passes, wrktr checks each environment with a url: the url must serve the manifest of the run’s commit, and Cloudflare must have the Worker versions the run uploaded deployed. The run is then serving, not serving (with what’s there instead), or unverified when neither can be told. "verify": { "check": "/health" } also requires a 2xx there; "verify": false turns off both the manifest and the check.

Where a branch went

Each run notes the branches it ships, the same list its manifest serves, so a landed branch knows every run that shipped it and where each stands: live, replaced by a newer run (its code is still there), rolled back, didn’t go out, or deploying. The branch page lists them under Deployments, and wrktr status under shipped. wrktr env wait <environment> waits on them: run it after wrktr land --when-ready, and it exits 0 once the branch is live there (and serving, if the environment checks its url).