Skip to content

PATTERN Cited by 1 source

Label-triggered backport

Intent

Use a GitHub label applied to a PR as the signal that a bot should cherry-pick that PR onto one or more older release branches. Leaves the per-PR backport decision to the PR author rather than enforcing a blanket "everything backports to everything" policy or requiring a central release manager to triage.

When to use it

  • You maintain multiple release branches and need selective backports (not every change belongs on every branch).
  • Authors have the context to decide whether their change is a bug fix that deserves backporting vs a feature that doesn't.
  • You already have an automated cherry-pick bot running; adding label-triggered flows is a small extension.
  • You can tolerate silent-omission as a failure mode, backed by an out-of-band reconciliation check.

Mechanism

  1. Define a label convention like Backport to: latest-22.0, Backport to: latest-21.0, etc. — one label per release branch.
  2. Author applies the appropriate label(s) when opening or reviewing the PR.
  3. Bot polls the repo on a schedule (or reacts to label-added webhooks) and finds labelled merged PRs not yet backported.
  4. For each, bot checks out the target release branch, cherry-picks the labelled PR's commit(s), and opens a new PR.
  5. On conflict, same draft-PR escalation as the primary cherry-pick flow.
  6. Bot records the backport status in its state store to avoid repeated cherry-picks.

From the canonical source: "Backports are not automatically triggered. Instead, they rely on labels applied to PRs in the vitess-private repository. Labels like Backport to: latest-x.0 signal the bot to initiate the backport. Once the label is applied, the bot executes the backporting steps, following a workflow akin to cherry-picking." (Source: sources/2026-04-21-planetscale-automating-cherry-picks-between-oss-and-private-forks)

Why labels rather than a branch naming convention or PR template?

  • Native GitHub surface — every GitHub user knows how to apply and filter labels; no new tooling to learn.
  • Multi-select — applying Backport to: latest-22.0 AND Backport to: latest-21.0 triggers two backports from a single PR. Harder with a single-value PR template.
  • Reviewable — reviewers can ask for additional labels before approving, or remove incorrect ones.
  • Retroactive — labels can be applied to already-merged PRs after the fact, so backport decisions aren't locked at merge time.
  • Searchable in reconciliation — an audit query like "find PRs with Backport to: latest-22.0 whose matching backport PR is missing from latest-22.0" is a simple GitHub search.

Author-owns-decision trade-off

The pattern deliberately shifts the backport decision from a central release manager to the author:

Benefits: - Author has the most context on whether the change is safe to backport (bug fix vs refactor, dependency on newer features, etc.). - Scales without adding human bottleneck at release time. - Reviewers can push back by removing labels.

Costs: - Silent-omission failure mode — author forgets to apply the label, the backport never happens, no error is raised. Only the reconciliation check catches this. - Requires label-discipline culture — teams without strong norms around labelling will have leaky backports. - No cross-PR deduplication — if several PRs fix the same bug, authors may all label, causing redundant backport PRs.

Variations

  • Webhook-triggered instead of cron-triggered — react to label-added events for lower latency. Canonical source uses cron, which is simpler but has hour-scale latency.
  • Validation on label add — CI check that confirms the labelled PR's target branch exists and has the same base structure as the PR's target at merge time. Prevents stale label applications from triggering broken backports.
  • Auto-label from CODEOWNERS — if the changed files belong to a release-managed area, auto-apply the label. Shifts the decision from author to CODEOWNERS policy.
  • Label suggests, not triggers — have the bot comment "Looks like a bug fix; would you like to backport to latest-22.0? Apply Backport to: latest-22.0." Author still has to confirm.

Consequences

Benefits

Costs / pitfalls

  • Silent omission when authors forget labels.
  • Depends on a reconciliation backstop to catch misses.
  • Doesn't scale to 5+ active release branches without a clean labelling taxonomy — label soup emerges.
  • Needs label protection — org-level rulesets should prevent non-maintainers from applying backport labels if backport policy is restricted.

Canonical instantiation

systems/vitess-cherry-pick-bot — PlanetScale's bot uses Backport to: latest-x.0 labels on merged PRs in the vitess-private repo to trigger backports from the upstream branch to the corresponding latest-x.0 release branch. Weekly reconciliation catches PRs backported to some but not all higher- numbered latest branches.

Last updated · 319 distilled / 1,201 read