Environments & Release Process

:::info Status Implemented. Source: DEPLOY.md. :::

Production deployments are triggered by git tags via a GitHub Actions workflow that SSHs into the server. See Deployment Architecture for the container topology this operates on.

Deploying a release

git tag v1.0.0
git push origin v1.0.0

Tag format is semantic versioning: v<major>.<minor>.<patch>. A manual trigger is also available (Actions → Deploy → Run workflow); leaving the tag field empty deploys the latest tag.

What happens during deployment

1. GitHub Actions SSHs into the production server.
2. Fetches the latest tags, checks out the specified tag.
3. Runs docker compose up -d --build --remove-orphans:
   • the migrate service runs alembic upgrade head and must exit 0;
   • fastapi-backend waits on service_completed_successfully from migrate and never starts against a half-migrated schema.
4. Prunes old Docker images.
5. Reports container status.

Required environment

GitHub Secret	Description
SSH_HOST	Production server IP/hostname
SSH_USER	SSH username
SSH_PRIVATE_KEY	SSH private key
SSH_PORT	SSH port (default 22)

GitHub Variable	Description
DEPLOY_PATH	Absolute path to the project directory on the server

Rollback

git push origin v0.9.0   # deploy an older tag

Or trigger the manual workflow with the desired tag. Because database migrations are forward-only by design (downgrade() deliberately raises NotImplementedError — see Backend Deployment), a code rollback does not revert schema; behavior changes instead roll back via feature-flag environment variables (FANOUT_V2, STREAM_AUTHZ_ENFORCE).

Concurrency

The deploy workflow uses a concurrency group (deploy-production, cancel-in-progress: false) — only one deployment runs at a time; queued deployments wait rather than get cancelled.

Troubleshooting a failed deploy

Symptom	Check
Deployment failed	GitHub Actions logs for the run
Containers won't start	docker compose logs --tail=50 on the server
Server disk space	docker system prune -af

More: Operations — Troubleshooting.