Skip to content
Agirunner

Upgrades And Versioning

Agirunner is publishing its first public release line in the 0.1.x range.

That means versioning should be treated deliberately even while the product is moving quickly.

Release Stages

Section titled “Release Stages”

The public release progression is:

  • alpha
  • beta
  • rc (release candidate)
  • final release

That gives the project a clear way to publish early milestones without pretending they are stable.

What To Version

Section titled “What To Version”

At minimum, track:

  • Git tags and releases
  • runtime image tags and digests
  • changelogs in each public repository
  • docs updates when public setup or APIs change

Canonical Tag Format

Section titled “Canonical Tag Format”

Use the same semantic version for the full stack, the platform components, and the runtime.

Git tags and GitHub releases use a leading v:

  • v0.1.0-alpha.1
  • v0.1.0-beta.1
  • v0.1.0-rc.1
  • v0.1.0

Container tags use the same version without the v prefix:

  • 0.1.0-alpha.1
  • 0.1.0-beta.1
  • 0.1.0-rc.1
  • 0.1.0

The meaning is:

  • alpha: early public milestone, useful for testing direction and packaging
  • beta: broader pre-release milestone, expected to be more complete
  • rc: release candidate, close to the intended stable release
  • final release: the first stable public artifact for that line

GitHub Release Policy

Section titled “GitHub Release Policy”

For GitHub Releases:

  • mark alpha, beta, and rc releases as prereleases
  • publish the final v0.1.0 release as the normal stable release

That keeps the public release feed readable and prevents prerelease tags from pretending to be the stable line.

Recommendation

Section titled “Recommendation”

Treat exact release artifacts as immutable:

  • Git tags
  • exact image tags
  • image digests

Rolling pointers such as latest can move, but exact release identities should not.

Rolling Tags

Section titled “Rolling Tags”

latest is a mutable pointer, not a registry feature that automatically chooses the newest artifact by date or semantic version.

If a registry returns latest, it only returns the image that was explicitly tagged latest.

For Agirunner right now:

  • every published release tag SHOULD publish its exact image tag
  • every published release tag SHOULD also move latest
  • that means latest tracks the newest published release in the repo, including alpha, beta, and rc, until the project chooses a stricter stability policy later

Why This Matters

Section titled “Why This Matters”

This is especially important for runtime images. Operators may accept a moving pointer for local development, but they usually want digest-pinned execution environments for anything they care about reproducing.

Repository Roles

Section titled “Repository Roles”

Use each repository for a different layer of release documentation:

  • agirunner owns the product-level release framing and links to this policy
  • agirunner-platform owns platform image and release workflow details
  • agirunner-runtime owns runtime image and release workflow details
  • changelogs describe what changed in each repository, but this page defines how versions are named

Release Sequence

Section titled “Release Sequence”

For a public stack milestone such as 0.1.0-alpha.1, release in this order:

  1. agirunner-runtime
  2. agirunner-platform
  3. agirunner

Why this order:

  • runtime first, so the published task-execution image exists
  • platform second, so the API, dashboard, and container-manager images exist and can point at the runtime line you just published
  • agirunner last, so the top-level docs and product bring-up path can be validated against the already-published images

In practice:

  • push v0.1.0-alpha.1 in agirunner-runtime
  • push v0.1.0-alpha.1 in agirunner-platform
  • verify the top-level agirunner stack works against those published images
  • then tag agirunner itself as v0.1.0-alpha.1

The runtime and platform release workflows already publish both the exact prerelease tag and latest. agirunner itself is not an image repo; it owns the product-facing docs, release framing, and top-level stack configuration.

For GitHub Releases, remember to mark alpha, beta, and rc releases as prereleases in the GitHub UI. The tag-triggered image publish workflows do not create that UI release object for you.

Database Schema Evolution

Section titled “Database Schema Evolution”

agirunner-platform owns database schema changes for the product stack.

  • pending SQL migrations run automatically when the platform API starts
  • applied migration filenames are tracked in schema_migrations
  • the current pre-0.1.0 line still allows baseline consolidation before first public release
  • once the public line is out, schema changes should move forward through new migrations instead of rewriting released history

Contributor-facing migration policy lives in agirunner-platform/MIGRATIONS.md.