fix: decouple npm provenance from OIDC trusted publishing (#1050)

Author: dhayab

packages/shipjs-lib/src/lib/config/defaultConfig.js

@@ -109,6 +109,7 @@ _This pull request is automatically generated by [Ship.js](https://github.com/al
   beforePublish: undefined, // ({ exec, dir }) => {}
   publishCommand: ({ isYarn, tag, defaultCommand, dir }) => defaultCommand,
   useOidcTokenProvider: false,
+  generateProvenance: false,
   afterPublish: undefined, // ({ exec, dir, version, releaseTag }) => {}
   getTagName: ({ version }) => `v${version}`,
   testCommandBeforeRelease: undefined, // ({ isYarn }) => isYarn ? 'yarn test' : 'npm run test',

packages/shipjs/src/helper/getPublishCommand.js

@@ -3,9 +3,9 @@ export default function getPublishCommand({
   publishCommand,
   tag,
   dir,
-  useOidcTokenProvider,
+  generateProvenance,
 }) {
-  const provenance = useOidcTokenProvider ? ' --provenance' : '';
+  const provenance = generateProvenance ? ' --provenance' : '';
   const npmPublish = `npm publish --tag ${tag}${provenance}`;
   const setRegistry = 'npm_config_registry=https://registry.npmjs.org/';
   const defaultCommand = isYarn ? `${setRegistry} ${npmPublish}` : npmPublish;

packages/shipjs/src/step/release/__tests__/runPublish.spec.js

@@ -81,6 +81,34 @@ describe('runPublish', () => {
     expect(run.mock.calls[0][0].command).not.toContain('npm config set');
   });
 
+  it('adds --provenance when generateProvenance is true', () => {
+    runPublish({
+      isYarn: true,
+      config: {
+        publishCommand: ({ defaultCommand }) => defaultCommand,
+        generateProvenance: true,
+      },
+      releaseTag: 'latest',
+      dir: '.',
+      dryRun: false,
+    });
+    expect(run.mock.calls[1][0].command).toContain('--provenance');
+  });
+
+  it('does not add --provenance when only useOidcTokenProvider is true', () => {
+    runPublish({
+      isYarn: true,
+      config: {
+        publishCommand: ({ defaultCommand }) => defaultCommand,
+        useOidcTokenProvider: true,
+      },
+      releaseTag: 'latest',
+      dir: '.',
+      dryRun: false,
+    });
+    expect(run.mock.calls[0][0].command).not.toContain('--provenance');
+  });
+
   it('works with monorepo', () => {
     const output = [];
     mockPrint(print, output);

packages/shipjs/src/step/release/runPublish.js

@@ -7,7 +7,12 @@ import runStep from '../runStep.js';
 
 export default ({ isYarn, config, releaseTag: tag, dir, dryRun }) =>
   runStep({ title: 'Publishing.' }, () => {
-    const { publishCommand, monorepo, useOidcTokenProvider } = config;
+    const {
+      publishCommand,
+      monorepo,
+      useOidcTokenProvider,
+      generateProvenance,
+    } = config;
 
     // This adds the following line to ~/.npmrc
     // > registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}
@@ -29,7 +34,7 @@ export default ({ isYarn, config, releaseTag: tag, dir, dryRun }) =>
           publishCommand,
           tag,
           dir: packageDir,
-          useOidcTokenProvider,
+          generateProvenance,
         });
         if (command) {
           print(`Running the following at ${info(packageDir)}`);
@@ -44,7 +49,7 @@ export default ({ isYarn, config, releaseTag: tag, dir, dryRun }) =>
         publishCommand,
         tag,
         dir,
-        useOidcTokenProvider,
+        generateProvenance,
       });
       run({ command, dir, dryRun });
     }

website/guide/getting-started.md

@@ -164,6 +164,8 @@ permissions:
 
 Note: OIDC trusted publishing requires npm v11.5.1 or later.
 
+To attach a [provenance statement](https://docs.npmjs.com/generating-provenance-statements) to your package, set [`generateProvenance`](/reference/all-config.html#generateprovenance) to `true` (off by default). It requires the same `id-token: write` permission and only works for public repositories. This is independent from `useOidcTokenProvider`: you can generate provenance whether you authenticate with a classic npm token or with OIDC trusted publishing.
+
 ## Setup with 'Nothing'
 
 If you never use any CI environment, you need to use NPM token to release package to NPM:

website/reference/all-config.md

@@ -332,6 +332,37 @@ permissions:
 OIDC trusted publishing requires npm v11.5.1 or later.
 :::
 
+This option only controls authentication. To attach a provenance attestation to your published package, use [`generateProvenance`](#generateprovenance).
+
+## `generateProvenance`
+
+_used at_: `shipjs trigger`
+
+_default:_ `false`
+
+When `true`, Ship.js adds `--provenance` to `npm publish` so npm generates a [provenance statement](https://docs.npmjs.com/generating-provenance-statements) linking the published package to the CI workflow that built it.
+
+```js
+// ship.config.js
+module.exports = {
+  generateProvenance: true,
+};
+```
+
+This is independent from [`useOidcTokenProvider`](#useoidctokenprovider): provenance works whether you authenticate with a classic npm token or with OIDC trusted publishing.
+
+Provenance signing relies on the CI's OIDC token, so your GitHub Actions workflow job needs the `id-token: write` permission:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+```
+
+::: warning Public repositories only
+npm rejects provenance for packages built from private or internal repositories. Enabling this on a private/internal repo will make the publish step fail.
+:::
+
 ## `afterPublish`
 
 _used at_: `shipjs trigger`