Integration Options

This guide covers CI/CD integration for PR reviews and pipeline gates. For runtime integration (agents, applications checking SQL before execution), see Runtime / Agent Integration.

Dashboard

The dashboard provides a web UI for viewing analysis results, trends, and findings.

# Start dashboard (reads from local directory)
lexega-sql dashboard --data-dir .lexega/

# Read from cloud storage (S3, GCS, or Azure)
lexega-sql dashboard --data-dir s3://my-bucket/lexega-data

# Custom port / don't auto-open browser
lexega-sql dashboard --data-dir .lexega/ --port 8080 --no-open

Expected Directory Structure

The dashboard expects decision and report JSON files under decisions/ and reports/ subdirectories:

<data-dir>/
  decisions/
    <run-id>/decision.json
    ...
  reports/
    <run-id>/risk_report.json
    ...

This structure is created automatically when you use --decision-out and --report-out with the right paths:

# Local: write artifacts into the directory the dashboard reads
lexega-sql analyze models/*.sql \
  --policy policy.yml --env prod \
  --decision-out .lexega/decisions/$GITHUB_RUN_ID/ \
  --report-out .lexega/reports/$GITHUB_RUN_ID/

# Cloud: same structure, just an S3/GCS/Azure prefix
lexega-sql analyze models/*.sql \
  --policy policy.yml --env prod \
  --decision-out s3://my-bucket/lexega-data/decisions/$GITHUB_RUN_ID/ \
  --report-out s3://my-bucket/lexega-data/reports/$GITHUB_RUN_ID/

Cloud Storage Support

Pass a cloud URI as --data-dir and the dashboard downloads files on startup and on refresh:

# S3
lexega-sql dashboard --data-dir s3://my-bucket/lexega-data

# GCS
lexega-sql dashboard --data-dir gs://my-bucket/lexega-data

# Azure Blob Storage
lexega-sql dashboard --data-dir az://my-container/lexega-data

Cloud credentials are read from standard environment variables (AWS_* / GOOGLE_APPLICATION_CREDENTIALS / AZURE_STORAGE_*).

Note: The dashboard runs on your machine—your data never leaves your infrastructure. When --data-dir points to a cloud URI, files are downloaded locally for display; no data is sent elsewhere.

CI/CD Integration

License Setup

For CI/CD runners, pass your license key via environment variable:

env:
  LEXEGA_LICENSE_KEY: ${{ secrets.LEXEGA_LICENSE_KEY }}  # GitHub
  # LEXEGA_LICENSE_KEY: $LEXEGA_LICENSE_KEY              # GitLab
  # LEXEGA_LICENSE_KEY: $(LEXEGA_LICENSE_KEY)            # Azure DevOps

The LEXEGA_LICENSE_KEY environment variable is checked before the license file on disk, making it ideal for ephemeral CI runners.

Automatic PR Comments

The easiest integration is using --pr-comment to automatically post review results directly to your PR:

GitHub Actions:

name: SQL Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: SQL Review
        env:
          LEXEGA_LICENSE_KEY: ${{ secrets.LEXEGA_LICENSE_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          lexega-sql review ${{ github.event.pull_request.base.sha }}..${{ github.sha }} . -r --pr-comment

GitLab CI:

sql-review:
  script:
    - lexega-sql review origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD . -r --pr-comment
  rules:
    - if: $CI_MERGE_REQUEST_IID
  variables:
    LEXEGA_LICENSE_KEY: $LEXEGA_LICENSE_KEY
    GITLAB_TOKEN: $CI_JOB_TOKEN

Bitbucket Pipelines:

pipelines:
  pull-requests:
    '**':
      - step:
          script:
            - export LEXEGA_LICENSE_KEY=$LEXEGA_LICENSE_KEY
            - export BITBUCKET_TOKEN=$BITBUCKET_TOKEN  # Set as repository variable
            - lexega-sql review origin/$BITBUCKET_PR_DESTINATION_BRANCH..HEAD . -r --pr-comment

The --pr-comment flag automatically detects your CI platform and posts/updates a comment on the PR. It uses a marker to update existing comments on subsequent runs rather than creating duplicates.

Policy-Based Blocking

For stricter enforcement, use policies to fail the pipeline. The default policy from lexega-sql init is permissive (warns only). To enable blocking, edit .lexega/policy.yml and change critical: warn to critical: block:

# .lexega/policy.yml (edit to enable blocking)
severity_actions:
  - critical: block   # Change from 'warn' to 'block'
    high: warn
default_action: allow

See Policy Reference for details on scoping severity actions by path or environment.

#!/bin/bash
# Policy-based blocking (exit 2 when policy blocks)
lexega-sql analyze \
  --policy policy.yaml \
  --env prod \
  --decision-out .lexega/decisions/$GITHUB_RUN_ID/ \
  --format json \
  *.sql > report.json

if [ $? -eq 2 ]; then
    echo "Policy blocked. See decision.json for details."
    exit 1
fi

Tip: Set LEXEGA_CI=1 to enforce that --policy is always provided (prevents accidental bypass in CI). When writing artifacts to cloud storage (S3/GCS/Azure), use a unique per-run directory prefix (for example s3://bucket/lexega/decisions/$GITHUB_RUN_ID/) so each run produces distinct artifacts.