Release Workflows Made Easy With Changesets

Jan 25, 2026 · 4 min read

Release Workflows Made Easy With Changesets

Publishing npm packages shouldn’t require custom scripts, manual version bumps, or remembering which packages changed since your last release. Yet many teams still cobble together fragile release processes that break at the worst times.

Changesets solves this by capturing release intent at contribution time, then automating the rest. This article covers how to build a modern Changesets release workflow—including npm trusted publishing, monorepo versioning with Changesets, and GitHub Actions package releases—without the maintenance burden.

Key Takeaways

Changesets captures release intent at contribution time through markdown files that specify affected packages and semver bump types
npm trusted publishing with OIDC tokens eliminates long-lived credentials and adds cryptographic provenance to your packages
Monorepo versioning becomes manageable with configuration options like linked, fixed, and updateInternalDependencies
Common CI pitfalls include permission issues, PR automation conflicts, and forgotten changesets

The Core Changesets Release Workflow

The workflow follows three phases:

Contributors add changeset files describing what changed and how significant it is (patch, minor, major)
CI creates a versioning PR that aggregates all changesets into version bumps and changelog entries
Merging the PR triggers publishing to npm with proper provenance

Each changeset is a markdown file in .changeset/ containing frontmatter that specifies affected packages and semver bump type, plus a human-readable summary. When multiple changesets exist, Changesets calculates the highest necessary version bump per package—two minor changes don’t become two minor bumps.

For monorepos, this matters significantly. Changesets automatically handles internal dependency updates when one workspace package depends on another that’s being released.

GitHub Actions Package Releases: The Modern Approach

Most tutorials show workflows using NPM_TOKEN secrets. That approach works but carries security risks—long-lived tokens can leak and require manual rotation.

npm trusted publishing using OIDC tokens is now the preferred method. Instead of storing credentials, your GitHub Actions workflow requests a short-lived token directly from npm during the publish step. The token exists only for that job and can’t be extracted or reused.

To enable this:

Link your npm package to your GitHub repository in npm’s package settings
Configure your workflow with id-token: write permission
Ensure provenance is enabled (npm can generate it automatically for trusted publishers, or via the --provenance flag on newer CLIs)

npm provenance adds cryptographic attestation proving the package was built from a specific commit in your repository. Users can verify exactly what source code produced the published artifact.

Current limitations to know: npm trusted publishing requires public repositories. Private repos still need the legacy NPM_TOKEN approach. Additionally, the official changesets/action has evolving support for OIDC—check current documentation for the latest integration patterns.

Monorepo Versioning With Changesets

Changesets was designed for monorepos from the start. Key configuration options in .changeset/config.json control multi-package behavior:

linked: Groups packages that should always share the same version number
fixed: Similar to linked, but all packages bump together even if only one changed
updateInternalDependencies: Controls whether dependents get patch bumps when their dependencies update

When a contributor runs the changeset CLI in a monorepo, they select which packages their change affects. The versioning PR then shows exactly which packages will release and at what versions.

Common CI Pitfalls

Permission issues cause most workflow failures. The GitHub token needs write access for creating PRs and pushing tags. For npm publishing, ensure your token (or OIDC configuration) has publish rights to all packages in your scope.

PR automation conflicts happen when branch protection rules block the bot from pushing version commits. Either allow the GitHub Actions bot to bypass protection or use a dedicated bot account with appropriate permissions.

Multi-package publishing order matters when packages depend on each other. Changesets handles this automatically, but network failures mid-publish can leave your monorepo in an inconsistent state. The changesets/action includes retry logic, but understanding this failure mode helps with recovery.

Forgotten changesets are the most common contributor mistake. The Changeset bot comments on PRs missing changesets, but you can also add CI checks that fail when changesets are required but absent.

Structuring Your Workflow Today

Most teams run the Changesets action on every push to main. The action either opens or updates a “Version Packages” PR when unreleased changesets exist, or publishes packages when the version PR merges.

This creates a natural release cadence: merge features throughout the week, then merge the version PR when you’re ready to ship. No manual version editing, no forgetting to update changelogs, no publishing the wrong packages.

Conclusion

A well-configured Changesets release workflow removes the cognitive overhead of package releases. Contributors declare intent upfront, CI handles the coordination, and npm trusted publishing ensures secure, verifiable artifacts.

Start with a single-package setup to understand the flow, then extend to monorepos as needed. The initial configuration investment pays off quickly in reduced release anxiety and fewer “oops, wrong version” moments.

FAQs

Changesets works well with both single packages and monorepos. For single packages, the workflow is simpler since you only track one package. Start with a single-package setup to learn the basics, then scale to monorepos when needed. The core workflow of adding changesets, creating version PRs, and publishing remains the same regardless of package count.

The Changeset bot automatically comments on pull requests that are missing changeset files. You can also configure CI checks to fail when changesets are required but absent. This prevents changes from merging without proper release documentation, though you can mark some PRs as not requiring changesets for documentation-only updates.

When you mark a package with a major version bump, Changesets checks which other packages depend on it. The updateInternalDependencies config option controls whether dependents automatically receive patch bumps. For tightly coupled packages, use the linked or fixed options to ensure version numbers stay synchronized across related packages.

No, npm trusted publishing with OIDC tokens currently requires public repositories. For private repos, you must use the traditional NPM_TOKEN approach with a long-lived access token stored as a repository secret. Keep these tokens secure and rotate them periodically to minimize security risks.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.