← All docs

GitHub Action

Run MigrationPilot as a GitHub Action to catch unsafe migrations in pull requests.

Basic Setup

Add MigrationPilot to your GitHub Actions workflow to automatically analyze migration files on every pull request:

# .github/workflows/migration-check.yml
name: Migration Safety Check
on:
  pull_request:
    paths:
      - 'migrations/**'

permissions:
  contents: read
  pull-requests: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mickelsamuel/migrationpilot@v1
        with:
          migration-path: "migrations/*.sql"
          fail-on: critical

Action Inputs

The GitHub Action supports the following inputs:

- uses: mickelsamuel/migrationpilot@v1
  with:
    # Glob for your migration files (required). A directory,
    # like migrations/, means every .sql file under it.
    migration-path: "db/migrations/*.sql"

    # Target PostgreSQL version (default: the config's pgVersion, else 17)
    pg-version: "16"

    # Fail threshold: critical, warning, irreversible, never
    # (default: the config's failOn, else critical)
    fail-on: critical

    # Production database URL for context
    database-url: ${{ secrets.DATABASE_URL }}

    # Comma-separated rules to exclude
    exclude: "MP037,MP041"

    # Config file (default: the .migrationpilotrc.yml nearest the repo root)
    config-file: ci/migrationpilot.yml

    # Org plan key: turns on the config's policy block and audit log
    license-key: ${{ secrets.MIGRATIONPILOT_LICENSE_KEY }}

PR Comment Output

MigrationPilot automatically posts a comment on the pull request with a summary of findings. The comment includes risk level, violation details with severity, lock types, and safe alternatives. Comments are updated on subsequent pushes rather than duplicated.

Files It Can't Check

A migration the Action can't read or parse fails the check, because nothing analyzed it. The failure names each file and the parser's error, and the PR comment lists those files at the top. A file the pull request changed but the checkout doesn't contain fails the same way, so check out the pull request's commit. Files that aren't plain SQL, such as ones with psql meta-commands or template placeholders, go under ignore in your config. With fail-on: never they're reported and the check still passes.

# .migrationpilotrc.yml
ignore:
  - "migrations/seed_*.sql"
  - "migrations/templates/**"

SARIF Integration

The Action writes its findings to migrationpilot-results.sarif in the workspace. Upload that file to GitHub Code Scanning for inline annotations:

- uses: mickelsamuel/migrationpilot@v1
  with:
    migration-path: "migrations/*.sql"

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: migrationpilot-results.sarif

Production Context

Give the Action a database URL and it can check table sizes, write traffic, replication state, and index definitions for context-aware analysis. This is free — no license key needed:

- uses: mickelsamuel/migrationpilot@v1
  with:
    migration-path: "migrations/*.sql"
    database-url: ${{ secrets.DATABASE_URL }}
← ConfigurationCI Integration →