chore: migrate release workflows to npm Trusted Publishers with unified workflow

[Copilot]

Plan: Migrate Release Workflows to npm Trusted Publishers

• Review current release workflows (release.yml and release-beta.yml)
• Update release.yml to remove NPM_TOKEN dependency
  • Remove "Create .npmrc" step that uses secrets.NPM_TOKEN
  • Add inline comments explaining npm Trusted Publishers setup
  • Ensure permissions include id-token: write, contents: read/write
• Update release-beta.yml to remove NPM_TOKEN dependency
  • Remove "Create .npmrc" step that uses secrets.NPM_TOKEN
  • Add inline comments explaining npm Trusted Publishers setup
  • Ensure permissions include id-token: write, contents: write
• Verify both workflows preserve existing behavior (build, test, versioning)
• Validate workflow syntax
• Update PUBLISHING.md documentation to reflect changes
• Request code review (passed with no comments)
• Run security checks (no alerts found)
• Unify workflows into single release.yml with beta boolean parameter
  • Add workflow_dispatch input for beta parameter (default: false)
  • Use conditional steps based on beta input
  • Remove release-beta.yml workflow
  • Update PUBLISHING.md to reflect unified workflow
• Fix prettier linting issues

Summary

Successfully migrated both release workflows to use npm Trusted Publishers and unified them into a single workflow with a boolean parameter. Fixed prettier formatting issues with the workflow file (changed single quotes to double quotes in description field).

Original prompt

Update the existing release workflows in the hypercerts-org/hypercerts-lexicon repository to use npm Trusted Publishers instead of a static NPM token.

Scope and requirements

• Repository: hypercerts-org/hypercerts-lexicon (from user-provided URL https://github.com/hypercerts-org/hypercerts-lexicon)
• Target: the two existing release workflows already in the repo under .github/workflows/ which handle npm publishing / release.
• Goal: migrate these workflows to use npm’s Trusted Publishers as per https://docs.npmjs.com/trusted-publishers.

Implementation details

1. Identify the two existing release workflows in .github/workflows/ which are responsible for publishing new releases to npm (or otherwise doing package release work) and confirm their current behavior.
2. For each of these workflows:
   • Ensure permissions include at minimum:
     • id-token: write (required for npm Trusted Publishers via GitHub OIDC)
     • contents: read
     • packages: write if applicable for npm publish.
   • Remove any dependency on NPM_TOKEN or similar long‑lived secrets for publishing. This includes:
     • Environment variables like NPM_TOKEN or NODE_AUTH_TOKEN coming from secrets.*.
     • Any steps that explicitly echo or configure such secrets in .npmrc.
   • Configure the workflow to be compatible with npm Trusted Publishers:
     • Use actions/setup-node@v4 with registry-url: https://registry.npmjs.org.
     • Use npm publish with --provenance and appropriate --access flag (likely --access public for public packages), preserving any existing tagging or dist-tag behavior.
     • Ensure that the workflow trigger (on: block) matches what npm Trusted Publishers expects (typically workflow_dispatch, release, or push with tag patterns like v*.*.*). Do not change triggers unless necessary; instead, ensure the configuration is valid with npm Trusted Publishers for the actual triggers used in this repo.
3. Preserve existing behavior
   • Keep the current release flow semantics: if the workflows currently build, test, lint, or generate artifacts before publishing, maintain that sequence.
   • Keep the Node.js version(s) already in use unless there is a clear reason to update; if multiple versions are used (e.g. matrix) ensure the publish step only runs once (on a single job).
   • Make sure any versioning / tagging logic (e.g. using git tags, npm version, or release notes) continues to work as before.
4. Documentation and comments
   • Add brief inline comments near the id-token: write permission and any npm publish step explaining that the workflow uses npm Trusted Publishers via GitHub OIDC and no NPM_TOKEN secret is required.
   • If appropriate, add a small note in the workflow file pointing to npm’s Trusted Publishers docs URL used by the user: https://docs.npmjs.com/trusted-publishers.
5. Validation
   • Run or configure the workflow so that it will fail clearly if npm Trusted Publisher is not correctly configured on npmjs.com (e.g. publish step errors will surface). No additional manual checks are needed in the YAML; rely on npm’s behavior.

Deliverables in the PR

• Updated YAML for the two release workflows under .github/workflows/ which currently handle releases, modified to use npm Trusted Publishers.
• No changes to unrelated workflows or repository configuration.
• Clear commit message(s) summarizing the migration (e.g. "chore: use npm trusted publishers for releases").

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Summary by CodeRabbit

• New Features

  • Beta releases are now integrated into the main release workflow with a checkbox option for easier management.

• Documentation

  • Updated publishing documentation to reflect npm Trusted Publisher authentication via GitHub OIDC and consolidated release workflow instructions for stable and beta releases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

The PR consolidates separate beta and stable release workflows into a single configurable workflow by removing the dedicated release-beta.yml and extending release.yml with conditional logic. Additionally, it updates publishing documentation to replace NPM_TOKEN-based authentication with npm Trusted Publisher using GitHub OIDC, and clarifies beta/stable release procedures.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflows .github/workflows/release-beta.yml, .github/workflows/release.yml	Removed standalone release-beta workflow; consolidated beta release logic into release.yml via new beta input parameter with conditional token handling, branch guards, prerelease mode, and versioning/publishing steps
Release Documentation PUBLISHING.md	Replaced NPM_TOKEN secret-based publishing with npm Trusted Publisher (OIDC); added explicit UI guidance for beta prerelease checkbox; updated instructions to reference single Release workflow; clarified RELEASE_PAT requirement for beta releases

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ci: align lexicon npmjs publishing with SDK / changesets #48: Modifies release CI workflows and changesets configuration, directly affecting the same GitHub Actions workflow files and publishing pipeline.
• feat: add npm publishing pipeline with GitHub Actions #42: Updates npm publishing pipeline and release workflow documentation, overlapping with PUBLISHING.md and GitHub Actions modifications.

Poem

🐰✨ One workflow to rule them all, they say,
No more split paths leading every way—
Beta and stable, now side by side,
OIDC tokens guard with trusty pride,
Carrots consolidated, hops renewed! 🥕

Pre-merge checks

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes: migration to npm Trusted Publishers and unification of two release workflows into one.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Lexicon Documentation Sync	✅ Passed	This custom check is not applicable to the pull request. The PR only modifies GitHub Actions workflow configuration files (.github/workflows/) and publishing-process documentation (PUBLISHING.md), neither of which affects JSON lexicon definitions, the main README.md, or ERD.puml.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[aspiers]

@copilot OK but it turns out npmjs only allows trusted publishing for one workflow so we need to unify release.yml and release-beta.yml into one top-level workflow. That means there should be a beta boolean parameter which decides which sub-workflow to use. All existing behaviour should be completely preserved; the only difference should be that there's one entrypoint instead of two.

[Copilot]

@copilot OK but it turns out npmjs only allows trusted publishing for one workflow so we need to unify release.yml and release-beta.yml into one top-level workflow. That means there should be a beta b...

Done. Unified both release workflows into a single release.yml with a beta boolean parameter. The workflow now uses conditional steps (if: inputs.beta or if: ${{ !inputs.beta }}) to execute the appropriate release logic. All existing behavior is preserved - stable releases use changesets/action and create PRs, while beta releases directly publish with version commits. Addressed in commit 4878eba.

[aspiers]

@copilot It failed the linter

[Copilot]

@copilot It failed the linter

Fixed. The linter was failing because prettier expected double quotes instead of single quotes in the workflow description field. Applied prettier formatting and the linter now passes. Addressed in commit ddcb578.

[aspiers]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 98ecd47 and 8db6376.

📒 Files selected for processing (3)

• .github/workflows/release-beta.yml
• .github/workflows/release.yml
• PUBLISHING.md

💤 Files with no reviewable changes (1)

• .github/workflows/release-beta.yml

🧰 Additional context used

📓 Path-based instructions (1)

!(types)/**/*.{js,ts,tsx,json,md}

📄 CodeRabbit inference engine (AGENTS.md)

Run npm run format with Prettier before committing to ensure consistent code formatting

Files:

• .github/workflows/release.yml
• PUBLISHING.md

🧠 Learnings (2)

📓 Common learnings

Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 37
File: lexicons/org/hypercerts/funding/receipt.json:1-71
Timestamp: 2025-12-15T15:33:27.052Z
Learning: For the hypercerts-org/hypercerts-lexicon repository, do not comment on Prettier formatting issues in code reviews because they are already reported by the lint workflow, and duplicating the report adds noise to the review.

📚 Learning: 2025-12-15T16:39:23.964Z

Learnt from: aspiers
Repo: hypercerts-org/hypercerts-lexicon PR: 39
File: README.md:17-17
Timestamp: 2025-12-15T16:39:23.964Z
Learning: In the hypercerts-lexicon repository, standardize on the hyphenless spelling 'onchain' across Markdown documentation (e.g., README.md and other md files) to match the industry standard. Update any occurrences of 'on-chain' to 'onchain' and ensure consistency throughout all documentation.

Applied to files:

• PUBLISHING.md

🔇 Additional comments (13)

PUBLISHING.md (1)

107-108: LGTM!

The RELEASE_PAT requirement for beta releases is correctly documented and matches the workflow implementation.

.github/workflows/release.yml (12)

20-22: LGTM!

The comment clearly explains the id-token: write permission requirement for npm Trusted Publishers and provides a helpful documentation link.

---

25-34: LGTM!

Good defensive check that fails fast with a clear error message if the required RELEASE_PAT secret is missing for beta releases.

---

39-40: LGTM!

The conditional token selection correctly uses RELEASE_PAT for beta releases (to bypass branch protection when pushing) and GITHUB_TOKEN for stable releases (which only create PRs).

---

42-52: LGTM!

The branch check correctly enforces that beta releases must run on the main branch, with a clear explanation of why this check is necessary for manual workflow triggers.

---

58-59: LGTM!

The registry-url configuration is correctly set for npm Trusted Publishers to enable OIDC authentication.

---

64-74: LGTM!

The prerelease mode entry logic is correct and idempotent—it only enters prerelease mode if not already in it. The commit will be pushed later along with version changes, which is efficient.

---

76-82: LGTM!

The version packages step correctly runs only for beta releases and provides the necessary GITHUB_TOKEN for changesets.

---

83-84: LGTM!

Clear explanation that no .npmrc creation is needed because npm Trusted Publishers uses OIDC tokens automatically.

---

86-98: LGTM!

The stable release path correctly uses changesets/action with proper conditionals, provenance settings, and a pinned action version.

---

100-108: LGTM!

The beta publish step correctly uses npm run release (consistent with the stable path) and enables provenance. The comment helpfully explains the validation behavior.

---

109-117: LGTM!

The commit and push logic correctly handles beta version changes, only committing when there are staged changes, and uses the PAT configured in the checkout step to bypass branch protection.

---

119-122: LGTM!

The logging step appropriately runs only for stable releases when packages were actually published, providing useful workflow output.