> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrades and rollback

> Check release compatibility and understand the limits of application rollback.

Mesh exposes release compatibility metadata at
`GET /.well-known/mesh-release`. Deployment tooling can use it when deciding
whether a specific older application image has been approved as a rollback
target. **The endpoint does not perform a rollback**, and this repository does
not implement a hosted deployment controller.

## Inspect a release

```sh theme={null}
curl --fail --silent --show-error \
  https://mesh.example.com/.well-known/mesh-release
```

The response is public JSON with `Cache-Control: no-store`:

| Field | Meaning |
| - | - |
| `protocol` | Metadata format version; currently `1`. |
| `schema` | SHA-256 fingerprint of the compiled, ordered migration filenames and SQL bytes. |
| `rollbackTo` | Full Git revisions explicitly approved as predecessors of this build. |

These are build facts, not tenant data or secrets. The fingerprint describes the
binary's embedded migrations, not a live inspection of its database. It also
does not identify the running image or Git revision; deployment tooling must
obtain that identity independently from its image registry or hosting provider.

The current approval file is empty. There are **no approved predecessors** in
this build. An older image without this endpoint cannot supply the metadata
required by this contract.

## What an approval means

This contract supports application rollback only across **identical migration
bundles**, and only after explicit compatibility testing. Matching fingerprints
alone are insufficient: application code can change stored data formats,
background work, authentication behavior, or external protocols without changing
SQL migrations.

Approval does not reverse migrations, restore a backup, bypass startup guards,
undo external effects, or certify arbitrary earlier releases.

## Approving a predecessor

For a release maintainer adding a revision to
[`internal/release/rollback-predecessors.json` (repository)](https://github.com/TextureHQ/mesh/blob/main/internal/release/rollback-predecessors.json):

1. Verify that the candidate and exact predecessor have identical migration
   bundles. Retain their immutable images and establish their Git revisions.
2. On an isolated database with representative data, run the predecessor, upgrade
   to the candidate, and exercise affected writes, jobs, settings, and sign-in.
3. Stop the candidate, run that exact predecessor against the resulting database
   and configuration, and verify reads, writes, sign-in, and recovery.
4. Record the rehearsal in the release PR and add the full predecessor revision.
   Recheck or remove approval when later behavior changes invalidate it.

The JSON file accepts unique, full 40-character lowercase Git revisions. Its
presence records an explicit maintainer decision; the runtime does not run the
compatibility rehearsal itself.

## Deployment-controller responsibilities

A controller adopting this contract must retain the previous healthy image
identity and compatibility evidence before replacement. It must compare the
actual candidate and predecessor, refuse missing or incompatible metadata, and
retain evidence outside a process that may become unhealthy. Whether a hosted
service supplies these behaviors depends on that service's implementation;
Mesh's public manifest alone does not establish them.

For an incompatible release, use a corrective release or a separately planned
database restore. A restore can lose subsequent writes and cannot undo external
side effects. Preserve the required key material with the database; see
[secrets and recovery](/secrets-and-recovery).

Implementation: [`internal/release/manifest.go` (repository)](https://github.com/TextureHQ/mesh/blob/main/internal/release/manifest.go)
and [`internal/migrate` (repository)](https://github.com/TextureHQ/mesh/tree/main/internal/migrate).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.