PR WORKFLOW

Learn how CAPYSQUASH automatically analyzes migrations in your pull request workflow.

THE AUTOMATIC FLOW

Timing: Typically completes in 15-30 seconds.

WHAT TRIGGERS ANALYSIS

CAPYSQUASH runs analysis when:

Smart Detection

CAPYSQUASH only runs when:

• Migration files are actually changed
• Changes are in configured migration paths
• PR targets an enabled branch

Skipped when:

• No migrations changed
• PR has skip labels (configurable)
• PR is draft (if configured to skip drafts)
• PR from bot (if configured to skip bots)

PR COMMENT ANATOMY

When analysis completes, CAPYSQUASH posts a detailed comment:

Example Comment

## 🦫 CAPYSQUASH Analysis

☑ **Migrations analyzed successfully!**

### <ChartBar size={20} weight="bold" /> RESULTS
- **Changed files:** 3 migrations
- **Current total:** 156 migrations
- **Total migrations:** 287 files
- **Consolidation opportunity:** Squashes to 1 optimized file (99% reduction)
- **Warnings:** 2 minor issues
- **Estimated deployment time:** +15 seconds

### <WarningCircle size={20} weight="bold" /> 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

### <Lightbulb size={20} weight="bold" /> RECOMMENDATIONS
- ☑ Migrations follow naming convention
- ☑ No syntax errors detected
- ⚠️ Consider consolidating after merge (92% reduction available)
- ⚠️ Review data loss warnings before merging

### <ChartLineUp size={20} weight="bold" /> IMPACT
**Current state:**
- 156 migrations
- ~2.5 minutes deployment time
- 12 MB total size

**After consolidation:**
- 12 migrations (92% reduction)
- ~10 seconds deployment time
- 1.2 MB total size
- ☑ Same end result, guaranteed

### <Target size={20} weight="bold" /> NEXT STEPS
1. Review warnings above
2. Fix non-nullable column issue
3. Consider backup strategy for dropped table
4. After merge, run consolidation: `pgsquash consolidate`

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

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

Comment Sections

STATUS CHECKS

In addition to the comment, CAPYSQUASH creates a GitHub status check:

Check States

Check Details

Click the check for detailed information:

CAPYSQUASH Analysis
☑ Migrations analyzed successfully

Details:
► 3 files changed
► 2 warnings detected
► 92% consolidation opportunity
► 15s deployment impact

View full report →

Branch Protection

Require CAPYSQUASH check to pass before merging:

1. Go to GitHub repo Settings
2. Branches → Add rule for your branch (e.g., main)
3. Require status checks to pass
4. Search for and select "CAPYSQUASH Analysis"
5. Save rule

Now PRs must pass CAPYSQUASH analysis to merge.

MANUAL TRIGGERS

Trigger analysis manually via PR comment:

Basic Trigger

@CAPYSQUASH analyze

Runs analysis with default settings.

With Safety Level

@CAPYSQUASH analyze --safety=conservative

Override default safety level for this run.

Specific Files

@CAPYSQUASH analyze migrations/002_*.sql

Analyze only specific migration files.

Force Reanalysis

@CAPYSQUASH analyze --force

Reanalyze even if nothing changed.

With Options

@CAPYSQUASH analyze --safety=paranoid --verbose

Combine multiple options.

Who Can Trigger?

• Repository collaborators: Yes
• External contributors (forks): Requires approval
• Organization members: Yes
• Bots: Can be configured

FORK PR WORKFLOW

Pull requests from forked repositories require special handling for security:

Security Restrictions

GitHub limits what apps can do on fork PRs:

• ☑ Can read PR details
• ☒ Cannot automatically read repo contents
• ☒ Cannot post comments automatically

Why: Prevent malicious forks from accessing private data.

Analyzing Fork PRs

Alternative: Wait until PR merged to branch, then automatic analysis on subsequent updates.

HANDLING WARNINGS

When CAPYSQUASH detects warnings:

1. Read Warning Details

Each warning includes:

• File: Which migration has the issue
• Issue: What's wrong
• Risk: Potential impact
• Suggestion: How to fix

2. Assess Severity

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

3. Take Action

Option A: Fix in PR

# 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
# Migration is intentional, data backed up, etc.

Option C: Override Safety Level

@CAPYSQUASH analyze --safety=aggressive

If warnings are too strict for your use case.

DRAFT PR BEHAVIOR

Configure how CAPYSQUASH handles draft PRs:

Option 1: Analyze Drafts (Default)

Analyze even when PR is draft.

Pros:

• Early feedback
• Fix issues before ready for review

Use case: Solo developers, early validation

Option 2: Skip Drafts

Don't analyze until PR marked ready:

skip_draft_prs: true

Pros:

• Reduce noise
• Only analyze when ready
• Save analysis quota

Use case: Teams with frequent WIP PRs

Note: Can manually trigger on draft PR: @CAPYSQUASH analyze

UPDATING AFTER ANALYSIS

When you push new commits to an analyzed PR:

Automatic Reanalysis

CAPYSQUASH automatically:

1. Detects new commits
2. Reruns analysis
3. Updates comment (or posts new one)
4. Updates status check

Comment Updates

Option A: Edit existing comment (default)

• Keeps PR clean
• Single source of truth
• Shows latest results

Option B: Post new comment

update_strategy: new_comment

• Keeps history of all analyses
• Can compare changes over time

CONSOLIDATION WORKFLOW

When CAPYSQUASH suggests consolidation:

In PR

💡 **Consolidation Opportunity:**
Can reduce 156 migrations → 12 migrations (92% reduction)

After Merge

Don't consolidate in the PR - it conflicts with migration history.

After merge:

# On main branch
git pull origin main

# Run consolidation
pgsquash consolidate

# Review changes
git diff

# Commit consolidated migrations
git add migrations/
git commit -m "chore: consolidate migrations"
git push origin main

Learn more about consolidation →

PERFORMANCE

Analysis Speed

Typical timing:

• Small projects (50-120 migrations): 15-30 seconds
• Medium projects (100-300 migrations): 30-60 seconds
• Large projects (300-800 migrations): 60-120 seconds

Factors Affecting Speed

Optimization Tips

1. Consolidate regularly - Fewer migrations = faster analysis
2. Configure path precisely - Don't scan entire repo
3. Use aggressive safety - For faster feedback (if acceptable)
4. Skip draft PRs - Reduce unnecessary analyses

TROUBLESHOOTING

Analysis Not Running

Problem: PR opened but no analysis

Check:

1. Do migration files actually change?
2. Are they in configured path?
3. Is PR targeting enabled branch?
4. Is PR from fork? (needs manual trigger)
5. Does PR have skip labels?

Comment Not Appearing

Problem: Analysis runs but no comment

Check:

1. GitHub App has write permission for PRs
2. Not rate limited by GitHub
3. Check dashboard for analysis results
4. Repository not archived/locked

Check Not Created

Problem: Comment appears but no status check

Check:

1. Checks enabled in repository settings?
2. Check mode set to "blocking" or "warning"?
3. GitHub App has write permission for checks

Wrong Results

Problem: Analysis doesn't match local pgsquash-engine

Check:

1. Same safety level used?
2. PR analyzing correct branch?
3. Different migration files than local?
4. Try manual trigger: @CAPYSQUASH analyze --verbose

BEST PRACTICES

For Developers

1. Run locally first - Use pgsquash-engine before opening PR

   pgsquash analyze migrations/*.sql --safety=conservative

2. Address warnings early - Fix issues before review

3. Clear commit messages - Help reviewers understand changes

   feat(db): add user profile table
   
   - New migration adds user_profiles table
   - Indexed on user_id for performance
   - CAPYSQUASH validated safe

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

NEXT STEPS