Automated Version Generation with Semantic Release

Why manual versioning is a headache

Manual version management is a typical source of human error. Someone forgets to bump the version in package.json, someone accidentally makes a minor where a patch was intended, release tags in git don't match the manifest version. The team spends hours tracking down inconsistencies, and the release is delayed. Each such error costs an average of $18–26 in debugging and redeployment. According to surveys, 40% of release problems are directly related to manual versioning. Semantic Release solves this radically: the version is determined automatically from the commit history, a tag is created, the artifact is published — everything in one pipeline without human involvement. Our experience shows that the time from commit to release is reduced tenfold, and the number of bugs due to human error approaches zero. Automation savings for a small team start at $450–650 per year. Order a repository audit and get a ready-made configuration within one day.

Semantic Versioning is a versioning standard described at SemVer.

How does Semantic Release determine the version?

The tool reads commits since the last tag and applies Semantic Versioning rules:

• fix: ... → patch (1.2.3 → 1.2.4)
• feat: ... → minor (1.2.3 → 1.3.0)
• feat!: ... or any commit with BREAKING CHANGE: in the footer → major (1.2.3 → 2.0.0)
• chore:, docs:, style: — no version change

This only works if the repository already has Conventional Commits configured. Without it, the tool either cannot work or will only produce patch versions for every commit.

Why automate versioning?

Automation eliminates three key pains:

• Missed updates. When a developer forgets to bump the version in package.json, the manifest diverges from the tag. This surfaces during deployment.
• Inconsistent CHANGELOG. Manual changelog maintenance either lacks entries or involves copy-pasting unsorted commits. Semantic Release generates a structured document by sections: Features, Bug Fixes, Breaking Changes.
• Pre-release complexity. To release a beta or rc version for testing, manual tagging is required. Semantic Release supports pre-release channels out of the box.

How to configure Semantic Release for your stack?

Basic .releaserc.json configuration:

{
  "branches": ["main", {"name": "beta", "prerelease": true}],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    ["@semantic-release/npm", {"npmPublish": false}],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],
    "@semantic-release/github"
  ]
}

The @semantic-release/git plugin commits the updated package.json and CHANGELOG.md back to the branch. The [skip ci] suffix in the commit message is mandatory — without it, the pipeline will trigger recursively.

"branches": [
  "main",
  {"name": "beta", "prerelease": true},
  {"name": "develop", "prerelease": "alpha"}
]

Integration with pipeline

In GitHub Actions:

---
release:
  runs-on: ubuntu-latest
  permissions:
    contents: write
    issues: write
    pull-requests: write
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
        persist-credentials: false
    - uses: actions/setup-node@v4
    - run: npm ci
    - run: npx semantic-release
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

fetch-depth: 0 is critically important. With a shallow clone (depth: 1), Semantic Release cannot see the tag history and either fails with an error or incorrectly determines the version.

Which Semantic Release plugins are mandatory?

Token permissions and common failures

The most common reason for semantic-release to fail when creating a tag is insufficient GITHUB_TOKEN permissions. For organizational repositories, a Personal Access Token with repo and workflow scopes is sometimes required. For GitLab, a Project Access Token with write_repository is needed.

The second common issue: the pipeline runs on a feature branch. The tool exits silently without error if the current branch is not in the branches list — this is normal behavior, but newcomers interpret it as a bug.

What the team gets in the end

After setup, the release process looks like this: merge PR into main → pipeline → Semantic Release analyzes commits → creates tag v1.5.0 → generates CHANGELOG → creates GitHub Release with description → optionally publishes to npm/Docker Registry. Zero manual actions. We guarantee stable configuration and documentation for your team. Order a repository audit and get a ready-made configuration within one day. Our engineers have extensive experience in DevOps and have implemented release automation in numerous projects.

Our process

1. Repository audit — checking current commit structure, CI settings, access rights.
2. Conventional Commits setup — installing commitlint, configuring pre-commit hooks, training the team.
3. Semantic Release installation and configuration — selecting plugins for your stack (Node, Python, Go, Docker), creating .releaserc.json.
4. CI/CD integration — updating pipeline (GitHub Actions, GitLab CI, Jenkins), configuring tokens.
5. Testing — running on a beta branch, verifying version correctness and artifacts.
6. Documentation — recording commit rules, configuration description, typical scenarios.

The cost is calculated individually after an infrastructure audit.

Timelines

One repository with basic configuration — 1 day. With multiple pre-release channels, publishing to npm/Docker Registry, and a custom CHANGELOG template — 2-3 days. Contact us for a consultation on your project.