Runbook — Upgrade and roll back RepoWrangler

Deploy only immutable vMAJOR.MINOR.PATCH tags. Do not build production from a moving branch, and do not retag a published version. RepoWrangler's best-effort support covers the latest patch release only.

Before the upgrade

1. Read the target release notes and changelog, including every database migration and configuration change since your installed version.
2. Record the current source tag, image digest, deployment configuration, and database migration state.
3. Take a database backup or snapshot and verify that your restore procedure is usable. For SQLite, stop writers and copy the database plus its WAL/SHM files consistently. For PostgreSQL, use a provider backup or point-in-time restore point. For D1, follow the D1 recovery runbook.
4. Confirm required secrets and variables exist without printing their values.
5. Test the release against a disposable or staging database when the release contains schema changes.

v1.0.8 through v1.0.10 contain no database migration relative to v1.0.2.

Deploy the immutable release

Fetch and check out the exact tag when building from source:

git fetch --tags --force
git checkout --detach vX.Y.Z
pnpm install --frozen-lockfile
pnpm typecheck && pnpm test && pnpm build

Then use the matching target recipe:

• Docker Compose / local hardware: rebuild from the checked-out tag or set the compose image to the immutable release tag, then run docker compose up -d.
• Cloudflare Worker + D1: apply any documented D1 migration, build from the tag, and run wrangler deploy.
• Azure Container Apps: build the server image from the tag, push it with that version, and apply the version-matched Bicep recipe. Pass the existing custom-domain certificate parameters when reapplying the template.
• Kubernetes: update the Deployment or Helm release to an image built from the tag, apply migrations once, and wait for rollout completion.

Run the scheduler on exactly one replica for a shared database.

Verify

Confirm all of the following before declaring the change complete:

• GET /health/live reports the target version and HTTP 200;
• GET /health/ready reports ready;
• the sign-in page and configured provider complete authentication;
• the latest application revision uses the intended image tag or digest;
• custom domains and TLS remain bound;
• scheduled jobs complete and the pending/failed queue does not grow; and
• a representative workspace and repository show current provider data.

Rollback policy

Rollback is a coordinated application-and-data operation, not merely an image change.

1. Stop or scale down writers if the failed release may have changed data.
2. If no database migration ran and the release notes explicitly permit it, redeploy the previously recorded immutable tag or digest.
3. If a migration ran, use only an explicitly documented backward-compatible rollback path. Otherwise restore the pre-upgrade database backup or point-in-time restore point, then deploy the previous tag.
4. Re-run the verification checks and retain the failed release logs.

RepoWrangler does not promise general backward compatibility with a newer schema. Never infer rollback safety from semantic version numbers alone.