Backport workflow #10435

ziggie1984 · 2025-12-09T09:53:38Z

Summary

This PR introduces an automated backport workflow that simplifies backporting merged PRs from master to release
branches.

How It Works

Merge a PR to master (or have it already merged)
Add a backport label in format: backport-v<version>-branch
- Example: backport-v0.20.x-branch
Workflow automatically:
- Validates the target branch exists
- Cherry-picks commits to a new branch
- Creates a PR targeting the release branch
- Adds no-changelog label (release notes already in master PR)

Key Features

Label-driven: Just add backport-v0.20.x-branch to trigger
Branch validation: Fails fast if target branch doesn't exist
Multiple backports: Add multiple labels to backport to several branches simultaneously
Conflict handling: Creates draft PR with conflict markers for manual resolution
Skip merge commits: Only cherry-picks actual changes, ignores sync merges
No manual work: Eliminates manual branch creation, cherry-picking, and PR creation

Example Usage

PR #1234 merged with label: backport-v0.20.x-branch

→ Workflow creates PR #1235
Title: [v0.20.x-branch] Backport #1234: Original Title
Base: v0.20.x-branch
Labels: no-changelog
Status: Ready for review (or Draft if conflicts)

Documentation

Detailed guide: docs/backport-workflow.md
Contributing: docs/code_contribution_guidelines.md

ziggie1984 · 2025-12-09T16:08:14Z

Verified the whole behaviour on my local repo, so take a look at if you wanna see how the created backports work:

https://github.com/ziggie1984/lnd/pulls

Created a PR which had 2 backport labels set, and also a PR which had a conflict.

ziggie1984 · 2025-12-09T16:17:46Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces comprehensive documentation for a new automated backport workflow. The new backport-workflow.md file is well-structured and provides clear instructions on how to use the workflow, handle conflicts, and troubleshoot common issues. The contribution guidelines are also updated to reference this new documentation. My review includes a few suggestions to improve clarity and fix a broken link in the new documentation.

docs/backport-workflow.md

This commit introduces an automated GitHub Actions workflow to streamline the backporting process for merged PRs from master to release branches. Key features: - Triggers on merged PRs with labels matching 'backport-v*' pattern (e.g., backport-v0.20.x-branch) - Validates that target branches exist before attempting backport - Creates separate backport PRs for each target branch - Automatically adds 'no-changelog' label to backport PRs - Handles merge conflicts by creating draft PRs with conflict markers - Supports multiple simultaneous backports via multiple labels Workflow steps: 1. Checkout repository with full git history 2. Validate all target branches exist in the remote repository 3. For each valid backport label: - Create a new branch (backport-<pr-num>-to-<target-branch>) - Cherry-pick commits from the master PR - Create a new PR targeting the release branch - Link back to the original PR 4. If conflicts occur, create a draft PR for manual resolution Label format: - Valid: backport-v0.20.x-branch, backport-v0.19.x-branch - Invalid: backport candidate, backport-candidate, backport-needed This automation reduces manual work and ensures consistency in the backporting process while maintaining full visibility and control for maintainers.

This commit adds detailed documentation for the automated backport workflow and updates the contribution guidelines to reference it. New documentation (docs/backport-workflow.md): - Complete overview of the automated backport process - Step-by-step usage instructions with examples - Detailed explanation of workflow triggers and label format - Technical details about workflow implementation - Conflict resolution procedures and best practices - Multiple backport scenarios and examples - Comprehensive troubleshooting guide Updated contribution guidelines (docs/code_contribution_guidelines.md): - Replaced detailed backport instructions with brief overview - Added reference to the new detailed documentation - Keeps contribution guidelines focused and concise The detailed documentation provides: - How to use backport labels correctly - What happens when labels are added before/after merge - How the workflow validates branches and handles errors - Step-by-step conflict resolution instructions - Solutions for common problems and edge cases - Examples of valid vs invalid label formats This documentation ensures contributors and maintainers have clear guidance on using the automated backport workflow effectively.

Roasbeef

I like the idea of using an existing solution for this, rather than rolling our own. I'm gonna check out the source of backport-action to learn a bit more about it.

Roasbeef · 2025-12-10T02:47:10Z

.github/workflows/backport.yml

+          labels: no-changelog
+
+          # Merge strategy - skip merge commits, use cherry-pick only.
+          merge_commits: skip


What's the distinction here? As won't we merge the backport PR into the release branch in the end?

Roasbeef · 2025-12-10T02:47:16Z

.github/workflows/backport.yml

+          merge_commits: skip
+
+          # If conflicts occur, create a draft PR with conflict markers.
+          experimental: '{"conflict_resolution": "draft_commit_conflicts"}'


Roasbeef · 2025-12-10T02:55:14Z

.github/workflows/backport.yml

+          fi
+
+      - name: Create backport PRs
+        uses: korthout/backport-action@v3


Pin to a hash here?

saubyk

Concept Ack.
Thanks for the pr and nice work, just a few nits on the documentation.

saubyk · 2025-12-10T03:14:03Z

docs/backport-workflow.md

+   - Validates the target branch exists
+   - Cherry-picks the commits
+   - Creates a new PR targeting the release branch
+   - Adds the `no-changelog` label (since release notes are in the master PR)


👍

Assuming there is no CI impact with no-changelog label

saubyk · 2025-12-10T03:18:26Z

docs/backport-workflow.md

+6. → Backport PR #1235 created immediately
+```
+
+### Scenario 2: Label After Merge (Recommended)


What's the reason for this to be a recommended approach?

saubyk · 2025-12-10T03:20:42Z

docs/backport-workflow.md

+
+- ✅ `backport-v0.20.x-branch` → backports to `v0.20.x-branch`
+- ✅ `backport-v0.19.x-branch` → backports to `v0.19.x-branch`
+- ✅ `backport-v0.18.5-beta-branch` → backports to `v0.18.5-beta-branch`


Is this a scenario, we will cater for? As in, maintain a specific branch for a minor release?
I thought that the idea is to maintain one branch for each major release version and cut minors from that after applying relevant changes.

If that is indeed the case, this last example can be confusing.

saubyk · 2025-12-10T03:24:33Z

docs/backport-workflow.md

+
+4. **PR Description**
+   ```markdown
+   Backport of #1234


saubyk · 2025-12-10T03:26:59Z

docs/backport-workflow.md

+
+## Multiple Backports
+
+You can backport to multiple release branches simultaneously by adding multiple labels.


ziggie1984 changed the title ~~Test backport workflow~~ Backport workflow Dec 9, 2025

ziggie1984 self-assigned this Dec 9, 2025

ziggie1984 force-pushed the test-backport-workflow branch 2 times, most recently from 9158cb3 to b152acd Compare December 9, 2025 16:04

ziggie1984 requested a review from saubyk December 9, 2025 16:06

ziggie1984 added the CI continuous integration label Dec 9, 2025

gemini-code-assist bot reviewed Dec 9, 2025

View reviewed changes

docs/backport-workflow.md Outdated Show resolved Hide resolved

docs/backport-workflow.md Show resolved Hide resolved

docs/backport-workflow.md Outdated Show resolved Hide resolved

ziggie1984 force-pushed the test-backport-workflow branch from b152acd to 2becf8d Compare December 9, 2025 16:42

ziggie1984 added no-changelog no-itest labels Dec 9, 2025

ziggie1984 force-pushed the test-backport-workflow branch from 2becf8d to 5a3ece0 Compare December 9, 2025 16:43

ziggie1984 added 2 commits December 9, 2025 17:53

ziggie1984 force-pushed the test-backport-workflow branch from 5a3ece0 to bd4fc35 Compare December 9, 2025 16:53

Roasbeef reviewed Dec 10, 2025

View reviewed changes

saubyk approved these changes Dec 10, 2025

View reviewed changes


		## Multiple Backports

		You can backport to multiple release branches simultaneously by adding multiple labels.

Backport workflow #10435

Are you sure you want to change the base?

Backport workflow #10435

Conversation

ziggie1984 commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How It Works

Key Features

Example Usage

Documentation

Uh oh!

ziggie1984 commented Dec 9, 2025

Uh oh!

ziggie1984 commented Dec 9, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Roasbeef left a comment

Choose a reason for hiding this comment

Uh oh!

Roasbeef Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Roasbeef Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Roasbeef Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

saubyk left a comment

Choose a reason for hiding this comment

Uh oh!

saubyk Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

saubyk Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

saubyk Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saubyk Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

saubyk Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ziggie1984 commented Dec 9, 2025 •

edited

Loading

saubyk Dec 10, 2025 •

edited

Loading