Add note about repo settings + handle existing branch in prepare release

Author: grahamplace

.github/workflows/prepare-release.yml

@@ -21,6 +21,7 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
+      id-token: write
     steps:
       - uses: actions/checkout@v4
         with:
@@ -64,12 +65,25 @@ jobs:
           echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
           echo "Current: $CURRENT_VERSION -> New: $NEW_VERSION"
 
-      # Create release branch
+      # Create release branch (delete if exists from previous failed run)
       - name: Create release branch
         run: |
           BRANCH_NAME="release/v${{ steps.version.outputs.new_version }}"
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Check if branch exists remotely and delete it if it does
+          if git ls-remote --heads origin $BRANCH_NAME | grep -q $BRANCH_NAME; then
+            echo "Branch $BRANCH_NAME exists remotely, deleting it..."
+            git push origin --delete $BRANCH_NAME || true
+          fi
+
+          # Check if branch exists locally and delete it if it does
+          if git show-ref --verify --quiet refs/heads/$BRANCH_NAME; then
+            echo "Branch $BRANCH_NAME exists locally, deleting it..."
+            git branch -D $BRANCH_NAME || true
+          fi
+
           git checkout -b $BRANCH_NAME
           echo "Created branch: $BRANCH_NAME"
 
@@ -92,6 +106,8 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           base: main
           branch: release/v${{ steps.version.outputs.new_version }}
+          delete-branch: false
+          push-to-fork: false
           title: 'Release v${{ steps.version.outputs.new_version }}'
           body: |
             ## Release v${{ steps.version.outputs.new_version }}

RELEASING.md

@@ -12,6 +12,13 @@ We follow [Semantic Versioning](https://semver.org/) (SemVer):
 
 ## Release Workflow
 
+**Important:** Before using the automated release workflow, ensure your repository settings allow GitHub Actions to create pull requests:
+
+1. Go to Repository Settings → Actions → General
+2. Under "Workflow permissions", select "Read and write permissions"
+3. Check "Allow GitHub Actions to create and approve pull requests"
+4. Click "Save"
+
 ### Option 1: Automated Release (Recommended)
 
 1. **Prepare Release:**