GitLab CI Component

Analyze your database migration scripts automatically on every merge request. The migracheck GitLab CI component posts a risk report as an MR note and sets a commit status 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 masked CI/CD variable named MIGRACHECK_API_KEY in Settings → CI/CD → Variables.
3. A GitLab access token with api scope — stored as a masked CI/CD variable named GITLAB_TOKEN. This is used by migracheck to post MR notes and set commit statuses. See Choosing a GitLab token below for which token type fits your plan.
4. Your project ID — visible in the web UI project page URL.

Choosing a GitLab token

GitLab offers several token types. Pick the one that fits your plan — in preference order:

In all cases, add the token as a masked CI/CD variable named GITLAB_TOKEN at Settings → CI/CD → Variables.

Why not just use CI_JOB_TOKEN? GitLab's built-in CI_JOB_TOKEN lacks the api scope needed to post MR notes and set commit statuses, so it cannot be used for this purpose.

Quick start

The component ships two templates. For most teams the analyze-changes template is the right choice — it diffs your changelog directory against the MR target branch (or the parent commit on a push) and runs migracheck on every changed migration file.

Add the following to your project's .gitlab-ci.yml:

include:
  - component: gitlab.com/migracheck/gitlab-component/analyze-changes@~latest
    inputs:
      project_id: "42"                              # from the migracheck web UI
      changelog_dir: "src/main/resources/db/changelog"
      migration_tool: "liquibase"                   # or "flyway"
      aurora_version: "8.0.28"
      replica_count: "2"
      fail_on: "critical,high"

What this does

1. Runs git diff against the MR target branch (or the parent commit on a push) to find changed files under changelog_dir.
2. For each changed file, runs migracheck analyze, posts an MR note with per-statement findings, and sets a commit status named migracheck.
3. Exits non-zero if any finding matches fail_on, blocking the MR (unless you set allow_failure: true for advisory mode).

Templates

The component ships two templates:

Inputs — analyze-changes

Inputs — analyze (single file)

Exit codes

The underlying CLI uses these exit codes to signal results:

• 0 — analysis complete, no threshold exceeded. Job passes.
• 1 — execution error (auth, network, invalid input). Job fails.
• 2 — severity threshold exceeded. Job fails, commit status is set to failed, MR note is posted.

Blocking merges

The commit status named migracheck shows up on the MR widget. To prevent merging MRs with critical or high-severity findings, require the status to pass:

1. Go to Settings → Repository → Merge request approvals (or Merge request settings, depending on GitLab tier).
2. Enable Pipelines must succeed, and/or add a merge rule that requires the migracheck status to be green.

Alternatively, use a Merge Request Approval Policy (Premium/Ultimate) to require passing external statuses.

Pinning

For reproducible pipelines, pin to a specific version instead of ~latest:

include:
  - component: gitlab.com/migracheck/gitlab-component/[email protected]

Multiple includes in one pipeline

Both templates can be included multiple times in a single pipeline — for example, to scan different directories with different thresholds. Use the job_name input (for analyze-changes) or job_suffix (for analyze) to give each inclusion a unique job name:

include:
  - component: gitlab.com/migracheck/gitlab-component/analyze-changes@~latest
    inputs:
      job_name: "migracheck-app-migrations"
      project_id: "42"
      changelog_dir: "app/db/changelog"
      migration_tool: "liquibase"

  - component: gitlab.com/migracheck/gitlab-component/analyze-changes@~latest
    inputs:
      job_name: "migracheck-reporting-migrations"
      project_id: "42"
      changelog_dir: "reporting/db/changelog"
      migration_tool: "liquibase"
      fail_on: "critical"   # advisory only for the reporting tier

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 — e.g. actual row counts to classify unbatched DML more precisely. No configuration needed.

Troubleshooting

"warning: post GitLab MR note: status 401"

The job's GITLAB_TOKEN is missing, expired, or doesn't have api scope. Recreate it following Choosing a GitLab token — a project access token is the right choice on Premium/Ultimate, a personal access token on Free. Confirm the CI/CD variable is masked and not scoped to a specific environment that doesn't match this pipeline.

"No migration changes under ... — skipping analysis"

The diff against the target branch didn't find any added or modified files matching file_glob under changelog_dir. Verify the paths, and confirm the MR actually touches migration files.

Shallow-clone errors on large MRs

If your MR has diverged significantly from the target branch, increase the diff depth via the git_depth input (default: 50).