Release Process

See Branch and Release Policy for the governing branch, promotion, and ruleset policy. This document describes the release mechanics that implement that policy.

ZeptoDB uses dev as the integration branch and main as the release branch. All normal development pushes should target dev. Promoting code to main starts the release automation.

Branch Flow

1. Push feature work to dev or to a short-lived branch that targets dev.
2. Run the required CI and review checks against dev.
3. Promote dev to main only when the repository is ready to publish a new version.
4. Do not push directly to main from local development. The repository pre-push hook blocks refs/heads/main unless ZEPTO_ALLOW_MAIN_PUSH=1 is set for an explicit release-admin override.

Automatic Versioning

Version Main Release runs on every push to main.

The workflow:

1. Fetches all vMAJOR.MINOR.PATCH tags.
2. Reads the current project versions from:
   • CMakeLists.txt
   • zepto_py/__init__.py
   • web/package.json
   • deploy/helm/zeptodb/Chart.yaml
   • both production Dockerfile ZEPTO_VERSION defaults
3. Compares the highest tag version with the highest checked-in version file.
4. Uses the checked-in version when it is ahead of the latest tag; otherwise bumps the latest tag’s patch component.
5. Commits the synchronized version files to main with chore(release): vX.Y.Z.
6. Creates tag vX.Y.Z.
7. Pushes the tag, which triggers the Release workflow.

This keeps binary artifact names, Docker tags, GitHub releases, and the Python package version aligned.

Release Workflow

The existing Release workflow still owns publishing:

• Linux amd64 and arm64 binary archives.
• Multi-arch Docker image tags zeptodb/zeptodb:X.Y.Z and zeptodb/zeptodb:latest.
• GitHub Release notes and downloadable archives.
• PyPI package publishing through trusted publishing.
• Homebrew tap update dispatch.

The full release workflow is triggered by a v* tag push. The workflow can also be run manually with workflow_dispatch plus a version input to republish Docker images and manifests for an existing release without creating a new GitHub Release, PyPI package, Homebrew dispatch, or tag.

Release binary builds use ccache with per-architecture restore keys so repeated tag builds can reuse unchanged C++ compilation results. Docker release builds use the repository .dockerignore to keep local build directories, web build output, docs, Git metadata, and benchmark artifacts out of the build context. The Docker image path builds and smoke-tests native amd64/arm64 images, verifies their version labels, generates SBOMs, blocks HIGH/CRITICAL vulnerabilities, archives those exact verified images, and only then publishes the per-arch tags and multi-arch manifest. Published images are therefore the same image bytes that passed verification rather than a later rebuild.

The Graviton ARM64 Build & Test workflow is not run for release-bot chore(release): vX.Y.Z version bump commits. The tag-triggered Release workflow calls the hosted x86_64 and ARM64 full production gate before building portable release binaries and verified native images. Release-version commits use a separate Graviton concurrency key so they do not cancel the main-merge Graviton run that preceded the version bump.

Repository Settings

The pipeline expects these GitHub settings:

• The repository secret RELEASE_BOT_TOKEN is configured with permission to push to main, create v* tags, and dispatch workflows. This repository is under an organization policy that disables write permissions for the default GITHUB_TOKEN, so the release workflow cannot rely on github.token.
• main and v* rulesets allow the release bot account to bypass release automation writes. The current repository ruleset uses repository-admin bypass, so the token owner must have admin permission or the ruleset must be updated to name a narrower bot actor.
• Required release secrets are present:
  • RELEASE_BOT_TOKEN
  • DOCKERHUB_USERNAME
  • DOCKERHUB_TOKEN
  • SITE_DEPLOY_TOKEN
• PyPI trusted publishing is configured for the pypi environment.
• The self-hosted ARM64 runner used by Graviton ARM64 Build & Test is online.

Version Policy

The default automatic bump is patch-only. Minor or major releases should be prepared by manually updating the version files on dev before promoting to main; the automation will publish that higher checked-in version exactly.

Active Rulesets

The repository is configured with these active rules:

• Dev branch safety: protects dev from deletion and non-fast-forward updates.
• Main release branch: protects main from deletion and non-fast-forward updates, requires a pull request, requires one approving review, dismisses stale reviews on push, and requires review-thread resolution.
• Release tags: protects v* tags from unauthorized creation, deletion, and non-fast-forward updates.