REPOSITORY SETUP

Configure how CAPYSQUASH analyzes migrations in each repository.

LINKING PROJECTS TO REPOSITORIES

Each CAPYSQUASH project can be linked to a GitHub repository:

MIGRATION PATH CONFIGURATION

Tell CAPYSQUASH where to find your migration files:

Common Patterns

Multiple Paths

If your migrations are in multiple directories:

migrations/
database/migrations/
sql/

Solution: Add all paths (comma-separated):

migrations/, database/migrations/, sql/

File Pattern

Specify which files are migrations:

Example custom pattern:

^\d{14}_.*\.sql$

Matches: 20240101120000_add_users.sql

BRANCH CONFIGURATION

Control which branches trigger analysis:

Option 1: All Branches (Default)

Analyze PRs targeting any branch:

branches: "*"

Best for: Most projects

Option 2: Specific Branches

Only analyze PRs to specific branches:

branches:
  - main
  - develop
  - production

Best for: Projects with strict branch workflow

Option 3: Branch Patterns

Use glob patterns:

branches:
  - main
  - release/*
  - hotfix/*

Best for: Gitflow or release branch strategies

ANALYSIS RULES

Configure when and how analysis runs:

Trigger Events

Skip Labels

Prevent analysis when PR has certain labels:

skip_labels:
  - skip-analysis
  - wip
  - do-not-merge

Add these labels to PRs to bypass CAPYSQUASH analysis.

Safety Level Override

Override project default safety level for PR analysis:

pr_safety_level: conservative  # Options: paranoid, conservative, standard, aggressive

Use case: Be more conservative for PR analysis than local development.

STATUS CHECK CONFIGURATION

Control how CAPYSQUASH reports pass/fail:

Check Behavior

Failure Conditions

Define what causes a check to fail (only in BLOCKING mode):

fail_conditions:
  data_loss_risk: true           # Fail if data loss detected
  warning_threshold: 3           # Fail if more than 3 warnings
  consolidation_threshold: 70    # Fail if >70% can be consolidated
  deployment_time_minutes: 10    # Fail if estimated deployment >10 min

Example scenarios:

MONOREPO CONFIGURATION

For repositories with multiple projects:

Path-Based Detection (Simple)

Link different projects to different paths:

Project: API
  Repository: monorepo
  Path: services/api/migrations/

Project: Dashboard
  Repository: monorepo
  Path: services/dashboard/migrations/

Project: Mobile
  Repository: monorepo
  Path: services/mobile/migrations/

CAPYSQUASH detects which project to analyze based on changed files.

Config File (Advanced)

Create .CAPYSQUASH.yml in repository root:

version: 1

projects:
  - name: "API"
    path: "services/api/migrations"
    label: "api"
    safety: conservative

  - name: "Dashboard"
    path: "services/dashboard/migrations"
    label: "dashboard"
    safety: standard

  - name: "Mobile"
    path: "services/mobile/migrations"
    label: "mobile"
    safety: aggressive

Benefits:

• Version controlled configuration
• Label-based project routing
• Per-project safety levels
• Team can modify without dashboard access

Label-based routing: Add labels to PRs to explicitly route to a project:

• PR with api label → Analyzes API project
• PR with dashboard label → Analyzes Dashboard project

NOTIFICATION CONFIGURATION

Get notified about analysis results:

PR Comments (Always On)

CAPYSQUASH always posts results as PR comment.

Additional Notifications

notifications:
  email:
    enabled: true
    recipients:
      - team@company.com
    events:
      - analysis_failed
      - warnings_detected

  slack:
    enabled: true
    webhook_url: "https://hooks.slack.com/..."
    channel: "#migrations"
    events:
      - analysis_completed
      - data_loss_risk

  discord:
    enabled: true
    webhook_url: "https://discord.com/api/webhooks/..."

Configure organization-wide notifications →

CUSTOM COMMENT TEMPLATE

Customize the PR comment format (Professional/Enterprise):

comment_template: |
  ## 🦫 Migration Analysis

  **Impact:** {{file_count}} files → {{optimized_count}} files ({{reduction}}%)
  **Warnings:** {{warnings_count}}

  {{#has_warnings}}
  ### ⚠️ Warnings
  {{#warnings}}
  - {{message}}
  {{/warnings}}
  {{/has_warnings}}

  {{#recommendations}}
  ### <span className="inline-flex items-center gap-2"><Lightbulb size={24} weight="bold" /> Recommendations</span>
  {{#items}}
  - {{text}}
  {{/items}}
  {{/recommendations}}

  [View full analysis →]({{analysis_url}})

Available variables:

• {{file_count}} - Number of migration files
• {{optimized_count}} - Files after consolidation
• {{reduction}} - Percentage reduction
• {{warnings_count}} - Number of warnings
• {{analysis_url}} - Link to full results
• Plus: warnings array, recommendations array, etc.

EXAMPLE CONFIGURATIONS

Startup - Aggressive Development

branch: main
path: supabase/migrations/
safety_level: standard
check_mode: informational
skip_draft_prs: true

Why: Fast iteration, don't block PRs, improve over time

Enterprise - Strict Quality

branches:
  - main
  - production
path: migrations/
safety_level: conservative
check_mode: blocking
fail_conditions:
  data_loss_risk: true
  warning_threshold: 0
  deployment_time_minutes: 5
skip_draft_prs: true
skip_bot_prs: true

Why: Production stability, zero-tolerance for risks

Agency - Multi-Client

# Each client project configured separately
# Client A
branches: ["main", "staging"]
path: migrations/
check_mode: warning
safety_level: conservative

# Client B
branches: ["production"]
path: db/migrate/
check_mode: blocking
safety_level: paranoid

Why: Different clients, different requirements

TESTING CONFIGURATION

After setup, test your configuration:

1. Create Test PR

git checkout -b test-config
echo "CREATE TABLE test (id INT);" > your-migration-path/test.sql
git add .
git commit -m "test: configuration"
git push origin test-config

2. Verify Analysis

Check that CAPYSQUASH:

• ☑ Detects the migration file
• ☑ Runs analysis
• ☑ Posts comment on PR
• ☑ Creates status check
• ☑ Respects your safety level
• ☑ Applies your rules

3. Check Logs

Review analysis logs in dashboard:

Dashboard → Projects → [Your Project] → Activity → [Latest Analysis]

UPDATING CONFIGURATION

Configuration changes take effect immediately:

1. Update settings in CAPYSQUASH dashboard
2. Or commit .CAPYSQUASH.yml changes
3. Next PR uses new configuration
4. No need to reinstall GitHub App

TROUBLESHOOTING

Migrations Not Detected

Problem: CAPYSQUASH says "No migrations changed" but you added migrations

Solutions:

1. Check path configuration matches your actual path
2. Verify file pattern matches your migration files
3. Check branch filter isn't excluding your PR target branch
4. Look for typos in path (trailing slash, etc.)

Wrong Project Analyzed

Problem: Monorepo analyzing wrong project

Solutions:

1. Check path configuration for each project
2. Verify paths don't overlap
3. Use .CAPYSQUASH.yml for explicit routing
4. Add labels to PR for explicit project selection

Analysis Not Triggering

Problem: PR opened but no analysis

Solutions:

1. Check if PR is from fork (requires manual trigger)
2. Verify PR doesn't have skip labels
3. Check if draft PR and skip_draft_prs is true
4. Verify webhook deliveries in GitHub App settings

NEXT STEPS