OpenFace v0.5.0

OpenFace v0.5.0 moves the pipeline control plane onto a durable PostgreSQL schema and gives operators an explicit, verifiable path from the v0.4.0 SQLite history. The same release makes repository files easier to inspect, keeps long Space names inside their responsive layout, and splits repository validation into isolated jobs that can run in parallel.

Highlights

• Persist pipeline state in PostgreSQL: pipeline audit history, production reconciliation state, cursors, and migration markers now live in the openface_pipeline schema of the existing openface_metrics database. Startup and /healthz fail closed when the database or schema is not ready.
• Migrate legacy history deliberately:spaces-runner/pipeline_migration.py requires an explicit SQLite source, checks integrity, schema, timestamps, reconciliation payloads, and source digest, and refuses conflicting or incomplete rows. Re-running an unchanged verified source is idempotent; normal startup never searches for a legacy file.
• Make upgrades and restores recoverable: the bilingual runbook and scripts/restore_lxc_deployment.sh cover the three PostgreSQL databases, named volumes, optional MCP state, protected credential sources, fail-closed preflight, restore verification, and post-upgrade comparison. The upgrade contract continues to prohibit docker compose down --volumes.
• Preview repository files on the right branch: blob views use the repository's default branch, render README Markdown through the existing sanitization path, resolve relative links and assets from the file's directory, and fall back to source text when a preview cannot be rendered.
• Keep long Space headers usable: the Space identity, repository name, tabs, metrics, and runtime controls now have independent shrinkable regions; tablet and mobile runners size themselves from the wrapped header instead of assuming a fixed height.
• Validate faster with isolated CI jobs: Compose/configuration, frontend, bilingual documentation, Python and Skill checks, Spaces runner tests, and maintenance-agent tests run independently with isolated caches and temporary state. The required validate job remains the aggregate gate.

Operator impact

• Existing v0.4.0 installations that contain /data/agents/pipelines/pipeline-audit.db must stop spaces-runner, back up the file and its volume, run the migration's --verify-only command, and then perform the import before accepting new pipeline writes.
• The migration is not automatic. Keep the original SQLite file and its backup until row counts, stable IDs, timestamps, audit history, cursors, and reconciliation state have passed the post-upgrade comparison.
• The default schema is openface_pipeline; set OPENFACE_PIPELINE_DB_SCHEMA only to a safe PostgreSQL identifier when a deployment needs another schema. OPENFACE_PIPELINE_DATA_DIR is reserved for deployment and preview artifacts, not authoritative pipeline state.
• A fresh install receives the schema from PostgreSQL initialization. Existing Compose projects still need the complete backup and restore rehearsal in the upgrade runbook before changing images or volumes.

Documentation

Read the Repository Pipelines guide, upgrade and data retention runbook, Operations guide, and Proxmox LXC deployment guide. The v0.5.0 walkthrough follows the migration and validation story from an operator's point of view.

Validation

The release checklist covers the bilingual documentation validator and VitePress production build, SVG asset validation, frontend lint/tests/build, Python compilation, Spaces runner tests including PostgreSQL integration, Compose configuration, the restore-helper tests, CI's aggregate gate, and the release QA inventory. The final release is published only after the docs deployment and live release URLs are verified.

Upgrade contract

• Target path: v0.4.0 to v0.5.0, or a fresh install. Operators coming from an earlier release should first follow the applicable earlier release notes and then use this runbook.
• Breaking operational change: pipeline audit/history and reconciliation state move from the legacy SQLite file to PostgreSQL. There is no implicit import and no safe in-place downgrade after a completed data migration.
• Migration: run pipeline_migration.py --source ... --verify-only, then the same command without --verify-only against the unchanged, backed-up source. The command records the source digest and rejects conflicts; keep the source until post-upgrade verification is complete.
• Backup: dump forgejo, openface_metrics, and openface_maintenance; archive the Forgejo, metrics, maintenance, shared-token, runner, and any enabled MCP volumes; and separately protect the configured MCP bind state, credentials, .env, Z.AI configuration, and gateway certificates.
• Compose and environment: PostgreSQL initialization creates openface_pipeline, and OPENFACE_PIPELINE_DB_SCHEMA selects the safe schema name. Do not use docker compose down --volumes as an upgrade step.
• Rollback: before migration, restore the old checkout and images only after health checks pass. After migration, restore verified PostgreSQL dumps and named-volume archives in an isolated rehearsal rather than downgrading the schema in place.
• Post-upgrade: compare Compose health, PostgreSQL schema/migration markers, Forgejo repositories and Issues/PRs, Spaces, metrics, maintenance, pipeline rows and run numbers, and runtime logs.
• Known checks: real deployment timing, operator-specific restore paths, and runtime visual checks remain deployment checks; the release notes do not treat them as repository-only evidence.

See the upgrade and data retention runbook for the complete sequence and keep the Japanese release page in sync.