GitHub App Installation
This guide walks you through the complete process of installing the recommit GitHub App and configuring repository access.
Prerequisites
Before installing the GitHub App, ensure you have:
- A recommit account (sign up at recommit.dev)
- Admin access to the GitHub organization or repositories
- At least one repository to connect
For organization repositories, you may need organization owner approval to install GitHub Apps.
Installation Options
recommit offers flexible installation options:
| Option | Best For | Repositories |
|---|---|---|
| Organization-wide | Teams with many repos | All current and future repos |
| Selected Repositories | Specific projects | Only chosen repos |
| Personal Account | Individual developers | Personal repositories |
Step-by-Step Installation
Open Installation Page
From the recommit Console:
- Navigate to Settings
- Click Install GitHub App
- Or use the quick link in the onboarding wizard
Choose Installation Scope
GitHub will ask where to install the app:
For Organizations:
- Select your organization from the dropdown
- You may need owner approval
For Personal Account:
- Select your username
Select Repository Access
Choose your access level:
All Repositories (Recommended for teams):
- Automatically includes new repositories
- No manual updates needed
- Best for organizations standardizing on recommit
Only Select Repositories:
- Manually choose specific repos
- More control, more maintenance
- Add new repos later as needed
Review Permissions
recommit requires these GitHub permissions:
| Permission | Level | Purpose |
|---|---|---|
| Repository contents | Read & Write | Read code, create branches |
| Pull requests | Read & Write | Create cherry-pick PRs |
| Metadata | Read | Repository information |
| Webhooks | Read & Write | Receive PR merge events |
These permissions are required for recommit to function. The app cannot operate with reduced permissions.
Complete Installation
Click Install & Authorize to finish.
GitHub redirects you back to recommit where your repositories will sync automatically.
Post-Installation Setup
After installation, complete these steps:
Verify Repository Sync
- Go to Console → Repositories
- Your authorized repos should appear
- If missing, click Refresh
Enable Repositories
Repositories are not enabled by default:
- Click on a repository
- Toggle Enable Cherry-picks
- Or bulk-enable from the list view
Link Roadmaps
Each enabled repository needs a Roadmap:
- Create a Roadmap (if you haven't)
- Link it to your repository
- Cherry-picks will use the Roadmap's branch configuration
Managing Installation
Adding More Repositories
To add repositories after initial installation:
Access GitHub Settings
- Go to GitHub → Settings
- Navigate to Applications → Installed GitHub Apps
- Find recommit.dev
Modify Repository Access
- Click Configure
- Under "Repository access", add or remove repos
- Save changes
Changes sync automatically to recommit.
Removing Repositories
To stop cherry-picks for a repository:
Option 1: Disable in recommit (Recommended)
- Repository stays authorized but inactive
- Easy to re-enable later
Option 2: Remove from GitHub App
- Revokes all access
- Must re-add to use again
Uninstalling the App
To completely remove recommit:
- Go to GitHub → Settings → Applications
- Find recommit.dev
- Click Uninstall
Uninstalling removes all repository connections. You'll need to reinstall and reconfigure to use recommit again.
Organization Setup
Installation for Organizations
When installing for a GitHub organization:
- You need Owner or Admin role
- Organization policies may require approval
- Branch protection rules may need updates
Handling Approval Requests
If you're not an organization owner:
- Request installation (creates pending request)
- Owner receives notification
- Owner approves in organization settings
- Installation completes
Branch Protection Considerations
For protected branches, ensure the GitHub App can:
- Create branches (
cherry-kit/*) - Push commits
- Create pull requests
You may need to add the app to branch protection bypass lists.
Troubleshooting Installation
"Request to access organization pending"
Cause: Organization requires owner approval for apps.
Solution: Contact your organization owner to approve the request.
Repositories Not Appearing
Causes:
- Installation still syncing
- Selected specific repos, didn't include this one
- Permission issue
Solutions:
- Wait 30 seconds and refresh
- Check GitHub App configuration for repo access
- Verify you have admin access to the repository
Permission Errors After Installation
Cause: Repository permissions may have changed.
Solution:
- Go to GitHub → Settings → Applications
- Find recommit.dev → Configure
- Review and update permissions
- Refresh recommit Console
Installation Stuck
If installation doesn't complete:
- Cancel the current attempt
- Clear browser cookies
- Log out of both GitHub and recommit
- Start fresh installation
Security Considerations
What recommit Can Access
With proper installation, recommit can:
✅ Read repository contents ✅ Create and push branches ✅ Create pull requests ✅ Read webhooks
What recommit Cannot Do
recommit cannot:
❌ Delete repositories ❌ Change repository settings ❌ Access private data outside authorized repos ❌ Merge PRs (only creates them)
Audit and Compliance
- All actions are logged in GitHub's security log
- recommit uses OAuth 2.0 for authentication
- Webhook payloads are verified using signatures
- No credentials are stored
Multiple Organizations
You can use recommit across multiple organizations:
- Each organization has separate installation
- Roadmaps are per-organization
- Billing is per-organization
- Switch organizations in Console dropdown