Versions and Compatibility¶

Every Mission Control release has a semantic version. This page explains what a version promises, how far an upgrade or a rollback may jump, how long a deprecated interface keeps working, how to check that an image is the one the project built, and how to read the version a deployment runs.

What a version promises¶

The root VERSION file names the release, for example 0.1.0, and a release tag is exactly v plus that version. A version is MAJOR.MINOR.PATCH:

Change	Example	What it may contain
Patch	`0.1.0` → `0.1.1`	Fixes only. No migration that changes behavior, no new setting, nothing removed.
Minor	`0.1.x` → `0.2.0`	Features and additive migrations. Removes only what an earlier release deprecated.
Major	`0.x` → `1.0.0`	Changes that break the rules on this page; the release notes say what to do.

While the major version is 0, a minor release may also carry a breaking change when a security fix needs one, and its release notes list it under Breaking changes with the upgrade step. Every release's notes are under Release notes.

Upgrade and rollback reach¶

Upgrade one minor version at a time: from any 0.1.x to any 0.2.x, not from 0.1.x to 0.3.x. Patch releases of the same minor version can be skipped freely.

A rollback to the previous minor version is code-only, because migrations are additive across one minor version: the earlier release keeps running against the migrated database (Upgrade and rollback). In an existing-VPS deployment, a release that could not honor this, for example because workers must understand new evaluation data, advances the runtime-contract floor; the start guard then refuses the older workers instead of letting them run incorrectly, and the release notes say so. Restore a database backup only to go back further than one minor version.

Deprecation¶

A public API route, request or response field, header, Organization YAML field, environment variable or command-line flag that is going away is first deprecated:

The release that deprecates it keeps it working and names it under Deprecations in its release notes, with the replacement.
It keeps working for at least one more minor release.
The release that removes it lists the removal under Breaking changes, and a configuration that still uses a removed field fails config:check and startup with a message naming it.

A security fix may shorten this, and its release notes then say why.

Verify an image¶

Releases publish the images ghcr.io/ziadmoubayed/mission-control-<target> for gateway, console, agent-runtime, collector and migrate, for linux/amd64 and linux/arm64. The release workflow signs each image digest with a keyless Sigstore signature tied to the tagged workflow run and attaches an SPDX software bill of materials as a signed attestation. The GitHub release lists every digest.

Prerequisites: cosign 2 or later. From any directory, with the digest from the release page (the value here is illustrative):

image=ghcr.io/ziadmoubayed/mission-control-gateway@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
identity="https://github.com/ziadmoubayed/mission-control/.github/workflows/release.yml@refs/tags/v0.1.0"
cosign verify "$image" \
  --certificate-identity "$identity" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
cosign verify-attestation "$image" --type spdxjson \
  --certificate-identity "$identity" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Expected result: both commands print Verification for ... -- followed by the checks that passed, and exit 0. A digest the release did not publish, or one signed by another workflow or tag, fails with no matching signatures; do not run that image.

Pull by digest, not by tag, so the image you verified is the image that runs.

Read the running version¶

Component	Where
Gateway	Private `GET /readyz` on the control listener: `version`, and `componentVersions` for the Agent runtime, Collector and Console
Console	Private `GET /healthz` on `CONSOLE_INTERNAL_PORT`: `version`
Any image	`docker image inspect <image> --format '{{ index .Config.Labels "org.opencontainers.image.version" }}'`
Tarball	`version` in the release manifest `release-<commit>.json`

Images set MISSION_CONTROL_VERSION from VERSION; do not set it yourself. A build from a source checkout reports 0.0.0-dev. See Health and logging for the probe bodies.