Handle npm tokens with environment variables (#1211)

Author: ecraig12345

.github/workflows/pr.yml

@@ -21,6 +21,8 @@ permissions: {}
 jobs:
   build:
     strategy:
+      # Sometimes it can be helpful to see if a failure is specific to a particular environment
+      fail-fast: false
       matrix:
         include:
           - os: ubuntu-latest
@@ -72,8 +74,31 @@ jobs:
         if: matrix.os == 'ubuntu-latest' && matrix.node == 14 && matrix.npm == 8
 
       - run: yarn lint:ci
+        if: matrix.os == 'ubuntu-latest' && matrix.node == 14 && matrix.npm == 8
 
       - run: yarn test --verbose
+        id: test
+
+      # See packageManager.ts comments...
+      - name: test publish (Windows bash)
+        if: matrix.os == 'windows-latest'
+        shell: bash
+        run: yarn workspace beachball test packagePublish
+
+      # For a few specific test failures, it can be helpful to see npm debug logs
+      # (usually not relevant, but there's not a good way to distinguish by specific failure)
+      - name: (on test failure) Get npm cache path
+        if: failure() && steps.test.outcome == 'failure'
+        shell: bash
+        run: echo "NPM_CACHE_DIR=$(npm config get cache)" >> "$GITHUB_ENV"
+
+      - name: (on test failure) Upload npm logs as artifact
+        if: failure() && steps.test.outcome == 'failure'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: npm-logs-${{ matrix.os }}-node${{ matrix.node }}-npm${{ matrix.npm }}
+          path: ${{ env.NPM_CACHE_DIR }}/_logs
+          retention-days: 3
 
   # The docs have a separate installation using Node 22 due to needing newer dependencies
   docs:

.vscode/launch.json

@@ -8,9 +8,9 @@
       "type": "node",
       "request": "launch",
       "name": "Debug current open test",
-      "runtimeExecutable": "npm",
-      "cwd": "${workspaceFolder}",
-      "runtimeArgs": ["run-script", "test"],
+      "runtimeExecutable": null,
+      "program": "${workspaceRoot}/scripts/debugTests.js",
+      "cwd": "${fileDirname}",
       "args": ["--", "--runInBand", "--watch", "--testTimeout=1000000", "${file}"],
       "sourceMaps": true,
       "outputCapture": "std",

change/change-7ef9ca8e-5091-4353-8feb-04a6da4310d3.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "type": "minor",
+      "comment": "Add support for providing npm token via NPM_TOKEN environment variable, and internally pass token to npm using an environment variable",
+      "packageName": "beachball",
+      "email": "elcraig@microsoft.com",
+      "dependentChangeType": "patch"
+    }
+  ]
+}

docs/cli/publish.md

@@ -15,7 +15,7 @@ Publishing automates all the bumping and synchronizing of package versions in th
 <!-- prettier-ignore -->
 | Option | Alias | Default | Description |
 | ------ | ----- | ------- | ----------- |
-| `--auth-type` | `-a` | `'authtoken'` | npm auth type: `'authtoken'` or `'password'` |
+| `--auth-type` | `-a` | `'authtoken'` | npm auth type for `NPM_TOKEN` or `--token`: `'authtoken'` or `'password'` |
 | `--git-tags`, `--no-git-tags` | | `true` (`--git-tags`) | whether to create git tags for published package versions |
 | `--keep-change-files` | | | don't delete the change files from disk after bumping |
 | `--message` | `-m` | `'applying package updates'` | custom commit message |
@@ -25,10 +25,23 @@ Publishing automates all the bumping and synchronizing of package versions in th
 | `--registry` | `-r` | `'https://registry.npmjs.org'` | npm registry for publishing |
 | `--retries` | | `3` | number of retries for a package publish before failing |
 | `--tag` | `-t` | `'latest'` | dist-tag for npm publishes |
-| `--token` | `-n` | | credential to use with npm commands (type is specified by `--auth-type`) - locally, use `npm login` instead, or see [alternatives for CI](../concepts/ci-integration) |
+| `--token` | `-n` | | Not recommended; see alternatives below |
 | `--verbose` | | `false` | prints additional information to the console |
 | `--yes` | `-y` | if CI detected, `true` | skips the prompts for publish |
 
+#### Providing a token
+
+There are a few different ways to handle npm authentication for `beachball publish`.
+
+In CI, you should use [trusted publishing](https://docs.npmjs.com/trusted-publishers) if supported to remove the need for tokens. Unfortunately this isn't available in Azure DevOps.
+
+If trusted publishing is unavailable or you're running `beachball` locally, you can do any of the following:
+
+- Set the `NPM_TOKEN` environment variable (`beachball` passes this through to `npm`)
+- Run `npm login` first (or a task which does the same)
+- Manually set the token in [`.npmrc`](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc#auth-related-configuration), possibly referencing an environment variable
+- Old way: use `--token <token>` on the command line (not recommended)
+
 ### Algorithm
 
 The `publish` command is designed to run steps in an order that minimizes the chances of mid-publish failure by doing validation upfront.

docs/concepts/ci-integration.md

@@ -57,6 +57,19 @@ There are a couple of options here:
 
 ## Setting options for publishing
 
+### Providing an npm token
+
+As mentioned above, if possible you should use [trusted publishing](https://docs.npmjs.com/trusted-publishers) to remove the need for tokens.
+
+Other options:
+
+- Set the `NPM_TOKEN` environment variable while running `beachball`
+- Run `npm login` first (or a task which does the same)
+- Manually set the token in [`.npmrc`](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc#auth-related-configuration), possibly referencing an environment variable
+- Old way: use `--token <token>` on the command line (not recommended)
+
+### Other options
+
 If you're passing any custom options besides the npm token to `beachball publish`, it's recommended to set them in either the `beachball` config (if they don't interfere with other commands), or a `package.json` script (if specific to `publish`).
 
 For example, the following script could be used for publishing public scoped packages (`access` is also safe to set in the beachball config):
@@ -152,10 +165,6 @@ This sample assumes the following:
   - `REPO_PAT`: A GitHub fine-grained personal access token with write access ([as described above](#github-token))
   - `NPM_TOKEN`: An npm token with write access to the package(s) and/or scope(s), such as a [fine-grained token for public npm](#npm-token)
 - A repo root `package.json` script `release` which runs `beachball publish`
-- A `.npmrc` file with the following content (change the registry if needed):
-  ```txt
-  //registry.npmjs.org/:_authToken=${NPM_TOKEN}
-  ```
 
 ```yml
 # Add trigger configuration of your choice (this one is manual only)
@@ -184,7 +193,7 @@ steps:
 
   - script: npm run release
     name: Publish
-    # This works because .npmrc references NPM_TOKEN
+    # Beachball will use this environment variable
     env:
       NPM_TOKEN: $(NPM_TOKEN)
 ```

packages/beachball/src/__e2e__/bump.test.ts

@@ -38,6 +38,7 @@ describe('bump command', () => {
     const parsedOptions = getParsedOptions({
       cwd: cwd || repo?.rootPath || '',
       argv: [],
+      env: {},
       testRepoOptions: { branch: defaultRemoteBranchName, fetch: false, ...repoOptions },
     });
     return { options: parsedOptions.options, parsedOptions };

packages/beachball/src/__e2e__/change.test.ts

@@ -84,6 +84,7 @@ describe('change command', () => {
     const parsedOptions = getParsedOptions({
       cwd: repo!.rootPath,
       argv: ['node', 'beachball', 'change', ...(extraArgv ?? [])],
+      env: {},
       testRepoOptions: {
         branch: defaultRemoteBranchName,
         ...repoOptions,

packages/beachball/src/__e2e__/getChangedPackages.test.ts

@@ -31,6 +31,7 @@ describe('getChangedPackages (basic)', () => {
     const parsedOptions = getParsedOptions({
       cwd: reusedRepo.rootPath,
       argv: [],
+      env: {},
       testRepoOptions: {
         fetch: false,
         branch: defaultRemoteBranchName,
@@ -127,6 +128,7 @@ describe('getChangedPackages', () => {
     const parsedOptions = getParsedOptions({
       cwd,
       argv: ['node', 'beachball', 'change', ...extraArgv],
+      env: {},
       testRepoOptions: {
         branch: defaultRemoteBranchName,
         fetch: false,

packages/beachball/src/__e2e__/publishE2E.test.ts

@@ -43,6 +43,7 @@ describe('publish command (e2e)', () => {
     const parsedOptions = getParsedOptions({
       cwd: repo!.rootPath,
       argv: ['node', 'beachball', 'publish', '--yes', ...(extraArgv || [])],
+      env: {},
       testRepoOptions: {
         branch: defaultRemoteBranchName,
         registry: 'fake',

packages/beachball/src/__e2e__/publishGit.test.ts

@@ -28,6 +28,7 @@ describe('publish command (git)', () => {
     const parsedOptions = getParsedOptions({
       cwd,
       argv: ['node', 'beachball', 'publish', '--yes'],
+      env: {},
       testRepoOptions: {
         branch: defaultRemoteBranchName,
         registry: 'http://localhost:99999/',