Release process

​

Commits

<type>(<scope>)!?: <short summary>

<brief explanation when needed>

​

Changelog and versions

• MAJOR: incompatible stable-interface changes after 1.0
• MINOR: features and potentially breaking pre-1.0 changes
• PATCH: fixes and internal changes

​

Release checklist

1. When the web app changed, rebuild its committed embedded copy and review the generated asset changes:
   make ui
   git diff -- core/ui/spa/dist
   
2. Move the [Unreleased] entries under the new version and date. Update developmentVersion in distro/cmd/suchi/main.go to the current source version line with a -dev suffix.
3. Confirm the shipped Microsoft OAuth registration still permits personal and work/school device-code sign-in.
4. Run the local verification suite:
   make check
   make security-check
   make smoke
   make bench-check
   docker build --check .
   docker compose config --quiet
   make docs-check
   git diff --check
   
5. Manually exercise behavior that depends on external services or accounts, including Microsoft sign-in, configured email providers, and hosted LLMs affected by the release.
6. Recheck public size, memory, startup, network, and feature claims against the accepted benchmark and the final build.
7. Commit the release metadata, then create and push a signed annotated tag:
   git tag -s v0.1.0 -m "suchi 0.1.0"
   git push origin v0.1.0
   
8. Dispatch the manual release workflow:
   make release VERSION=v0.1.0
   
   Use PUBLISH=false for an artifacts-only run.

​

Publishing container images without Actions

export VERSION=v0.1.0-beta.1
export IMAGE=ghcr.io/johnnybravo-xyz/suchi
export CACHE_AMD64="$IMAGE:buildcache-amd64"
export CACHE_ARM64="$IMAGE:buildcache-arm64"

git worktree add --detach "/tmp/suchi-$VERSION" "$VERSION"
cd "/tmp/suchi-$VERSION"

printf '%s' "$CR_PAT" |
  docker login ghcr.io -u "$GITHUB_USER" --password-stdin
unset CR_PAT

​

Build on native architecture hosts

docker buildx build \
  --file Dockerfile \
  --target standard \
  --platform linux/amd64 \
  --build-arg VERSION="$VERSION" \
  --build-arg REVISION="$(git rev-parse HEAD)" \
  --tag "$IMAGE:$VERSION-amd64" \
  --label org.opencontainers.image.source=https://github.com/johnnybravo-xyz/suchi \
  --label org.opencontainers.image.version="$VERSION" \
  --label org.opencontainers.image.licenses=AGPL-3.0 \
  --cache-from type=registry,ref="$CACHE_AMD64" \
  --cache-to type=registry,ref="$CACHE_AMD64",mode=max \
  --provenance=mode=max \
  --sbom=true \
  --push .

docker buildx build \
  --file Dockerfile \
  --target standard \
  --platform linux/arm64 \
  --build-arg VERSION="$VERSION" \
  --build-arg REVISION="$(git rev-parse HEAD)" \
  --tag "$IMAGE:$VERSION-arm64" \
  --label org.opencontainers.image.source=https://github.com/johnnybravo-xyz/suchi \
  --label org.opencontainers.image.version="$VERSION" \
  --label org.opencontainers.image.licenses=AGPL-3.0 \
  --cache-from type=registry,ref="$CACHE_ARM64" \
  --cache-to type=registry,ref="$CACHE_ARM64",mode=max \
  --provenance=mode=max \
  --sbom=true \
  --push .

docker buildx imagetools create \
  --tag "$IMAGE:$VERSION" \
  --tag "$IMAGE:beta" \
  --tag "$IMAGE:beta-standard" \
  "$IMAGE:$VERSION-amd64" \
  "$IMAGE:$VERSION-arm64"

docker buildx imagetools inspect "$IMAGE:$VERSION"
docker pull --platform linux/amd64 "$IMAGE:$VERSION"
docker pull --platform linux/arm64 "$IMAGE:$VERSION"

​

Automation

• checks.yml is the single manual entry point for repository validation.
• ci.yml runs formatting, tests, vet, lint, and UI checks when called by it.
• smoke.yml tests the built images and ingest paths when called by it. Both variants are rebuilt with the exported AnyDoc context and an unusable Rust base to catch accidental recompilation; binary and license bytes must match the export before the usual ingestion checks run.
• restore-drill.yml validates backup restoration when called by it.
• release.yml publishes only when manually dispatched from an existing tag. Its preflight runs fresh Go/UI checks, embedded bundle parity, and dependency advisory scans. Images wait for both binary matrices before publication and reuse the AnyDoc matrix’s verified binaries rather than rebuilding them. Artifacts-only branch runs use snapshot-<commit> names and skip signing and publication; they still produce ordinary workflow artifacts and GHA caches.