---

Title: Installing the GitHub App. Description: Set up the CAPYSQUASH GitHub App for your repositories.

INSTALLING THE GITHUB APP

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

PREREQUISITES

WHAT YOU NEED

☑ Active CAPYSQUASH organization (Creator plan or higher) ☑ Admin access to GitHub organization or repository ☑ At least one project created in CAPYSQUASH

⚠️ Note: GitHub integration is not available on the Free plan. Upgrade to Creator, Professional, Agency, or Enterprise.

INSTALLATION STEPS

INSTALL IN 3 STEPS

1

• GO TO ORGANIZATION SETTINGS

• Navigate to your organization integrations page:

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

• 2

• INSTALL GITHUB APP

• Click "Install GitHub App" button

• ► Redirected to GitHub authorization page

• ► Choose organization or personal account

• ► Select repositories (all or specific ones)

• ► Grant permissions and install

• 3

• CONFIGURE PROJECTS

• Link CAPYSQUASH projects to GitHub repositories:

• ► Return to CAPYSQUASH dashboard

• ► Go to each project's settings

• ► Link to GitHub repository

• ► Configure analysis rules

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)

💡 Security: The app only reads migration files from configured paths. It never writes to your repository or accesses other files.

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

📁 REPOSITORY SETUP Configure migration paths and analysis rules

🔄 PR WORKFLOW Learn how analysis works in pull requests

SUPPORT

Need help with installation?

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