diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 81b40cf2..738c76e3 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -21,14 +21,23 @@ jobs:
     name: Build
     runs-on: github-ubuntu-latest-s
     timeout-minutes: 30
+    outputs:
+      BUILD_NUMBER: ${{ steps.build-number.outputs.BUILD_NUMBER }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
-      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
+      - uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
         with:
           version: 2026.10.10
+      - name: Allocate build number
+        id: build-number
+        uses: SonarSource/ci-github-actions/get-build-number@cf2fe6f1f61c0ba87a28f7f907fbad7703747299 # PR #362: PR-head bookkeeping refs
+        with:
+          ref-sha: ${{ github.event.pull_request.head.sha || github.sha }}
       - uses: SonarSource/ci-github-actions/build-gradle@v2
+        env:
+          BUILD_NUMBER: ${{ steps.build-number.outputs.BUILD_NUMBER }}
         with:
           artifactory-reader-role: private-reader
           artifactory-deployer-role: qa-deployer
@@ -55,11 +64,12 @@ jobs:
     name: Promote
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
+      - uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
         with:
           cache_save: false
           version: 2026.10.10
-      - uses: SonarSource/ci-github-actions/get-build-number@v2
       - uses: SonarSource/ci-github-actions/promote@v2
+        env:
+          BUILD_NUMBER: ${{ needs.build.outputs.BUILD_NUMBER }}
         with:
           promote-pull-request: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 25bfa40b..ef6e79eb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,17 +1,21 @@
 name: sonar-release
 
 on:
-  release:
-    types:
-      - published
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Full version including build number, e.g. 1.2.3.456'
+        required: true
+        type: string
 
 jobs:
   release:
     permissions:
       id-token: write
       contents: write
-    uses: SonarSource/gh-action_release/.github/workflows/main.yaml@v6
+    uses: SonarSource/gh-action_release/.github/workflows/main.yaml@v7
     with:
+      version: ${{ inputs.version }}
       publishToBinaries: true
       mavenCentralSync: true
       slackChannel: ops-ci-experience
diff --git a/README.md b/README.md
index 8e640e31..77178cb7 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,20 @@ Also note that the version no longer follows SonarQube Server's versions. The `s
 
 See the [releases](https://github.com/SonarSource/sonar-plugin-api/releases) for changelogs.
 
+## Releasing
+
+After the build and promotion succeed for the commit to release, go to **Actions → sonar-release → Run workflow**.
+Select the branch containing that commit and enter the full version including the build number (for example, `14.1.0.5543`).
+You can also start the workflow from the CLI:
+
+```sh
+gh workflow run release.yml --repo SonarSource/sonar-plugin-api --ref <branch> -f version=<full-version>
+```
+
+The workflow creates or reuses a draft GitHub release, publishes the artifacts and Javadoc, and publishes the release after all publication steps succeed.
+Start releases through this workflow; do not manually publish the GitHub release.
+If a release fails, fix the cause and re-run the failed workflow from GitHub Actions using the same version. The draft remains available for the retry.
+
 
 ## Deprecation Policy