Most small teams have a release process that lives partly in a README, partly in someone's head and partly in shell history. It works until the week you release while tired, skip one step and end up with a tagged commit that doesn't match the published build. The fix is cheap. Write the checklist down as one script that does each step in order and stops at the first problem.

This post walks through how to build that script. The examples use Bash and a generic web or CLI project, but the structure carries over to mobile apps, libraries and static sites.

What a release actually is

Before writing any code, list what you actually do when you release. For most small projects it comes down to these steps:

  1. Make sure you are releasing the right code (clean tree, correct branch, up to date with the remote).
  2. Set the new version number.
  3. Run the tests and build the artifact.
  4. Commit the version change and create a tag.
  5. Publish the artifact (registry, server, store upload, CDN).
  6. Push the commit and tag.
  7. Check that what is live matches what you meant to ship.

If your list is longer, good. Every step you write down is one you can't forget later.

Design rules before code

  • Fail early and loudly. Every check that can run before anything changes should run first.
  • Keep one source of truth for the version. If the version string is typed in three files, it will eventually disagree with itself.
  • Do the irreversible step once, as late as possible. A local commit or tag is easy to undo. A published package or a deployed build often is not.
  • Support a dry run. You should be able to see every command the script would run without it changing anything.
  • Keep secrets out of the script. Read tokens from the environment, never from the repo.

The skeleton

Start with strict mode, a small error helper and a wrapper that respects dry-run mode:

#!/usr/bin/env bash
set -euo pipefail

die() { echo "release: $*" >&2; exit 1; }

VERSION="${1:-}"
DRY_RUN="${2:-}"
[[ -n "$VERSION" ]] || die "usage: release.sh <version> [--dry-run]"
[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || die "version must look like 1.2.3"

run() {
  if [[ "$DRY_RUN" == "--dry-run" ]]; then
    echo "[dry-run] $*"
  else
    "$@"
  fi
}

set -euo pipefail makes the script exit on any failing command, any unset variable or any failure inside a pipeline. Without it, a failed build can scroll past and the script carries on and tags anyway.

Route every command that changes state through run. Read-only checks can run directly, so a dry run still tells you whether the preflight checks pass.

Step 1: Preflight checks

This section prevents more mistakes than any other part of the script. None of it changes anything.

[[ -z "$(git status --porcelain)" ]] || die "working tree is not clean"
[[ "$(git rev-parse --abbrev-ref HEAD)" == "main" ]] || die "not on main"

git fetch origin main --quiet
[[ "$(git rev-parse HEAD)" == "$(git rev-parse origin/main)" ]] \
  || die "local main differs from origin/main"

if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
  die "tag v$VERSION already exists"
fi

for cmd in git make shasum curl; do
  command -v "$cmd" >/dev/null || die "missing tool: $cmd"
done

: "${PUBLISH_TOKEN:?PUBLISH_TOKEN is not set}"

The last line checks that the publish credential exists before you spend minutes building. Where that token comes from is a separate problem. A local keychain, a password manager CLI or your CI's secret store all work, as long as the token never ends up in the repository. Keeping Secrets Out of Your Repos covers that setup in more detail.

Step 2: One place for the version

Choose one file to own the version and generate or read everything else from it. For a simple project that can be a plain VERSION file. For an npm package it is package.json. For an Android app it is often a Gradle property, and for iOS the marketing version in the project settings.

run sh -c "echo '$VERSION' > VERSION"
# npm projects instead:
# run npm version "$VERSION" --no-git-tag-version

If another file has to contain the version, such as an about screen or a /version endpoint, have the build read it from the source file instead of updating it by hand.

Step 3: Test and build

run make test
run make build
run sh -c "cd dist && shasum -a 256 * > SHA256SUMS"

Delegate to whatever you already use, whether that's make, npm scripts or Gradle tasks. The release script decides the order of steps and leaves the build details to those tools. Recording checksums costs nothing and lets you prove later that the artifact you published is the one you built.

Step 4: Changelog, commit and tag

A fully generated changelog is usually noise. A generated draft that you edit is a reasonable middle ground:

PREV=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
RANGE=${PREV:+$PREV..}HEAD
git log --oneline --no-merges "$RANGE" > .release-notes.txt
run "${EDITOR:-vi}" .release-notes.txt

run git commit -am "Release v$VERSION"
run git tag -a "v$VERSION" -F .release-notes.txt

The commit and tag stay local for now, so if anything later fails you can undo both with git tag -d and git reset --hard HEAD~1.

Step 5: Publish, then push

run make publish   # uses PUBLISH_TOKEN from the environment
run git push origin main
run git push origin "v$VERSION"

The order is deliberate. Publishing is the step you can't take back cleanly, so everything before it is reversible. If the push fails after a successful publish, the fix is simply to push again. If you pushed the tag first and publishing failed, the remote would have a tag pointing at a release that doesn't exist, and collaborators or CI jobs might already have acted on it.

For app store builds, "publish" usually means uploading to a review or testing channel rather than releasing to users. Treat the upload as the irreversible step and keep the final "release to everyone" action manual.

Step 6: Verify what is live

A release isn't finished when the upload command exits. It is finished when you have confirmed the live system reports the new version:

if [[ "$DRY_RUN" != "--dry-run" ]]; then
  for i in 1 2 3 4 5 6; do
    LIVE=$(curl -fsS https://example.com/version || true)
    [[ "$LIVE" == "$VERSION" ]] && { echo "live: $LIVE"; exit 0; }
    sleep 10
  done
  die "live version is '$LIVE', expected '$VERSION'"
fi

The retry loop allows for deploys and caches that take a little while to update. Time a few real releases to see how long yours take, then set the loop length from that instead of guessing. If you already run uptime or health checks, add this version check to them. Simple Monitoring for a Small Server covers what else is worth watching.

Local script or CI?

Both work, and the same script can run in either place.

  • Run locally when you release rarely, need an interactive step like editing notes, or sign builds with keys that only live on your machine.
  • Run in CI, triggered by a manual workflow or a pushed tag, when you want a clean environment every time and an automatic log of each release.

A common setup is to run the preflight and tagging steps locally and let CI build and publish when the tag arrives. If you split it that way, keep the logic in the script and make the CI config a thin wrapper that calls it. That way you can still run the release from your laptop when CI is down.

A short checklist for your script

  • Strict mode is on, and every state-changing command goes through a dry-run wrapper.
  • Branch, clean tree, remote sync, duplicate tag, required tools and credentials are all checked before any change.
  • The version lives in exactly one place.
  • Tests run before the build is published, never after.
  • The irreversible step happens once, after everything reversible.
  • The script confirms the live version at the end.
  • You have run it with --dry-run at least once since you last edited it.

Wrapping up

A release script doesn't need a framework or a plugin. Fifty to a hundred lines of careful shell can replace a checklist you only half remember. Start by writing down the steps you already do, run every check before you change anything, and save the one step you can't undo for last. After a few releases you'll stop thinking about the process, and that's the goal. Your attention goes back to what you're shipping.