# 2. Automate releases with release-please and publish to NPM via GitHub Actions

Date: 2026-04-08

## Status

Accepted

## Context

Releases for `@volusion/element-block-scripts` have historically been performed manually using the [`np`](https://github.com/sindresorhus/np) CLI tool, which requires a developer to run `npm run release` locally, enter credentials, and manage the version bump and git tag by hand. This approach is error-prone, requires local environment setup, and provides no audit trail of what changed between releases.

The team follows [Conventional Commits](https://www.conventionalcommits.org/) (e.g. `feat:`, `fix:`, `chore:`) which makes it possible to determine version bumps and generate changelogs automatically.

## Decision

Releases will be automated using two GitHub Actions workflows and [release-please](https://github.com/googleapis/release-please):

**`.github/workflows/release-please.yml`** — Runs on every push to `master`. Uses `google-github-actions/release-please-action@v4` to open and maintain a "Release PR" that bumps `package.json` version and updates `CHANGELOG.md`. When the Release PR is merged, release-please creates a GitHub Release and git tag automatically.

**`.github/workflows/npm-publish.yml`** — Triggers on `release: types: [published]`. Runs `npm ci`, `npm test`, and `npm publish --provenance --access public` using the `NPM_TOKEN` secret. The `--provenance` flag generates a signed attestation on npmjs.com linking the published package to this repository and commit, improving supply chain security.

Two bootstrap files are committed to the repository root so that release-please starts at the current version (`2.4.5`) rather than resetting to `1.0.0`:

- **`release-please-config.json`** — declares `release-type: node`
- **`.release-please-manifest.json`** — records the current released version as `2.4.5`

A **`commit-msg` git hook** is added via [Husky](https://typicode.github.io/husky/) to enforce the commit message format at commit time:

```
<type>: <JIRA-TICKET-ID> <description>

e.g. feat: ET-4591 add release automation
```

Allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `build`, `ci`, `perf`, `revert`. The JIRA ticket pattern must match `[A-Z]+-[0-9]+`. The hook is installed automatically for all contributors via a `prepare: "husky"` script in `package.json`.

The `np` dependency and `release` script are removed from `package.json` as they are superseded by this automation.

## Consequences

Releases no longer require any local developer action beyond merging the release-please PR. Version bumps and changelogs are derived from commit messages automatically: `fix:` → patch, `feat:` → minor, `BREAKING CHANGE` footer → major.

All contributors must use the conventional commit format with a Jira ticket ID. The `commit-msg` hook enforces this locally; PRs from forks will not have the hook enforced but will still need to follow the format for release-please to classify the change correctly.

The `NPM_TOKEN` secret must remain valid in GitHub repository settings. If it expires, the publish job will fail and a new token must be rotated in.

npm provenance attestations are visible on the package's npmjs.com page, providing a verifiable link between the published artifact and the source commit.