Skip to main content

Release Process

O.D.I.N. uses a 6-phase automated release pipeline powered by GitHub Actions and Make targets. Every release follows the same process, from version bump to container registry push.

Triggering a Release​

Releases are triggered by pushing a version tag:

git tag v1.7.3
git push origin v1.7.3

The v* tag pattern triggers the release workflow in GitHub Actions. Manual releases via the GitHub Actions UI are also supported for hotfixes.

The 6-Phase Pipeline​

Phase 1: Version Bump & Changelog​

  • The tagged version is extracted from the git tag
  • Version strings are updated in the codebase (package.json, Python metadata, frontend constants)
  • A changelog is generated from conventional commit messages since the last tag
  • The changelog is formatted for the GitHub Release notes

Phase 2: Lint & Type Check​

  • Backend: Python linting (ruff), type checking (mypy)
  • Frontend: ESLint, TypeScript compilation (tsc --noEmit)
  • The pipeline aborts if any lint or type check fails

Phase 3: Test Suite​

  • Backend unit tests — pytest against SQLite
  • Backend integration tests — pytest against PostgreSQL (Docker service container)
  • Frontend tests — Vitest
  • API contract tests — validates OpenAPI spec against actual route definitions
  • All test suites must pass. Failure at this phase blocks the release.

Phase 4: Build​

  • Frontend: vite build produces the production bundle
  • Backend: Python dependencies are locked and vendored
  • Docker image: Multi-stage Dockerfile builds the final image
    • Stage 1: Node.js build (frontend assets)
    • Stage 2: Python runtime with compiled frontend embedded
    • Final image is based on python:3.11-slim with supervisord
  • Multi-arch: Images are built for both linux/amd64 and linux/arm64 using Docker Buildx

Phase 5: Publish​

  • The Docker image is pushed to ghcr.io/hughkantsime/runsodin:<version> and ghcr.io/hughkantsime/runsodin:latest
  • A GitHub Release is created with the changelog and build artifacts
  • The release notes include upgrade instructions if there are breaking changes or migration steps

Phase 6: Post-Release​

  • Documentation site is rebuilt if any docs changed in the release
  • The latest tag on the container registry is updated
  • Discord announcement is posted to the release channel
  • Health check confirms the new image pulls and starts correctly

Make Targets​

The pipeline steps map to Make targets that can be run locally:

TargetDescription
make lintRun all linters (ruff, eslint, tsc)
make testRun all test suites
make buildBuild frontend and Docker image
make release-checkDry-run: lint + test + build without publishing

Run make release-check before pushing a tag to catch issues locally.

Versioning​

O.D.I.N. follows Semantic Versioning:

  • Major — breaking API changes or incompatible database migrations
  • Minor — new features, non-breaking API additions
  • Patch — bug fixes, security patches, documentation updates

The current version is always visible in the web UI footer and via GET /api/v1/health.

Hotfix Process​

For critical fixes that cannot wait for a normal release cycle:

  1. Branch from the latest release tag: git checkout -b hotfix/v1.7.3 v1.7.2
  2. Apply the fix and commit
  3. Tag and push: git tag v1.7.3 && git push origin v1.7.3
  4. The same 6-phase pipeline runs, but only the patch version increments

See Also​