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

supabase/migrations/

prisma/migrations/

drizzle/

migrations/
db/migrate/
sql/

branches:
  main
  develop
  production

branches:
  main
  release/*
  hotfix/*

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

version: 1

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

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

## 🦫 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)_

@capysquash analyze

# Override safety level

@capysquash analyze --safety=conservative

# Force reanalysis

@capysquash analyze --force

# Verbose output

@capysquash analyze --verbose

</Tab>

<Tab value="Specific Files">
  ```bash
# Analyze specific migrations

@capysquash analyze migrations/002_\*.sql

# Multiple patterns

@capysquash analyze migrations/002__.sql migrations/003__.sql

Manual trigger commands are documented but need platform team verification. Check with support if
you need manual trigger functionality. Current alternative: Trigger analysis from the CAPYSQUASH
dashboard. 

### Fork PR Workflow

Pull requests from forked repositories require manual approval:





### Contributor Opens Fork PR

External contributor submits PR from their fork.





### Maintainer Reviews PR

Check if PR is safe and contains migrations.





### Maintainer Triggers Analysis

Comment: `@capysquash analyze`





### CAPYSQUASH Analyzes

Runs with maintainer's approval and posts results.






**Why manual approval?** GitHub limits app permissions on forked PRs for security. 

### Handling Warnings

When CAPYSQUASH detects warnings:





Each warning includes:

**File:** Which migration has the issue

**Issue:** What's wrong

**Risk:** Potential impact

**Suggestion:** How to fix





**Critical (🔴 High Risk):**

Data loss
Production breaking changes
Security issues

**Medium (🟡 Medium Risk):**

Performance concerns
Non-nullable without default
Missing indexes

**Low (🟢 Low Risk):**

Style issues

Optimization opportunities

Best practice suggestions





**Option A: Fix in PR**
```bash
# Update migration file.

git add migrations/fixed.sql
git commit -m "fix: address CAPYSQUASH warnings"
git push

CAPYSQUASH automatically reanalyzes.

**Option B: Document Why Ignoring**

Add comment explaining decision (intentional, data backed up, etc.)

**Option C: Override Safety Level**
```bash
@capysquash analyze --safety=aggressive
`

If warnings are too strict for your use case.





---

## Permissions & Security [#permissions-security]

### Required Permissions

The GitHub App requires minimal permissions to function:



📝 Pull Requests - Read & Write
Why we need it:

► Read PR details and changed files
► Post analysis results as comments
► Read manual trigger commands

What we DON'T do:

► Never merge or close PRs
► Never modify PR descriptions
► Never request reviews




📁 Contents - Read Only
Why we need it:

► Read migration files from configured paths
► Detect changed files in PRs

What we DON'T do:

► Never write or modify files
► Never create commits
► Never read outside migration paths




☑ Checks - Read & Write
Why we need it:

► Create status checks on PRs
► Update check status (pass/fail)
► Add check details and links




- ℹ️ Metadata - Read Only
- Standard GitHub permission:

- ► Repository name and description
- ► Repository visibility
- ► Default branch information





### What We Access



☑ We DO Access

► Migration files only
► Files in configured migration paths
► Only when PR changes them
► PR metadata (number, title, author)
► Repository info (name, owner)




- ☒ We DON'T Access

- ► Your application code
- ► Configuration files
- ► Secrets/environment variables
- ► Database credentials
- ► Files outside migration paths
- ► Other repositories





### 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

| Data Type | Retention |
| ----------------------- | ------------------------------------- |
| Analysis results | Forever (or until you delete project) |
| File metadata | Forever |
| Temporary analysis data | Deleted immediately after analysis |
| Webhook payloads | Not stored |
| Migration file contents | Not stored |

### Security Measures



🔒 Encryption

► TLS 1.3 in transit
► AES-256 at rest
► Encrypted backups




🛡️ Isolation

► Separate analysis environments
► Network isolation
► No cross-tenant access




🔐 Access Control

► Role-based permissions
► Audit logging
► 2FA for team members




- 📋 Compliance

- ► SOC 2 Type II (in progress)
- ► GDPR compliant
- ► Regular security audits







The app only reads migration files from configured paths. It never writes to your repository,
accesses databases, or reads sensitive data. 

### 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





**Check:**

1. Is the repository connected in CAPYSQUASH?
2. Are migration files in the configured path?
3. Does the PR actually change migration files?
4. Is the PR from a fork? (requires manual approval)

**Solutions:**

Verify repository settings in dashboard

Check webhook deliveries in GitHub App settings

Try manual trigger: `@capysquash analyze`





**Common causes:**

Invalid SQL syntax in migrations
Migration files not in expected format
Path configuration incorrect
Permissions issue

**Solutions:**

Check analysis logs in CAPYSQUASH dashboard

Verify migration files locally with capysquash-cli

Update repository settings

Contact support if persists





**Check:**

1. Is "Enable checks" turned on in settings?
2. Does your plan include GitHub integration?
3. Are checks enabled in repository settings?

**Solutions:**

Verify settings in both CAPYSQUASH and GitHub

Reinstall the app if needed

Check GitHub App has write permission for checks





**Why:** GitHub limits app permissions on forked PRs for security.

**Solution:**

Maintainer manually triggers: `@capysquash analyze`

Or wait until PR merged to branch





**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




---

## 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:



Go to GitHub repo **Settings** → **Branches**
Add rule for your branch (e.g., `main`)
Enable **"Require status checks to pass before merging"**
Search for and select **"CAPYSQUASH Analysis"**
Save branch protection rule 

---

## Usage & Pricing

PR analyses count toward your monthly limit:

| Plan | Monthly Analyses |
| ------------ | ----------------- |
| Free | Not available |
| Creator | 50 analyses/month |
| Professional | Unlimited |
| Agency | Unlimited |
| Enterprise | Unlimited |



GitHub integration is only available on paid plans (Creator and above). 

---

## 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"

Historical analysis data is preserved even after uninstalling.

---

## Related Resources







---

## Support

Need help with GitHub integration?

- 📧 Email: support@capysquash.dev
- 💬 Discord: [Join community](https://discord.gg/capysquash)
- 🎫 Support: Open ticket in dashboard
- 🔐 Security: security@capysquash.dev