fix: backtrack workflow fails with 403 — lock/unlock steps are inverted (#187)

- [x] Understand the gap: base branch (`github.base_ref`) was not locked
during backtracking, allowing new PR merges into it concurrently
- [x] Lock base branch (`github.base_ref`) with `lock-branch: 'true'`
before the merge steps
- [x] Restore permanent protection on base branch after backtrack
(always, guarded by lock step outcome)

Author: petesramek

.github/actions/github/branch-protection/lock/action.yml

@@ -8,6 +8,10 @@ inputs:
   token:
     description: 'GitHub token with administration:write (repo admin) permission. Use a PAT; GITHUB_TOKEN cannot call the branch protection API.'
     required: true
+  lock-branch:
+    description: 'When true, sets lock_branch to prevent even PR merges (use during automated operations). When false (default), only direct pushes are blocked; PRs with required reviews can still be merged.'
+    required: false
+    default: 'false'
 
 runs:
   using: composite
@@ -30,7 +34,7 @@ runs:
           "restrictions": null,
           "allow_force_pushes": false,
           "allow_deletions": false,
-          "lock_branch": false
+          "lock_branch": ${{ inputs.lock-branch }}
         }
         EOF
         then

.github/workflows/backtrack.yml

@@ -61,36 +61,75 @@ jobs:
             echo "::warning::Develop branch '${{ steps.targets.outputs.develop-branch }}' not found, skipping backtrack."
           fi
 
+      - name: 'Lock base branch'
+        id: lock-base
+        uses: './.github/actions/github/branch-protection/lock'
+        with:
+          branch: ${{ github.base_ref }}
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+          lock-branch: 'true'
+
+      - name: 'Lock preview branch'
+        id: lock-preview
+        if: ${{ steps.targets.outputs.preview-branch != '' }}
+        uses: './.github/actions/github/branch-protection/lock'
+        with:
+          branch: ${{ steps.targets.outputs.preview-branch }}
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+          lock-branch: 'true'
+
       - name: 'Lock develop branch'
         id: lock-develop
         if: ${{ steps.check-develop.outputs.exists == 'true' }}
         uses: './.github/actions/github/branch-protection/lock'
         with:
           branch: ${{ steps.targets.outputs.develop-branch }}
           token: ${{ secrets.GH_ADMIN_TOKEN }}
+          lock-branch: 'true'
 
       - name: 'Backtrack: merge ${{ github.base_ref }} into ${{ steps.targets.outputs.preview-branch }}'
         if: ${{ steps.targets.outputs.preview-branch != '' }}
+        env:
+          GH_TOKEN: ${{ secrets.GH_ADMIN_TOKEN }}
         run: |
-          git fetch origin
-          git checkout -B ${{ steps.targets.outputs.preview-branch }} origin/${{ steps.targets.outputs.preview-branch }}
-          git merge --no-ff origin/${{ github.base_ref }} -m "Backtrack: merge ${{ github.base_ref }} into ${{ steps.targets.outputs.preview-branch }}"
-          git push origin ${{ steps.targets.outputs.preview-branch }}
+          gh api --method POST /repos/${{ github.repository }}/merges \
+            --field base="${{ steps.targets.outputs.preview-branch }}" \
+            --field head="${{ github.base_ref }}" \
+            --field commit_message="Backtrack: merge ${{ github.base_ref }} into ${{ steps.targets.outputs.preview-branch }}"
 
       - name: 'Backtrack: merge ${{ steps.targets.outputs.merge-source }} into ${{ steps.targets.outputs.develop-branch }}'
         if: ${{ steps.check-develop.outputs.exists == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GH_ADMIN_TOKEN }}
         run: |
-          git fetch origin
-          git checkout -B ${{ steps.targets.outputs.develop-branch }} origin/${{ steps.targets.outputs.develop-branch }}
-          git merge --no-ff origin/${{ steps.targets.outputs.merge-source }} -m "Backtrack: merge ${{ steps.targets.outputs.merge-source }} into ${{ steps.targets.outputs.develop-branch }}"
-          git push origin ${{ steps.targets.outputs.develop-branch }}
+          gh api --method POST /repos/${{ github.repository }}/merges \
+            --field base="${{ steps.targets.outputs.develop-branch }}" \
+            --field head="${{ steps.targets.outputs.merge-source }}" \
+            --field commit_message="Backtrack: merge ${{ steps.targets.outputs.merge-source }} into ${{ steps.targets.outputs.develop-branch }}"
+
+      - name: 'Restore protection: base branch'
+        if: ${{ always() && steps.lock-base.outcome == 'success' }}
+        uses: './.github/actions/github/branch-protection/lock'
+        with:
+          branch: ${{ github.base_ref }}
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+          lock-branch: 'false'
 
-      - name: 'Unlock develop branch'
-        if: ${{ always() && steps.lock-develop.outcome != 'skipped' }}
-        uses: './.github/actions/github/branch-protection/unlock'
+      - name: 'Restore protection: preview branch'
+        if: ${{ always() && steps.lock-preview.outcome == 'success' }}
+        uses: './.github/actions/github/branch-protection/lock'
+        with:
+          branch: ${{ steps.targets.outputs.preview-branch }}
+          token: ${{ secrets.GH_ADMIN_TOKEN }}
+          lock-branch: 'false'
+
+      - name: 'Restore protection: develop branch'
+        if: ${{ always() && steps.lock-develop.outcome == 'success' }}
+        uses: './.github/actions/github/branch-protection/lock'
         with:
           branch: ${{ steps.targets.outputs.develop-branch }}
           token: ${{ secrets.GH_ADMIN_TOKEN }}
+          lock-branch: 'false'
 
       - name: 'Write backtrack summary'
         if: ${{ always() }}