Skip to content

Commit 004c6eb

Browse files
SwimburgerSwimburger
committed
Make migration more detailed
1 parent f021b55 commit 004c6eb

File tree

1 file changed

+190
-7
lines changed

1 file changed

+190
-7
lines changed

‎fern/products/sdks/overview/typescript/publishing-to-npm.mdx‎

Lines changed: 190 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -306,7 +306,54 @@ Add your `FERN_TOKEN` as a repository secret (run `fern token` to generate one),
306306

307307
If you're currently using token-based authentication and need to migrate to OIDC, follow these steps:
308308

309+
### Why migrate to OIDC
310+
311+
npm is implementing trusted publishing to eliminate security risks associated with long-lived tokens, which can be:
312+
313+
- Accidentally exposed in logs or configuration files
314+
- Compromised and used persistently until manually revoked
315+
- Difficult to manage and rotate
316+
317+
OIDC-based publishing uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.
318+
319+
### Prerequisites
320+
321+
Before migrating, ensure you have:
322+
323+
- A package published to [npmjs.org](https://npmjs.org)
324+
- A GitHub repository with GitHub Actions configured
325+
- Access to your package settings on [npmjs.com](https://npmjs.com)
326+
- Fern CLI version `0.94.0` or later (for local generation)
327+
328+
### Choose your migration path
329+
330+
Select the approach that fits your situation:
331+
332+
<AccordionGroup>
333+
<Accordion title="Path 1: Upgrade your generator (Recommended)">
334+
335+
This is the easiest path if you can upgrade to version 3.12.0 or later of the TypeScript SDK generator.
336+
337+
**When to use this path:**
338+
- You're able to upgrade to Fern TypeScript SDK generator version 3.12.0 or later
339+
- You haven't `.fernignore`'d your CI workflow file
340+
309341
<Steps>
342+
<Step title="Configure trusted publishing on npmjs.com">
343+
344+
Follow npm's ["Add a trusted publisher on npmjs.com"](https://docs.npmjs.com/trusted-publishers#step-1-add-a-trusted-publisher-on-npmjscom) instructions:
345+
346+
1. Navigate to your package settings on [npmjs.com](https://npmjs.com)
347+
1. Find the "Trusted Publisher" section and click "Add trusted publisher"
348+
1. Select "GitHub Actions" as your provider
349+
1. Configure:
350+
- **Organization or user**: Your GitHub username or organization
351+
- **Repository**: Your TypeScript SDK repository name
352+
- **Workflow filename**: `ci.yml` (the default Fern workflow file)
353+
- **Environment name**: Leave blank (unless you use GitHub environments)
354+
355+
</Step>
356+
310357
<Step title="Update your generators.yml">
311358

312359
Change the `output.token` field from `${NPM_TOKEN}` to `OIDC` and ensure you're using version 3.12.0 or later:
@@ -329,20 +376,20 @@ If you're currently using token-based authentication and need to migrate to OIDC
329376

330377
</Step>
331378

332-
<Step title="Configure trusted publishing">
333-
334-
Follow the [Configure trusted publishing on npmjs.com](#oidc-based-publishing-recommended) instructions in the OIDC section above to add your repository as a trusted publisher.
335-
336-
</Step>
337-
338379
<Step title="Regenerate your SDK">
339380

340-
Regenerate your SDK locally or via GitHub Actions:
381+
Regenerate your SDK with the updated CI configuration. You can do this either:
382+
383+
**Locally:**
341384

342385
```bash
343386
fern generate --group ts-sdk
344387
```
345388

389+
**Or via GitHub Actions:**
390+
391+
If you use the Fern GitHub Action to generate your SDK, simply push your updated `generators.yml` file and let the workflow regenerate the SDK for you.
392+
346393
This will update your `.github/workflows/ci.yml` file with the required OIDC permissions.
347394

348395
</Step>
@@ -354,6 +401,142 @@ If you're currently using token-based authentication and need to migrate to OIDC
354401
</Step>
355402
</Steps>
356403

404+
</Accordion>
405+
406+
<Accordion title="Path 2: Manual CI workflow update">
407+
408+
Use this path if you cannot upgrade the generator or have customized your CI workflow.
409+
410+
**When to use this path:**
411+
- You cannot upgrade due to breaking changes or bugs
412+
- You've customized your CI workflow and added it to `.fernignore`
413+
- Path 1 didn't update your workflow file
414+
415+
<Steps>
416+
<Step title="Configure trusted publishing on npmjs.com">
417+
418+
Follow the same instructions as Path 1 to add your repository as a trusted publisher on npmjs.com.
419+
420+
</Step>
421+
422+
<Step title="Update your CI workflow manually">
423+
424+
Open your `.github/workflows/ci.yml` file and make these changes to the `publish` job:
425+
426+
```yaml title=".github/workflows/ci.yml"
427+
publish:
428+
needs: [ compile, test ]
429+
if: github.event_name == 'push' && contains(github.ref, 'refs/tags/')
430+
runs-on: ubuntu-latest
431+
permissions:
432+
id-token: write # ADD THIS: Required for OIDC
433+
steps:
434+
- name: Checkout repo
435+
uses: actions/checkout@v4
436+
437+
- name: Set up node
438+
uses: actions/setup-node@v4
439+
440+
# ADD THIS: Ensure npm 11.5.1 or later is installed for OIDC support
441+
- name: Update npm
442+
run: npm install -g npm@latest
443+
444+
- name: Install pnpm
445+
uses: pnpm/action-setup@v4
446+
447+
- name: Install dependencies
448+
run: pnpm install
449+
450+
- name: Build
451+
run: pnpm build
452+
453+
# MODIFY THIS: Remove npm config set and env block
454+
- name: Publish to npm
455+
run: |
456+
if [[ ${GITHUB_REF} == *alpha* ]]; then
457+
npm publish --access public --tag alpha
458+
elif [[ ${GITHUB_REF} == *beta* ]]; then
459+
npm publish --access public --tag beta
460+
else
461+
npm publish --access public
462+
fi
463+
# Previously had:
464+
# run: |
465+
# npm config set //registry.npmjs.org/:_authToken ${NPM_TOKEN}
466+
# if [[ ${GITHUB_REF} == *alpha* ]]; then
467+
# npm publish --access public --tag alpha
468+
# elif [[ ${GITHUB_REF} == *beta* ]]; then
469+
# npm publish --access public --tag beta
470+
# else
471+
# npm publish --access public
472+
# fi
473+
# env:
474+
# NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
475+
```
476+
477+
**Key changes:**
478+
- Add `permissions` block with `id-token: write` to the publish job
479+
- Add step to update npm to version 11.5.1 or later
480+
- Remove the `npm config set` line from the publish step
481+
- Remove the `env` block with `NPM_TOKEN` from the publish step
482+
483+
</Step>
484+
485+
<Step title="(Optional) Add ci.yml to .fernignore">
486+
487+
If you haven't already, add your CI workflow to `.fernignore` to prevent future generator updates from overwriting your manual changes:
488+
489+
```text title=".fernignore"
490+
.github/workflows/ci.yml
491+
```
492+
493+
</Step>
494+
495+
<Step title="Remove the NPM_TOKEN secret">
496+
497+
After verifying the migration works, remove the `NPM_TOKEN` secret from your GitHub repository settings.
498+
499+
</Step>
500+
</Steps>
501+
502+
</Accordion>
503+
</AccordionGroup>
504+
505+
### Verify your migration
506+
507+
After completing either migration path:
508+
509+
1. **Trigger a workflow run** by creating a GitHub release with an alpha tag (e.g., `v1.0.0-alpha`)
510+
2. **Check the workflow logs** to verify the publish step succeeds
511+
3. **Verify provenance** by visiting your package on [npmjs.com](https://npmjs.com) - you should see a provenance badge
512+
513+
### Migration troubleshooting
514+
515+
<AccordionGroup>
516+
<Accordion title='"Unable to authenticate" error'>
517+
518+
**Common causes:**
519+
- Workflow filename doesn't match exactly (must be `ci.yml` with the `.yml` extension)
520+
- Missing `id-token: write` permission in workflow
521+
- npm CLI version is older than 11.5.1
522+
- Using self-hosted runners (not currently supported)
523+
524+
**Solution:** Double-check your trusted publisher configuration on npmjs.com matches your actual workflow file name and verify all requirements are met.
525+
526+
</Accordion>
527+
528+
<Accordion title="Workflow still using NPM_TOKEN">
529+
530+
If your workflow continues using the old token-based authentication:
531+
532+
- Verify you've removed the `npm config set` line and the `env: NPM_TOKEN` block from the publish step
533+
- Check that npm CLI version 11.5.1+ is installed (add the update npm step)
534+
- Ensure you're using generator version 3.12.0 or later (if using Path 1)
535+
- When using `--local` generation, you need to use Fern CLI version 0.94.0 or later
536+
537+
</Accordion>
538+
</AccordionGroup>
539+
357540
## Additional resources
358541

359542
- [npm Trusted Publishing Documentation](https://docs.npmjs.com/trusted-publishers)

0 commit comments

Comments
 (0)