npm-release-via-github-actions

name

npm-release-via-github-actions

description

Use this skill whenever the user asks for a new npm version, npm release, package release, new release, version bump, publishing to npm, cutting a GitHub release, tagging a release, or anything similar. It publishes through GitHub Actions and GitHub Releases, not from the local machine, and uses Changesets to generate CHANGELOG.md/release notes. Trigger even for casual phrasing like "ship a release", "bump npm", "publish the package", or "make a new version".

Publish npm packages via GitHub Actions

The user explicitly does not want local npm publishing. For release requests, route publishing through the repository's GitHub Actions workflow, usually triggered by a published GitHub Release.

This project also uses Changesets for changelog generation. Release prep should consume .changeset/*.md fragments into CHANGELOG.md before the GitHub Release is created.

Core rules

Do not publish from the local machine.

Avoid these commands unless the user explicitly overrides this skill for an unusual emergency:

• npm publish
• npm run publish:npm
• pnpm publish, yarn publish, or equivalent package-manager publish commands
• any local publish workaround after a GitHub Actions problem

It is OK to run local safety checks and release-prep commands that do not publish, such as:

• npm run verify
• npm run build
• npm run pack:dry
• npm run changelog:status
• npm run release:version
• npm version <version> --no-git-tag-version when an exact custom version needs to be enforced

First inspect the repository release setup

Before acting, read:

1. package.json for package name, current version, scripts, and package manager.
2. package-lock.json, pnpm-lock.yaml, or yarn.lock if present, so version bumps keep lockfiles consistent.
3. .changeset/config.json and pending .changeset/*.md files, if present.
4. .github/workflows/publish.yml or similarly named release workflow.

Confirm the workflow publishes on GitHub, preferably from one of these triggers:

on:
  release:
    types: [published]
  workflow_dispatch:

For the pi-web repository, the expected workflow is .github/workflows/publish.yml; it publishes with npm publish --access public --provenance from GitHub Actions. Use the GitHub Release path by default.

If there is no GitHub Actions publish workflow, stop and explain that one must be added or fixed. Do not fall back to local npm publish.

Standard release workflow

1. Check repo state

   • Run git status --short --branch.
   • Ensure you are on the intended branch, usually main.
   • If there are unrelated or user-owned uncommitted changes, pause and ask before including, stashing, or working around them.
   • Pull/rebase only when it is safe and the user has not left local work that could be disrupted.

2. Review and normalize pending changesets

   • Run:

     npm run changelog:status
     

   • Inspect .changeset/*.md files.
   • If there are no changesets but there are user-visible changes to release, pause and ask whether to add a changeset. Do not create a low-quality release note just to proceed.
   • If changesets exist, make sure their text is user-facing.
   • For pi-web, non-breaking changesets must use patch even for new features. The package uses CalVer shaped as semver: MAJOR.YYYYMM.PATCH. The semver minor position is the release month, not feature size.
   • If a pending changeset uses minor for a non-breaking change, edit its frontmatter to patch before versioning. Do not ask the user whether to use a patch increase or date change.
   • Use major only when the user explicitly requests a breaking/major release.
   • If you believe the pending changes introduce a breaking change but the user has not explicitly requested a major release, pause before versioning and ask the user to confirm whether this should be released as a breaking major version or changed to remain non-breaking.

3. Compute the pi-web CalVer version

   • For pi-web, always compute the version from the release date as MAJOR.YYYYMM.PATCH.
   • Use the current date at release time for YYYYMM (for example, date +%Y%m). Do not ask whether to use a same-month patch increase or a date change.
   • Keep the current MAJOR unless the user explicitly requests a breaking/major release. Do not infer or perform a major version bump on your own.
   • Set PATCH deterministically:
     • If the current package version already has the target MAJOR and release-month , use current patch + 1.

Reruns and special cases

• If a GitHub Actions publish run failed due to a transient infrastructure issue, prefer gh run rerun <run-id> --failed or rerun the workflow in GitHub.
• If using workflow_dispatch, pass the intended ref/tag explicitly where possible:

  gh workflow run publish.yml --ref v<version>
  

  Use this mainly for reruns or repositories designed around manual dispatch. For normal releases, prefer a published GitHub Release.
• If the npm version already exists, npm will reject publishing. Bump to a new version and create a new release; do not try to overwrite an existing npm version.
• If a GitHub Release/tag was created incorrectly, fix it on GitHub with care and tell the user exactly what changed.
• Never use local npm publish as a workaround for a GitHub Actions or npm provenance issue.

Final response format

After completing or attempting a release, summarize concisely:

• Version requested/released
• Changelog source: generated CHANGELOG.md section or other notes used
• Commit hash and pushed branch
• GitHub Release URL
• GitHub Actions run URL and status
• npm verification result, if published
• Any follow-up needed from the user