Skip to main content
Use this when a pull request changes schema files and CI should prove the migration before review. This workflow renders the migration from the PR diff, checks replay safety, and verifies apply-twice behavior against a disposable PostgreSQL service.

Do this

The scan step writes the job summary, creates a supaschema scan check run on the pull-request head SHA, and updates one PR comment with the score and top issues. It requires checks: write for the check run and issues: write because GitHub stores pull-request timeline comments through the Issues comments API. To include generated-contract usage diagnostics in that same scan report, pass the source directory explicitly:

Protected sync

Use the same action for a protected deploy job when supaschema.config.json defines workflow.migration_sync, sync.targets, generated output policies, and deploy safety gates. The action passes argv through unchanged; it does not set remote approval for you.

Keep

  • Use fetch-depth: 0 so git: sources can read the base ref.
  • Pin a PostgreSQL major that matches production, or run a matrix over supported majors.
  • Add --ensure-roles when migrations grant to roles that a bare PostgreSQL service does not have.
  • Use SUPASCHEMA_DATABASE_URL instead of repeating --database-url when multiple steps need the same target.
  • Set a remote approval variable, such as SUPASCHEMA_REMOTE_SYNC_APPROVED, only in the protected workflow or environment that is allowed to deploy.

Verify

For a smaller drift-only gate:
Upload SARIF when you want code-scanning results:

CI gate

Decide which checks belong in required status.

Diff command

Compare configured sources or explicit refs.

Check command

See reporter and diagnostic options.

Verify command

Prove apply-twice behavior in a disposable database.
Last modified on July 11, 2026