Quickstart

SchemaDrift Guardian is a CI check that blocks breaking database and API schema changes at the pull request. Setting it up takes six steps and about ten minutes. Your production database is never contacted — the check builds a throwaway database from the pull request’s own migrations.

1. Install the GitHub App. Install the SchemaDrift Guardian GitHub App on the repositories you want to gate, so verdicts can post as a Check Run and pull request comment.
2. Sign in with GitHub. Sign in at schemadrift.dev with GitHub. A workspace is created for you on first sign-in.
3. Connect a schema. Add a data source: a name, the owner/repo to gate, and which database schemas to read. This is where the generated workflow and API key come from.
4. Copy the generated workflow. Copy the workflow the dashboard generates. It is pre-filled with your source name and the database and migration settings you entered.
5. Save the API key as a repository secret. Store the key the dashboard shows you once as the repository secret SCHEMADRIFT_API_KEY. It is stored as a hash and cannot be shown again.
6. Commit the workflow. Commit the workflow to .github/workflows/schema-drift.yml. The next pull request that changes the schema gets a verdict.

The workflow

The dashboard generates this for you, pre-filled. It stands up a throwaway Postgres, applies your migrations with migrate-command, introspects the result, and compares it against the baseline from your default branch. Start with fail-on-drift: false so the check reports without blocking, then switch it on once the verdicts have earned trust.

name: Schema drift
on: pull_request

jobs:
  schema-drift:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        ports: ['5432:5432']
    steps:
      - uses: actions/checkout@v4
      - uses: BraydensJones/schemadrift-guardian-action@v1
        with:
          api-key: ${{ secrets.SCHEMADRIFT_API_KEY }}
          data-source: your-source-name
          database-url: postgres://postgres:postgres@localhost:5432/postgres
          schemas: public
          migrate-command: <your migrate command>
          fail-on-drift: false

What counts as breaking

Anything that can break a reader without the reader’s code changing — a dropped column, table, or enum variant; a narrowed type; a column becoming NOT NULL; a removed or narrowed API response field. Additive changes are reported as informational and never fail a build. The FAQ covers supported databases, migration tools, and what the check can and cannot see.