Release Rollback Guide

Ops Use this guide when a new release tag is wrong and you need to return to a known good tag (for example v0.11.1 -> v0.10.14).

This guide documents the tag/release rollback procedure used in this repository.

What this rollback does

Removes bad release tags from GitHub and from your local clone.
Removes matching GitHub Releases so they are not used accidentally.
Makes the previous good release (for example v0.10.14) the latest valid version again.

Prerequisites

Repository admin or maintainer permissions.
git and gh CLI installed locally.
Authenticated GitHub CLI session:

gh auth status

Rollback steps

Identify the bad tags and the rollback target

Example:
- bad tags: v0.11.1 (and any follow-up tags you want to discard)
- rollback target: v0.10.14
Delete the GitHub Release for each bad tag
Terminal window
```
gh release delete v0.11.1 --yes
```
Repeat for every bad tag.
Delete bad tags from the remote
Terminal window
```
git push origin :refs/tags/v0.11.1
```
Delete bad tags from your local clone
Terminal window
```
git tag -d v0.11.1
```
Fetch tags and verify rollback state
Terminal window
```
git fetch --tags --force
git tag --sort=-version:refname | head -n 10
gh release list --limit 10
```
Confirm the latest valid tag is your rollback target (for example v0.10.14).

Optional: bulk-delete several bad tags

If multiple consecutive tags are bad, delete them in one pass:

for tag in v0.11.1 v0.11.2 v0.11.3; do
  gh release delete "$tag" --yes || true
  git push origin ":refs/tags/$tag"
  git tag -d "$tag" 2>/dev/null || true
done

git fetch --tags --force

After rollback

For the next release, run Ops: Release with the intended bump type.
Verify the generated tag in workflow logs before announcing the release.

See also: Infrastructure Migration Guide for host-level rollback safety, Backup Production Database for SQLite backup/restore workflow, and Staging Deployment Guide for image-tag rollback on the staging host.