Skip to content
Docs
Repositories
Link Roadmap

Link Repository to Roadmap

Linking a repository to a roadmap tells recommit which branches should receive cherry-picks when PRs are merged.

Why Link a Roadmap?

A repository needs a roadmap to know:

  • Where to cherry-pick (target branches)
  • In what order to process branches
  • Whether to include the default branch

Without a linked roadmap, auto cherry-pick won't work even if the repository is enabled.

Linking a Roadmap

Navigate to Repository

  1. Go to Console → Repositories
  2. Find the repository you want to configure
  3. Click on the repository row to open settings

Select a Roadmap

  1. Find the Roadmap dropdown
  2. Click to open the list of available roadmaps
  3. Select the appropriate roadmap

Confirm the Link

The roadmap is linked automatically when selected. You'll see:

  • Roadmap name displayed
  • Target branches shown
  • Ready to enable

Choosing the Right Roadmap

Consider these factors when selecting a roadmap:

FactorConsideration
Branch StrategyDoes the roadmap include all branches you need?
Release CadenceMatch roadmap to repo's release pattern
Version SupportInclude LTS/supported versions

Example Scenarios

Scenario 1: Single Roadmap for All

If all your repositories follow the same branching strategy:

  • Create one roadmap (e.g., "Standard Releases")
  • Link all repositories to it

Scenario 2: Different Strategies

If repositories have different needs:

  • frontend-app → "Main Only" roadmap
  • backend-api → "Multi-Version" roadmap
  • shared-lib → "LTS Support" roadmap

Unlinking a Roadmap

To remove the roadmap association:

Open Repository Settings

  1. Go to Console → Repositories
  2. Click on the repository

Clear the Roadmap

  1. Click the Roadmap dropdown
  2. Select the empty/none option (or click clear)
  3. The roadmap is unlinked
⚠️

Unlinking a roadmap will stop all future cherry-picks for this repository, even if it's still enabled.

Changing Roadmaps

To switch to a different roadmap:

  1. Open repository settings
  2. Click the Roadmap dropdown
  3. Select the new roadmap
  4. Change takes effect immediately

What happens:

  • New PRs use the new roadmap configuration
  • In-progress cherry-picks continue with their original settings
  • Historical records remain unchanged

Multiple Repositories, Same Roadmap

You can link many repositories to one roadmap:

Roadmap: "Release Branches" (main; v3; v2; v1)
    ├── repo-a ✓
    ├── repo-b ✓
    ├── repo-c ✓
    └── repo-d ✓

Benefits:

  • Consistent cherry-pick behavior across repos
  • Update once, apply to all
  • Easier management

One Repository, One Roadmap

Each repository can only link to one roadmap at a time.

If you need different cherry-pick rules for different scenarios:

  • Create a comprehensive roadmap that covers all needs
  • Or manually trigger cherry-picks for edge cases

Troubleshooting

No Roadmaps Available

Problem: Dropdown is empty

Solutions:

  1. Create a roadmap first
  2. Ensure you're in the correct organization
  3. Check that you have owner permissions

Wrong Branches Being Used

Problem: Cherry-picks going to unexpected branches

Check:

  1. Verify the correct roadmap is linked
  2. Review the roadmap's branch configuration
  3. Check if "Cherry-pick to Default Branch" is affecting results

Link Not Saving

Problem: Selection doesn't persist

Try:

  1. Refresh the page
  2. Check your network connection
  3. Verify you have edit permissions
  4. Contact support if issue persists

Related

Enable RepositoryHow It Works