10. CI/CD and release
Continuous integration
.github/workflows/ci.yml runs on every push and pull request across Ubuntu and Windows with Node 20, 22 and 24, and macOS with Node 24 (7 jobs; macOS runs Node 24 only). Each job runs:
npm testnpm run demonpm run doctorcontextsutra audit --out artifacts/auditnode scripts/build-docs.mjs --check, which fails when the committed HTML documentation is out of date.
On Node 24 the audit and demo artifacts are uploaded. Permissions are read-only. Actions are pinned by major version.
Release checklist
- Update
CHANGELOG.mdand the version inpackage.jsonandCITATION.cff. npm test,npm run audit,npm run evidence,npm run docs.- Commit, push, and wait for all CI jobs to pass. Do not tag on red.
- Tag
vX.Y.Zand create a GitHub release with the audit report attached. npm pack --dry-runand check the file list contains no secrets or test artifacts.npm publish --access public(requires the maintainer's npm login and 2FA).- Verify with
npx contextsutra@X.Y.Z versionfrom an empty directory.
Versioning
Semantic Versioning. The capsule schema is versioned separately (contextsutra.capsule.v1); a breaking schema change needs a new schema string and a migration note.
Provenance
Releases are not yet signed. Planned: npm provenance from GitHub Actions and Sigstore signatures.
Automatic npm publish
.github/workflows/release.yml runs on every push to main. If the version in package.json is not on npm yet, it runs the tests, the audit and the docs check, confirms CHANGELOG.md has a section for that version, publishes with npm provenance, and creates a GitHub release with the audit reports attached. If the version is already published it does nothing.
One-time setup (trusted publishing, no token):
- On npmjs.com open the package settings, then Trusted Publisher, choose GitHub Actions, and enter user
shahvatsalofficial, repositorycontextsutra, workflow filenamerelease.yml, empty environment, and tick Allow npm publish. - To release: bump
versioninpackage.jsonandCITATION.cff, add a## X.Y.Zsection toCHANGELOG.md, runnpm run docs, commit, push tomain.
npm exchanges a short-lived GitHub identity token for publish rights, so no long-lived secret is stored. Requires npm 11.5.1 or newer, which ships with Node 24.