ci: add automated backmerge workflow for version bump commits from main to develop

Author: mkzopio

.github/pr-backmerge.yml

@@ -4,14 +4,18 @@
 # to the develop branch, but only when triggered by version bump commits.
 # This ensures that version updates made in production are properly synchronized back to the
 # development branch, maintaining version consistency across branches.
+#
+# Workflow logic:
+# 1. Triggers only on pushes to main branch with 'bump version' in commit message
+# 2. Checks if there are differences between main and develop branches
+# 3. Creates a PR to merge main into develop if differences exist
 
 name: Backmerge main to develop after version bump
 
 # Trigger conditions for the workflow
 on:
   push:
     branches:
-      # Only trigger on pushes to the main branch
       - main
 
 # Add permissions needed for PR creation
@@ -23,26 +27,25 @@ jobs:
   backmerge:
     runs-on: ubuntu-latest
     # Only run this workflow when the commit message contains 'bump version'
-    # This prevents unnecessary backmerges for regular commits to main
     if: contains(github.event.head_commit.message, 'bump version')
 
     steps:
-      # Step 1: Check out the repository code
-      # This gives the workflow access to the repository contents
+      # Step 1: Check out the repository code with full history
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           fetch-depth: 0 # Fetch all history for proper branch comparison
 
-      # Step 1.5: Ensure we have the latest develop branch and check if there are differences
-      - name: Fetch develop branch
+      # Step 2: Fetch the latest develop branch and display branch information
+      - name: Fetch develop branch and display branch info
         run: |
           git fetch origin develop:develop
           git branch -a
           echo "Current branch: $(git branch --show-current)"
           echo "Develop branch commit: $(git rev-parse develop)"
           echo "Main branch commit: $(git rev-parse main)"
 
+      # Step 3: Check if there are differences between main and develop branches
       - name: Check for differences between main and develop
         id: check_diff
         run: |
@@ -52,41 +55,54 @@ jobs:
           else
             echo "Found differences between main and develop branches."
             echo "has_diff=true" >> $GITHUB_OUTPUT
+            echo "Changes detected:"
+            git diff --stat main develop
           fi
 
-      # Step 2: Create an automated pull request for the backmerge
-      # Uses the peter-evans/create-pull-request action to generate a PR
+      # Step 4: Create an automated pull request for the backmerge
       - name: Create Backmerge PR
         uses: peter-evans/create-pull-request@v5
         if: steps.check_diff.outputs.has_diff == 'true'
         with:
-          # Use the default GitHub token for authentication
           token: ${{ secrets.GITHUB_TOKEN }}
-          # Target branch that will receive the changes
           base: develop
-          # Name of the temporary branch that will be created for this PR
           branch: auto/backmerge-main-to-develop
-          # Title of the pull request with emoji for better visibility
           title: "🔁 Backmerge: main → develop (after version bump)"
-          # Detailed description of what this PR does
           body: |
-            This automated PR syncs the **develop** branch with **main** after a production version bump.
-
-            Triggered by commit:
-            `${{ github.event.head_commit.message }}`
-
-          # Commit message for the changes in this PR
+            ## Automated Backmerge PR
+            
+            This PR syncs the **develop** branch with **main** after a production version bump.
+            
+            ### Details
+            - Triggered by commit: `${{ github.event.head_commit.message }}`
+            - Commit SHA: `${{ github.sha }}`
+            - Workflow run: [View Run](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})
+            
+            Please review the changes and merge when ready.
           commit-message: "chore(backmerge): sync main into develop after version bump"
-          # Clean up by deleting the temporary branch after the PR is merged or closed
           delete-branch: true
+          labels: |
+            automated-pr
+            backmerge
           
+      # Step 5: Report workflow status
       - name: PR Creation Status
         if: always()
         run: |
           echo "has_diff value: ${{ steps.check_diff.outputs.has_diff }}"
           if [ "${{ steps.check_diff.outputs.has_diff }}" != 'true' ]; then
-            echo "No PR created because there are no differences between main and develop branches."
+            echo "✅ No PR created: No differences found between main and develop branches."
           else
-            echo "PR creation attempted. If no PR was created, check GitHub token permissions."
-            echo "GitHub token permissions: ${{ toJson(github.token_permissions) }}"
+            echo "PR creation attempted."
+            echo "If no PR was created, please check:"
+            echo "1. GitHub token permissions: ${{ toJson(github.token_permissions) }}"
+            echo "2. Repository settings for GitHub Actions"
+            echo "3. Branch protection rules on develop branch"
           fi
+          
+      # Step 6: Notify on workflow completion
+      - name: Workflow Summary
+        if: always()
+        run: |
+          echo "::notice::Backmerge workflow completed at $(date)"
+          echo "::notice::Triggered by commit: ${{ github.event.head_commit.message }}"