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

# Server and dashboard

> Release notes for the self-hosted Patch server and its bundled dashboard, by version.

# Server and dashboard release notes

Release notes for the server image, tagged `codemagic-patch-server-vX`. The
dashboard is included in the image and has no separate version. Every entry
starts with **Upgrade impact**: migrations, configuration changes, and anything
that restarts or replaces a service. Review it before upgrading. Managed Patch
runs the latest server; self-host operators upgrade with
[`cmpatch selfhost upgrade`](/docs/reference/cli-reference#self-hosting). The
other surfaces' releases are on the
[Release Notes](/docs/releases) page.

Reference: [Configuration](/docs/reference/configuration) ·
[Operations](/docs/reference/operations) ·
[GitHub releases](https://github.com/codemagic-ci-cd/codemagic-patch/releases?q=codemagic-patch-server)

## 0.11.0 {#v0-11-0}

*19th November 2026*

### Upgrade impact

- Runs migration `0023_webhooks`. It adds three tables and one column on
  `release_job`, and leaves existing rows as they are.
- No configuration changes are required.
- Do not roll back to an older image after the migration. Server 0.10.0 does
  not start on a migrated database. See
  [Upgrades](/docs/setup/ongoing-maintenance#upgrades).

### Webhooks {#v0-11-0-webhooks}

Adds webhooks for release events. Register a URL for your team, and the server
sends it a signed `POST` when a release goes live, changes, or fails.

```bash
cmpatch webhook create --url https://example.com/hooks/patch
```

- Sends `release.published`, `release.promoted`, `release.rolled_back`,
  `release.updated`, `release.disabled`, `release.enabled`, and
  `release.failed`, plus `ping` for a test.
- Signs every request as described by
  [Standard Webhooks](https://www.standardwebhooks.com/), so you can verify it
  with an existing library.
- Retries a failed delivery for about a day. After that you can send it again
  yourself. Delivery history is kept for 30 days.
- Accepts public `https` URLs only. On a self-hosted server, set
  `WEBHOOK_ALLOW_PRIVATE_TARGETS=true` to allow private addresses and `http`.

Team admins and owners manage webhooks on the dashboard's **Webhooks** page or
with `cmpatch webhook` in [CLI 0.11.0](/docs/releases/cli#v0-11-0). See
[Webhooks](/docs/using-patch/webhooks).

### Other changes

- Adds `owner` to `POST /v1/teams`. The request creates the team and invites
  its owner, and it works with an API token. A server older than 0.11.0
  ignores `owner`, so check the response for `owner_invitation`. See
  [API tokens](/docs/using-patch/security#api-tokens-ci-and-automation).
- Makes the dashboard usable on a phone. Tables drop their secondary columns,
  and management actions are hidden on narrow screens.
- The Add member dialog now says that no email is sent to the person you add.
- Shortens page subtitles and dialog text across the dashboard.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.11.0).

## 0.10.0 {#v0-10-0}

*17th November 2026*

### Upgrade impact

- Update `cmpatch` to [CLI 0.10.0](/docs/releases/cli#v0-10-0) or later
  before you upgrade. CLI 0.9.0 and older leave the server's checkout on the
  default branch, and this release's upgrade script refuses a checkout that
  is not at a release tag. A refused upgrade changes nothing, so update the
  CLI and run it again.
- The upgrade checks out the `codemagic-patch-server-v0.10.0` tag and pulls
  `ghcr.io/codemagic-ci-cd/codemagic-patch-server:0.10.0` instead of building,
  so the server must reach `ghcr.io`. `--build-from-source` builds on the
  server as before.
- Runs the stock `caddy:2-alpine` image for Caddy, pinned by digest, and
  serves the dashboard from the server image. `/worker/*` answers 404 instead
  of the dashboard page, and a plain-HTTP install no longer sends an HSTS
  header.
- Runs migration `0021_credential_generation`, which adds one integer column
  each to `user_account`, `api_token`, and `oauth_session`.
- Runs migration `0022_service_account_owner_team`, which adds
  `user_account.owner_team_id`. It marks a `member provision` account as a
  service account of its team when it has never signed in and belongs to
  that team only. Existing tokens and sessions stay valid.
- A session older than 90 days fails at its next refresh. Sign in again.
- CI that uses an API token to create tokens, add or invite members, change
  roles, or transfer apps stops working. See
  [API tokens](#v0-10-0-api-tokens).
- Do not switch back to an older image alone once the database is migrated.
  If the upgrade fails after the stack is recreated, follow the steps the
  command prints, which end with restoring the pre-upgrade backup. See
  [Upgrades](/docs/setup/ongoing-maintenance#upgrades).

### Breaking: API tokens cannot create credentials or grant access {#v0-10-0-api-tokens}

An API token (`cm_pat_…`) can no longer give access to anyone else, so a
leaked token leaves no access behind once it is deleted. These need a browser
sign-in (the dashboard, or `cmpatch login` without `--token`) and answer a
token with `403`, reason `session_required`:

- `token create`, and approving a CLI login
- `member add`, `member invite`, `member update`
- `member provision`, `member rotate-token`
- `app transfer`

A token can still manage apps, deployments, and releases, and remove
members, invitations, and tokens.

- The server logs each refused request with the token's ID.
- Roles and invitations a token granted before this release are not revoked.
  If a token may have leaked, review your team's members.
- An account that has never signed in through a provider loses its API
  tokens at its first provider sign-in. This covers `member provision`
  accounts, and accounts created before OAuth sign-in that are linked by
  email. Create new tokens after that sign-in.

See [API tokens](/docs/using-patch/security#api-tokens-ci-and-automation).

### Sessions

- A sign-in ends 90 days after the provider sign-in, however often it
  refreshes. A CLI sign-in approved from the dashboard shares that dashboard
  sign-in's deadline.
- Adds sign out everywhere to the dashboard's API tokens page. It ends every
  session on your account, including the current browser and every CLI, and
  deletes all your API tokens. See
  [Sessions and signing out everywhere](/docs/using-patch/security#sessions-and-signing-out-everywhere).

### Service accounts

- A `member provision` account is a service account of the team that created
  it. It has access in that team only, even if it is added to another team,
  and the Members page marks it with a **Service account** badge.
- An admin of the owning team replaces its token with **Rotate token** on the
  Members page or
  [`cmpatch member rotate-token`](/docs/releases/cli#v0-10-0). The old token
  stops working immediately.

### Self-hosting

- Each server release publishes one image for x86 and ARM, with a build
  provenance attestation. [CLI 0.10.0](/docs/releases/cli#v0-10-0) installs
  and upgrades from it instead of building on the server.
- The server refuses to start on a database that has applied a migration the
  release does not know. `cmpatch selfhost upgrade` checks for that before it
  changes anything.

### Metrics API

Metrics responses now include values the dashboard used to calculate itself.
Existing fields are unchanged.

- Adds `success_rate` to every metrics object. It is applied over applied
  plus failed, from 0 to 1, or `null` when both are 0.
- Adds `summary` to deployment metrics and timeseries responses. It holds the
  totals of the returned page or range, and the active devices of the last
  complete UTC day.
- Adds `cumulative_success` to each timeseries series, the running Applied
  total per day.

### Dashboard

- Removes the Metrics pages. A deployment page shows adoption over time and
  the totals of the selected range, and a release page shows its counters and
  the failure drill-down. Old `/metrics` links answer 404.
- The release page shows who created and last updated the release, what they
  did, and when. Job attempts and failure detail appear only while a job runs
  or after it fails.
- The deployment page refreshes its release history while a release is
  processing.
- Each provider's sign-in button shows its logo.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.10.0).

## 0.9.0 {#v0-9-0}

*3rd November 2026*

### Upgrade impact

- Runs migration `0020_server_instance`, which creates the empty
  `server_instance` table for the usage report's instance id. No existing
  table is touched and no lock of note is taken.
- Sends Codemagic an anonymous usage report of aggregate counts once a day,
  on by default. Codemagic uses it only for public statistics, never to
  enforce the licence's 1M MAU limit. Set `SERVER_TELEMETRY=false` (or
  `DO_NOT_TRACK=1`) in `.env.selfhost` to turn it off.
- `docker-compose.selfhost.yml` now passes `SERVER_TELEMETRY`,
  `DO_NOT_TRACK`, and `SERVER_UPDATE_CHECK` through to the server. A
  `SERVER_UPDATE_CHECK=false` line in `.env.selfhost` was silently dropped
  before, and now turns the GitHub release lookup off.
- Rollback is safe. An older image ignores the `server_instance` table.

### Dashboard

- The deployment charts use muted series colours instead of neon ones, in
  light and dark mode.
- The Status page names the bundled object store Silo, which is what runs.
  The health check path is unchanged.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.9.0).

## 0.8.0 {#v0-8-0}

*28th October 2026*

### Upgrade impact

- Runs migration `0019_metricEventDailyAggregates`, which adds the daily
  aggregate tables and the fold watermark, and builds an index on
  `metric_event (emitted_at)`. Metrics ingest waits for the index build,
  which takes longer on a large history. Reads are not blocked.
- Shortly after startup, the server folds the existing history outside the
  raw retention window and deletes those raw events, including individual
  failure details. On a large history, the first run takes one long
  transaction per folded day.
- Postgres keeps the space the fold frees for new rows instead of returning
  it to the operating system, so the volume stops growing but does not
  shrink. To shrink it, see
  [Disk size](/docs/setup/ongoing-maintenance#disk-growth).
- A server older than 0.8.0 reads raw rows only, so the days already folded
  disappear from its metrics. To roll back, restore the pre-upgrade backup
  instead of only switching back to an older image.
- No configuration changes are required.

### Metrics: 8-day raw retention

- Keeps raw metric events for 8 UTC days. Older events are folded once a day
  into daily aggregates, which are kept indefinitely. Counters, adoption
  charts, timeseries, and failure reasons are unchanged across the fold.
- The per-event failure list (`failure-events` in the CLIs, the failure
  dialog's event list in the dashboard) covers the retained days only. A
  later `Applied` clears a device's earlier `Failed` events only within that
  window.
- Acknowledges but does not store an event dated 8 or more days before the
  day the server receives it, or more than 24 hours ahead. SDKs already drop
  events older than 7 days, so devices with a correct clock are unaffected.

### Self-hosting

- The self-host scripts support a local stack reached at an ngrok `https://`
  address through
  [`cmpatch selfhost install --ngrok`](/docs/releases/cli#v0-8-0).
- The Status page's upgrade hint now says to run `cmpatch selfhost upgrade`
  from the machine you installed from, which covers Fly installs as well as
  SSH ones.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.8.0).

## 0.7.0 {#v0-7-0}

*19th October 2026*

### Upgrade impact

- Runs migration `0018_drop_metric_event_sdk_version`, which drops the unused
  `sdk_version` column from the `metric_event` table. The lock is brief and
  the table is not rewritten. Older SDKs that still send `sdk_version` keep
  working, and the server ignores the field.
- A server older than 0.7.0 still writes `sdk_version`, so its metrics ingest
  fails after this migration. To roll back, restore the pre-upgrade backup
  instead of only switching back to an older image.
- No configuration changes are required.

### Fixes

- The deployment and release pages fetch only the selected adoption chart
  range instead of all four. This reduces database load, and the pages no
  longer stall under heavy usage.
- A backup restarts the exact server container it stopped. Before, the
  restart could start a server with a different image or configuration if
  either changed during the backup, as happens during
  `cmpatch selfhost upgrade`.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.7.0).

## 0.6.0 {#v0-6-0}

*6th October 2026*

### Upgrade impact

- Runs migration `0017_app_framework`, which adds a `framework` column to the
  `app` table with the default `react-native`. No index is rebuilt.
- Problem details include a machine-readable `reason`, and `detail` no longer
  names a `cmpatch` command. CLI 0.6.0 and `cmpatch-capacitor` print the
  remedy themselves. Update scripts that matched the old `detail` text.
- No configuration changes are required.

### Capacitor apps

The server stores each app's framework (`react-native` or `capacitor`), and
`cmpatch-capacitor` sets it on `app create`. `GET /v1/teams/:id/apps` accepts
`framework=` and returns only apps with that framework, or all apps without
it. Apps created before this release are treated as React Native.

The dashboard shows commands for the app's framework. For a Capacitor app,
the New release dialog takes the built web assets (the `webDir` of
`capacitor.config`, or a ZIP of its contents), requires a target binary
version, and shows the `cmpatch-capacitor release` command instead of
`cmpatch release-react`.

### Binary version filter

Adds a **Binary version** menu to the deployment page. It filters the
Adoption card and the release history table, and lists the versions that
reported in the selected range, plus group rows such as `1.x` and `1.0.x`
when a group covers two or more versions. The Metrics page has the same menu,
and its Active devices card counts the selected version or group. Release
detail has a **By binary version** table with Downloaded, Ready, Applied,
Failed, and success rate per reported binary version, shown when two or more
versions reported.

- `GET /v1/metrics/deployments/:id/timeseries` and
  `GET /v1/deployments/:id/releases` accept `binary_version` (exact) or
  `binary_version_prefix` (dot-separated digits; `1` matches `1.0.0` and
  `1.10.2`, not `10.0.0`). Both together return `400 invalid_combination`.
  The timeseries response includes `binary_versions`, and
  `GET /v1/metrics/releases/:releaseId` now returns `{ binary_versions, release }`.
- In filtered release history, a release matches when its explicit target
  binary version matches or any version in its current resolved target set
  matches. Fingerprint-expanded targets are included and superseded
  generations are not. Rollback gating and the suggested target for a new
  release use the unfiltered history.

### Full and diff download metrics

Adds a card to release detail with the size and download count of the full
bundle and of the diff from the previous release. The diff size is measured
against the previous release only, so it is approximate when devices skip
releases.

See the [configuration reference](/docs/reference/configuration) and
[server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.6.0).

## 0.5.1 {#v0-5-1}

*2nd October 2026*

### Upgrade impact

- Replaces the bundled MinIO object storage images, which are no longer
  available to pull, with PGSTY Silo images. The upgrade replaces the storage
  container. Existing storage volumes stay compatible and need no data
  migration.
- No database migration or configuration change.

### Fixes

- A backup restarts only the server service. It no longer recreates
  dependent services such as object storage or the database before the
  backup is confirmed.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.5.1).

## 0.5.0 {#v0-5-0}

*23rd September 2026*

### Upgrade impact

- Runs migration `0016_metric_event_lifecycle_names`, which rebuilds an index
  on the `metric_event` table while holding an exclusive lock on it. On
  servers with a large metrics history, the upgrade takes longer.
- Stores events from SDK 0.4.x and earlier under the new `Ready` and
  `Applied` lifecycle names. Existing data is kept as is, and the metrics API
  response keys (`installed`, `success`) are unchanged. SDK 0.5.0 needs this
  server; see [compatibility](/docs/releases#upgrade-order-and-compatibility).
- Adds the optional setting `GITLAB_OAUTH_BASE_URL`, for GitLab sign-in on a
  self-managed instance. Leaving it unset changes nothing.

### GitLab sign-in

Adds GitLab sign-in for self-hosted servers, on gitlab.com or a self-managed
instance set with `GITLAB_OAUTH_BASE_URL`. GitLab accounts that have only a
confirmed primary email can sign in, and the sign-in button shows the GitLab
name and icon.

### Command palette and navigation

Adds a command palette (⌘K / Ctrl+K) that opens apps, releases, metrics, and
teams, and runs common actions. The deployment page shows update adoption and
links to the Metrics screens, and the sidebar lists apps with their
deployments. Release details include a cumulative `Applied` chart of update
adoption over time.

- Fixes dashboard page scrolling and removes blank space that a hidden chart
  table added at the bottom of the page. Cleans up how the deployment and
  release detail pages show status, metrics, charts, and history.

See the [configuration reference](/docs/reference/configuration) and
[server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.5.0).

## 0.4.0 {#v0-4-0}

*14th September 2026*

### Upgrade impact

- Adds the optional setting `S3_INTERNAL_BUCKET`, described below. Leaving it
  unset keeps single-bucket routing.
- No database migration.

### Changes

- S3-compatible storage can use `S3_INTERNAL_BUCKET` to keep internal uploads
  and worker artifacts in a separate private bucket while release artifacts
  are served publicly. Leaving it unset keeps single-bucket routing.
- Adds light, dark, and system themes to the dashboard, refreshes branding,
  and improves accessibility. Fixes translucent callouts in dark mode.
- Release details no longer show Active counts in delivery metrics.
  Deployment summaries show successful installs, and release history includes
  downloads. Success counts are installations, not users currently running a
  version.
- Run `scripts/selfhost/install.sh --allow-http` from a local clone to test
  the self-hosted stack on localhost over HTTP, without TLS certificates or
  public DNS. Service ports bind to loopback, and OAuth setup is still
  required.

See the [configuration reference](/docs/reference/configuration) and
[server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.4.0).

## 0.3.0 {#v0-3-0}

*7th September 2026*

### Upgrade impact

- Runs migration `0013_metric_event_failure_payload`, which adds the nullable
  `failure_payload` column to `metric_event` without backfilling existing
  events.
- Runs migrations `0014_metric_event_failure_feed` and
  `0015_metric_event_device_outcome`, which create three indexes on that
  table for failure details and device outcomes. Index creation is not
  concurrent and blocks writes to the table, so allow extra upgrade time on
  servers with a large metrics history.
- If you use Cloudflare, delete the two-hour Edge TTL Cache Rule for `.json`
  from the previous setup guide after you upgrade, and remove any
  `MANIFEST_CACHE_CONTROL` line from `.env.selfhost`. The Cache Rule
  overrides the origin `s-maxage` and extends the stale window from five
  minutes to two hours. A leftover `MANIFEST_CACHE_CONTROL` pins the old
  `no-cache` value, so manifests are never cached at the edge. See
  [CDN settings](/docs/reference/cdn#add-cache-rules).
- No configuration change beyond the Cloudflare cleanup.

### CloudFront delivery

Devices can fetch artifacts from Amazon CloudFront, in addition to Cloudflare
or the origin host, for bundled MinIO or external S3/GCS. The install wizard
prints the AWS Console values, generates the origin secret, and verifies the
distribution before you move DNS. It does not create AWS resources or ask for
AWS credentials beyond the scoped purge key. See
[CDN settings](/docs/reference/cdn#cloudfront).

### Failure details

Failed installs reported by [SDK 0.3.0](/docs/releases/react-native#v0-3-0)
include diagnostic details: HTTP status, the origin or platform error
message, and on Android 11+ the previous process exit reason. Before, the
dashboard showed only a `network` count. On the metrics view, open a failure
reason to see its codes, then open a code to see the values behind it. See
[Analytics and metrics](/docs/using-patch/analytics).

### Failure counts exclude later successes

Failure counts include only devices that never got the update, not network
retries that later succeeded. When a device later installs the same package
successfully, its earlier `Failed` events for that package are dropped. A
late `Failed` after an `Applied` is acknowledged and discarded.

### Status page

Adds a **Status** page to the dashboard. It shows API and database health,
whether the download URL is reachable, disk use on a bundled single-host
install, and the running server version compared with the latest GitHub
release. The disk and version cards are hidden on topologies where they do
not apply.

See the [server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.3.0).

## 0.2.0 {#v0-2-0}

*25th August 2026*

### Upgrade impact

- Rejects uploads from CLI 0.2.0 and the dashboard with `409` when the
  fingerprint disagrees with the one recorded for the deployment and binary
  version, unless the client overrides it. Older clients keep the
  warning-only behavior.
- Adds optional setup for Compose to target an external PostgreSQL database
  and S3-compatible bucket (see below). The default install is unchanged.

### Fingerprint mismatch check

Uploads can send `block_on_fingerprint_mismatch: true`. When the release
fingerprint differs from the value already recorded for that deployment and
binary version, the server returns `409` and creates no release. The
dashboard compares fingerprints the same way and shows the details before you
proceed. CLI 0.2.0 and the dashboard send the flag by default. Older clients
and explicit overrides keep the previous warning-only behavior. See
[Fingerprinting](/docs/using-patch/fingerprinting).

### Failure reasons

Adds `failure_reasons` to each release in the metrics APIs and the
dashboard. It breaks failures down by category: integrity, signature,
rollout, or another category. The counts sum to `failed`. See
[Analytics and metrics](/docs/using-patch/analytics).

### External Postgres and object storage

Compose can use a managed PostgreSQL database and an S3-compatible bucket
instead of the bundled Postgres and MinIO containers. The default
`scripts/selfhost/install.sh` run still creates the bundled stack. For an
external database or storage, pass the install script's database and storage
flags, then configure adapters as described in
[Infrastructure](/docs/setup/infrastructure) and
[Configuration reference](/docs/reference/configuration).

The default backup script does not copy external databases or buckets. Use
provider-level backups for those components. See
[Operations](/docs/reference/operations) and the
[server release](https://github.com/codemagic-ci-cd/codemagic-patch/releases/tag/codemagic-patch-server-v0.2.0).
