GitHub Actions

Analyze your database migration scripts automatically on every pull request. The migracheck GitHub Action posts a risk report as a PR comment and creates a check run that fails when severity thresholds are exceeded.

Prerequisites

1. A migracheck account with a project set up for your repo.
2. An API key — generate one in the web UI under your organization's API Keys page, then add it as a repository secret named MIGRACHECK_API_KEY in Settings → Secrets and variables → Actions.
3. Your project ID — visible in the web UI project page URL.

Quick start

Create .github/workflows/analyze-migrations.yml in your repository:

name: Analyze migrations

on:
  pull_request:
    paths:
      - 'db/migration/**'   # adjust to your migration directory

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  detect:
    runs-on: ubuntu-latest
    outputs:
      files: ${{ steps.changed.outputs.files }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: List changed migration files
        id: changed
        run: |
          git fetch origin "$GITHUB_BASE_REF" --depth=1 || true
          mapfile -t files < <(git diff --name-only --diff-filter=AM \
            "origin/$GITHUB_BASE_REF...HEAD" \
            -- 'db/migration/*.sql')
          if [ "${#files[@]}" -eq 0 ]; then
            echo "files=[]" >> "$GITHUB_OUTPUT"
          else
            json=$(printf '%s\n' "${files[@]}" | jq -R . | jq -sc .)
            echo "files=${json}" >> "$GITHUB_OUTPUT"
          fi

  analyze:
    needs: detect
    if: needs.detect.outputs.files != '[]'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        file: ${{ fromJson(needs.detect.outputs.files) }}
    steps:
      - uses: actions/checkout@v4

      - name: Analyze ${{ matrix.file }}
        uses: beachygreg/migracheck-action@v1
        with:
          project-id: "YOUR_PROJECT_ID"
          script: ${{ matrix.file }}
          api-key: ${{ secrets.MIGRACHECK_API_KEY }}
          migration-tool: flyway
          aurora-version: "8.0.28"
          fail-on: critical,high

What this does

1. detect — finds new or changed .sql files in your migration directory and outputs them as a JSON array.
2. analyze — runs once per changed file via matrix strategy. Each run posts a collapsible PR comment with per-statement findings and creates a GitHub check run with the overall verdict.

Action inputs

Exit codes

The action uses the CLI's exit codes to control the check result:

• 0 — analysis complete, no threshold exceeded. Check passes.
• 1 — execution error (auth, network, invalid input). Check fails.
• 2 — severity threshold exceeded. Check fails.

Blocking merges

To prevent merging PRs with critical or high-severity findings, add a branch protection rule for your main branch:

1. Go to Settings → Branches → Add branch protection rule.
2. Enable Require status checks to pass before merging.
3. Search for and select the migracheck check.

Permissions

The workflow needs these permissions for the action to post comments and check runs:

permissions:
  contents: read        # checkout the code
  pull-requests: write  # post PR comments
  checks: write         # create check runs

The action uses the default GITHUB_TOKEN provided by GitHub Actions — no additional tokens or GitHub App installation required.

Metadata snapshots

If your project has metadata snapshots uploaded (via the CLI or web UI), the analysis automatically uses the most recent snapshot for richer risk assessment. No configuration needed — just keep your snapshots up to date.