Upgrades

Treat upgrades as an operational change: back up state, run migrations once, deploy compatible services together, and validate product workflows before inviting users back in.

Upgrade checklist

Read release notes or the relevant pull request.
Back up Postgres.
Back up or snapshot the graph database.
Preserve current deployment secrets and image tags or commit SHA.
Confirm there are no long-running connector or ingestion jobs you need to let finish first.
Run migrations against the target database.
Deploy backend, worker, UI, and codesearch from the same commit or release.
Validate health, sign-in, repository indexing, Chat/MCP, and connectors.

Docker Compose flow

For source-based Compose deployments:

git fetch origin
git checkout <target-ref>
docker compose --profile deploy build
docker compose --profile deploy up -d

The deploy profile runs the migrate service before app services. Check the migrator logs before validating the app.

docker compose logs migrate
docker compose logs backend worker codesearch

Image-based flow

For platforms that run prebuilt images:

Build images for backend, worker, UI, and codesearch from the same commit.
Push images with an immutable tag, such as a commit SHA.
Run migrations using the backend image for that same commit.
Update all app services to the new image tags.
Keep the previous image tags available until validation completes.

Validation

After deployment:

Area	Validation
Backend	`GET /.status` returns `status: "ok"`
Auth	Sign in with the configured provider
UI	Open app through `AUTH_BASE_URL`; do not bypass backend proxy
Repositories	Existing repository list loads; new or reindexed repository succeeds
Codesearch	Search and file retrieval work for an indexed repository
Graph	Knowledge graph page loads for an organization with indexed data
MCP	MCP client connects using OAuth
Connectors	GitHub webhook and Confluence setup/sync still work
Observability	Logs and traces continue to reach your configured sinks

Rollback

Rollback depends on whether the upgrade ran database migrations.

Situation	Rollback approach
No migrations ran	Revert service images or source ref and restart services.
Forward-compatible migrations ran	Revert services only if the previous version can tolerate the new schema.
Breaking migrations ran	Restore Postgres from backup, restore graph data if needed, then redeploy the previous version.

Backups define rollback quality

A code rollback without a database restore is not always safe. Take a backup before running migrations and test restore in the environment style you use for production.

Upgrade notes by component

Component	Watch for
Backend	Schema migrations, auth behavior, MCP route compatibility, connector API changes
Worker	Workflow compatibility, connector job changes, Forge provisioning changes
UI	Build-time public URL values, connector wizard behavior
Codesearch	Index format or clone/cache behavior
Graph database	Provider configuration and graph projection compatibility
Model provider	Default model names, embedding dimensions, provider-specific auth

Operations

Backups, logs, and recovery checks.

Configuration

Deployment variables and image setup.

Production readiness

Preflight checklist for live deployments.