Remove npm auth handling in favor of docs (#695)

* Add docs for npm auth setup

* Show bash examples

* Improve bash pattern

* Update and reference docs

* Remove setup auth code

* Update

* Update

* Update

.changeset/strict-hotels-laugh.md

@@ -0,0 +1,7 @@
+---
+"@changesets/action": major
+---
+
+Removed `.npmrc` handling when the `NPM_TOKEN` environment variable is set.
+
+Authentication should be handled via Trusted Publishing instead. If a token is still needed, use `actions/setup-node` to set it up instead via the `registry-url` option. Check out the updated action README for more information of setting up npm authentication in GitHub Actions.

README.md

@@ -72,7 +72,7 @@ jobs:
 
 #### With Publishing
 
-Before you can setup this action with publishing, you'll need to have an [npm token](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) that can publish the packages in the repo you're setting up the action for and doesn't have 2FA on publish enabled ([2FA on auth can be enabled](https://docs.npmjs.com/about-two-factor-authentication)). You'll also need to [add it as a secret on your GitHub repo](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables) with the name `NPM_TOKEN`. Once you've done that, you can create a file at `.github/workflows/release.yml` with the following content.
+Check the [npm authentication guide](./docs/set-up-npm-auth.md) to set up publishing to npm. After that, an example workflow with publishing may look like this:
 
 ```yml
 name: Release
@@ -99,6 +99,7 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 26
+          registry-url: https://registry.npmjs.org/ # makes the action set up npm authentication
 
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
@@ -110,31 +111,7 @@ jobs:
           # This expects you to have a script called release which does a build for your packages and calls changeset publish
           publish-script: pnpm release
         env:
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Send a Slack notification if a publish happens
-        if: steps.changesets.outputs.published == 'true'
-        # You can do something when a publish happens.
-        run: my-slack-bot send-notification --message "A new version of ${GITHUB_REPOSITORY} was published!"
-```
-
-By default the GitHub Action creates a `.npmrc` file with the following content:
-
-```txt
-//registry.npmjs.org/:_authToken=${process.env.NPM_TOKEN}
-```
-
-However, if a `.npmrc` file is found, the GitHub Action does not recreate the file. This is useful if you need to configure the `.npmrc` file on your own.
-For example, you can add a step before running the Changesets GitHub Action:
-
-```yml
-- name: Creating .npmrc
-  run: |
-    cat << EOF > "$HOME/.npmrc"
-      //registry.npmjs.org/:_authToken=$NPM_TOKEN
-    EOF
-  env:
-    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
 #### Custom Publishing
@@ -166,6 +143,7 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: 26
+          registry-url: https://registry.npmjs.org/ # makes the action set up npm authentication
 
       - name: Install Dependencies
         run: pnpm install --frozen-lockfile
@@ -178,6 +156,8 @@ jobs:
         if: steps.changesets.outputs.hasChangesets == 'false'
         # You can do something when a publish should happen.
         run: pnpm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
 
 #### With version script

docs/set-up-npm-auth.md

@@ -0,0 +1,199 @@
+# How to set up npm authentication
+
+This is a brief guide on setting up npm authentication in GitHub Actions. Most of the information below are also applicable outside of Changesets and can be referenced for other npm workflows.
+
+## Recommended Setup
+
+It is recommended by npm to use [Trusted Publishing](https://docs.npmjs.com/trusted-publishers), or [Staged Publishing](https://docs.npmjs.com/staged-publishing), or both, to securely publish packages from CI.
+
+Note that Staged Publishing does not work with Changesets at the moment, so it's recommended to use Trusted Publishing instead for now. Check out [its docs](https://docs.npmjs.com/trusted-publishers) for more information to set it up.
+
+Also, in contrary to npm's [workflow recommendation](https://docs.npmjs.com/trusted-publishers#step-2-configure-your-cicd-workflow), make sure the `id-token: write` is only set on the job that needs to publish. As such, consider splitting the build, test, publish flows etc into separate jobs. Here's an example setup with Changesets:
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+permissions: {} # recommended: reset permissions
+
+jobs:
+  select-mode:
+    runs-on: ubuntu-latest
+    outputs:
+      mode: ${{ steps.select-mode.outputs.mode }}
+      publish-plan-artifact-id: ${{ steps.select-mode.outputs.publish-plan-artifact-id }}
+    permissions:
+      contents: read # to check out repo (actions/checkout)
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm install
+      - uses: changesets/action/select-mode@v2
+        id: select-mode
+
+  version:
+    if: needs.select-mode.outputs.mode == 'version'
+    needs: select-mode
+    runs-on: ubuntu-latest
+    outputs:
+      version-dir-artifact-id: ${{ steps.version.outputs.version-dir-artifact-id }}
+    permissions:
+      contents: read # to check out repo (actions/checkout)
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm install
+      - uses: changesets/action/version@v2
+        id: version
+
+  pack:
+    if: needs.select-mode.outputs.mode == 'publish'
+    needs: select-mode
+    runs-on: ubuntu-latest
+    outputs:
+      pack-dir-artifact-id: ${{ steps.pack.outputs.pack-dir-artifact-id }}
+    permissions:
+      contents: read # to check out repo (actions/checkout)
+    steps:
+      - uses: actions/checkout@v7
+      - run: npm install
+      - run: npm build
+      - uses: changesets/action/pack@v2
+        id: pack
+        with:
+          publish-plan-artifact-id: ${{ needs.select-mode.outputs.publish-plan-artifact-id }}
+
+  publish:
+    needs: pack
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # for trusted publishing (changesets/action)
+    steps:
+      - uses: changesets/action/publish@v2
+        with:
+          pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
+```
+
+## Token-based Publishing
+
+> [!CAUTION]
+> Token-based publishing (with [Granular Access Tokens](https://docs.npmjs.com/about-access-tokens#about-granular-access-tokens)) is no longer recommended, with many restrictions that make it difficult to use in CI workflows. For example:
+>
+> - They expire after a maximum of 90 days, which requires periodic manual token rotation.
+> - 2FA-bypass tokens are [being deprecated](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/#2fa-bypass-tokens-will-no-longer-publish-directly) and will soon be not allowed to publish packages with 2FA enabled.
+>
+> However, if you're using a different npm-compatible registry that does not support Trusted Publishing or Staged Publishing, you may still opt for token-based publishing. Check out the [next section](#token-based-publishing) for more information.
+
+You'll need an [npm token](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) with "Bypass two-factor authentication" checked (to prevent npm requesting 2FA in CI). [Add this token as a secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) in your GitHub repo with the name `NPM_TOKEN` so it can be used in the workflow below.
+
+In most cases, you can use [actions/setup-node](https://github.com/actions/setup-node) to set up token-based authentication automatically.
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+permissions: {} # recommended: reset permissions
+
+jobs:
+  # ... other jobs like select-mode and version
+  publish:
+    if: needs.select-mode.outputs.mode == 'publish'
+    needs: select-mode
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # to check out repo (actions/checkout)
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/ # set this option to set up npm authentication
+      - run: npm install
+      - run: npm build
+      - uses: changesets/action/publish@v2
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # pass the token here
+```
+
+> [!TIP]
+> Pass `registry-url: https://npm.pkg.github.com/` and `NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` to publish to the GitHub Package Registry instead of npm.
+
+Internally, `actions/setup-node` will set up a `.npmrc` file that looks like this:
+
+```ini
+//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
+```
+
+This syntax allows to authenticate with the npm registry only when the `NODE_AUTH_TOKEN` environment variable is set, which is the safer approach than storing the token directly in the `.npmrc` file.
+
+### Manual Setup
+
+For advanced use cases, you can also set up the [`~/.npmrc` file](https://docs.npmjs.com/cli/configuring-npm/npmrc) manually. Make sure to remove the `registry-url` option from `actions/setup-node` to prevent conflicts with your custom `.npmrc` file.
+
+For example, if you need to publish different scopes to different registries, you can set up the `~/.npmrc` file like below:
+
+```yaml
+- run: |
+    cat << 'EOF' > ~/.npmrc
+
+    # For unscoped packages, publish to the default npm registry
+    //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
+
+    # For @foo/* packages, publish to a custom registry
+    @foo:registry=https://my-registry.com/
+    //my-registry.com/:_authToken=${NODE_FOO_AUTH_TOKEN}
+
+    # For @bar/* packages, publish to the GitHub Package Registry
+    @bar:registry=https://npm.pkg.github.com/
+    //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+
+    EOF
+```
+
+### Package Managers Edge Cases
+
+#### pnpm
+
+An `.npmrc` file in a project directory with pnpm does not support environment variables due to [security reasons](https://pnpm.io/blog/2026/06/11/env-variables-in-repository-npmrc). As such, it's recommended to set up in the home directory instead. This is also the general recommendation for other package managers to not mix potential existing config setups in projects.
+
+#### yarn
+
+[Yarn](https://yarnpkg.com) does not support the `.npmrc` file, compared to every other package managers that do. To set up authentication for yarn, use a [`~/.yarnrc.yml` file](https://yarnpkg.com/configuration/yarnrc) instead:
+
+```yaml
+- run: |
+    cat << 'EOF' > ~/.yarnrc.yml
+    npmAuthToken: "${NODE_AUTH_TOKEN}"
+    EOF
+```
+
+For advanced use cases, similar to the `.npmrc` example above, the equivalent looks something like this:
+
+```yaml
+- run: |
+    cat << 'EOF' > ~/.yarnrc.yml
+
+    npmAuthToken: "${NODE_AUTH_TOKEN}"
+
+    npmScopes:
+      foo:
+        npmRegistryServer: "https://my-registry.com/"
+        npmAuthToken: "${NODE_FOO_AUTH_TOKEN}"
+      bar:
+        npmRegistryServer: "https://npm.pkg.github.com/"
+        npmAuthToken: "${GITHUB_TOKEN}"
+
+    EOF
+```
+
+#### Miscellaneous
+
+Other package managers may also support (or recommend) configuring the tokens in their own configuration files. Check their documentation for more information.

src/index.ts

@@ -1,10 +1,8 @@
-import fs from "node:fs/promises";
 import * as core from "@actions/core";
 import { GitHub } from "./github.ts";
 import readChangesetState from "./readChangesetState.ts";
 import { runPublish, runVersion } from "./run.ts";
 import {
-  fileExists,
   getOptionalInput,
   getRequiredInput,
   throwOnRenamedInputs,
@@ -84,51 +82,6 @@ import {
         "No changesets found. Attempting to publish any unpublished packages to npm",
       );
 
-      if (process.env.NPM_TOKEN) {
-        const userNpmrcPath = `${process.env.HOME}/.npmrc`;
-
-        if (await fileExists(userNpmrcPath)) {
-          core.info("Found existing user .npmrc file");
-          const userNpmrcContent = await fs.readFile(userNpmrcPath, "utf8");
-          const authLine = userNpmrcContent.split("\n").find((line) => {
-            // check based on https://github.com/npm/cli/blob/8f8f71e4dd5ee66b3b17888faad5a7bf6c657eed/test/lib/adduser.js#L103-L105
-            return /^\s*\/\/registry\.npmjs\.org\/:[_-]authToken=/i.test(line);
-          });
-          if (authLine) {
-            core.info(
-              "Found existing auth token for the npm registry in the user .npmrc file",
-            );
-          } else {
-            core.info(
-              "Didn't find existing auth token for the npm registry in the user .npmrc file, creating one",
-            );
-            await fs.appendFile(
-              userNpmrcPath,
-              `\n//registry.npmjs.org/:_authToken=${process.env.NPM_TOKEN}\n`,
-            );
-          }
-        } else {
-          core.info(
-            "No user .npmrc file found, creating one with NPM_TOKEN used as auth token",
-          );
-          await fs.writeFile(
-            userNpmrcPath,
-            `//registry.npmjs.org/:_authToken=${process.env.NPM_TOKEN}\n`,
-          );
-        }
-      } else if (
-        process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN &&
-        process.env.ACTIONS_ID_TOKEN_REQUEST_URL
-      ) {
-        core.info(
-          "No NPM_TOKEN found, but OIDC is available - using npm trusted publishing",
-        );
-      } else {
-        core.info(
-          "No NPM_TOKEN or OIDC available - assuming npm is already authenticated",
-        );
-      }
-
       const createGithubReleases = core.getBooleanInput(
         "create-github-releases",
       );

src/utils.ts

@@ -119,13 +119,6 @@ export function isErrorWithCode(err: unknown, code: string) {
   );
 }
 
-export function fileExists(filePath: string) {
-  return fs.access(filePath, fs.constants.F_OK).then(
-    () => true,
-    () => false,
-  );
-}
-
 export function getOptionalInput(name: string) {
   // normalize empty string default return value of `core.getInput` to undefined
   return core.getInput(name) || undefined;