v1.4 Release Checklist

This checklist is the fail-closed bar for MUTX v1.4.

Owners

Area	Owner
Backend and contracts	`area:api`
Dashboard and browser UX	`area:web`
Desktop runtime and packaging	`area:desktop`
Release validation	`area:testing`
Docs and positioning	`area:docs`
Infrastructure and Helm	`area:infra`
Security and auth	`area:security`

Gate

Check	Owner	Pass condition
Python validation suite	`area:api`	`bash scripts/test.sh` passes its Python lint, compile, and pytest stages
Generated contract verification	`area:api`	`bash scripts/verify-generated-artifacts.sh` reports current artifacts with no drift
Release lint	`area:web`	`npm run lint` passes for the release-critical web and desktop surfaces
Typecheck	`area:web`	`npx tsc --noEmit` passes
Production build	`area:web`	`npm run build` passes with `proxy.ts` and no deprecated `middleware.ts` warning
Serial browser smoke	`area:testing`	`npm run test:e2e:release` passes the Chromium dashboard, auth, and registration flows
Desktop cockpit smoke	`area:desktop`	`npm run test:e2e:release` passes the desktop cockpit scenarios against the standalone build
Compose smoke	`area:api`	`bash scripts/smoke-compose-prod.sh` passes without skips
Signing environment	`area:desktop`	`npm run desktop:signing-check` passes on the release machine
Signed macOS package	`area:desktop`	`npm run desktop:package:release` builds signed `.app` bundles and ZIPs, then assembles DMGs whose mounted apps still pass recursive codesign verification
Notarization validation	`area:desktop`	`npm run desktop:notarize:status` reports valid signatures, mounted-DMG app integrity, Gatekeeper acceptance, and stapled tickets
Built app launch smoke	`area:desktop`	`npm run desktop:launch:smoke` launches the built `.app` and exits cleanly after readiness
SDK contract tests	`area:testing`	`pytest sdk/tests/` — all 20 contract test modules pass
RBAC enforcement	`area:security`	Routes under `/audit/`, `/security/`, `/policies/`, `/approvals/` reject unprivileged tokens
OIDC token validation	`area:security`	JWKS fetcher resolves, JWT signature and claim validation pass with test IdP
Helm chart lint	`area:infra`	`helm lint infrastructure/helm/mutx/` passes clean
Helm template render	`area:infra`	`helm template mutx infrastructure/helm/mutx/` renders 14 resources without errors
Railway production promotion	`area:ops`	frontend and backend Railway services deploy from the release commit using the production-promotion workflow
Public production smoke	`area:testing`	`bash scripts/verify-production-release.sh` passes against `mutx.dev`, `app.mutx.dev`, `api.mutx.dev`, and the synced release-notes page
Self-hosted docs live	`area:docs`	`https://docs.mutx.dev/docs/v1.4` is reachable after merge
Public release summary	`area:web`	`https://mutx.dev/releases` reflects the current desktop artifact set and links
Surface positioning	`area:docs`	preview/stable language in docs matches the actual gated surface set

Positioning Rule

Promote app.mutx.dev/dashboard to Supported only when all checks above pass on the release candidate machine, including signed packaging, notarization, checksum publication, and launch validation.

Keep app.mutx.dev/control/* and preview or redirect-backed dashboard routes labeled Preview and out of the primary stable navigation until their live contracts are complete.

Launch Order

Confirm the notarized macOS assets exist on the v1.4.0 GitHub release.
Confirm docs/releases/v1.4.md is merged, https://docs.mutx.dev/docs/v1.4 is live, and https://mutx.dev/releases reflects the same release.
Verify RBAC enforcement on /audit/*, /security/*, /policies/*, /approvals/* routes.
Verify OIDC token validation with configured IdP (optional — skip if no external IdP).
Run helm lint infrastructure/helm/mutx/ and helm template to validate the chart.
Run the Railway production-promotion workflow for the frontend and backend services.
Run bash scripts/verify-production-release.sh.
Verify the public download, release, auth, dashboard, API, docs, and Kubernetes surfaces point to the supported v1.4 surfaces.

New Environment Variables

The v1.4 release introduces these optional environment variables:

# OIDC Token Validation (optional — enable when connecting an external IdP)
OIDC_ISSUER=
OIDC_CLIENT_ID=
OIDC_JWKS_URI=

# CrewAI Adapter (required if using run_crew())
MUTX_API_KEY=***

Breaking Changes

RBAC is now enforced. Update test fixtures or service accounts that relied on open access to /audit/*, /security/*, /policies/*, /approvals/* with appropriate roles.
CrewAI run_crew() no longer accepts an empty API key. Set MUTX_API_KEY or pass api_key explicitly.

Railway Secrets Contract

The production-promotion workflow expects:

RAILWAY_TOKEN
RAILWAY_PROJECT_ID
RAILWAY_FRONTEND_SERVICE_ID
RAILWAY_API_SERVICE_ID
RAILWAY_ENVIRONMENT_ID

Optional overrides:

MUTX_SITE_URL
MUTX_APP_URL
MUTX_API_URL
MUTX_DOCS_RELEASE_URL

Helm Values Contract

Three value overlays are available:

Overlay	File	Use case
Dev	`values.yaml`	Single replica, minimal resources, managed DB enabled
Staging	`values.staging.yaml`	Middle ground — moderate replicas, reduced resources
Production	`values.prod.yaml`	HA replicas, topology spread, PDBs, managed DB disabled

Area

Owner

Backend and contracts

area:api

Dashboard and browser UX

area:web

Desktop runtime and packaging

area:desktop

Release validation

area:testing

Docs and positioning

area:docs

Infrastructure and Helm

area:infra

Security and auth

area:security

Gate

Check

Owner

Pass condition

Python validation suite

area:api

bash scripts/test.sh passes its Python lint, compile, and pytest stages

Generated contract verification

area:api

bash scripts/verify-generated-artifacts.sh reports current artifacts with no drift

Release lint

area:web

npm run lint passes for the release-critical web and desktop surfaces

Typecheck

area:web

npx tsc --noEmit passes

Production build

area:web

npm run build passes with proxy.ts and no deprecated middleware.ts warning

Serial browser smoke

area:testing

npm run test:e2e:release passes the Chromium dashboard, auth, and registration flows

Desktop cockpit smoke

area:desktop

npm run test:e2e:release passes the desktop cockpit scenarios against the standalone build

Compose smoke

area:api

bash scripts/smoke-compose-prod.sh passes without skips

Signing environment

area:desktop

npm run desktop:signing-check passes on the release machine

Signed macOS package

area:desktop

npm run desktop:package:release builds signed .app bundles and ZIPs, then assembles DMGs whose mounted apps still pass recursive codesign verification

Notarization validation

area:desktop

npm run desktop:notarize:status reports valid signatures, mounted-DMG app integrity, Gatekeeper acceptance, and stapled tickets

Built app launch smoke

area:desktop

npm run desktop:launch:smoke launches the built .app and exits cleanly after readiness

SDK contract tests

area:testing

pytest sdk/tests/ — all 20 contract test modules pass

RBAC enforcement

area:security

Routes under /audit/*, /security/*, /policies/*, /approvals/* reject unprivileged tokens

OIDC token validation

area:security

JWKS fetcher resolves, JWT signature and claim validation pass with test IdP

Helm chart lint

area:infra

helm lint infrastructure/helm/mutx/ passes clean

Helm template render

area:infra

helm template mutx infrastructure/helm/mutx/ renders 14 resources without errors

Railway production promotion

area:ops

frontend and backend Railway services deploy from the release commit using the production-promotion workflow

Public production smoke

area:testing

bash scripts/verify-production-release.sh passes against mutx.dev, app.mutx.dev, api.mutx.dev, and the synced release-notes page

Self-hosted docs live

area:docs

https://docs.mutx.dev/docs/v1.4 is reachable after merge

Public release summary

area:web

https://mutx.dev/releases reflects the current desktop artifact set and links

Surface positioning

area:docs

preview/stable language in docs matches the actual gated surface set

Positioning Rule

Keep app.mutx.dev/control/* and preview or redirect-backed dashboard routes labeled Preview and out of the primary stable navigation until their live contracts are complete.

Launch Order

Confirm the notarized macOS assets exist on the v1.4.0 GitHub release.

Confirm docs/releases/v1.4.md is merged, https://docs.mutx.dev/docs/v1.4 is live, and https://mutx.dev/releases reflects the same release.

Verify RBAC enforcement on /audit/*, /security/*, /policies/*, /approvals/* routes.

Verify OIDC token validation with configured IdP (optional — skip if no external IdP).

Run helm lint infrastructure/helm/mutx/ and helm template to validate the chart.

Run the Railway production-promotion workflow for the frontend and backend services.

Run bash scripts/verify-production-release.sh.

Verify the public download, release, auth, dashboard, API, docs, and Kubernetes surfaces point to the supported v1.4 surfaces.

Helm Values Contract

Three value overlays are available:

Overlay

File

Use case

Dev

values.yaml

Single replica, minimal resources, managed DB enabled

Staging

values.staging.yaml

Middle ground — moderate replicas, reduced resources

Production

values.prod.yaml

HA replicas, topology spread, PDBs, managed DB disabled

v1.4 Release Checklist#

Owners#

Gate#

Positioning Rule#

Launch Order#

New Environment Variables#

Breaking Changes#

Railway Secrets Contract#

Helm Values Contract#

v1.4 Release Checklist#

Owners#

Gate#

Positioning Rule#

Launch Order#

New Environment Variables#

Breaking Changes#

Railway Secrets Contract#

Helm Values Contract#

v1.4 Release Checklist

Owners

Gate

Positioning Rule

Launch Order

New Environment Variables

Breaking Changes

Railway Secrets Contract

Helm Values Contract

v1.4 Release Checklist

Owners

Gate

Positioning Rule

Launch Order

New Environment Variables

Breaking Changes

Railway Secrets Contract

Helm Values Contract