Use NPM_TOKEN after failed retry of publish

[prisis]

Clear and concise description of the problem

This blocks some release cases...

npm/cli#8547

Suggested solution

To have a workaround for it, lets use the env token when available, after the retry of failed oicd, so new packages without oicd can be released

Alternative

No response

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• ERROR  Failed to replace env in config: ${version}\n #152
• Feature Request: Support for Root-Level File Changes to Trigger Package Releases #243
• Duplicate publish with @semantic-release/npm #203

👤 Suggested Assignees

• tiagoporto
• fulgas
• lbennett-stacki

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[coderabbitai]

Coding Plan

Approach

Ticket Overview

Implement retry logic to fall back to NPM_TOKEN authentication when publish operations fail with OIDC, addressing limitations where OIDC Trusted Publishers don't support certain npm commands, particularly for new packages without OIDC configuration and dist-tag operations.

Observations

Codebase Summary

The semantic-release-pnpm package is a semantic-release plugin that handles npm package publishing using pnpm. It implements a verification-then-publish workflow with four main lifecycle functions: verifyConditions, prepare, publish, and addChannel. OIDC authentication is currently limited to the publish operation, with other npm commands requiring traditional authentication methods. The current authentication flow checks OIDC availability during verification and gracefully falls back to NPM_TOKEN if OIDC fails, writing credentials to .npmrc for use during publish operations.

Assumptions

Assumption 1: When to trigger fallback retry

Options Considered:

• Retry on all publish failures if OIDC was used
• Retry only on specific error codes or messages that indicate OIDC limitations
• Add configuration option to control retry behavior

Chosen Option: Retry on all publish failures when OIDC was used and NPM_TOKEN is available in the environment.

Rationale: This provides the broadest coverage for OIDC limitations while remaining simple to implement. The approach gracefully handles both packages that can't publish their initial version using OIDC and dist-tag operations that aren't supported by OIDC. Since we only retry once, the performance impact of unnecessary retries is minimal.

Assumption 2: Tracking authentication method across lifecycle phases

Options Considered:

• Store authentication method in semantic-release context object
• Use module-level variable shared across function calls
• Re-detect OIDC availability at publish time

Chosen Option: Use a module-level variable to track which authentication method was successfully configured during verification.

Rationale: This aligns with the existing caching pattern in verify-auth.ts, avoids modifying semantic-release's context structure, and provides simple access across function boundaries. The variable will be set during verification and read during publish/addChannel operations.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Track Authentication Method During Verification

Enhance the verification phase to record which authentication strategy (OIDC or token-based) was successfully configured, making this information available for retry logic during publish operations.

Task 1: Add Authentication State Tracking

Introduce state management to track the authentication method used during verification.

• Add a module-level variable in src/verify/verify-auth.ts to store the authentication method (e.g., 'oidc' | 'token' | null)
• Set this variable to 'oidc' when OIDC token exchange succeeds and credentials are written to .npmrc
• Set this variable to 'token' when falling back to setNpmrcAuth() with NPM_TOKEN or other traditional methods
• Export a getter function (e.g., getAuthMethod()) to allow other modules to query which authentication was used
• Reset the variable at the start of verifyAuth() to ensure clean state for each verification run

Task 2: Export Helper Function for Fallback Detection

Create utility to determine if NPM_TOKEN fallback should be attempted.

• Export a function from src/verify/verify-auth.ts (e.g., shouldRetryWithNpmToken()) that returns true if OIDC was used and NPM_TOKEN is available in environment
• This function checks both the stored authentication method and the presence of process.env.NPM_TOKEN
• Encapsulates the fallback eligibility logic in a single location for reuse in publish and addChannel operations

🤖 Prompt for AI agents

Track which authentication method (OIDC or token-based) was used during
verification so publish operations can determine if fallback retry is needed.

In `src/verify/verify-auth.ts`:
- Add module-level variable to store authentication method ('oidc' | 'token' |
null)
- Reset variable at start of verifyAuth()
- Set to 'oidc' when OIDC token exchange succeeds
- Set to 'token' when falling back to setNpmrcAuth() with NPM_TOKEN
- Export getAuthMethod() getter function
- Export shouldRetryWithNpmToken() function that returns true if OIDC was used
and NPM_TOKEN exists in environment

Phase 2: Implement Publish Retry with NPM_TOKEN Fallback

Add retry logic to the publish operation that reconfigures authentication and retries when OIDC publish fails.

Task 1: Create Authentication Reconfiguration Helper

Build a reusable function for switching from OIDC to NPM_TOKEN authentication.

• Create new function in src/utils/set-npmrc-auth.ts (e.g., reconfigureWithNpmToken()) that forces NPM_TOKEN authentication regardless of current .npmrc state
• Function should accept registry and npmrc path parameters
• Clear any existing OIDC-based auth tokens from .npmrc and write NPM_TOKEN configuration
• Use existing nerfDart() utility and npmrc writing patterns from setNpmrcAuth()
• Handle errors gracefully if NPM_TOKEN is not available or .npmrc writing fails

Task 2: Add Retry Logic to Publish Function

Wrap the publish operation with error handling and retry capability using NPM_TOKEN.

• Modify src/publish.ts to wrap the execa("pnpm", ...) call in try-catch
• On publish failure, check if retry should be attempted using shouldRetryWithNpmToken()
• If eligible for retry: log informative message about retrying with NPM_TOKEN, call reconfigureWithNpmToken() to update .npmrc, and re-execute the pnpm publish command
• On second failure or if not eligible for retry, throw the original error wrapped in AggregateError as currently done
• Ensure logger messages clearly distinguish between initial publish failure and retry attempts

🤖 Prompt for AI agents

Add retry logic to publish operations that falls back to NPM_TOKEN
authentication when OIDC publish fails.

In `src/utils/set-npmrc-auth.ts`:
- Create reconfigureWithNpmToken() function accepting registry and npmrc path
- Clear existing OIDC auth tokens from .npmrc
- Write NPM_TOKEN configuration using nerfDart() utility
- Handle errors if NPM_TOKEN unavailable or .npmrc write fails

In `src/publish.ts`:
- Wrap pnpm publish command in try-catch
- On failure, check shouldRetryWithNpmToken()
- If eligible: log retry message, call reconfigureWithNpmToken(), retry pnpm
publish
- On second failure or ineligible, throw error wrapped in AggregateError
- Add clear logger messages distinguishing initial failure from retry

Phase 3: Implement AddChannel Retry with NPM_TOKEN Fallback

Apply the same retry pattern to dist-tag operations which are not supported by OIDC Trusted Publishers.

Task 1: Add Error Handling and Retry to AddChannel

Enhance addChannel function with try-catch and NPM_TOKEN fallback.

• Modify src/add-channel.ts to wrap the execa("pnpm", ["dist-tag", "add", ...]) call in try-catch
• On failure, check if retry should be attempted using shouldRetryWithNpmToken() from verify-auth module
• If eligible: log retry message, call reconfigureWithNpmToken() to switch authentication, and retry the dist-tag command
• On second failure or if not eligible, re-throw the error for semantic-release to handle
• Ensure npmrc path is passed through environment variables on retry attempt via NPM_CONFIG_USERCONFIG

Task 2: Add Debug Logging for Troubleshooting

Enhance observability for authentication fallback scenarios.

• Add debug log messages in both publish.ts and add-channel.ts when fallback is triggered
• Log which authentication method was initially used (retrieved via getAuthMethod())
• Log when NPM_TOKEN fallback is attempted and whether it succeeds or fails
• Include relevant error messages from failed operations to aid in diagnosing OIDC limitations
• Use existing logger and context.logger patterns consistent with the codebase

🤖 Prompt for AI agents

Apply retry logic to dist-tag operations with NPM_TOKEN fallback and add debug
logging for authentication troubleshooting.

In `src/add-channel.ts`:
- Wrap pnpm dist-tag command in try-catch
- On failure, check shouldRetryWithNpmToken()
- If eligible: log retry message, call reconfigureWithNpmToken(), retry dist-tag
command
- Pass npmrc path via NPM_CONFIG_USERCONFIG on retry
- On second failure or ineligible, re-throw error

In both `publish.ts` and `add-channel.ts`:
- Add debug logs when fallback is triggered
- Log initial authentication method using getAuthMethod()
- Log NPM_TOKEN fallback attempt status (success/failure)
- Include error messages from failed operations
- Follow existing logger patterns

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Track which authentication method (OIDC or token-based) was used during
verification so publish operations can determine if fallback retry is needed.

In `src/verify/verify-auth.ts`:
- Add module-level variable to store authentication method ('oidc' | 'token' |
null)
- Reset variable at start of verifyAuth()
- Set to 'oidc' when OIDC token exchange succeeds
- Set to 'token' when falling back to setNpmrcAuth() with NPM_TOKEN
- Export getAuthMethod() getter function
- Export shouldRetryWithNpmToken() function that returns true if OIDC was used
and NPM_TOKEN exists in environment
===============================================================================

Task: 2

Add retry logic to publish operations that falls back to NPM_TOKEN
authentication when OIDC publish fails.

In `src/utils/set-npmrc-auth.ts`:
- Create reconfigureWithNpmToken() function accepting registry and npmrc path
- Clear existing OIDC auth tokens from .npmrc
- Write NPM_TOKEN configuration using nerfDart() utility
- Handle errors if NPM_TOKEN unavailable or .npmrc write fails

In `src/publish.ts`:
- Wrap pnpm publish command in try-catch
- On failure, check shouldRetryWithNpmToken()
- If eligible: log retry message, call reconfigureWithNpmToken(), retry pnpm
publish
- On second failure or ineligible, throw error wrapped in AggregateError
- Add clear logger messages distinguishing initial failure from retry
===============================================================================

Task: 3

Apply retry logic to dist-tag operations with NPM_TOKEN fallback and add debug
logging for authentication troubleshooting.

In `src/add-channel.ts`:
- Wrap pnpm dist-tag command in try-catch
- On failure, check shouldRetryWithNpmToken()
- If eligible: log retry message, call reconfigureWithNpmToken(), retry dist-tag
command
- Pass npmrc path via NPM_CONFIG_USERCONFIG on retry
- On second failure or ineligible, re-throw error

In both `publish.ts` and `add-channel.ts`:
- Add debug logs when fallback is triggered
- Log initial authentication method using getAuthMethod()
- Log NPM_TOKEN fallback attempt status (success/failure)
- Include error messages from failed operations
- Follow existing logger patterns

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!

[github-actions]

This issue has been automatically marked as stale because it has been open for 21 days with no activity. It will be closed in 7 days if no further activity (Remove label or comment) occurs.
If we missed this issue please reply to keep it active.
Thanks for being a part of this project. 🙏

[github-actions]

This issue has been automatically marked as stale because it has been open for 21 days with no activity. It will be closed in 7 days if no further activity (Remove label or comment) occurs.
If we missed this issue please reply to keep it active.
Thanks for being a part of this project. 🙏

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.