MetaMask · mcmire · Oct 24, 2025 · Oct 24, 2025
@@ -9,6 +9,9 @@ jobs:
     name: Determine whether this issue comment was on a pull request from a fork
     if: ${{ github.event.issue.pull_request && startsWith(github.event.comment.body, '@metamaskbot publish-preview') }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
     outputs:
       IS_FORK: ${{ steps.is-fork.outputs.IS_FORK }}
     steps:
@@ -17,23 +20,46 @@ jobs:
         id: is-fork
         run: echo "IS_FORK=$(gh pr view --json isCrossRepository --jq '.isCrossRepository' "${PR_NUMBER}" )" >> "$GITHUB_OUTPUT"
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.issue.number }}
 
-  publish-preview:
-    name: Publish build preview
+  react-to-comment:
+    name: React to the comment
     needs: is-fork-pull-request
-    permissions:
-      pull-requests: write
     # This ensures we don't publish on forks. We can't trust forks with this token.
     if: ${{ needs.is-fork-pull-request.outputs.IS_FORK == 'false' }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: React to the comment
+        run: |
+          gh api \
+            --method POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            "/repos/${REPO}/issues/comments/${COMMENT_ID}/reactions" \
+            -f content='+1'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          REPO: ${{ github.repository }}
+
+  publish-preview:
+    name: Publish build preview
+    needs: react-to-comment
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
       - uses: actions/checkout@v4
       - name: Check out pull request
         run: gh pr checkout "${PR_NUMBER}"
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.issue.number }}
       - name: Checkout and setup environment
         uses: MetaMask/action-checkout-and-setup@v1
@@ -42,17 +68,15 @@ jobs:
       - name: Get commit SHA
         id: commit-sha
         run: echo "COMMIT_SHA=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
-      - run: yarn prepare-preview-builds @metamask-previews ${{ steps.commit-sha.outputs.COMMIT_SHA }}
+      - run: ./scripts/prepare-preview-builds.sh @metamask-previews ${{ steps.commit-sha.outputs.COMMIT_SHA }}
       - run: yarn build
-      - name: Publish preview build
-        run: yarn publish-previews
+      - name: Publish preview builds
+        run: yarn workspaces foreach --all --no-private --parallel --verbose run npm publish --tag preview
         env:
           YARN_NPM_AUTH_TOKEN: ${{ secrets.PUBLISH_PREVIEW_NPM_TOKEN }}
-      - name: Generate preview build message
-        run: yarn tsx scripts/generate-preview-build-message.ts
-      - name: Post build preview in comment
-        run: gh pr comment "${PR_NUMBER}" --body-file preview-build-message.txt
+      - name: Post list of preview build identifiers
+        run: ./scripts/generate-preview-build-message.sh | gh pr comment "${PR_NUMBER}" --body-file -
         env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COMMIT_SHA: ${{ steps.commit-sha.outputs.COMMIT_SHA }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.issue.number }}
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -129,70 +129,44 @@ If you're developing your project locally and want to test changes to a package,
 
 3. Due to the use of Yarn's `file:` protocol, if you update the package in the monorepo, then you'll need to run `yarn install` in the project again.
 
-### Testing changes to packages with preview builds
+## Testing changes against other projects using preview builds
 
-If you want to test changes to a package where it would be unwieldy or impossible to use a local version, such as on CI, you can publish a preview build and configure your project to use it.
+If you are working on a pull request and want to test changes to one or more packages in another project before you publish them, you can create _preview builds_ and then configure your project to use them.
 
-#### Publishing preview builds as a MetaMask contributor
-
-If you're a member of the MetaMask organization, you can create preview builds based on a pull request by following these steps:
-
-1. Post a comment on the pull request with the text `@metamaskbot publish-preview`. This starts the `publish-preview` GitHub action, which will create preview builds for all packages in the monorepo.
-2. After a few minutes, the action should complete and you will see a new comment that lists the newly published packages along with their versions.
-
-   Note two things about each package:
+### Creating preview builds
 
+1. Within your pull request, post a comment with the text `@metamaskbot publish-preview`. This starts the `publish-preview` GitHub action, which will build all of the packages as they exist on the branch and publish them to NPM under a special namespace.
+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`.
 
-Now you can [use these preview builds in your project](#using-preview-builds).
-
-If you make more changes to a package, follow step 2 again, making sure to update the reference to the package in your project's `package.json` to use the newly published preview version.
-
-#### Publishing preview builds as an independent contributor
-
-If you've forked this repository, you can create preview builds based on a branch by following these steps:
-
-1. First, since an NPM scope is used to host preview build releases, you'll need access to one. If you do not, you can either [create a new organization](https://www.npmjs.com/org/create) or [convert your existing username into an organization](https://www.npmjs.com/org/upgrade).
-
-2. Once you've done this, open the `package.json` for each package that you want to publish and change the scope in the name from `@metamask` to `@<NPM_ORG>`, replacing `NPM_ORG` with your NPM organization.
-
-3. Next, run the following command to create and publish the preview builds (again, replacing `NPM_ORG` as appropriate):
-
-   ```
-   yarn prepare-preview-builds "@<NPM_ORG>" "$(git rev-parse --short HEAD)" && yarn build && yarn publish-previews
-   ```
-
-   You should be able to see the published version of each package in the output. Note two things:
-
-   - The name is scoped to the NPM organization you entered 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`.
-
-Now you can [use these preview builds in your project](#using-preview-builds).
-
-If you make more changes to a package, follow step 3 again, making sure to update the reference to the package in your project's `package.json` to use the newly published preview version.
+### Using preview builds
 
-#### Using preview builds
+To use preview builds 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:
 
-To use a preview build for a package 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 dependency entry for the core package for which you want to use a preview build.
+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:
+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/foo-controller@^1.2.3": "npm:@metamask-previews/[email protected]"
+     ```
+   - For Yarn Classic, you will add something like this to `resolutions`:
+     ```
+     "@metamask/foo-controller": "npm:@metamask-previews/[email protected]"
+     ```
+   - For NPM, you will add something like this to `overrides`:
+     ```
+     "@metamask/foo-controller": "npm:@metamask-previews/[email protected]"
+     ```
+4. Run `yarn install`.
 
-   ```
-   "@metamask/<PACKAGE_NAME>@<PRODUCTION_VERSION_RANGE>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
-   ```
+### Updating preview builds
 
-   > **Example:**
-   >
-   > - If your project uses Yarn, `@metamask/controller-utils` is listed in dependencies at `^1.1.4`, and you want to use the preview version `1.2.3-preview-e2df9b4`, add the following to `resolutions`:
-   >
-   >   ```
-   >   "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/[email protected]"
-   >   ```
+If you make more changes to your pull request and want to create a new set of preview builds:
 
-4. Run `yarn install`.
+1. Post another `@metamaskbot` comment on the pull request and wait for the response.
+2. Update the version of the preview builds in your project's `package.json`. Make sure to re-run `yarn install`!
 
 ## Releasing changes
 

diff --git a/package.json b/package.json
@@ -30,8 +30,6 @@
     "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path .gitignore",
     "lint:teams": "tsx scripts/lint-teams-json.ts",
     "prepack": "./scripts/prepack.sh",
-    "prepare-preview-builds": "./scripts/prepare-preview-builds.sh",
-    "publish-previews": "yarn workspaces foreach --all --no-private --parallel --verbose run publish:preview",
     "setup": "yarn install",
     "test": "yarn test:scripts --silent --collectCoverage=false --reporters=jest-silent-reporter && yarn test:packages",
     "test:clean": "yarn workspaces foreach --all --parallel --verbose run test:clean && yarn test",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/account-tree-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/account-tree-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/accounts-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/accounts-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/address-book-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/address-book-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/announcement-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/announcement-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/app-metadata-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/app-metadata-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/approval-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/approval-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/assets-controllers",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/assets-controllers",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -50,7 +50,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/base-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/base-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/bridge-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/bridge-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/bridge-status-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/bridge-status-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/build-utils",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/build-utils",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/chain-agnostic-permission",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/chain-agnostic-permission",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/composable-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/composable-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/controller-utils",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/controller-utils",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -40,7 +40,6 @@
     "changelog:update": "../../scripts/update-changelog.sh @metamask/core-backend",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/core-backend",
     "since-latest-release": "../../scripts/since-latest-release.sh",
-    "publish:preview": "yarn npm publish --tag preview",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/delegation-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/delegation-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",

@@ -39,7 +39,6 @@
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/earn-controller",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/earn-controller",
-    "publish:preview": "yarn npm publish --tag preview",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",