breakaway 1.0.2-main.20 → 1.0.2-main.22

package/README.md

@@ -174,7 +174,7 @@ breakaway publishes releases and never deploys an install. Every install, the ow
 - **Every merge to `main`**, once CI passes, publishes a GitHub pre-release `vX.Y.Z-main.N` on the `main` channel. It carries the bundle (`breakaway-bundle.tar.gz`: the Worker's files and the web app's `dist`), a `manifest.json` (version, channel, commit, `manual`, and the lowest version it updates from), its signature `manifest.json.sig` (Ed25519, made with a key only the release workflow holds; the public key is `src/release-key.js`), and `SHA256SUMS`. The notes list the merged pull requests by title.
 - **A stable release** `vX.Y.Z` is the owner's: they run the **Release** workflow with the pre-release to promote. The bundle is that pre-release's, unchanged, and the notes cover everything since the last stable.
 - **The CLI** is on npm as [`breakaway`](https://www.npmjs.com/package/breakaway), staged on npm by the same workflow, with provenance, and live once the owner approves it there with 2FA. npm's trusted publishing can't yet read the OIDC identity of a repository as new as this one ([npm/cli#9969](https://github.com/npm/cli/issues/9969)), so until it can, a token that can stage but never publish by itself stands in, in an environment only `main` can use. Every pre-release goes out under the `next` dist-tag, and a stable release as `latest`. `npx breakaway <command>` is `node scripts/tasks.mjs <command>`.
-- **A major release** is one where an install has to do something by hand: a config or binding change, a Durable Object class or migration, a route or cron. Its notes have a **Manual steps** section and its manifest says `manual: true`, which an install's deploy stops on. A change that needs it sets `manual` and `manualSteps` in `release.json`, and the pull request that ships the steps clears them. Data the Durable Object stores changes forward-only and additively, so an install can always go back one release.
+- **A major release** is one where an install has to do something by hand: a config or binding change, a Durable Object class or migration, a route or cron. Its notes have a **Manual steps** section and its manifest says `manual: true`, which an install's deploy stops on. A change that needs it sets `manual` and `manualSteps` in `release.json`, and the pull request that ships the steps clears them. When the only step is `wrangler deploy` (a new Durable Object class, a cron, a route), it also sets `wranglerDeploy: true`, and an install whose Deploy may run `wrangler deploy` does it itself (the install template's README says when). Data the Durable Object stores changes forward-only and additively, so an install can always go back one release, except across a new Durable Object class, which Cloudflare doesn't roll back.
 - **The version** is `package.json`'s; the release workflow sets it to the pre-release's before it builds. `GET /api/ping` and `GET /api/health` report it as `release`. An install that deploys a stable passes it as the `BREAKAWAY_VERSION` variable, since the bundle was built as the pre-release.
 
 </details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakaway",
-  "version": "1.0.2-main.20",
+  "version": "1.0.2-main.22",
   "description": "The task board for you and your coding agents: a Cloudflare Worker, its web app, Taskwarrior sync, and the CLI (npx breakaway).",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",

package/prompts/install.md

@@ -54,6 +54,12 @@ The Cloudflare API token is theirs to make. On Cloudflare: My Profile, API Token
 gh secret set CLOUDFLARE_API_TOKEN --env production --repo <owner>/<name>
 ```
 
+That token can run `wrangler deploy`, so Deploy can apply a new address, cron triggers, or a new Durable Object class by itself instead of stopping for them. That's theirs to turn on; after a yes:
+
+```sh
+gh variable set BREAKAWAY_DEPLOY_CHANGES --body true --repo <owner>/<name>
+```
+
 **Check:** `gh api repos/<owner>/<name>/environments/production/secrets --jq '.secrets[].name'` lists both secrets, and the workflows are on `main`.
 
 ## 2. The board's secrets

package/scripts/install/cli.js

@@ -11,14 +11,12 @@ import { ask } from '../tasks/ask.js';
 import { QUESTIONS, configFrom, stateFrom, writeInstall } from './init.js';
 import {
   bumpBody,
-  checkManifest,
-  configStop,
+  deployPlan,
   deployTarget,
   isHealthy,
   latestReleases,
   parseState,
   previousVersionId,
-  shapeChanges,
   shapeOf,
   updatePlan,
   workerMissing,
@@ -72,6 +70,28 @@ const configIn = (path) => {
   }
 };
 
+/** A file's JSON, or null when it's missing or isn't JSON. */
+const jsonIn = (path) => {
+  try {
+    return path ? JSON.parse(readFileSync(path, 'utf8')) : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The running Worker's shape for `check`, or null when nothing says what it is. */
+function runningShape(opts) {
+  const running = jsonIn(opts['running-config']);
+  if (running && typeof running === 'object') return shapeOf(running);
+  const before = jsonIn(opts.before);
+  if (!before) return null; // no earlier config (the first deploy, or a dispatch): nothing to compare with
+  try {
+    return shapeOf(wranglerConfig(parseInstall(before)));
+  } catch {
+    return null;
+  }
+}
+
 /** The Worker's wrangler config for a downloaded release: the install's config, with the code and web app where the bundle put them. */
 export function bundleConfig(config, bundle) {
   const out = wranglerConfig(config);
@@ -99,20 +119,17 @@ export async function runStep(step, opts, io) {
     const version = opts.version;
     if (!version) throw new Stop('check needs --version, the release being deployed.');
     const manifest = readJson(opts.manifest ?? 'release/manifest.json', 'the release’s manifest');
-    const verdict = checkManifest(manifest, { version, running: opts.running || null });
-    if (verdict.ok === false) throw new Stop(verdict.message, 2);
-    if (opts.before) {
-      let before = null;
-      try {
-        before = parseInstall(JSON.parse(readFileSync(opts.before, 'utf8')));
-      } catch {
-        before = null; // no earlier config (the first deploy, or a dispatch): nothing to compare with
-      }
-      const now = configIn(join(dir, 'breakaway.config.json'));
-      const stop = before && configStop(shapeChanges(shapeOf(wranglerConfig(before)), shapeOf(wranglerConfig(now))));
-      if (stop) throw new Stop(stop, 2);
-    }
+    // The Worker as it runs: the config the running release's own CLI made (--running-config), else this release's code
+    // with the config from before this push (--before). Neither (a first deploy, or a dispatch): nothing to compare.
+    const before = runningShape(opts);
+    const after = before && shapeOf(wranglerConfig(configIn(join(dir, 'breakaway.config.json'))));
+    const apply = opts['deploy-changes'] === true || opts['deploy-changes'] === 'true';
+    const plan = deployPlan(manifest, { version, running: opts.running || null, before, after, apply });
+    if (plan.ok === false) throw new Stop(plan.message, 2);
     io.out('ok=true');
+    io.out(`deploy=${plan.deploy}`);
+    io.out(`changes=${plan.changes.join(', ')}`);
+    io.out(`address_changed=${plan.addressChanged}`);
     return 0;
   }
   if (step === 'config') {

package/scripts/install/lib.js

@@ -78,13 +78,19 @@ export function deployTarget(state, releases) {
   return { version: latest.version, tag: tagOf(latest.version), channel: 'main' };
 }
 
+/** How Deploy is allowed to run wrangler deploy, for the messages that stop it. */
+const LET_DEPLOY =
+  "give CLOUDFLARE_API_TOKEN the scopes this repository's README lists for it and set the repository variable BREAKAWAY_DEPLOY_CHANGES to true";
+
 /**
  * Whether a downloaded release may be deployed by the workflow. A release that needs hands, or one the running version
- * can't update from, stops with the message the workflow prints.
- * @param {{ version?: string, manual?: boolean, manualSteps?: string[], updatesFrom?: string }} manifest
- * @returns {{ ok: true } | { ok: false, message: string }}
+ * can't update from, stops with the message the workflow prints. A manual release whose only step is wrangler deploy
+ * (`wranglerDeploy`, BRK-62) passes when the install lets Deploy run it (`apply`), and says it needs wrangler deploy.
+ * @param {{ version?: string, manual?: boolean, manualSteps?: string[], wranglerDeploy?: boolean, updatesFrom?: string }} manifest
+ * @param {{ version: string, running?: string | null, apply?: boolean }} options
+ * @returns {{ ok: true, wrangler?: true } | { ok: false, message: string }}
  */
-export function checkManifest(manifest, { version, running = null }) {
+export function checkManifest(manifest, { version, running = null, apply = false }) {
   if (!manifest || typeof manifest !== 'object')
     return { ok: false, message: 'the release’s manifest.json isn’t readable, so nothing was deployed.' };
   if (manifest.version !== version)
@@ -92,13 +98,6 @@ export function checkManifest(manifest, { version, running = null }) {
       ok: false,
       message: `the manifest is for ${manifest.version}, not ${version}, so nothing was deployed. Try again; if it persists, the release was published wrongly.`,
     };
-  if (manifest.manual === true) {
-    const steps = (manifest.manualSteps ?? []).map((s) => `\n  - ${s}`).join('');
-    return {
-      ok: false,
-      message: `breakaway ${version} needs steps by hand, so the workflow didn't deploy it. Do these, then deploy it yourself with wrangler:${steps}`,
-    };
-  }
   if (
     running &&
     manifest.updatesFrom &&
@@ -110,40 +109,131 @@ export function checkManifest(manifest, { version, running = null }) {
       ok: false,
       message: `breakaway ${version} updates from ${manifest.updatesFrom} or newer, and this install runs ${running}. Update to ${manifest.updatesFrom} first (set it in breakaway.json), then to ${version}.`,
     };
+  if (manifest.manual === true) {
+    const byWrangler = manifest.wranglerDeploy === true;
+    if (byWrangler && apply) return { ok: true, wrangler: true };
+    const steps = (manifest.manualSteps ?? []).map((s) => `\n  - ${s}`).join('');
+    const hint = byWrangler
+      ? `\nThese steps are what wrangler deploy does, so Deploy can do them itself: ${LET_DEPLOY}, then run Deploy again.`
+      : '';
+    return {
+      ok: false,
+      message: `breakaway ${version} needs steps by hand, so the workflow didn't deploy it. Do these, then deploy it yourself with wrangler:${steps}${hint}`,
+    };
+  }
   return { ok: true };
 }
 
-/** What a deploy by the workflow can't change: routes, crons, the Durable Object classes, and their migrations. */
+/**
+ * What a version upload can't change (BRK-62): the Worker and its Durable Object, its routes and crons, and the Durable
+ * Object classes and their migrations. Made from the Worker's wrangler config.
+ */
 export function shapeOf(wrangler) {
+  const inst = wrangler.vars?.TASKS_INSTALL;
   return {
+    worker: wrangler.name ?? null,
+    store: (inst && typeof inst === 'object' ? inst.store : null) ?? null,
+    jurisdiction: wrangler.vars?.TASKS_JURISDICTION ?? null,
     routes: wrangler.routes ?? [],
     workers_dev: Boolean(wrangler.workers_dev),
     crons: wrangler.triggers?.crons ?? [],
     durable_objects: wrangler.durable_objects?.bindings ?? [],
     migrations: wrangler.migrations ?? [],
-    jurisdiction: wrangler.vars?.TASKS_JURISDICTION ?? null,
   };
 }
 
-/** What differs between two installs' shapes, as phrases for the message; empty when a deploy may go ahead. */
+const json = (value) => JSON.stringify(value);
+/** A migration that only makes classes, which wrangler deploy applies; any other kind deletes, renames, or moves one. */
+const CREATES = new Set(['tag', 'new_sqlite_classes', 'new_classes']);
+
+/**
+ * The classes `after` adds, when adding is all its Durable Object change does: its migrations are `before`'s with only
+ * new classes after them, and it keeps every binding `before` has. Null for anything else.
+ */
+function addedClasses(before, after) {
+  const kept = before.migrations.every((m, i) => json(m) === json(after.migrations[i]));
+  const added = after.migrations.slice(before.migrations.length);
+  if (!kept || !added.every((m) => Object.keys(m).every((key) => CREATES.has(key)))) return null;
+  if (!before.durable_objects.every((b) => after.durable_objects.some((a) => json(a) === json(b)))) return null;
+  return added.flatMap((m) => [...(m.new_sqlite_classes ?? []), ...(m.new_classes ?? [])]);
+}
+
+/**
+ * What differs between the Worker's shape as it runs and as this deploy makes it, each with whether wrangler deploy may
+ * apply it (BRK-62): an address, cron triggers, and new Durable Object classes, yes. Another Worker, another Durable
+ * Object, or a class deleted, renamed, or moved, never: the first two open an empty board, and the last is a release's
+ * manual step. Empty when a version upload carries the whole deploy.
+ * @returns {{ change: string, apply: boolean, why?: string, address?: true }[]}
+ */
 export function shapeChanges(before, after) {
-  const names = {
-    routes: 'its address (routes)',
-    workers_dev: 'its workers.dev address',
-    crons: 'its cron triggers',
-    durable_objects: 'its Durable Object classes',
-    migrations: 'its Durable Object migrations',
-    jurisdiction: 'its jurisdiction',
-  };
-  return Object.keys(names)
-    .filter((key) => JSON.stringify(before[key]) !== JSON.stringify(after[key]))
-    .map((key) => names[key]);
+  const differs = (key) => json(before[key]) !== json(after[key]);
+  const out = [];
+  const empty = 'another Durable Object is an empty board';
+  if (differs('worker'))
+    out.push({
+      change: 'its Worker’s name (worker)',
+      apply: false,
+      why: 'a new name makes a new Worker, with an empty board',
+    });
+  if (differs('store')) out.push({ change: 'its Durable Object (store)', apply: false, why: empty });
+  if (differs('jurisdiction')) out.push({ change: 'its jurisdiction', apply: false, why: empty });
+  if (differs('routes')) out.push({ change: 'its address (routes)', apply: true, address: true });
+  if (differs('workers_dev')) out.push({ change: 'its workers.dev address', apply: true, address: true });
+  if (differs('crons')) out.push({ change: 'its cron triggers', apply: true });
+  if (differs('durable_objects') || differs('migrations')) {
+    const added = addedClasses(before, after);
+    if (added === null)
+      out.push({
+        change: 'its Durable Object classes: it deletes, renames, or moves one',
+        apply: false,
+        why: 'that is a release’s manual step, and it can lose a board',
+      });
+    else
+      out.push({
+        change: added.length
+          ? `its Durable Object classes: it adds ${added.join(', ')}`
+          : 'its Durable Object bindings',
+        apply: true,
+      });
+  }
+  return out;
 }
 
-/** The message that stops a deploy when the install's config changed what the workflow can't deploy, or null. */
+/** The message that stops a deploy whose changes need wrangler deploy when the install hasn't allowed it, or null. */
 export function configStop(changes) {
   if (!changes.length) return null;
-  return `breakaway.config.json changed ${changes.join(', ')}, which the workflow doesn't deploy. Apply it yourself with wrangler (npx wrangler deploy, with the config npx breakaway install config makes), then run the workflow again.`;
+  return `This deploy changes ${changes.join(', ')}, which a version upload can't carry, so nothing was deployed. To let Deploy run wrangler deploy for it, ${LET_DEPLOY}, then run Deploy again. Or apply it yourself with wrangler (npx wrangler deploy, with the config npx breakaway install config makes), then run Deploy again.`;
+}
+
+/** The message that stops a deploy with a change Deploy never makes. */
+function neverStop(changes) {
+  const why = [...new Set(changes.map((c) => c.why))].join('; ');
+  return `This deploy changes ${changes.map((c) => c.change).join(', ')}, which Deploy never does, so nothing was deployed: ${why}. If breakaway.config.json changed it, put it back as it was. If the release did, its notes say what to do by hand.`;
+}
+
+/**
+ * What Deploy does with a release (BRK-62): stop with a message, upload a version (`versions`), or run wrangler deploy
+ * (`wrangler`) for what a version can't carry. `before` and `after` are the Worker's shapes as it runs and as this deploy
+ * makes it; `before` is null when there is nothing to compare with (a first deploy, or a dispatch with no running release
+ * to ask). `apply` is whether the install lets Deploy run wrangler deploy: BREAKAWAY_DEPLOY_CHANGES, set for a token that
+ * can. `addressChanged` tells the health check to wait for a new custom domain.
+ * @returns {{ ok: false, message: string } | { ok: true, deploy: 'versions' | 'wrangler', changes: string[], addressChanged: boolean }}
+ */
+export function deployPlan(manifest, { version, running = null, before = null, after = null, apply = false }) {
+  const verdict = checkManifest(manifest, { version, running, apply });
+  if (verdict.ok === false) return verdict;
+  const found = before && after ? shapeChanges(before, after) : [];
+  const never = found.filter((c) => !c.apply);
+  if (never.length) return { ok: false, message: neverStop(never) };
+  const changes = found.map((c) => c.change);
+  const byWrangler = changes.length > 0 || verdict.wrangler === true;
+  if (byWrangler && !apply) return { ok: false, message: configStop(changes) };
+  return {
+    ok: true,
+    deploy: byWrangler ? 'wrangler' : 'versions',
+    changes,
+    addressChanged: found.some((c) => c.address === true),
+  };
 }
 
 /**

package/src/cli-version.js

@@ -4,5 +4,5 @@
  * and how to update it. scripts/tasks/version.test.js fails when the copied files change and this doesn't:
  * so it lives in the board's package (CLD-135) and the CLI imports it from here.
  */
-export const CLI_VERSION = 44;
-export const CLI_FINGERPRINT = 'd89515e35e35eacd';
+export const CLI_VERSION = 45;
+export const CLI_FINGERPRINT = '947c6296a0dd677e';

package/template/.github/workflows/deploy.yml

@@ -1,7 +1,9 @@
 # Deploys a breakaway release to this install's Worker: the release breakaway.json pins (stable), or the latest
 # pre-release (main). Runs on a push to main, which is how a merged update pull request deploys, and by hand.
-# It stops with a plain message when the release needs steps by hand, or when breakaway.config.json changed
-# something it can't deploy (the address, cron triggers, or Durable Object classes): those are yours to deploy.
+# A deploy uploads a version of the Worker. A change a version can't carry (the address, cron triggers, or a new
+# Durable Object class) needs wrangler deploy: Deploy runs it when the repository variable BREAKAWAY_DEPLOY_CHANGES is
+# true, for a token that can (the README says which), and otherwise stops with a plain message, as it does for a release
+# that needs steps by hand. It never changes the Worker's name or its Durable Object, which would open an empty board.
 name: Deploy
 
 on:
@@ -40,6 +42,8 @@ jobs:
       CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
       DRY_RUN: ${{ inputs.dry-run }}
+      # true lets Deploy run wrangler deploy for an address, cron triggers, or a new Durable Object class (BRK-62).
+      DEPLOY_CHANGES: ${{ vars.BREAKAWAY_DEPLOY_CHANGES }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -91,6 +95,7 @@ jobs:
           (cd release && sha256sum --check SHA256SUMS)
 
       - name: Check it can deploy by itself
+        id: check
         env:
           CLI: ${{ steps.release.outputs.cli }}
           VERSION: ${{ steps.release.outputs.version }}
@@ -98,15 +103,34 @@ jobs:
           ADDRESS: ${{ vars.BREAKAWAY_URL }}
         run: |
           set -euo pipefail
-          # Nothing is deployed yet on the first run, so there is no running release to compare with.
-          address=${ADDRESS:-$(node -p "require('./breakaway.config.json').url || ''")}
+          # The config as it was before this push, to see whether it changed what a version upload can't carry.
+          rm -f before.json running.wrangler.json
+          case "$BEFORE" in ''|0000000000000000000000000000000000000000) ;; *) git show "$BEFORE:breakaway.config.json" > before.json 2>/dev/null || rm -f before.json ;; esac
+          was=breakaway.config.json
+          if [ -f before.json ]; then was=before.json; fi
+          # Where the running board answers: the address from before this push, if the push changes it.
+          address=${ADDRESS:-$(node -p "require('./$was').url || ''")}
           running=""
-          # A board that doesn't say its release (one from before BRK-10) runs none this check knows.
+          # A board that doesn't say its release (one from before BRK-10) runs none this check knows. Nothing is deployed
+          # yet on the first run, so there is no running release to compare with.
           if [ -n "$address" ]; then running=$(curl -fsS --max-time 20 "$address/api/ping" | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).release ?? ''" 2>/dev/null || true); fi
-          # The config as it was before this push, to see whether it changed what a deploy can't.
-          rm -f before.json
-          case "$BEFORE" in ''|0000000000000000000000000000000000000000) ;; *) git show "$BEFORE:breakaway.config.json" > before.json 2>/dev/null || rm -f before.json ;; esac
-          node "$CLI" install check --version "$VERSION" --manifest release/manifest.json --running "$running" --before before.json
+          # The Worker as it runs: the config the running release's own CLI makes from the config it was deployed with, so
+          # a release that changes the cron triggers or the Durable Object classes shows as a change too. Without it (the
+          # same release, or one that can't be read), the check compares the configs with this release's code.
+          if [ -n "$running" ] && [ "$running" != "$VERSION" ]; then
+            dir="$RUNNER_TEMP/running"
+            mkdir -p "$dir/src"
+            if gh release download "v$running" --repo "$BREAKAWAY_REPO" --archive tar.gz -O - 2>/dev/null | tar -xz -C "$dir/src" --strip-components 1 2>/dev/null; then
+              cp "$was" "$dir/breakaway.config.json"
+              (cd "$dir" && node src/scripts/tasks.mjs install config --out "$GITHUB_WORKSPACE/running.wrangler.json" > /dev/null 2>&1) || rm -f running.wrangler.json
+            fi
+          fi
+          status=0
+          node "$CLI" install check --version "$VERSION" --manifest release/manifest.json --running "$running" \
+            --before before.json --running-config running.wrangler.json --deploy-changes "${DEPLOY_CHANGES:-false}" > check.out || status=$?
+          cat check.out
+          if [ "$status" -ne 0 ]; then exit "$status"; fi
+          cat check.out >> "$GITHUB_OUTPUT"
 
       - name: Make the Worker config
         env:
@@ -127,7 +151,15 @@ jobs:
 
       - name: Dry run
         if: ${{ inputs.dry-run }}
-        run: npx --yes wrangler@4 deploy --dry-run --outdir "$RUNNER_TEMP/dry" -c wrangler.generated.json
+        env:
+          DEPLOY: ${{ steps.check.outputs.deploy }}
+          CHANGES: ${{ steps.check.outputs.changes }}
+        run: |
+          set -euo pipefail
+          npx --yes wrangler@4 deploy --dry-run --outdir "$RUNNER_TEMP/dry" -c wrangler.generated.json
+          if [ "$DEPLOY" != wrangler ]; then echo "A deploy would upload a version."
+          elif [ -n "$CHANGES" ]; then echo "A deploy would run wrangler deploy for $CHANGES."
+          else echo "A deploy would run wrangler deploy, the release's manual step."; fi
 
       - name: Upload and deploy
         if: ${{ !inputs.dry-run }}
@@ -135,6 +167,9 @@ jobs:
           CLI: ${{ steps.release.outputs.cli }}
           VERSION: ${{ steps.release.outputs.version }}
           ADDRESS: ${{ vars.BREAKAWAY_URL }}
+          DEPLOY: ${{ steps.check.outputs.deploy }}
+          CHANGES: ${{ steps.check.outputs.changes }}
+          ADDRESS_CHANGED: ${{ steps.check.outputs.address_changed }}
         run: |
           set -euo pipefail
           wrangler() { npx --yes wrangler@4 "$@" -c wrangler.generated.json; }
@@ -150,6 +185,11 @@ jobs:
           fi
           if [ -z "$previous" ]; then
             wrangler deploy --var "BREAKAWAY_VERSION:$VERSION"
+          elif [ "$DEPLOY" = wrangler ]; then
+            # What a version can't carry (BRK-62): wrangler deploy applies the address, cron triggers, and new Durable
+            # Object classes with the code, and the Worker can still go back to $previous unless a class was added.
+            if [ -n "$CHANGES" ]; then echo "This deploy changes $CHANGES, so it runs wrangler deploy."; else echo "breakaway $VERSION's manual step is wrangler deploy, so this deploy runs it."; fi
+            wrangler deploy --var "BREAKAWAY_VERSION:$VERSION" --message "breakaway $VERSION"
           else
             export WRANGLER_OUTPUT_FILE_PATH="$RUNNER_TEMP/wrangler-output.ndjson"
             wrangler versions upload --var "BREAKAWAY_VERSION:$VERSION" --message "breakaway $VERSION"
@@ -157,22 +197,33 @@ jobs:
             wrangler versions deploy "$uploaded@100%" --yes
           fi
           # Health check: the new release answers /api/ping. Without it, go back to the previous version.
-          address=${ADDRESS:-$(node -p "require('./breakaway.config.json').url || ''")}
+          url=$(node -p "require('./breakaway.config.json').url || ''")
+          address=${ADDRESS:-$url}
+          tries=12
+          if [ "$ADDRESS_CHANGED" = true ]; then
+            # A new address: check it, not the old one, and give its custom domain five minutes for its certificate.
+            address=${url:-$ADDRESS}
+            tries=60
+          fi
           if [ -z "$address" ]; then
             echo "::warning title=Not checked::There is no address to check. Set the repository variable BREAKAWAY_URL to where the board answers (a workers.dev address, say) and the next deploy checks it."
             exit 0
           fi
-          for attempt in $(seq 1 12); do
+          for attempt in $(seq 1 "$tries"); do
             if curl -fsS --max-time 15 "$address/api/ping" | node "$CLI" install healthy --version "$VERSION"; then
               echo "breakaway $VERSION is running at $address."
               exit 0
             fi
             sleep 5
           done
-          if [ -n "$previous" ]; then
-            wrangler rollback "$previous" --message "breakaway $VERSION failed its check" --yes
-            echo "::error title=Rolled back::breakaway $VERSION didn't answer $address/api/ping within a minute, so the Worker went back to its previous version. Nothing is lost; read the Worker's logs on Cloudflare."
+          waited=$([ "$tries" -gt 12 ] && echo "five minutes" || echo "a minute")
+          if [ -z "$previous" ]; then
+            echo "::error title=Failed its check::breakaway $VERSION didn't answer $address/api/ping within $waited, and this was the first deploy, so there is no version to go back to. Read the Worker's logs on Cloudflare."
+          elif wrangler rollback "$previous" --message "breakaway $VERSION failed its check" --yes; then
+            kept=""
+            if [ "$DEPLOY" = wrangler ]; then kept=" Rolling back brings back the code only: what wrangler deploy changed${CHANGES:+ ($CHANGES)} stays as it left it."; fi
+            echo "::error title=Rolled back::breakaway $VERSION didn't answer $address/api/ping within $waited, so the Worker went back to its previous version.$kept Nothing is lost; read the Worker's logs on Cloudflare."
           else
-            echo "::error title=Failed its check::breakaway $VERSION didn't answer $address/api/ping within a minute, and this was the first deploy, so there is no version to go back to. Read the Worker's logs on Cloudflare."
+            echo "::error title=Couldn't roll back::breakaway $VERSION didn't answer $address/api/ping within $waited, and the Worker couldn't go back to its previous version: Cloudflare doesn't roll back across a new Durable Object class. The board's data is still in its Durable Object. Read the Worker's logs on Cloudflare, then deploy a fix."
           fi
           exit 1

package/template/README.md

@@ -17,7 +17,7 @@ The board answers at {{address}}.
 ## Set it up once
 
 1. **Push this to a private GitHub repository.**
-2. **Make a GitHub environment named `production`** (Settings, Environments) with two secrets: `CLOUDFLARE_API_TOKEN`, a token that can edit Workers on your account, and `CLOUDFLARE_ACCOUNT_ID`.
+2. **Make a GitHub environment named `production`** (Settings, Environments) with two secrets: `CLOUDFLARE_API_TOKEN`, a Cloudflare API token ([which token does what](#which-token-does-what)), and `CLOUDFLARE_ACCOUNT_ID`.
 3. **Allow the update workflow to open pull requests:** Settings, Actions, General, "Allow GitHub Actions to create and approve pull requests".
 4. **Set the board's secrets** (`npx breakaway init-secrets`, then the Worker's secrets or your Secrets Store: see `.dev.vars.example`).
 5. **Run the Deploy workflow** from the Actions tab. Choose "dry-run" first to check everything up to the Worker without changing it.
@@ -32,7 +32,25 @@ Both workflows run breakaway's CLI from the release's own source on GitHub, with
 
 If Deploy stops with "Couldn't list the Worker's deployments", it changed nothing: only a Worker that doesn't exist yet counts as a first deploy. Check that `CLOUDFLARE_ACCOUNT_ID` is your account's ID (32 hex characters) and that `CLOUDFLARE_API_TOKEN` can read and edit Workers on it, then run Deploy again.
 
-A release can need steps by hand (a change to the Durable Object classes, say). The workflow stops with those steps in its message and deploys nothing; do them, then deploy with `wrangler`. The same stop happens when you change something in `breakaway.config.json` the workflow can't deploy: the address, cron triggers, or Durable Object classes. Apply that change yourself (`npx breakaway install config` makes the Worker config), then run Deploy again.
+A release can need steps by hand (a Durable Object class deleted or renamed, say). The workflow stops with those steps in its message and deploys nothing; do them, then deploy with `wrangler`. A release whose only step is `wrangler deploy` says so in its notes, and Deploy runs it itself when it may ([below](#which-token-does-what)). The same goes for a new address in `breakaway.config.json`, which a version upload can't carry: without that, apply it yourself (`npx breakaway install config` makes the Worker config), then run Deploy again.
+
+## Which token does what
+
+`CLOUDFLARE_API_TOKEN` decides what Deploy can do by itself. Most deploys only upload a new version of the Worker. A deploy that changes the address, the cron triggers, or the Durable Object classes needs `wrangler deploy`, and so a token that can run it:
+
+| Token | What Deploy does |
+| --- | --- |
+| **Workers Editor on this Worker** | Uploads each release, checks it, and goes back if it fails. It stops on an address, cron, or Durable Object class change, and you apply that yourself. |
+| **Workers Editor on every Worker**, and **Zone, Workers Routes, Write** on the board's zone | The same, and with the repository variable `BREAKAWAY_DEPLOY_CHANGES` set to `true`, it runs `wrangler deploy` for those changes too. Custom domains don't support per-Worker roles yet, so Editor has to cover every Worker. |
+
+Either token also needs **Account, Secrets Store, Edit** when the board has a Secrets Store: every deploy binds its secrets. The very first deploy makes the Worker, which takes **Workers Admin**; after that, Editor is enough.
+
+Whatever the token, Deploy never changes the Worker's name, its Durable Object (`store`), or its jurisdiction: each opens an empty board, so it stops instead.
+
+With `wrangler deploy`:
+
+- **A new address replaces the old one.** The Worker answers only on the addresses in its config, so the old one stops answering, and in a workflow `wrangler deploy` takes over the new hostname's DNS record, or another Worker's domain on it, without asking. Moving to another zone needs Workers Routes, Write on both zones. The check after the deploy asks the new address, for up to five minutes while its certificate is issued. If you set `BREAKAWAY_URL`, change it with the address.
+- **Going back brings back the code only.** The address and cron triggers stay as `wrangler deploy` left them, and Cloudflare doesn't roll back across a new Durable Object class, so after one the only way is forward.
 
 ## Change the install