Tagged Releases and Semantic Versioning in CI

A release without a version identity is a release you cannot discuss, compare, or roll back to. Semantic versioning gives your releases an explicit contract, and a CI pipeline that derives and applies the version automatically removes the most error-prone step. This post covers adopting the MAJOR.MINOR.PATCH scheme and wiring it into your pipeline so tags, artifacts, and releases stay in lockstep.

The Version Contract

Semantic versioning is simple: MAJOR.MINOR.PATCH. Bump the major for breaking changes, the minor for backward-compatible new features, and the patch for backward-compatible bug fixes. The discipline is that these numbers are a promise to consumers — a compatible API must never change the major version.

• **MAJOR** increments break compatibility.
• **MINOR** adds functionality, still compatible.
• **PATCH** fixes bugs, still compatible.

A 1.2.3 means major 1, minor 2, patch 3. Pre-release suffixes like 1.2.3-rc.1 and build metadata like 1.2.3+build.7 are optional and add orderable refinement.

Deriving the Version in CI

You can let a human type the version when they create a release, but automation is more reliable. A common pattern: decide the version bump from commit messages or a version file, tag the release commit, and let the pipeline read the tag.

  release:
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/v')
    steps:
      - uses: actions/checkout@v4
      - run: |
          VERSION=$(git describe --tags --abbrev=0)
          echo "releasing $VERSION"
          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
      - run: npm run build
      - run: ./package-and-publish.sh "$VERSION"

The if: guard means the release job only runs when a v-prefixed tag is pushed. The version is read back from the tag with git describe, so the artifact, the tag, and the release are all stamped from the same value. No hand-maintained version list that can drift.

Tagging Workflow from the Release Branch

The bump direction is a human decision, but you can automate the mechanics. Push a tag with a conventional commit or a version manifest: major increments on breaking changes, minor on features, patch on fixes. Tools like standard-version or semantic-release read conventional commit messages and derive the bump, write the changelog, and push the tag. You can also keep it manual and explicit — create a tag and let the pipeline do the rest.

# decide the version, then tag and push
git tag -a v2.4.0 -m "Release 2.4.0"
git push origin v2.4.0

The decision of *which* bump is the meaningful human step. Everything downstream — building, stamping, uploading the artifact — is the machine's job.

Why the Artifact Must Carry the Version

The artifact and the version must travel together, because later you cannot reliably recover "which version was this?" from an untagged bundle. Stamp the version into the artifact name or metadata at build time:

# stamp the version into a built archive
tar -czf release-$VERSION.tar.gz dist/
sha256sum release-$VERSION.tar.gz > release-$VERSION.sha256

Keeping the checksum alongside the artifact lets anyone verify integrity. Storing a versioned, checksummed artifact makes rollback and audit trivial: you know exactly what you deployed, when, and whether it matches what was published.

Guard the Tag Purity

A tag should point at a commit that is, or descends from, CI-green code. To keep releases clean:

• Only tag commits that have passed CI.
• Make tags immutable; never move or overwrite a tag you have released.
• Record the source commit and the artifact digest in the release notes.
• Treat pre-release tags distinctly from final tags.

If a tag can be silently moved, your "stable at v2.4.0" confidence collapses. Immutable tags are part of your chain of custody.

Takeaway

Apply semantic versioning, let the pipeline read the version from the tag, stamp the artifact and its checksum with that version, and keep tags immutable. A traceable version is the difference between an arbitrary deployment and a release you can reason about and roll back.

To host artifact registries, release servers, or the runners that stamp them, a Netbay VPS gives you a clean, isolated box — provision one at netbayhosts.in.