Core Concepts
This page explains the key concepts you need to understand to use recommit effectively.
Cherry-Pick
What is Cherry-Pick?
In Git, cherry-pick means taking a commit from one branch and applying it to another branch. It's like copying a specific change to a different location in your codebase.
# Traditional cherry-pick command
git cherry-pick <commit-sha>Why Cherry-Pick?
Cherry-picking is useful when you need to:
- Backport bug fixes to older versions
- Apply security patches across all supported releases
- Synchronize specific features between branches
The Problem with Manual Cherry-Pick
Manual cherry-picking is:
- Time-consuming: Each fix requires multiple operations
- Error-prone: Easy to forget a branch or make mistakes
- Doesn't scale: More versions = more work per fix
How recommit Automates It
recommit watches for Pull Request events and automatically:
- When PR is opened/updated, displays an interactive checklist of target branches in the comment
- When PR is merged, cherry-picks to each selected target branch
- Pushes commits to target branches
- Shows execution results in the PR comment
Organization
What is an Organization?
An Organization in recommit represents your team or company. It's the top-level container for:
- Repositories
- Roadmaps
- Team members
- Billing information
Organization vs GitHub Organization
Your recommit organization typically maps to your GitHub organization, but they're separate entities. When you sign up, recommit creates an organization for you.
Ownership
Each organization has an Owner who can:
- Create and manage Roadmaps
- Enable/disable repositories
- Manage billing and subscription
- Invite team members (coming soon)
Repository
What is a Repository?
A Repository in recommit represents a GitHub repository that you've authorized for automatic cherry-picking.
Repository States
| State | Description |
|---|---|
| Normal | Active and ready for cherry-picks |
| Suspended | GitHub App access is suspended |
| Disabled | User manually disabled cherry-picks |
Repository Requirements
For cherry-picks to work, a repository must:
- Be authorized via GitHub App
- Be linked to a Roadmap
- Be enabled
recommit provides free basic functionality for one repository. For more repositories, subscribe to a paid plan.
Roadmap
What is a Roadmap?
A Roadmap is a configuration template that defines:
- Target branches: Where to cherry-pick
- Processing order: Which branch first
- Options: Like including default branch
Roadmap vs Repository
- Roadmap: Defines the rules (what branches, what order)
- Repository: Where the rules are applied
One Roadmap can be shared by multiple repositories with similar branching strategies.
Branch List
The branch list in a Roadmap specifies target branches:
main v3 v2 v1Cherry-picks are processed in order v1 → v2 → v3 → main (reverse of the list). When a PR is merged, cherry-picks start from the branch after the source branch. For example, if a PR targets v2, it will be cherry-picked to v3 and main.
Default Branch Option
When "Cherry-pick to Default Branch" is enabled:
- The repository's default branch is always included
- It's added to the front of the branch list
- Useful when PRs may target any branch
Cherry-Pick Task
What is a Cherry-Pick Task?
When a PR is merged, recommit creates a Cherry-Pick Task that represents the work to be done.
Task Lifecycle
PR Merged
│
▼
Processing Started
│
▼
Cherry-Pick Executed
│
▼
Pushed to Target Branch
│
▼
Complete (Succeed/Failed/Skip)Result Status
| Status | Icon | Meaning |
|---|---|---|
| Succeed | ✅ | Cherry-pick completed, pushed to target branch |
| Failed | ❌ | Error occurred (e.g., conflicts) |
| Pending | ⏳ | Waiting in queue to be processed |
| Skip | ⏭️ | Skipped (e.g., target branch doesn't exist) |
When a cherry-pick fails (e.g., due to conflicts), you need to manually cherry-pick locally and resolve the conflicts.
Pull Request (PR)
Trigger PR
The Trigger PR is the original Pull Request that was merged and initiated the cherry-pick process.
PR Comment Interaction
When a PR is opened or updated, recommit adds a comment with:
- An interactive checklist listing all target branches
- Users can check/uncheck branches to cherry-pick
- After PR merge, displays cherry-pick execution results
Branch
Source Branch
The branch where the original PR was merged (e.g., feature-branch merged into main).
Target Branch
A branch that should receive the cherry-picked changes (e.g., v2, v1).
Cherry-Pick Branch
The temporary branch recommit creates to hold cherry-picked changes:
cherry-kit/<pr-number>-<target-branch>Example: cherry-kit/123-v2
Webhook
What is a Webhook?
A Webhook is a way for GitHub to notify recommit when events happen (like PR merges).
How It Works
- You merge a PR in GitHub
- GitHub sends a webhook to recommit
- recommit processes the event
- Cherry-pick tasks are created
Supported Events
| Event | Purpose |
|---|---|
pull_request | Detect merged PRs |
installation | App install/uninstall |
installation_repositories | Repo authorization changes |
create | New branch detection |
Subscription
What is a Subscription?
A Subscription represents your plan level with recommit, determining:
- Number of repositories
- Number of cherry-picks per month
- Available features
Free Plan
recommit provides free basic functionality for one repository permanently, no subscription required. For more repositories, subscribe to a paid plan.
Subscription States
| State | Cherry-picks? |
|---|---|
| Active | ✅ Yes |
| Expired | ❌ No (beyond free quota) |
| Free | ✅ Yes (1 repository) |
Summary Diagram
┌─────────────────────────────────────────────────────────────┐
│ Organization │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Roadmap A │ │ Roadmap B │ │ Subscription │ │
│ │ main;v3;v2 │ │ lts-v5;v4 │ │ (Active Plan) │ │
│ └──────┬──────┘ └──────┬──────┘ └─────────────────────┘ │
│ │ │ │
│ ┌────┴────┐ ┌────┴────┐ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Repo 1│ │Repo 2│ │Repo 3│ │Repo 4│ ← Repositories │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
└─────────────────────────────────────────────────────────────┘