Skip to content

ci: add npm release workflow triggered by version tags - #24

Merged
llbbl merged 1 commit into
mainfrom
ci/release-workflow
Jul 28, 2026
Merged

ci: add npm release workflow triggered by version tags#24
llbbl merged 1 commit into
mainfrom
ci/release-workflow

Conversation

@llbbl

@llbbl llbbl commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Releases trigger on v* tags and publish to npm via trusted publishing (OIDC), so no npm token is stored in repo secrets.
  • The tag is the trigger but is not trusted: the job refuses to publish unless the tag, package.json, and a non-empty CHANGELOG.md section all name the same version.
  • The tarball is packed once, then validated with attw and publint and published as that exact file, so the validated bytes are the shipped bytes.

Changes

CI

  • .github/workflows/release.yml: New workflow, triggered on v* tags, that publishes to npm via OIDC trusted publishing.
    • Both mutating steps (npm publish, GitHub Release creation) are idempotent, so a run that dies between publishing and creating the GitHub Release can be re-run rather than stranding the tag.
    • Prereleases are routed to the next dist-tag instead of latest.
    • npm is pinned to 11.18.0 rather than @latest because the job holds an OIDC publish identity.
    • POLYDOC_REQUIRE_PANDOC makes the Pandoc-backed tests fail rather than skip, so a release cannot ship on a run where they quietly skipped.

This workflow cannot be fully exercised until a real v* tag is pushed — the npmjs.com trusted-publisher config (repo agentic-tooling/polydoc-core, workflow filename release.yml) is unverified until then. NPM_CONFIG_LOGLEVEL: verbose is set on the publish step deliberately: npm's OIDC helper never throws, so a misconfigured trusted publisher otherwise surfaces as an opaque E404. Consider dropping it once a publish has succeeded.

Refs #7

Test plan

  • Push a real v* tag and confirm the workflow publishes to npm and creates a GitHub Release
  • Confirm the npmjs.com trusted-publisher config for agentic-tooling/polydoc-core / release.yml is verified by a successful OIDC exchange

Releases now trigger on `v*` tags and publish to npm via trusted
publishing (OIDC), so no npm token is stored in repo secrets.

### Features
- The tag is the trigger but is not trusted: the job refuses to
  publish unless the tag, package.json, and a non-empty CHANGELOG.md
  section all name the same version.
- The tarball is packed once, then validated with attw and publint and
  published as that exact file, so the validated bytes are the shipped
  bytes.
- Both mutating steps (npm publish, GitHub Release creation) are
  idempotent, so a run that dies between publishing and creating the
  GitHub Release can be re-run rather than stranding the tag.
- Prereleases are routed to the `next` dist-tag instead of `latest`.
- npm is pinned to 11.18.0 rather than `@latest` because the job holds
  an OIDC publish identity.
- `POLYDOC_REQUIRE_PANDOC` makes the Pandoc-backed tests fail rather
  than skip, so a release cannot ship on a run where they quietly
  skipped.

Refs #7
@llbbl
llbbl merged commit 402f933 into main Jul 28, 2026
4 checks passed
@llbbl
llbbl deleted the ci/release-workflow branch July 28, 2026 13:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant