semantic-release-script

A bash implementation of semantic release, so a release does not depend on a tree of npm packages. It reads the conventional commits, decides the version, writes the notes, tags and publishes — with a human gate before each step.

Requires git, bash 4+ and the GitHub CLI. Run locally, gh must already be logged in (gh auth login); in CI, a GH_TOKEN in the environment stands in for the login.

Releasing

./scripts/release/release.sh --dry-run   # see the version and the notes, change nothing
./scripts/release/release.sh             # the real thing, one gate per step

A real run stops at a human gate before each step. A dry run reaches no remote — no tag pushed, no release created — so its gates guard nothing: it runs straight through, and needs no terminal to answer on. That is what lets a CI job preview a release with --dry-run alone. The cost is local: a dry run no longer pauses between its steps.

A real run needs a terminal to answer on, or --yes in place of one. A runner has neither: there /dev/tty is still a device node, but nothing opens it, so the run stops at the first gate and exits 1 telling you to pass --yes — rather than reading the answer it could not get as a decline and going green having released nothing.

It is the remote a dry run leaves alone, not your disk. --notes, --changelog and --summary write their file under --dry-run exactly as they do on a real run, and now with no gate in front of them. --local still gates, because it writes a tag to your machine.

Option	Effect
-y, --yes	Skip every human gate (unattended run).
-n, --dry-run	Do everything but push the tag and create the release. Reaches no remote, so every gate is skipped.
-l, --local	Create the tag locally, but neither push it nor publish a release.
--since <ref>	Read the commits since <ref> instead of the last v* tag.
--trunk <name>	The branch releases are cut from, instead of GitHub's default branch.
--level <level>	Force the bump: major, minor or patch.
--level-from <ref>	Force the bump from a branch name: the segment right after release/ in release/major/<id>, release/minor/<id> or release/patch/<id>, or the bare release/major, release/minor or release/patch. A name with no level there changes nothing. A level below what the commits imply (release/patch/<id> over a feat) is refused with 3; forcing up is allowed. The value must be a branch, locally or on origin, or the run errors. Not with --level, which is never refused for being lower.
--exclude-paths <a|b>	Keep the commits that only touch these paths out of the notes and the bump. One value, entries separated by |, quoted in a shell. See Excluding paths.
--notes <file>	Also write the release notes to <file>.
--changelog <file>	Prepend the release to <file>, newest release on top.
--summary <file>	Write what the run decided to <file>, as key=value lines.
--check	Print the setup report instead of releasing. Takes only --trunk, --to, --since, --level-from and .

Cutting a release

.github/workflows/release.yml cuts this repository's own releases.

• Preview: a push to main, or a manual dispatch left on preview, dry-runs the release and writes the pending version and notes to the job summary. Nothing is written.
• Publish: push a release/* branch cut from main, or dispatch the workflow with publish from main or a release/* branch. The tag and the GitHub release are created, and a push-triggered run then deletes the release/* branch.

Publish refuses a release/* ref that main does not contain, and does not start until the bats suite is green for that commit.

The workflow runs release.sh fetched at the commit named by RELEASE_SCRIPT_REF at the top of the file, not the copy on the commit being released. It points at the commit the v1.1.0 tag targets, named in a comment above it, until the next pin move. To move the pin, set RELEASE_SCRIPT_REF to the SHA of the commit to run (for a version tag, git rev-parse 'vX.Y.Z^{commit}') and update the comment to name it, then merge that change: the next push to main previews with it.

The "Fetch the pinned release.sh" step (a curl of the file at RELEASE_SCRIPT_REF, then chmod +x) appears in both the preview and the publish job, and that is intended, not an oversight for consumers to factor out. The two jobs never run in the same workflow run, so each run downloads the script once; the SHA is declared once, in RELEASE_SCRIPT_REF, so a pin move touches one line. No composite action or reusable workflow is published from this repository: it would carry a second ref to pin, and the step is two commands. A consumer copying the workflow keeps both steps. See ADR 0002.

Both jobs pass the ref name to --level-from, so a push to release/major/<id> publishes a major, and a preview dispatched from that branch shows the forced version. A push or dispatch from main forces no level.

Forcing the level from the branch name

The segment right after release/ can force the bump, so CI can cut a release the commits alone would not.

Branch	Effect
release/major/<id>, release/major	Forces a major.
release/minor/<id>, release/minor	Forces a minor.
release/patch/<id>, release/patch	Forces a patch.
release/20261015.1, main, release/hotfix-login	No level: the commits decide, as before.
release/mayor/x, release/Major/x, release/major-x/y	Near-misses: no level either, and not refused. Only the three lowercase values count.

The contract is release.sh's own (--level-from), so a consumer vendoring the script gets the same one. It ends in these outcomes:

This is the beginning of the README. Read the rest at the original. Read the full README ↗