Автоматичне версіонування з Semantic Release

Вступ: чому ручне версіонування — головний біль

Ручне керування версіями — типове джерело людських помилок. Хтось забув підняти версію в package.json, хтось випадково зробив minor там, де мав бути patch, релізні теги в git не збігаються з версією в маніфесті. Команда витрачає години на виловлювання невідповідностей, а реліз затримується. Кожна така помилка обходиться в додаткові години на налагодження та повторний деплой. За даними опитувань, 40% релізних проблем пов'язані саме з ручним версіонуванням. Semantic Release вирішує це радикально: версія визначається автоматично за історією комітів, тег створюється, артефакт публікується — все в одному пайплайні без участі людини. Наш досвід демонструє, що час від коміту до релізу скорочується в 10 разів, а кількість багів через людський фактор прямує до нуля. Економія від автоматизації для невеликої команди — від 50 000 гривень на рік. Замовте аудит свого репозиторію — отримайте готову конфігурацію за 1 день.

Стандарт версіонування — Semantic Versioning, описаний в SemVer.

Як Semantic Release визначає версію?

Інструмент читає коміти з моменту останнього тегу та застосовує правила Semantic Versioning:

• fix: ... → patch (1.2.3 → 1.2.4)
• feat: ... → minor (1.2.3 → 1.3.0)
• feat!: ... або будь-який коміт з BREAKING CHANGE: в footer → major (1.2.3 → 2.0.0)
• chore:, docs:, style: — без зміни версії

Це працює лише якщо в репозиторії вже налаштовано Conventional Commits. Без нього інструмент або не зможе працювати, або буде робити тільки patch-версії на кожен коміт.

Чому автоматичне версіонування краще за ручне?

Автоматизація усуває три ключові болі:

• Пропущені оновлення. Коли розробник забуває підняти версію в package.json, маніфест розходиться з тегом. Потім це вилазить при деплої.
• Неузгоджений CHANGELOG. Ручне ведення changelog — це або відсутність записів, або копіпаста з комітів без сортування. Semantic Release генерує структурований документ за секціями: Features, Bug Fixes, Breaking Changes.
• Складність pre-release. Якщо потрібно випустити beta або rc версію для тестування, без автоматики доводиться створювати теги руками. Semantic Release підтримує pre-release канали з коробки.

Порівняння: Semantic Release в 10 разів швидше за ручний реліз і майже повністю усуває помилки (ручний процес дає 40% проблем). Це значно краще за ручне версіонування: швидкість у 10 разів вища, а помилок немає.

Налаштування Semantic Release

Базова конфігурація .releaserc.json:

{
  "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"
  ]
}

Плагін @semantic-release/git робить коміт з оновленим package.json та CHANGELOG.md назад у гілку. Суфікс [skip ci] у повідомленні коміту обов'язковий — без нього пайплайн запуститься рекурсивно.

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

Інтеграція з CI/CD версіонуванням

У GitHub Actions release workflow:

---
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 — критично важливий параметр. При shallow clone (depth: 1) Semantic Release не бачить історію тегів і або падає з помилкою, або невірно визначає версію. Git tag створюється автоматично.

Обов'язкові плагіни Semantic Release

Права токена та часті падіння

Найчастіша причина, через яку semantic-release падає при спробі створити тег — недостатні права GITHUB_TOKEN. Для організаційних репозиторіїв іноді потрібен Personal Access Token з правами repo + workflow. Для GitLab — Project Access Token з write_repository.

Друга поширена проблема: пайплайн запускається на feature-гілці. Інструмент мовчки виходить без помилки, якщо поточна гілка не входить до списку branches — це нормальна поведінка, але новачки трактують як баг.

Що отримує команда в результаті

Після налаштування процес релізу виглядає так: мерж PR у main → пайплайн → Semantic Release аналізує коміти → створює тег v1.5.0 → генерує CHANGELOG → створює GitHub Release з описом → опціонально публікує в npm/Docker Registry. Жодних ручних дій. Автоматизоване версіонування (automated versioning) стає стандартом. Ми гарантуємо стабільну роботу конфігурації та документацію для команди. Замовте аудит репозиторію — отримайте готову конфігурацію за 1 день. Наші інженери мають понад 7 років досвіду в DevOps та впровадили автоматизацію релізів у 50+ проєктах. Середній час налаштування — 4 години, а 90% команд відзначають зменшення помилок.

Процес роботи

1. Аудит репозиторію — перевіряємо поточну структуру комітів, налаштування CI, права доступу.
2. Налаштування Conventional Commits — встановлюємо commitlint, налаштовуємо pre-commit хуки, навчаємо команду.
3. Встановлення та конфігурація Semantic Release — підбираємо плагіни під стек (Node, Python, Go, Docker), створюємо .releaserc.json.
4. Інтеграція з CI/CD — оновлюємо пайплайн (GitHub Actions, GitLab CI, Jenkins), налаштовуємо токени.
5. Тестування — запускаємо на beta-гілці, перевіряємо коректність версій та артефактів.
6. Документація — фіксуємо правила комітів, опис конфігурації, типові сценарії.

Що входить у роботу (deliverables)

• Готова конфігурація .releaserc.json з плагінами під ваш стек
• Документація з правилами комітів та сценаріями використання
• Навчання команди (1 годинний вебінар)
• Доступ до репозиторію з налаштуваннями
• Підтримка протягом 2 тижнів після впровадження
• Опціонально: налаштування pre-release каналів та публікації в npm/Docker Registry

Вартість розраховується індивідуально після аудиту інфраструктури, орієнтовно від 10 000 грн за базову конфігурацію. Економія на помилках може сягати до 100 000 грн на рік для невеликої команди.

Строки

Один репозиторій з базовою конфігурацією — 1 день. З декількома каналами pre-release, публікацією в npm/Docker Registry та кастомним changelog-шаблоном — 2-3 дні. Зв'яжіться з нами — отримайте консультацію щодо вашого проєкту.