npm-oidc-release-demo

Demo of automated npm releases with OIDC authentication and semantic-release.

This repository demonstrates a complete setup for secure, automated npm publishing without static tokens.

What This Demo Shows

Automated Release Pipeline

• Two-step release process - Prepare release PR, review, then publish
• Semantic versioning - Commit messages determine version bumps
• Generated changelogs - Release notes created automatically
• Git tags and GitHub releases - Created for every version

Security-First Publishing

• OIDC authentication - No npm tokens stored in repository secrets
• SLSA provenance - Cryptographic proof of package origin
• Multi-Node testing - Releases blocked if tests fail on Node 20, 22, or 24

Developer Experience

• Conventional commits - Enforced via git hooks (commitlint)
• Automated validation - Commit format checked before push

How It Works

1. Commit with conventional format: feat: add new feature
2. Merge PR to main branch
3. Prepare Release workflow runs automatically:
   • Runs after tests pass
   • semantic-release analyzes commits
   • Determines version bump (major/minor/patch)
   • Updates CHANGELOG.md, package.json, and package-lock.json
   • Creates a release PR (e.g., release/v1.2.3)
4. Review and merge the release PR
5. Release workflow runs automatically:
   • Detects the release commit
   • Publishes to npm with OIDC + provenance
   • Creates GitHub release and git tag

See RELEASE.md for detailed release workflow and commit message guidelines.

Key Configuration Files

• .releaserc/prepare.json - semantic-release config for preparing releases (no npm publish)
• .releaserc/publish.json - semantic-release config for publishing to npm
• .commitlintrc.json - Conventional commit validation rules (Commitlint Docs)
• .husky/commit-msg - Git hook that enforces commit message format (Husky Docs)
• .github/workflows/prepare-release.yml - Creates release PR after tests pass
• .github/workflows/release.yml - Publishes to npm with OIDC (npm provenance)
• .github/workflows/test.yml - Multi-Node test matrix (GitHub Actions Docs)

Development

Prerequisites

• Node.js >= 20
• npm >= 9

Setup

# Clone repository
git clone https://github.com/sw3txn/npm-oidc-release-demo.git
cd npm-oidc-release-demo

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

Security

This package includes SLSA provenance attestation. Verify package authenticity:

npm audit signatures

Demonstration Progress

This repository demonstrates semantic-release through a series of pull requests that show different commit types and their effects on versioning.

Story Arc: Building a Math Library

| Version | PR | Type | Change | Release | |---------|----|----|--------|---------| | 1.0.0 | - | - | Initial release | v1.0.0 | | 1.0.0 | #1 | docs: | Add npm OIDC configuration instructions | No release | | 1.1.0 | #2 | feat: | Add multiply function | v1.1.0 | | 1.1.1 | #3 | fix: | Fix multiply for negative numbers | v1.1.1 | | 1.1.1 | #4 | test: | Add test for negative multiply | No release | | 1.1.1 | #6 | ci: | Fix beta release workflow | No release | | 1.2.0-beta.1 | #5 | feat: | Add subtract (beta) | v1.2.0-beta.1 | | 1.2.0 | #7 | merge | Promote subtract to stable | v1.2.0 | | 1.3.0 | #8 | feat: | Add factorial function | v1.3.0 | | 1.3.0 | #9 | style: | Add braces to factorial conditionals | No release | | 1.3.0 | #10 | refactor: | Convert factorial to iterative | No release | | 1.3.1 | #11 | perf: | Add memoization to factorial | v1.3.1 | | 1.3.2 | #12 | revert: | Remove factorial memoization | v1.3.2 | | 2.0.0 | #13 | feat!: | BREAKING: Rename add() to sum() | v2.0.0 | | 2.0.0 | #14 | chore: | Enable stricter TypeScript checks | No release | | 2.0.0 | #16 | ci(scope): | Pin GitHub Actions to commit SHAs | No release |

Each PR demonstrates a different conventional commit type and shows how semantic-release handles versioning and publishing.

Resources

• npm package
• Release process documentation
• Changelog

License

MIT License - see LICENSE file for details.