From a8ac8e97a088e3efd0a098d559e479bf3806b8ed Mon Sep 17 00:00:00 2001
From: Salah-Eddine Saakoun <salah-eddine.saakoun@consensys.net>
Date: Mon, 7 Sep 2026 12:42:02 +0200
Subject: [PATCH] ci: add preview build publishing

Wires up the reusable publish-preview workflow from github-tools so a
`@metamaskbot publish-preview` comment on a PR publishes a preview build
to the `@metamask-previews` scope. Adds a README section covering how to
create and consume one.
---
 .github/workflows/publish-preview.yml | 19 +++++++++++++
 README.md                             | 39 +++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 .github/workflows/publish-preview.yml

diff --git a/.github/workflows/publish-preview.yml b/.github/workflows/publish-preview.yml
new file mode 100644
index 00000000..ad79c1a8
--- /dev/null
+++ b/.github/workflows/publish-preview.yml
@@ -0,0 +1,19 @@
+name: Publish a preview build
+
+on:
+  issue_comment:
+    types: created
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  publish-preview:
+    if: ${{ github.event.issue.pull_request && startsWith(github.event.comment.body, '@metamaskbot publish-preview') }}
+    uses: MetaMask/github-tools/.github/workflows/publish-preview.yml@v1
+    with:
+      docs-url: 'https://github.com/MetaMask/utils/blob/main/README.md#testing-changes-in-other-projects-using-preview-builds'
+      is-monorepo: false
+    secrets:
+      PUBLISH_PREVIEW_NPM_TOKEN: ${{ secrets.PUBLISH_PREVIEW_NPM_TOKEN }}
diff --git a/README.md b/README.md
index f1c7088e..1a83b6cf 100644
--- a/README.md
+++ b/README.md
@@ -65,3 +65,42 @@ The project follows the same release process as the other libraries in the MetaM
    - Be very careful to use a clean local environment to publish the release, and follow exactly the same steps used during CI.
    - Use `npm publish --dry-run` to examine the release contents to ensure the correct files are included. Compare to previous releases if necessary (e.g. using `https://unpkg.com/browse/[package name]@[package version]/`).
    - Once you are confident the release contents are correct, publish the release using `npm publish`.
+
+### Testing changes in other projects using preview builds
+
+If you are working on a pull request and want to test changes in another project before you publish them, you can create a _preview build_ and then configure your project to use it.
+
+#### Creating a preview build
+
+1. Within your pull request, post a comment with the text `@metamaskbot publish-preview`. This starts the `publish-preview` GitHub action, which will create a preview build and publish it to NPM.
+2. After a few minutes, the action should complete and you will see a new comment. Note two things:
+   - The name is scoped to `@metamask-previews` instead of `@metamask`.
+   - The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-preview-e2df9b4` instead of `1.2.3`.
+
+#### Using a preview build
+
+To use a preview build within a project, you need to override the resolution logic for your package manager so that the "production" version of that package is replaced with the preview version. Here's how you do that:
+
+1. Open `package.json` in the project and locate the entry for this package in `dependencies`.
+2. Locate the section responsible for resolution overrides (or create it if it doesn't exist). If you're using Yarn, this is `resolutions`; if you're using NPM or any other package manager, this is `overrides`.
+3. Add a line to this section that mirrors the dependency entry on the left-hand side and points to the preview version on the right-hand side. Note the exact format of the left-hand side will differ based on which version of Yarn or NPM you are using. For example:
+   - For Yarn Modern, you will add something like this to `resolutions`:
+     ```
+     "@metamask/utils@^1.2.3": "npm:@metamask-previews/utils@1.2.3-preview-abcdefg"
+     ```
+   - For Yarn Classic, you will add something like this to `resolutions`:
+     ```
+     "@metamask/utils": "npm:@metamask-previews/utils@1.2.3-preview-abcdefg"
+     ```
+   - For NPM, you will add something like this to `overrides`:
+     ```
+     "@metamask/utils": "npm:@metamask-previews/utils@1.2.3-preview-abcdefg"
+     ```
+4. Run `yarn install`.
+
+#### Updating a preview build
+
+If you make more changes to your pull request and want to create a new preview build:
+
+1. Post another `@metamaskbot` comment on the pull request and wait for the response.
+2. Update the version of the preview build in your project's `package.json`. Make sure to re-run `yarn install`!