sqlfluff-ci-rollout

name	sqlfluff-ci-rollout
description	Use when adding SQLFluff to CI or making SQLFluff PR checks manageable for a large SQL or dbt-style project.
compatibility	Requires sqlfluff on PATH and CI support for artifacts or annotations when used in CI.

SQLFluff CI Rollout

Purpose

Introduce SQLFluff to CI in phases so teams get useful feedback without blocking all work on existing violations. Use this when the user asks for CI integration, PR annotations, SARIF output, rollout strategy, or performance tuning for large SQL/dbt projects.

Workflow

1. Start report-only

   • Use --nofail while collecting the first baseline.
   • Write structured output to an artifact with --write-output.
   • Disable progress bars for cleaner CI logs.

2. Choose the CI feedback format

   • Use github-annotation-native for GitHub-native annotations.
   • Use github-annotation when a generic GitHub annotation format is needed.
   • Use sarif when uploading results to code scanning or long-lived artifacts.
   • Use json for custom summaries.

3. Scope the rollout

   • Prefer changed files, selected directories, or selected rule families.
   • Use --rules for allowlisted rollout.
   • Use --exclude-rules for a small number of temporary exceptions.

4. Measure runtime

   • Use --processes 0 when full CPU parallelism is acceptable.
   • Use --persist-timing to find slow files or rules.

5. Move toward blocking

   • Once violations are understood, remove --nofail for the selected scope.
   • Keep report-only jobs for broader scopes until they are clean enough to gate.

6. Document the policy

   • Record which paths/rules are blocking, which are report-only, and what must happen before expanding the gate.

Command Patterns

sqlfluff lint models/staging --format github-annotation-native --annotation-level warning --nofail --disable-progress-bar
sqlfluff lint models/staging --format sarif --write-output sqlfluff.sarif --nofail --disable-progress-bar
sqlfluff lint models/staging --persist-timing sqlfluff-timing.csv --disable-progress-bar

Output

Return:

• Proposed CI mode: report-only, scoped blocking, or full blocking.
• Command examples for the target CI environment.
• Artifact or annotation format.
• Runtime measurement plan.
• Criteria for expanding enforcement.

Progressive Disclosure

• Rollout patterns: references/rollout-patterns.md