How Cherry-Pick Works

Cherry-picking is the process of taking a commit from one branch and applying it to other branches. recommit automates this process so you don't have to do it manually.

The Workflow

When you open or update a Pull Request, here's what happens:

1. PR opened or updated
         │
         ▼
2. recommit validates:
   - Repository enabled?
   - Roadmap linked?
         │
         ▼
3. Cherry-pick preview shown in PR comment
   (with checkable target branch list)
         │
         ▼
4. After PR merge, for each selected branch:
   - Cherry-pick commit
   - Push to target branch
         │
         ▼
5. Done! Check results in PR comment

What Triggers a Cherry-Pick?

Cherry-picks are triggered when:

Event	Triggered?
PR merged	✅ Yes
PR closed (not merged)	❌ No
Direct commit to branch	❌ No
PR opened/updated	❌ No (summary only)

Cherry-Pick Process

Step 1: Receive Webhook

When a PR is merged, GitHub sends a webhook event to recommit containing:

Repository information
PR details (number, title, author)
Merge commit SHA
Target branch

Step 2: Validation

recommit checks:

Repository status - Must be enabled and "Normal"
Roadmap linked - Must have a roadmap associated

If any check fails, the cherry-pick is skipped.

Step 3: Determine Target Branches

recommit reads the linked roadmap to get:

List of target branches
Whether to include default branch
Branch processing order

Step 4: Execute Cherry-Picks

For each selected target branch, recommit:

Cherry-picks the merge commit
Pushes the commit to the target branch

Step 5: Track Results

Each cherry-pick is logged with:

Status (Pending, Processing, Success, Failed)
Source and target branches
Commit SHA

Cherry-Pick Status

Status	Description
Pending	Task queued, waiting to execute
Processing	Currently executing cherry-pick
Success	Completed successfully, pushed to target branch
Failed	Error occurred, may need manual intervention

Interactive Branch Selection

When a PR is opened or updated, recommit displays an interactive checklist in the PR comment:

Will be cherry-picked to the following branches:
 
- [x] v3
- [x] v2
- [x] v1

How to Use

Default selection: All branches after the source branch in the roadmap are selected by default
Deselect: Click the checkbox to exclude branches from cherry-pick
Reselect: Click the checkbox again to include branches
Applied on merge: When the PR is merged, only selected branches will receive the cherry-pick

⚠️

Adjust the checklist before merging the PR. Once merged, recommit executes cherry-picks based on the selection at that time.

Cherry-Pick Results

After the PR is merged, recommit adds a result report in the comments:

Result:
| Branch | Status      | Reason   |
|--------|-------------|----------|
| v3     | ✅ Succeed  |          |
| v2     | ✅ Succeed  |          |
| v1     | ❌ Failed   | conflict |

Handling Multiple Branches

Cherry-picks are processed in order v1 → v2 → v3 → main:

Roadmap: main v3 v2 v1
Processing order: v1 → v2 → v3 → main

Example: PR merged to v2
Cherry-pick to:
1. v3
2. main
(v1 is skipped because it's before v2 in processing order)

If one fails, others continue processing.

Concurrency Control

To prevent conflicts, recommit uses locking:

Only one cherry-pick task per repository runs at a time
Multiple PRs merged quickly are queued and processed in order

Best Practices

Use Squash Merge

We recommend enabling squash merge in your repository settings:

Creates cleaner cherry-picks (single commit)
Reduces conflict chances
Easier to track changes

Keep Branches Updated

Regularly sync your version branches to minimize divergence:

Less conflict likelihood
Faster cherry-pick execution
Cleaner git history

Review Cherry-Pick Results

Always review the cherry-pick results in PR comments:

Verify changes were pushed correctly
Check for any failures
Address conflicts if needed

Link Roadmap Conflict Resolution