Permissions & Security
Understanding GitHub App permissions and security
PERMISSIONS & SECURITY
Learn what permissions the CAPYSQUASH GitHub App requires and how your data is protected.
REQUIRED PERMISSIONS
The GitHub App requires minimal permissions to function:
Repository Permissions
WHAT WE ACCESS
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
What we DON'T do:
- âē Never modify other checks
- âē Never bypass required checks
METADATA - READ ONLY
Why we need it:
- âē Repository name and description
- âē Repository visibility (public/private)
- âē Default branch information
Standard GitHub permission - cannot be disabled
Organization Permissions
ORGANIZATION ACCESS (OPTIONAL)
MEMBERS - READ ONLY
Why it's optional:
- âē Only for organization-wide installations
- âē Helps identify team members vs external contributors
- âē Not required for functionality
Webhook Events
The app subscribes to these events:
| Event | When | Purpose |
|---|---|---|
pull_request | PR opened/updated/reopened | Trigger automatic analysis |
pull_request_review_comment | Comment on PR | Detect manual triggers |
Note: We ignore all other webhooks (issues, commits, deployments, etc.)
WHAT WE ACCESS
We DO Access
â Migration files only
- Files in configured migration paths
- Only when PR changes them
- During analysis only
â PR metadata
- PR number, title, author
- Changed files list
- Target branch
â Repository info
- Repository name
- Owner/organization
- Visibility status
We DON'T Access
â Your code
- Application code
- Configuration files
- Secrets/environment variables
- Any files outside migration paths
â Sensitive data
- Database credentials
- API keys
- User data
- Business logic
â Other repositories
- Only access repositories you explicitly install on
DATA HANDLING
What We Store
In CAPYSQUASH cloud:
- 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 |
Data Location
- Servers: US/EU (depending on your region selection)
- Database: Encrypted at rest
- In transit: TLS 1.3 encryption
- Backups: Encrypted, 30-day retention
SECURITY MEASURES
Infrastructure Security
đ 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
Analysis Environment
Each analysis runs in isolated environment:
Secure Container
âââ Temporary file system (ephemeral)
âââ No network access (except CAPYSQUASH API)
âââ Read-only migration files
âââ No persistent storage
âââ Destroyed after analysisSecurity features:
- No internet access during analysis
- Cannot make external API calls
- Cannot write to your repository
- Cannot access other organizations' data
GitHub App Security
OAuth flow:
- Standard GitHub OAuth
- Scoped access tokens
- Token rotation
- Revocable anytime
Webhook verification:
- HMAC signature validation
- Replay attack prevention
- IP allowlist (optional)
PERMISSION UPDATES
When CAPYSQUASH needs new permissions:
UPDATE PROCESS
NOTIFICATION
We email you and show banner in dashboard explaining why
YOUR CHOICE
You approve or reject - app stops working until approved
GITHUB APPROVAL
Redirect to GitHub to accept new permissions
RESUME SERVICE
App continues with new permissions
Note: We will NEVER add permissions without your explicit approval.
REVOKING ACCESS
You can revoke access anytime:
From CAPYSQUASH
Dashboard â Organization â Settings â Integrations â GitHub â DisconnectWhat happens:
- Analysis stops immediately
- Webhook subscriptions removed
- Historical data preserved (but not accessible via GitHub)
- Can reconnect later
From GitHub
GitHub Settings â Applications â Installed GitHub Apps â CAPYSQUASH â UninstallWhat happens:
- Same as disconnecting from CAPYSQUASH
- Plus: All permissions revoked in GitHub
- OAuth tokens invalidated
ORGANIZATION POLICIES
Third-Party App Restrictions
If your GitHub organization restricts third-party apps:
- Organization admin must approve CAPYSQUASH
- Go to:
Organization Settings â Third-party access â GitHub Apps - Review CAPYSQUASH and approve
- Then install normally
IP Allowlists
If your organization uses IP allowlists:
CAPYSQUASH IP ranges:
US Region:
- 35.123.45.0/24
- 35.123.46.0/24
EU Region:
- 52.234.56.0/24
- 52.234.57.0/24Add these to your GitHub organization allowlist.
Single Sign-On (SSO)
For organizations with SAML SSO:
- Install app normally
- Authorize SSO for CAPYSQUASH
- Go to:
GitHub Settings â Applications â CAPYSQUASH â Configure SSO - Authorize for your organization
Note: SSO authorization required per organization.
AUDIT LOGGING
Track all GitHub App activity:
In CAPYSQUASH Dashboard
Organization â Settings â Audit LogSee:
- App installations/uninstallations
- Permission changes
- Analysis triggers
- Configuration changes
- Team member actions
In GitHub
Organization Settings â Audit logFilter by app:CAPYSQUASH to see:
- Installation events
- Repository access
- Permission grants
- Webhook deliveries
SECURITY BEST PRACTICES
For Organizations
-
Review permissions regularly
- Check what CAPYSQUASH can access
- Verify only necessary repositories
-
Enable SSO (if available)
- Additional authentication layer
- Centralized access control
-
Monitor audit logs
- Review GitHub App activity
- Watch for unexpected behavior
-
Limit repository access
- Install only on repos that need it
- Don't use "All repositories" unless necessary
For Developers
-
Use strong passwords
- On both GitHub and CAPYSQUASH accounts
- Enable 2FA
-
Review PR comments
- Don't ignore security warnings
- Understand what CAPYSQUASH reports
-
Don't commit secrets
- Keep credentials out of migrations
- Use environment variables
COMPLIANCE
GDPR
Data subject rights:
- â Right to access: Export your data anytime
- â Right to deletion: Delete projects/data
- â Right to portability: Download analysis results
- â Right to object: Stop processing by disconnecting
Legal basis: Legitimate interest (service functionality)
SOC 2 Type II
Currently in audit process. Expected completion: Q2 2024.
Covered:
- Security
- Availability
- Confidentiality
- Processing integrity
Data Processing Agreement (DPA)
Available for Enterprise plan:
- Custom data retention
- Specific security controls
- Liability terms
- Compliance requirements
INCIDENT RESPONSE
If you suspect a security issue:
Report Security Vulnerabilities
DO:
- Email: security@CAPYSQUASH.dev
- Encrypted: PGP Key
- Include: Description, impact, reproduction steps
DON'T:
- Post publicly on GitHub
- Share in Discord/Slack
- Announce before patched
Response time:
- Acknowledgment: <24 hours
- Assessment: <72 hours
- Fix (if valid): Depends on severity
What We Do
- Investigate reported issue
- Develop fix if vulnerability confirmed
- Deploy patch to production
- Notify affected customers
- Public disclosure after patch deployed
TRUST & TRANSPARENCY
Open About Security
- Public security policy
- Transparent permission requirements
- Clear data handling practices
- Responsive to concerns
Regular Updates
- Security patches applied promptly
- Dependencies kept up to date
- Infrastructure reviewed quarterly
- Third-party audits
Bug Bounty Program
Coming soon: Report security issues for rewards.
Details at: CAPYSQUASH.dev/security
FREQUENTLY ASKED QUESTIONS
SECURITY FAQ
Can CAPYSQUASH access my production database?
No. We only analyze migration files, never connect to your database.
Do you store my migration files?
No. We analyze them and discard immediately. Only metadata stored (filename, size, etc).
Can you modify my code?
No. We only have read access to contents, and only write to PR comments and checks.
What happens if CAPYSQUASH is compromised?
Worst case: Attacker could read migration files from configured paths. Cannot modify repos, access databases, or access other files.
Do you share data with third parties?
No, except: GitHub (for OAuth), Stripe (for billing), and infrastructure providers (AWS/GCP). Never sold or shared with advertisers.
Is my data encrypted?
Yes. TLS 1.3 in transit, AES-256 at rest. All data encrypted.
NEXT STEPS
CONTACT SECURITY TEAM
- đ§ General: security@CAPYSQUASH.dev
- đ Vulnerabilities: security@CAPYSQUASH.dev (PGP available)
- đ Legal/DPA: legal@CAPYSQUASH.dev
- đĢ Support: support@CAPYSQUASH.dev
How is this guide?