Skip to content

RELEASING.md

Latest commit

 

History

History
82 lines (58 loc) · 4.09 KB

RELEASING.md

File metadata and controls

82 lines (58 loc) · 4.09 KB

Releasing chartmogul-node

Prerequisites

  • You must have push access to the repository
  • git, gh, jq, node, and npm must be installed
  • Tags matching v* are protected by GitHub tag protection rulesets
  • Releases are immutable once published (GitHub repository setting)
  • npm trusted publishing must be configured for the package (see Repository Settings)

Release Process

Run the release script from the repository root:

bin/release.sh <patch|minor|major>

The script will:

  1. Verify prerequisites and that CI is green on main
  2. Show any open PRs targeting main and ask for confirmation
  3. Bump the version in package.json and package-lock.json
  4. Create a release branch, commit, push, and open a PR
  5. Wait for the PR to be merged (poll every 10s)
  6. Tag the merge commit and push the tag
  7. Wait for the release workflow to complete, which will:
    • Run the full test suite across Node.js 18, 20, 22, and latest
    • Verify that package.json version matches the tag
    • Create a GitHub Release with auto-generated release notes
    • Publish to npm via OIDC trusted publishing with provenance
  8. Print links to the GitHub Release and npm package

Changelog

Release notes are auto-generated from merged PR titles by the release workflow. To ensure useful changelogs:

  • Use clear, descriptive PR titles (e.g., "Add External ID field to Contact model")
  • Prefix breaking changes with BREAKING: so they stand out in release notes
  • After the release is created, review and edit the notes on the Releases page if needed

Pre-release Versions

For pre-release versions, use a semver pre-release suffix:

git tag vX.Y.Z-rc1
git push origin vX.Y.Z-rc1

These will be automatically marked as pre-releases on GitHub and published to npm under the next dist-tag (not latest).

Security

Repository Protections

  • Immutable releases: Once a GitHub Release is published, its tag cannot be moved or deleted, and release assets cannot be modified
  • Tag protection rulesets: v* tags cannot be deleted or force-pushed

npm Registry

  • Publishing uses OIDC trusted publishing — no long-lived npm tokens are stored in the repository. GitHub Actions authenticates directly with npm via short-lived OIDC tokens.
  • Once a package version is published to npm, it cannot be republished with different contents
  • npm records integrity hashes (SHA-512) in package-lock.json for all installed packages, ensuring reproducible and tamper-evident installs
  • Packages are published with provenance, linking each version to the specific GitHub Actions run that built it

What This Protects Against

  • A compromised maintainer account cannot modify or delete existing releases
  • No long-lived npm tokens exist that could be leaked or stolen
  • Tags cannot be moved to point to different commits after publication
  • The npm registry provides an independent immutability layer beyond GitHub
  • npm provenance allows anyone to verify a package was built from this repository by GitHub Actions

Repository Settings (Admin)

These settings must be configured by a repository admin:

  1. Immutable Releases: Settings > General > Releases > Enable "Immutable releases"
  2. Tag Protection Ruleset: Settings > Rules > Rulesets > New ruleset targeting tags matching v* with deletion, force-push, and update prevention
  3. GitHub Actions Environment: Settings > Environments > New environment named npm
  4. npm Trusted Publishing: On npmjs.com, go to chartmogul-node access settings and configure a trusted publisher with: repository chartmogul/chartmogul-node, workflow release.yml, environment npm