Compatibility Policy

Hephaestus follows Semantic Versioning 2.0.0. This page defines what a version number promises to operators. It covers the public contract, required upgrade actions, and supported versions. The CHANGELOG and GitHub Releases describe release contents.

The public contract

Semantic versioning applies to the surfaces an operator or API consumer depends on:

Surface	What is covered
Database migration chain	Liquibase applies changesets in changelog order. A newer release builds on the previous schema. Follow the database migration instructions before an upgrade.
Runtime prerequisites	The minimum PostgreSQL major version and its required extensions. The minimum Kubernetes version and the required kernel features. The required outbound network destinations and external services. Adding or raising one is a breaking change.
REST API	The methods and paths in Public REST operations: the extension calls and the API operations documented in the admin and user guides. The OpenAPI specification defines their request and response shapes. The base path is /api. Error responses use the problem types in API error handling. Open enums states what a client must accept.
Helm chart values	The values of the Helm chart, and the key names that Secret custody lists for secret.name. Removing or renaming a value, accepting less than before, or changing its meaning is a breaking change. A new optional value or a wider limit is a minor change.
Signed release	The assets that Release image lock lists and the schema of the joint lock. The location of the chart, and the image names in Docker image tags.
Backups	The pgBackRest stanza name of the bundled PostgreSQL, because an existing repository uses it.
Practice scripts	What Write a practice script documents: the shape of a script, its context, its result, and the modules that it imports. Removing or renaming one, or changing the script contract version, is a breaking change. Other modules of the toolkit are not covered.
Practice definitions and catalog	The fields of a practice definition, its Applies when conditions, and the practice and group slugs of the catalog. A new field or condition is a minor change. A changed catalog practice reaches a workspace as an offer that an admin accepts.
Alert rules	The alert names of the shipped rules, and the metrics that those rules read.
Provider connections	The webhook routes that you registered at a provider, and the permissions of the GitHub App, the GitLab token and the Slack app. A new required permission is a breaking change. A minor release can ask for a permission only if its feature stays off, with a recorded reason, until you grant it.
Posted text	The destinations in Posted links, including their query parameters. The hidden <!-- hephaestus… markers in comments also keep their format.

CI enforces these rules from 1.0.0: see Public contract gate and API compatibility.

The previous-release API check covers every OpenAPI operation, including internal web app calls. This protects browser tabs that still run the previous release. It does not add these operations to the 1.x public promise. From 1.0, the promised operations must stay compatible with the stable release.

A limit that a release states can go in a minor release. One GitLab instance for each install is an example.

Other surfaces can change in any release without notice:

• Java and TypeScript internals.
• The database schema itself, as distinct from the migration chain.
• Environment variables and hephaestus.* properties. The chart sets them, so set chart values instead.
• Operations outside Public REST operations, and the operation IDs and tags of OpenAPI.
• UI layout, and web app routes that posted text does not link to. A moved route gets no redirect.
• The wording of comment footers, email and notifications.
• The workspace layout of a sandbox, the tool protocol, and the contents of the agent-pi image. A custom sandbox image is not supported.
• The provider inbox subject names.
• The interfaces between the server and its GitHub, GitLab, Slack and Outline adapters.
• Metrics that no shipped alert rule reads, and log fields.

Discovery and browser routes

GET /.well-known/hephaestus.json is part of the public contract. The web app host serves this document. All four fields are present:

Field	Type	Meaning
apexOrigin	String	Configured instance origin. It can be empty when unset.
baseDomain	String	Domain for workspace hosts. It can be empty when workspace subdomains are off.
workspaceSubdomainsEnabled	Boolean	Whether workspace hosts are enabled.
version	String	Application version.

The extension uses it to resolve a workspace host to the instance origin. This requires an HTTPS apexOrigin without a port, a matching baseDomain, and workspaceSubdomainsEnabled: true. Otherwise, the extension keeps the origin that the person entered.

These browser routes are also part of the contract, although OpenAPI does not list all of them:

• GET /api/auth/login: start browser sign-in or link an identity.
• GET /api/login/oauth2/code/{registrationId}: a login provider's registered callback.
• GET /api/oauth/callback/{kind}: a workspace provider connection's registered callback.
• POST /api/auth/bootstrap-admin: recover instance administration, with a signed-in session, CSRF protection, and the configured bootstrap token.

For installed-client sign-in, /api/auth/login accepts mode=client, provider, client_id, redirect_uri, code_challenge, code_challenge_method=S256, and state. When development sign-in is enabled, the extension uses GET /api/auth/dev-login/client instead. That route accepts username and admin in place of provider and mode, with the same client and PKCE parameters. Production refuses development sign-in.

A successful installed-client handoff returns code and state to the registered extension redirect URI. A failed handoff returns error and, when available, state. The extension treats error=access_denied as a declined sign-in. For browser sign-in, provider selects the login provider and optional returnTo selects the page after sign-in. mode=link links that provider identity to the signed-in account, with the same provider and returnTo parameters.

The bootstrap request body has a token field, as Instance administration describes.

The login callback and the connection callback are separate routes. Keep the callback URL registered at each provider when you upgrade.

Conversation stream

The documented live-answer endpoint GET /api/workspaces/{workspaceSlug}/mentor/events is part of the public contract. It uses server-sent events, which OpenAPI does not describe. Server runtime § Live answers gives its connection behavior.

Posted links

The public contract covers these destinations for provider comments, Slack messages, and email:

Destination	Path on the instance
Home	/
Feedback on work	/w/<short name>/feedback/<item>
Conversation entry	/w/<short name>/conversation?entry=<entry>
Workspace settings	/w/<short name>/admin/settings
Review details from the extension	/w/<short name>/admin/practices/reviews/?itemId=<item>&detail=item:<item>
Instance product feedback	/admin/feedback
Your product feedback	/product-feedback
Account settings	/settings
Email unsubscribe confirmation	/unsubscribe?token=<token>
One-click email unsubscribe	POST /api/notifications/unsubscribe/<token>

With workspace subdomains, the four workspace paths start at the workspace host and omit /w/<short name>. The other destinations use the instance host. The conversation path also works without entry. The entry, token, itemId, and detail query parameters retain their meaning. One-click unsubscribe requests send List-Unsubscribe=One-Click as form data.

Version numbers

Bump	Meaning
Major (X.y.z)	You must act before or during the upgrade. Causes include required new, removed, or renamed chart values, manual or destructive migrations, and removed APIs. The release notes say what to do. MIGRATION.md has the details.
Minor (x.Y.z)	New functionality. The upgrade needs no action. It can include new optional chart values.
Patch (x.y.Z)	Bug and security fixes. The upgrade needs no action.

CAUTION: Pre-1.0

Below 1.0.0, the Minor row above does not apply. There are no major releases yet. Breaking changes occur in minor releases (0.x.0 → 0.y.0), per SemVer item 4. A pre-1.0 minor release can require action. The release notes state the required action. This exception ends with the 1.0.0 release.

CI still fails on a 0.x API break until the change lists it as accepted.

1. Read the release notes.
2. Test the upgrade in staging first.

Open enums

A response enum of the REST API is open. A client must accept a value that it does not know, and must not fail on it. Thus, a new value in a response is a minor change. A new recorded reason is an example.

A request enum stays closed: removing a value that a client can send is a breaking change.

The observation outcomes and the problem severities are not open. A new outcome or severity is a major change, because it changes what an observation means. The product vocabulary defines them.

Database migrations

The migrate run mode applies pending changesets, in order, before the runtime roles of a release start. The release notes flag schema migrations and direct you to the required backup and upgrade instructions. Read those instructions before starting any target runtime role.

A release-specific migration procedure takes precedence over normal startup. For the native Hibernate JSON cutover, follow its procedure before starting the new runtime roles. That procedure owns the requirements to stop writers, verify the backup, apply the migration, and restart the roles.

Upgrade guarantee

From 1.0 onward, any 1.x can be upgraded to any later 1.y without intermediate releases. Use the target release's Helm chart. Follow the database migration instructions for its supported database baseline. Only the previous release can run beside a new schema. Thus, an upgrade that skips a release stops every role before the migration.

A release before 1.0.0-rc.1 cannot upgrade directly. Hephaestus 1.x starts from 1.0.0-rc.1. Fresh databases initialize automatically.

Database baseline prerequisites

Installed release	Required path to the target release
Older than 1.0.0-rc.1	Install 1.0.0-rc.1 with its versioned upgrade instructions, then upgrade to the target release.
1.0.0-rc.1 or later	Follow the target release migration procedure.

The database history determines whether a database has reached 1.0.0-rc.1. The migration refuses an older history before it writes anything, and tells you which release to install.

On a database at 1.0.0-rc.1, the first migration also checks the schema against a new install of that release. If they differ, it stops without a change and lists each difference. The current release can keep running. Contact the maintainers with the list. If a build later than 1.0.0-rc.1 ran on the database, the migration also stops without a change. Restore the backup from 1.0.0-rc.1, then upgrade from there.

Released migrations remain immutable. CI checks fresh initialization and selected upgrade fixtures. It does not prove that every migration is safe for every existing production dataset. Data-affecting migrations still require review and a rehearsal against a restored backup. Take a database backup before upgrading. Downgrades are not supported.

Deprecation policy

The release notes announce functionality to remove at least one minor release before its removal. That functionality continues to work until the removal release. After 1.0.0, removals occur only in major releases.

Supported deployment

The Helm chart is the only supported deployment. A Kubernetes cluster and a single k3s host use the same chart. Docker Compose remains local development infrastructure only.

Before upgrading an existing installation to the chart-only release, complete the 0.95.0 deployment move. Apply 0.95.1 and install its reconciler tooling before upgrading to the chart-only release. The chart values and signed joint release lock are part of the public contract. ADR 0058 records the deployment decision.

Support statement

Before 1.0.0, we support the latest release only. Support for 1.x gives the rules from 1.0.0. Fixes ship as new releases on top of the current version. There are no backport branches. If you hit a bug on an older version, upgrade to the latest release before reporting it. This mirrors comparable self-hosted products — for example, Sentry provides no dedicated self-hosted support and expects operators to upgrade regularly.

Support for 1.x

From 1.0.0, these rules apply to the Helm chart, the only supported deployment (Supported deployment).

The upgrade guarantee lets you move from any 1.x to the latest 1.y. Thus, the latest 1.x release is the supported one, and fixes ship on it.

When 2.0.0 is released, the last 1.x minor release gets security fixes for 12 months. It is the only older release that gets fixes. Those fixes ship as patch releases of that minor release. That minor release gets no new features and no other fixes. After the 12 months, 1.x is unsupported.

Docker image tags

The application images (webapp, application-server, agent-pi, postgres) under ghcr.io/hephaestus-build/ are published with:

Tag	Meaning	Stability
X.Y.Z	Exact release	Human-readable label. Production uses the signed digest lock
X.Y	Latest patch of a minor release	Moves on every patch release
latest	Latest release	Moves on every release
main, <sha>	Unreleased development builds	Unsupported — never deploy these

Releases published before the ls1intum → hephaestus-build organization transfer remain under ghcr.io/ls1intum/hephaestus/ — GHCR packages do not transfer between organizations, and their signatures name the old repository forever. security/release-identities.json in the repository records which image namespace and signing identity each release uses.

For digest-pinned release images, see Release image lock.