mirror-helper/changesets-action
1
0
Fork 0
mirror of https://github.com/changesets/action synced 2026-10-26 16:39:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* Add docs for npm auth setup

* Show bash examples

* Improve bash pattern

* Update and reference docs

* Remove setup auth code

* Update

* Update

* Update
This commit is contained in:
Bjorn Lu
2026-07-24 15:24:09 +00:00
committed by GitHub
parent 8a9495e0ee
commit 469993ce57
5 changed files with 212 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/strict-hotels-laugh.md
+7
View File
@@ -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
+6 -26
View File
@@ -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 }}
- 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 }}
NODE_AUTH_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
+199
View File
@@ -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
-47
View File
@@ -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
-7
View File
@@ -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;