---
since: 1.1.1
---

# Release Runbook

1. Confirm the working tree is clean.
2. Update `[project].version` in `pyproject.toml`.
3. Update `CHANGELOG.md` (or generate the entry with `gitaiflow --changelog --since <last-release-date> --path .`).
4. Run linting: `make lint`.
5. Run tests: `make test`.
6. Run the deterministic regression suites (core service layer and telemetry consent — internal-only, not published here).
7. Build all four platform binaries: `make build-all` (the macOS leg must run on real Apple Silicon hardware).
8. Verify architecture headers: `file installers/*` (see expected output in [`../deployment/binary-distribution.md#5-verify-artifact-architecture-headers`](../deployment/binary-distribution.md)).
9. Generate `RELEASE_NOTES.md` from the `CHANGELOG.md` entry for this version (`gitaiflow --release-notes`), then create and push the annotated release tag — either directly (`git tag -a vX.Y.Z -m "..."`, `git push origin vX.Y.Z`) or via `scripts/release/tag_release.sh`, which also creates the GitLab/GitHub releases from `RELEASE_NOTES.md` and links the built binaries.
10. Publish: `make release` (uploads every binary in `installers/vX.Y.Z/` to the GitLab Generic Package Registry as both the versioned and `latest` assets, then regenerates the R2 manifest — including `installers/latest.txt` — and syncs to Cloudflare R2) — or `make all` to chain test → build-all → release in one command.
11. Install the published version in a clean environment (`curl -fsSL https://install.djangoplay.org/gitaiflow | bash -s -- vX.Y.Z`).
12. Verify `gitaiflow --version` and `gitaiflow --help`.
13. Run the full platform verification matrix — macOS, Linux amd64/arm64 containers, Windows PowerShell — from [`../deployment/binary-distribution.md#section-d-verification--integration-testing`](../deployment/binary-distribution.md).
14. Run a real functional smoke test against a configured AI provider (`gitaiflow --path . --change-summary`) to confirm the compiled binary's bundled dependencies (`httpx`, `certifi`, and — on Windows — the `prompts`/`templates` data files) came through the compile intact.
15. Spot-check telemetry consent behavior post-release (`gitaiflow --telemetry status`) — see the telemetry consent test suite (internal-only) Part 2 for the full sequence.

## Versioning

gitaiflow follows [Semantic Versioning](https://semver.org/). The current package metadata (`pyproject.toml`) declares:

```text
version = "1.1.0"
requires-python = ">=3.11"
```

## Rollback

Because both the one-line installers and the Generic Package Registry `latest` pointer are overwritten in place on each successful release, there is no separate "rollback" action beyond re-running `registry_update.sh` with a previous version's `installers/` directory if a bad release has already reached users:

```bash
git checkout vX.Y.Z-1 -- installers/  # or rebuild that tag with make build-all
GITLAB_TOKEN=<token> ./scripts/release/registry_update.sh latest
```

If a release step fails mid-way, `registry_update.sh` is safe to re-run once the underlying issue is fixed — package-registry uploads and the R2 sync (which uses `--checksum`) are both idempotent.