feat: add opt-in README SHA update to release workflow

.github/workflows/release.yml

@@ -19,6 +19,11 @@ on:
         required: false
         type: boolean
         default: false
+      update-readme-sha:
+        description: "Open a PR to update SHA-pinned action references in README.md"
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   resolve-version:
@@ -131,4 +136,50 @@ jobs:
             fi
             gh release create $RELEASE_FLAGS "$VERSION_TAG"
           fi
-
+
+  update-readme-sha:
+    needs: [resolve-version, release]
+    if: ${{ inputs.update-readme-sha && !inputs.prerelease }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: main
+
+      - name: Update README with release SHA
+        env:
+          VERSION_TAG: v${{ needs.resolve-version.outputs.version }}
+        run: |
+          RELEASE_SHA=$(git rev-parse "HEAD")
+          REPO_NAME="${GITHUB_REPOSITORY}"
+          echo "Release: $VERSION_TAG | SHA: $RELEASE_SHA | Repo: $REPO_NAME"
+
+          # Update SHA-pinned references: owner/repo@<sha> # v<version>
+          ESCAPED_REPO=$(echo "$REPO_NAME" | sed 's/[\/&]/\\&/g')
+          sed -i -E \
+            "s|${ESCAPED_REPO}@[0-9a-f]{12,40}(\s+# v[0-9.]+)?|${REPO_NAME}@${RELEASE_SHA} # ${VERSION_TAG}|g" \
+            README.md
+
+          if git diff --quiet README.md; then
+            echo "No SHA changes needed in README.md"
+            exit 0
+          fi
+
+          git diff README.md
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          token: ${{ github.token }}
+          commit-message: "docs: update README action SHA to v${{ needs.resolve-version.outputs.version }}"
+          title: "docs: update README action SHA to v${{ needs.resolve-version.outputs.version }}"
+          branch: chore/update-readme-sha
+          base: main
+          labels: documentation
+          body: |
+            Automated PR to update the SHA-pinned action reference in README.md to match the latest release **v${{ needs.resolve-version.outputs.version }}**.
+