feat: GitHub Actions templates and CI/CD integration guide

[Lazialize]

Problem

There are no official templates or guides for using Strata in CI/CD pipelines. Users must build GitHub Actions workflows from scratch, and best practices (validate → diff check → apply ordering, destructive change detection, etc.) are not standardized.

Proposed Solution

Provide reusable workflow templates for GitHub Actions and a CI/CD integration guide.

Templates to Provide

1. PR Schema Validation Workflow

# .github/workflows/strata-validate.yml
name: Schema Validation
on:
  pull_request:
    paths: ['schema/**']
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Strata
        run: |
          curl -sSL https://github.com/Lazialize/stratum/releases/latest/download/strata-linux-x86_64 -o strata
          chmod +x strata
      - name: Validate Schema
        run: ./strata validate --format json
      - name: Check for Destructive Changes
        run: |
          output=$(./strata generate --dry-run --format json)
          if echo "$output" | jq -e '.destructive_changes | length > 0'; then
            echo "::warning::Destructive changes detected!"
          fi

2. Migration Apply Workflow

# .github/workflows/strata-apply.yml
name: Apply Migrations
on:
  push:
    branches: [main]
jobs:
  migrate:
    runs-on: ubuntu-latest
    environment: production  # GitHub Environment protection rules
    steps:
      - uses: actions/checkout@v4
      - name: Apply Migrations
        run: ./strata apply --yes --env production
        env:
          STRATA_DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

3. Diff Report Workflow (PR Comment)

# Post diff report as a PR comment
- name: Generate Diff Report
  run: ./strata generate --dry-run --format json > diff.json
- name: Comment PR
  uses: actions/github-script@v7
  with:
    script: |
      const diff = require('./diff.json');
      // Post diff summary as PR comment

Implementation Plan

1. Template files (examples/ci/ — new)

   • github-actions-validate.yml — Schema validation on PR
   • github-actions-apply.yml — Apply on main merge
   • github-actions-diff-report.yml — PR diff report

2. strata init --ci option (src/cli/src/cli/commands/init.rs)

   • Copy templates to .github/workflows/ during project initialization
   • Customize templates based on dialect and environment names

3. Enrich JSON output (existing commands)

   • Add CI/CD-friendly exit code mapping to strata check --format json
   • Exit codes: 0=OK, 1=error, 2=warnings (destructive changes, etc.)

4. Environment variable support (src/core/src/core/config.rs)

   • Allow overriding config values via STRATA_DB_HOST, STRATA_DB_PASSWORD, etc.
   • Facilitate integration with secret management

Files Affected

• examples/ci/ (new) — Template files
• src/cli/src/cli/commands/init.rs — --ci option
• src/core/src/core/config.rs — Environment variable overrides
• src/cli/src/cli/commands/check.rs — Exit code refinement

Alternatives Considered

• Custom GitHub Action: Publish as uses: Lazialize/strata-action@v1. Binary distribution and version management add complexity, so templates come first
• Docker image: Provide a CI/CD Docker image. Templates are lighter and more flexible

Additional Context

• Corresponds to the entire "CI/CD Integration" section in ROADMAP.md
• The existing strata check command (validate + dry-run) serves as a CI/CD foundation
• JSON output is already supported (--format json), providing a structured data base