GitHub Integration

Automate migration analysis in pull requests with set-and-forget automation that catches migration issues before they reach production

Why GitHub Integration?

The GitHub App provides true automation for your migration workflow:

Quick Navigation

Installation

Dashboard → [Your Organization] → Settings → Integrations → GitHub

git checkout -b test-capysquash
echo "CREATE TABLE test (id INT);" > migrations/test.sql
git add migrations/test.sql
git commit -m "test: CAPYSQUASH integration"
git push origin test-capysquash

Installation Options

How It Works

Automatic Analysis Flow

Timing: Typically completes in 15-30 seconds.

What Triggers Analysis

Repository Configuration

Migration Path Configuration

Tell CAPYSQUASH where to find your migration files:

supabase/migrations/

prisma/migrations/

drizzle/

migrations/
db/migrate/
sql/

migrations/, database/migrations/, sql/

File Pattern

Specify which files are migrations:

Branch Configuration

branches:
  - main
  - develop
  - production

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

Analysis Rules

Configure when and how analysis runs:

Status Check Configuration

Control how CAPYSQUASH reports pass/fail:

fail_conditions:
  data_loss_risk: true
  warning_threshold: 3
  consolidation_threshold: 70
  deployment_time_minutes: 10

Monorepo Configuration

For repositories with multiple projects:

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

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

version: 1

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

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

PR Workflow

PR Comment Example

When analysis completes, CAPYSQUASH posts a detailed comment:

## 🦫 CAPYSQUASH Analysis

☑ Migrations analyzed successfully!

### 📊 Results
- **New migrations:** 3 files
- **Total migrations:** 156 files
- **Consolidation opportunity:** Can squash to 12 files (92% reduction)
- **Warnings:** 2 minor issues
- **Estimated deployment time:** +15 seconds

### ⚠️ Warnings
1. **Migration 20240115_add_column.sql**
   - Adding non-nullable column without default
   - Risk: May fail if table has existing rows
   - Suggestion: Add DEFAULT value or make nullable

2. **Migration 20240116_drop_table.sql**
   - Dropping table `old_data`
   - Risk: Permanent data loss
   - Suggestion: Backup data first or use soft delete

### 💡 Recommendations
- ☑ Migrations follow naming convention
- ☑ No syntax errors detected
- ⚠️ Consider consolidating after merge (92% reduction available)
- ⚠️ Review data loss warnings before merging

### 📈 Impact
**Current:** 156 migrations, ~2.5min deployment
**After consolidation:** 12 migrations, ~10sec deployment (15x faster!)

[View full analysis →](https://capysquash.dev/runs/abc123)

---
*CAPYSQUASH Professional · [Configure](https://capysquash.dev/settings/github)*

Status Check States

Manual Triggers

Trigger analysis manually via PR comment:

@capysquash analyze

# Override safety level
@capysquash analyze --safety=conservative

# Force reanalysis
@capysquash analyze --force

# Verbose output
@capysquash analyze --verbose

# Analyze specific migrations
@capysquash analyze migrations/002_*.sql

# Multiple patterns
@capysquash analyze migrations/002_*.sql migrations/003_*.sql

Fork PR Workflow

Pull requests from forked repositories require manual approval:

Handling Warnings

When CAPYSQUASH detects warnings:

Permissions & Security

Required Permissions

The GitHub App requires minimal permissions to function:

What We Access

Data Handling

What We Store:

• Analysis results (warnings, recommendations)
• Migration file metadata (name, size, timestamp)
• PR metadata (number, title, link)
• Repository name and link

We do NOT store:

• Full migration file contents (discarded after analysis)
• Your database schema (only temporary during analysis)
• Any data from your database
• Code from other parts of repository

Data Retention

Security Measures

Analysis Environment

Each analysis runs in an isolated environment:

Secure Container
├── Temporary file system (ephemeral)
├── No network access (except CAPYSQUASH API)
├── Read-only migration files
├── No persistent storage
└── Destroyed after analysis

Troubleshooting

Best Practices

For Developers

1. Run locally first - Use capysquash-cli before opening PR
2. Address warnings early - Fix issues before review
3. Clear commit messages - Help reviewers understand changes
4. Regular consolidation - Keep migrations manageable

For Reviewers

1. Check CAPYSQUASH comment - Review before manual review
2. Understand warnings - Not all warnings are blockers
3. Verify fixes - If author fixed warnings, confirm
4. Consider context - Team's risk tolerance varies

For Teams

1. Set clear policies - When to block vs warn
2. Document overrides - When and why to bypass checks
3. Regular consolidation - Schedule periodic cleanup
4. Monitor trends - Track migration quality over time

Branch Protection

Require CAPYSQUASH check before merging:

Usage & Pricing

PR analyses count toward your monthly limit:

Uninstalling

To remove the GitHub App:

From CAPYSQUASH:

1. Dashboard → Organization → Settings → Integrations → GitHub
2. Click "Disconnect"
3. Confirm removal

From GitHub:

1. GitHub Settings → Applications → Installed GitHub Apps
2. Find CAPYSQUASH
3. Click "Uninstall"

Related Resources

Support

Need help with GitHub integration?

• 📧 Email: support@capysquash.dev
• 💬 Discord: Join community
• 🎫 Support: Open ticket in dashboard
• 🔐 Security: security@capysquash.dev