From 38428ee53e6a5adbf4993c3d2bc47a6b072c8afc Mon Sep 17 00:00:00 2001
From: BLACKBOX Agent <code@blackbox.ai>
Date: Thu, 6 Nov 2025 17:02:18 +0000
Subject: [PATCH] fix(ci): resolve out-of-date branch warning in auto PR
 workflow

---
 docs/common-issues.md | 79 ++++++++++++++++++++++++++++++++++++++++++-
 docs/examples.md      |  9 +++--
 2 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/docs/common-issues.md b/docs/common-issues.md
index b72aceffb5..10cc3aed96 100644
--- a/docs/common-issues.md
+++ b/docs/common-issues.md
@@ -2,7 +2,8 @@
 
 - [Troubleshooting](#troubleshooting)
   - [Create using an existing branch as the PR branch](#create-using-an-existing-branch-as-the-pr-branch)
-- [Frequently requested features](#use-case-create-a-pull-request-to-update-x-on-release)
+  - [Pull request shows "This branch is out-of-date with the base branch"](#pull-request-shows-this-branch-is-out-of-date-with-the-base-branch)
+- [Frequently requested features](#frequently-requested-features)
   - [Disable force updates to existing PR branches](#disable-force-updates-to-existing-pr-branches)
   - [Add a no-verify option to bypass git hooks](#add-a-no-verify-option-to-bypass-git-hooks)
 
@@ -16,6 +17,82 @@ If you have an existing branch that you just want to create a PR for, then I rec
 
 Alternatively, if you are trying to keep a branch up to date with another branch, then you can follow [this example](https://github.com/peter-evans/create-pull-request/blob/main/docs/examples.md#keep-a-branch-up-to-date-with-another).
 
+### Pull request shows "This branch is out-of-date with the base branch"
+
+When creating pull requests to promote changes from one branch to another (e.g., `dev` → `prod`), you may see a warning from GitHub stating "This branch is out-of-date with the base branch" even though the pull request should contain all the latest changes.
+
+#### Root Cause
+
+This issue occurs when the workflow checks out the **target** branch (e.g., `prod`), resets it locally to match the **source** branch (e.g., `dev`), and then creates a pull request. The problem is:
+
+1. The local target branch is reset to match the source
+2. The pull request branch is created from the locally reset target
+3. However, the **remote** target branch remains unchanged
+4. GitHub compares the pull request branch against the remote target branch
+5. Since the remote target is behind, GitHub shows the "out-of-date" warning
+
+#### Incorrect Workflow Pattern
+
+```yml
+# ❌ This pattern causes the "out-of-date" warning
+name: Auto PR from dev to prod
+on:
+  push:
+    branches:
+      - dev
+jobs:
+  check-and-create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: prod  # ❌ Checking out target branch
+      - name: Reset promotion branch
+        run: |
+          git fetch origin dev:dev
+          git reset --hard dev
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: prod-promotion
+          title: "Auto PR: Merge changes from dev to prod"
+```
+
+#### Correct Solution
+
+Check out the **source** branch and specify the **target** branch using the `base` input:
+
+```yml
+# ✅ Correct pattern - no "out-of-date" warning
+name: Auto PR from dev to prod
+on:
+  push:
+    branches:
+      - dev
+jobs:
+  check-and-create-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: dev  # ✅ Check out source branch
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: prod-promotion
+          base: prod  # ✅ Specify target branch as base
+          title: "Auto PR: Merge changes from dev to prod"
+          body: "This pull request has been automatically created to merge changes from the dev branch into the prod branch."
+```
+
+This approach ensures that:
+- The pull request branch is created from the source branch (`dev`)
+- The pull request targets the correct base branch (`prod`)
+- GitHub correctly shows the diff between source and target
+- No "out-of-date" warning appears
+
+For more examples of branch promotion workflows, see [Keep a branch up-to-date with another](https://github.com/peter-evans/create-pull-request/blob/main/docs/examples.md#keep-a-branch-up-to-date-with-another).
+
 ## Frequently requested features
 
 ### Disable force updates to existing PR branches
diff --git a/docs/examples.md b/docs/examples.md
index 0ceadd7fea..1719ce2218 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -73,17 +73,16 @@ jobs:
   productionPromotion:
     runs-on: ubuntu-latest
     steps:
+      # Checkout the source branch (main) that contains the changes
       - uses: actions/checkout@v4
         with:
-          ref: production
-      - name: Reset promotion branch
-        run: |
-          git fetch origin main:main
-          git reset --hard main
+          ref: main
+      # Create a pull request to merge main into production
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v7
         with:
           branch: production-promotion
+          base: production
 ```
 
 ## Use case: Create a pull request to update X on release