Versioning & Releases

SafeLLM follows Semantic Versioning (SemVer) to ensure predictable, auditable releases.

Version Format

MAJOR.MINOR.PATCH

Type	When to increment	Example
PATCH	Bug fixes, no behavior change	Regex fix, crash fix
MINOR	New features, backward compatible	New L1 filter, new PII type
MAJOR	Breaking changes	Config format change, API change

Source of Truth

The version is defined in a single file:

safellm-oss/VERSION

All other artifacts (Docker images, Helm charts, pyproject.toml) read from this file.

Release Process

1. Update VERSION

echo "2.0.0" > VERSION

2. Commit

git add VERSION
git commit -m "chore(release): v2.0.0"

3. Create Tag

git tag -a v2.0.0 -m "Release v2.0.0"
git push origin v2.0.0

4. Automatic Pipeline

Pushing the tag triggers GitHub Actions which:

1. Builds multi-arch Docker image (amd64, arm64)
2. Tags the image:
   • ghcr.io/safellmio/safellm-apisix-gateway-sidecar:2.0.0 (exact version)
   • ghcr.io/safellmio/safellm-apisix-gateway-sidecar:2.0 (minor)
   • docker.io/safellm/safellm-apisix-gateway-sidecar:2.0.0 (exact version)
   • docker.io/safellm/safellm-apisix-gateway-sidecar:2.0 (minor)
   • docker.io/safellm/safellm-apisix-gateway-sidecar:2 (major)
   • ghcr.io/safellmio/safellm-apisix-gateway-sidecar:latest (optional)
3. Pushes to GHCR (and optionally Docker Hub)
4. Creates GitHub Release with:
   • Release notes
   • Image digest (SHA256)
   • docker-compose.release.yaml

Pinned Versions (Production Requirement)

Never use latest in production

The latest tag is mutable and can change at any time. Always pin to a specific version.

Development (OK to use build:)

# docker-compose.yml (dev)
services:
  sidecar:
    build:
      context: .
      dockerfile: sidecar/Dockerfile

Production (Must pin versions)

# docker-compose.release.yaml (prod)
services:
  apisix:
    image: apache/apisix:3.14.1-debian # Pinned
  sidecar:
    image: ghcr.io/safellmio/safellm-apisix-gateway-sidecar:2.0.0 # Pinned
  redis:
    image: redis:7.2-alpine # Pinned

Maximum Security (Pin by digest)

services:
  sidecar:
    image: ghcr.io/safellmio/safellm-apisix-gateway-sidecar@sha256:abc123...

Docker Registries

SafeLLM images are published to:

Registry	URL	Purpose
GHCR	ghcr.io/safellmio/safellm-apisix-gateway-sidecar	Primary, GitHub integration
Docker Hub	docker.io/safellm/safellm-apisix-gateway-sidecar	Public distribution

Both registries have identical images with the same digest.

Helm Chart Versioning

Helm charts follow the same version as the application:

Chart.yaml

apiVersion: v2
name: safellm-oss
version: 2.0.0 # Chart version
appVersion: '2.0.0' # App version (same)

Install specific version:

helm install safellm safellm/safellm-oss --version 2.0.0

Verifying Releases

Check image digest

docker inspect ghcr.io/safellmio/safellm-apisix-gateway-sidecar:2.0.0 --format='{{.RepoDigests}}'

docker inspect safellm/safellm-apisix-gateway-sidecar:2.0.0 --format='{{.RepoDigests}}'

Compare with release notes

Each GitHub Release includes the expected digest. Compare:

# From release notes
Expected: sha256:abc123...

# From your local pull
Actual:   sha256:abc123...

Version History

Version	Date	Notes
2.0.0	2026-02	Current OSS release baseline
0.8.0	2026-01	Initial OSS release

See CHANGELOG for detailed history.