INSTALLING THE GITHUB APP

Automatically analyze migrations in pull requests by installing the CAPYSQUASH GitHub App.

PREREQUISITES

INSTALLATION STEPS

PERMISSION SCOPES

The GitHub App requires these permissions:

Repository Permissions

Organization Permissions

Webhook Events

The app subscribes to:

• pull_request (opened, synchronize, reopened)
• pull_request_review_comment (for manual triggers)

INSTALLATION OPTIONS

Option 1: All Repositories

Install on all current and future repositories:

Pros:

• Automatic for new repositories
• One-time setup
• Consistent across organization

Cons:

• Broader access
• May analyze non-relevant repos

Best for: Organizations with consistent migration practices

Option 2: Specific Repositories

Install only on selected repositories:

Pros:

• More control
• Limited access scope
• Only relevant repos

Cons:

• Manual selection for new repos
• Must update as you add repos

Best for: Organizations with mixed tech stacks or selective needs

MULTIPLE ORGANIZATIONS

You can install the GitHub App on multiple GitHub organizations:

1. Each GitHub org has separate installation
2. Link each to the same or different CAPYSQUASH organization
3. Manage installations independently
4. Usage counts toward your CAPYSQUASH plan limit

Example setup:

GitHub Org: acme-frontend    → CAPYSQUASH Org: ACME Inc
GitHub Org: acme-backend     → CAPYSQUASH Org: ACME Inc
GitHub Org: client-projects  → CAPYSQUASH Org: Agency Team

VERIFYING INSTALLATION

After installation, verify everything is connected:

1. Check Integration Status

In CAPYSQUASH:

Organization → Settings → Integrations → GitHub

You should see:

• ☑ Connected status
• GitHub organization/account name
• List of installed repositories
• Installation date

2. Test with a PR

Create a test PR with a migration file:

# In your repo
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

# Open PR on GitHub
gh pr create --title "Test CAPYSQUASH" --body "Testing GitHub App"

Within 30 seconds, CAPYSQUASH should:

• Post a comment on the PR
• Create a status check
• Show analysis results

3. Check Webhook Deliveries

In GitHub:

Settings → GitHub Apps → CAPYSQUASH → Advanced → Recent Deliveries

You should see successful webhook deliveries.

TROUBLESHOOTING

App Not Showing in CAPYSQUASH

Problem: GitHub redirect completed but app not showing in dashboard

Solutions:

1. Wait 30 seconds and refresh
2. Check if installation was for correct GitHub account
3. Verify you have admin access to CAPYSQUASH organization
4. Try disconnecting and reinstalling

Repositories Not Listed

Problem: Installed app but repositories don't appear

Solutions:

1. Go to GitHub → Settings → Applications → CAPYSQUASH
2. Click "Configure"
3. Verify repositories are selected
4. Save changes
5. Refresh CAPYSQUASH dashboard

Installation Failed

Problem: Error during GitHub authorization

Solutions:

1. Check you have admin access to GitHub org/repo
2. Try in incognito/private browser window
3. Clear cookies and try again
4. Check GitHub status page for outages
5. Contact support if persists

Permission Denied

Problem: App installed but can't access repositories

Solutions:

1. Verify your GitHub role has sufficient permissions
2. Check organization's third-party application policy
3. Ask GitHub org admin to approve the app
4. Reinstall with correct permissions

UPDATING PERMISSIONS

If CAPYSQUASH updates permission requirements:

1. You'll see a notification in dashboard
2. Click "Update Permissions" button
3. Redirected to GitHub to approve new permissions
4. Confirm and save

Note: App won't work properly until permissions are updated.

REPOSITORY SELECTION

Adding Repositories Later

Add more repositories after initial install:

1. Go to CAPYSQUASH → Organization → Integrations → GitHub
2. Click "Manage Repositories"
3. Redirected to GitHub configuration
4. Select additional repositories
5. Save changes

Removing Repositories

Remove repositories from the app:

1. Same process as adding
2. Deselect repositories to remove
3. CAPYSQUASH will stop analyzing PRs for those repos
4. Historical data is preserved

ORGANIZATION VS PERSONAL ACCOUNT

GitHub Organization Install

When:

• Working in a team
• Company/startup repositories
• Multiple collaborators

Benefits:

• Central management
• Team visibility
• Organization-wide policies

Personal Account Install

When:

• Personal projects
• Solo developer
• Side projects

Benefits:

• Simpler setup
• Direct control
• Lower plan requirements

Note: Both work the same way in CAPYSQUASH

NEXT STEPS

SUPPORT

Need help with installation?

• 📧 Email: support@CAPYSQUASH.dev
• 💬 Discord: Join community
• 📖 Docs: Check troubleshooting guide
• 🎫 Support: Open ticket in dashboard