From 98f36b3e5d3445c206f6f615ca53955139d60604 Mon Sep 17 00:00:00 2001
From: Haseeb Ahmad <haseeb.ahmad@mapbox.com>
Date: Wed, 24 Jun 2026 11:56:37 +0200
Subject: [PATCH] CLOUDPLAT-3162: add npm OIDC publish workflow

https://mapbox.atlassian.net/browse/CLOUDPLAT-3162
---
 .github/workflows/npm-release.yml | 15 +++++++++++++++
 CONTRIBUTING.md                   | 16 ++++++++++++++++
 package.json                      |  7 +++++--
 3 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/npm-release.yml

diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml
new file mode 100644
index 00000000000..ba2ea448e16
--- /dev/null
+++ b/.github/workflows/npm-release.yml
@@ -0,0 +1,15 @@
+name: NPM release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  npm-release:
+    uses: mapbox/gha-public/.github/workflows/workflow-npm-oidc-publish.yml@main
+    permissions:
+      id-token: write
+      contents: write
+    with:
+      create-github-release: true
+      environment: npm-release
+      run-tests: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3b4c7c5c361..34973b4321e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -213,3 +213,19 @@ Our labeling system is
 - [Drawing Text with Signed Distance Fields in Mapbox GL](https://blog.mapbox.com/drawing-text-with-signed-distance-fields-in-mapbox-gl-b0933af6f817)
 - [Map Label Placement in Mapbox GL](https://blog.mapbox.com/map-label-placement-in-mapbox-gl-c6f843a7caaa)
 - [Signed Distance Fields](http://bytewrangler.blogspot.com/2011/10/signed-distance-fields.html)
+
+## Releasing a new version
+
+Releases are published to npm via GitHub Actions.
+
+### Steps
+
+1. **Bump the version** in `package.json` (follow [semver](https://semver.org))
+2. **Update `CHANGELOG.md`** with a summary of what changed
+3. **Open a PR**, get it reviewed and merged to `main`
+4. **Trigger the release** from the [Actions tab](../../actions/workflows/npm-release.yml):
+   - Select **NPM release** → **Run workflow** → run from `main`
+
+The workflow will publish to npm and create a GitHub release with auto-generated notes.
+
+> **Note:** Only Mapbox maintainers with write access to this repository can trigger the release workflow. External contributors can open and contribute to PRs, but releases are always cut by the owning team.
diff --git a/package.json b/package.json
index 4cacdd0dadb..8f4bef56bc3 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "mapbox-gl",
   "description": "A WebGL interactive maps library",
-  "version": "3.25.0",
+  "version": "3.25.1",
   "main": "dist/mapbox-gl.js",
   "style": "dist/mapbox-gl.css",
   "types": "dist/mapbox-gl.d.ts",
@@ -234,5 +234,8 @@
       "name": "UMD bundle (gzip)",
       "path": "dist/mapbox-gl.js"
     }
-  ]
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }