Skip to content

Releases and versioning

Pre-release readiness BaseHarbor uses Semantic Versioning for normal releases with Git tags prefixed by v. During the v0.4 line, emergency hotfixes use the documented four-part MAJOR.MINOR.PATCH.HOTFIX extension.

Examples: v0.3.0, v0.4.15, v0.4.15.1, v1.0.0.

Stability policy

BaseHarbor is currently in the 0.x series.

During 0.x:

  • patch releases (0.4.0 -> 0.4.1) stay backward-compatible within the active minor line and may contain fixes, security hardening and additive capabilities;
  • minor releases (0.4.x -> 0.5.0) may contain intentionally documented breaking changes or larger contract shifts;
  • every breaking change must be called out in CHANGELOG.md and GitHub Release notes;
  • consumers should pin an explicit compatible range instead of tracking main.

After v1.0.0, breaking public CLI, manifest, persisted-state or supported integration changes require a new major version.

Compatibility contract

The versioned contract includes documented baha commands and flags, the baseharbor.yaml schema, persisted BaseHarbor state, supported backup/restore formats, application-facing environment/service contracts, and runtime image tags coupled to CLI versions.

Internal Go packages are not public API unless explicitly documented.

Manifest v1 remains the supported v0.4 compatibility surface. v0.4 adds provider-neutral contract/runtime seams behind that surface rather than forcing applications to rewrite their manifest for future providers.

Development versus releases

BaseHarbor uses two long-lived branches with distinct responsibilities:

  • main is the released source line. It should represent the currently published release and should only advance through a release PR from develop or an explicitly documented hotfix.
  • develop is the integration branch for the next release. Normal feature, fix, chore and dependency branches target develop.

Published channels:

  • GitHub tag/release vX.Y.Z or v0.4 hotfix vX.Y.Z.H: immutable supported release created from main;
  • ghcr.io/mcpdev80/baseharbor-runtime:X.Y.Z or X.Y.Z.H: matching runtime image;
  • ghcr.io/mcpdev80/baseharbor-runtime:latest: latest stable release;
  • ghcr.io/mcpdev80/baseharbor-runtime:edge: moving development build from develop.

Normal development branches must not target main directly. Hotfix branches start from main, are released through main, and must then be merged/backported into develop so the next release retains the fix.

Hotfix releases

During the current v0.4 line, an emergency correction to an already published patch uses a four-part BaseHarbor hotfix version:

MAJOR.MINOR.PATCH.HOTFIX

Example:

v0.4.15 -> v0.4.15.1

Hotfix workflow:

  1. Start the hotfix release branch from the exact released main line, never from in-progress develop.
  2. Link every correction to the hotfix release parent issue.
  3. Keep the branch defect-only: no unrelated features, refactors or dependency updates.
  4. Use focused validation while implementing individual fixes.
  5. Update changelog, release notes and any affected operator/reference documentation.
  6. Run the complete pre-release gate exactly once at the release boundary against the final hotfix candidate.
  7. Open the hotfix release PR to main only after the candidate evidence is green.
  8. Publish the immutable four-part tag and matching runtime image from the merged main commit.
  9. Verify release artifacts/provenance, then forward-port the same fixes to develop.
  10. Remove temporary hotfix/validation branches only after publication and forward-port are complete.

If a proposed change alters runtime identity, persisted-state migration, public contracts or architecture beyond what is required to correct the released defect, move it back to the normal roadmap instead of expanding the hotfix.

Rollback rule: do not move or rewrite a published tag. If a hotfix itself is defective, revert the release change on the released line as appropriate and publish a new hotfix version.

Evidence rule: the release issue and release notes must identify the exact BaseHarbor candidate SHA, the external demo revision used by pre-release validation, and the successful release-boundary evidence.

Release preparation

Normal releases are prepared on develop and promoted to main only after the release candidate is proven. Hotfix releases follow the main-based workflow above.

The mandatory end-to-end checklist is docs/internal/pre-release-documentation-audit.md. Despite its historical filename, it is the canonical complete pre-release audit and covers scope/issues, BaseHarbor implementation, contracts, EN/DE docs, roadmap/staleness, changelog/release notes, baseharbor-demo, GitHub Pages, exact-candidate evidence, promotion, publishing and post-release verification. A release must not skip checklist sections because the feature code or normal CI is already green.

  1. Review the final implementation on develop against docs/DEVELOPMENT_GUIDELINES.md, including ownership, isolation, secret-safety, fail-closed behavior, tests and documentation consistency.
  2. Review and update all affected canonical documentation, including both EN/DE variants where they exist. Search explicitly for stale version numbers, implementation-status claims, examples and future-work statements.
  3. Move relevant entries from [Unreleased] into a dated ## [X.Y.Z] - YYYY-MM-DD section in CHANGELOG.md (or X.Y.Z.H for a v0.4 hotfix).
  4. Write human-readable release notes at docs/releases/vX.Y.Z.md (or vX.Y.Z.H.md for a v0.4 hotfix). They are the canonical GitHub Release message and must explain what changed, why it matters, compatibility/upgrade impact, security implications and intentionally deferred work; a raw commit list or generated Git log is not an acceptable release message.
  5. Finish and merge the exact external baseharbor-demo revision intended for release validation, then record its immutable 40-character commit SHA in docs/releases/vX.Y.Z.demo-ref (or vX.Y.Z.H.demo-ref). Moving baseharbor-demo/main is never an acceptable release pin.
  6. Review compatibility impact and select the documented release-version increment.
  7. Run local/Hugging Face validation first where practical.
  8. Only after implementation, documentation, CHANGELOG, README, human-readable release notes, the external baseharbor-demo and the versioned demo-ref file are complete, run the mandatory GitHub pre-release workflow against the exact release-candidate SHA. Pre-release is an orchestrator over independently rerunnable atomic gates: static contract/DX gates run without a container runtime, while Docker and Podman gates use declared minimal resource profiles. Every gate uploads evidence bound to the exact BaseHarbor SHA, demo SHA, runtime and gate name.
  9. If the baseline finds failures, do not rerun successful gates. Fix one failure area at a time and rerun exactly the failed atomic gate through Targeted Atomic Gate with the unchanged candidate/demo SHA until it is green. A code change invalidates the affected evidence and requires the relevant gates to be rerun; unrelated green evidence is not discarded merely because another gate failed.
  10. Once all atomic gates are individually green on the final unchanged candidate, run the complete pre-release orchestrator once as the release-boundary approval. The final evidence manifest must contain the complete expected atomic gate set for the exact BaseHarbor candidate SHA and pinned external demo SHA.
  11. Open one release PR from develop to main. Do not mix unrelated changes into this PR.
  12. Merge develop -> main only after the pre-release gate is green and the release diff is understood.
  13. Create the immutable release tag on the resulting main release commit and push it.
  14. The release workflow consumes the successful immutable pre-release approval instead of rerunning the same source/runtime/demo acceptance suite. It performs only release-only checks not already covered, publishes the matching runtime image, GitHub Release, archives and provenance.
  15. Verify the resulting GitHub Release, binaries, checksums, provenance, matching runtime image and referenced pre-release evidence before declaring the release usable. A pushed tag without a successful published release is not release completion.

Never move a published version tag. Fix a bad release with a new patch release.

Immutable v0.4.24 ecosystem inputs

For v0.4.24 and v0.4.25, the final Connector commit's integration-candidate.json binds the exact Core, Console and Demo commits. The Console manifest must bind the same Core and Demo, and the Demo's baseharbor-core.ref must equal that Core commit. This replaces the Core-owned .demo-ref for these releases: mutually pinning future Git commits would create a circular dependency. Targeted v0.4.25 atomic pushes use the same canonical matrix resolver as the pre-release source step; a mixed or mutable source is rejected before execution.

An explicit only_gates selection or validation/pre-release/selected/* branch runs only the selected qualification set and skips the final approval job. Its individual artifacts are evidence; they cannot create release approval. For an unchanged candidate, a temporary ref named validation/pre-release/selected/gates/<comma-separated exact gate IDs> can point directly at its immutable commit. The existing selector validates every requested ID; no source commit or consumer pin changes to choose a different small group.

scripts/ecosystem_release_pins.py validates all bindings and resolves the public consumer evidence manifest. The pre-release workflow accepts an optional exact consumer_ref, or resolves the reviewed Connector integration branch once and freezes its 40-character SHA. Approval retains that immutable consumer origin; release revalidation resolves the same commits. The complete native Connector job also verifies the exact Console browser receipt, so its authenticated artifact can prove Console integration without repeating the same journey. All existing atomic gates remain required.

Preparing these inputs does not start or approve a pre-release. The tested SHA matrix and completed pre-release validation are recorded in PR #837.

Release artifacts

Each release publishes:

  • baseharbor_linux_amd64.tar.gz
  • baseharbor_linux_arm64.tar.gz
  • checksums.txt
  • GitHub build-provenance attestations
  • matching versioned GHCR runtime images

Verify binary metadata with:

baha version

Verify checksums with:

sha256sum -c checksums.txt --ignore-missing

GitHub provenance can additionally be verified with:

gh attestation verify baseharbor_linux_amd64.tar.gz -R mcpdev80/baseharbor

Consumer guidance

A real application should never silently follow main. During the 0.x series, an application validated against v0.4.15 should normally constrain itself to the compatible minor line, for example >=0.4.0 <0.5.0, unless it intentionally validates against a newer minor release.

Applications moving through the v0.4 line keep Manifest v1 and the existing Compose developer journey. v0.4.3 added the open Provider Integration Contract and deterministic read-only repository inspection. v0.4.4 added provider-neutral managed HTTP/HTTPS exposure. v0.4.5 added provider-neutral secure-binding/workload-identity semantics. v0.4.6 added object-storage.s3/v1 with a replaceable SeaweedFS Compose reference provider, bucket-scoped credentials and authenticated S3 readiness. v0.4.7 added provider-neutral telemetry.otlp/v1, a lazy shared OpenTelemetry Collector reference provider, external OTLP binding and real OTLP export verification. v0.4.8 added metrics/v1, Prometheus placement/isolation, Runtime Resource API execution and directed cross-application connectivity. v0.4.9 added provider-neutral centralized workload logs through Loki/Alloy, rendered-Compose workload security preflight and executable provider conformance/fault injection. v0.4.10 added generic provider observability and trace storage, v0.4.11 hardened repository adoption and lifecycle UX, v0.4.12 added the agent-native machine/MCP surface, v0.4.13 added explicit environment and policy semantics, v0.4.14 completed typed reconciliation/ownership/convergence semantics, v0.4.15 added first-class Targets, native Podman Quadlet execution, the TLS/service-access baseline, complete provider/runtime observability semantics, the full agent-native MCP/JSON lifecycle and installation-wide full destroy, v0.4.16 added selectable application recovery units plus shared Audit/Evidence v1 semantics, v0.4.17 added managed identity/operator authentication/shared-provider lifecycle and the versioned Runtime Provider boundary, and v0.4.18 adds the greenfield Development Extension path, multi-repository workspaces, capability-subset acceptance and local Docker/Podman host-resource preflight while retaining Manifest v1.