Semantic-release в GitLab: автоматизируем CHANGELOG / Хабр

Привет, Хабр!

На проекте была одна довольно типичная и, мягко говоря, надоедливая проблема: разработчики вручную заполняли CHANGELOG при выкатке новой версии приложения. Иногда информация туда попадала точная и соответствующая реальным изменениям, иногда – частично верная, а иногда и вовсе напрочь забытая.

Решение нашлось довольно элегантное – интегрировать инструмент semantic-release в наш пайплайн CI/CD. Но оказалось, что найти полноценное руководство по его настройке, особенно с учетом корпоративного GitLab и плагина semantic-release/changelog, не так-то просто. Пришлось собирать информацию буквально по крупицам из различных источников, и вот теперь делеимся с вами проверенной пошаговой инструкцией.

Настройка

1. Установите необходимые пакеты в devDependencies:

"semantic-release": "^24.2.0",
"@semantic-release/changelog": "^6.0.3",
"@semantic-release/git": "^10.0.1",
"@semantic-release/gitlab": "^10.0.1",
"@semantic-release/npm": "^12.0.1"

2. Добавляем поле release в package.json:

Все, что написано в формате SCREAM_CASE, замените на свои значения.

"release": {  
"branches": [    
  "master" 
],
  "repositoryUrl": 
  "https://gitlab.COMPANY.ru/GROUP/SUBGROUP_1/SUBGROUP_2/PROJECT.git",  
  "plugins": [    
    "@semantic-release/commit-analyzer",    
    "@semantic-release/release-notes-generator",    
    "@semantic-release/npm",    
    "@semantic-release/changelog",   
    [      
      "@semantic-release/gitlab",     
      { 
        "gitlabUrl": "https://gitlab.COMPANY.ru"     
      }   
    ],   
    [      "@semantic-release/git",   
     {     
       "assets": [         
         "CHANGELOG.md",        
         "package.json"       
       ],        
       "message": "YOUR_PROJECT_NAME: ${nextRelease.version} 
       \n\n${nextRelease.notes}"     
     } 
  ] 
  ]
}

3. Создайте Access token для проекта

Создайте Access token с названием GL_TOKEN и следующими правами:

Scopes: api, read_api, read_repository, write_repository
Role: Maintainer

4. Добавьте переменные CI/CD в GitLab

В настройках CI/CD Variables проекта GitLab добавьте созданный токен под названием GL_TOKEN, а также обязательно задайте переменные:

GIT_AUTHOR_EMAIL
GIT_AUTHOR_NAME
GIT_COMMITTER_EMAIL
GIT_COMMITTER_NAME

Это важно, так как присутствует проверка на корпоративную почту при выполнении git config user.email.

5. Создайте задачу в .gitlab-ci.yml

create_tag_release:
   image: node:20
   stage: compile
   tags:
     - ci
   only:
     - master
   script:
     - yarn install
     - yarn semantic-release
   when: manual

6. Убедитесь, что последний тег начинается с буквы v, например, v3.2.11.

Инструкция по применению

Теперь, при создании коммитов в Merge Request обязательно используйте приставки:

fix: – для исправлений
feat: – для нового функционала

После двоеточия обязательно ставьте пробел!

Примеры:

fix: package.json bump vite
feat: добавлен семантик релиз

Ручной запуск (when: manual) нужен для создания релиза именно тогда, когда это необходимо, а не на каждый merge в master. После запуска задача автоматически создаст тег и релиз, обновит версию в package.json согласно семантической версии и аккуратно дополнит CHANGELOG.md подробным описанием версии.

Пример описания версии:

4.10.0 (2025-04-21) 
Bug Fixes
· добавлен border к datepicker (95b2251) 
· правки по дизайну на странице dashboard (91e616d) 
· EML-10987 рефактор страницы рейтинга (ed2b4e5) 

Features
· Добавлено обращение к API по ролям EML-10999 (689bebc)

Запускать задачу стоит, когда не идут другие пайплайны, так как semantic-release может падать с ошибкой в этот момент. Если упал – спокойно перезапустите, когда все остальные пайплайны завершатся.

Опыт использования semantic-release через полгода

Спустя шесть месяцев непрерывного использования команда окончательно сформировала мнение о данной технологии.

Какие сложности возникли?

На подключение и настройку ушло около двух рабочих дней.
Потребовалось еще две-три недели, чтобы вся команда привыкла правильно оформлять сообщения коммитов.

Но это все минусы, которые удалось обнаружить. Теперь перейдём к плюсам!

Преимущества автоматизации semantic-release:

Автоматизированы типовые операции: больше нет необходимости вручную заполнять CHANGELOG. Semantic-release автоматически формирует подробный лог изменений со ссылками на соответствующие коммиты.
Управление деплоем: менеджер видит точный перечень коммитов, входящих в каждый релиз.
Прозрачность и удобство анализа: легче обнаруживать изменения, приведшие к проблемам, даже если ошибка была выявлена спустя несколько релизов.
Повышение прозрачности процессов: четко обозначены даты релизов и авторы коммитов, что облегчает контроль сроков и производительности команды.

И приятный бонус: если у вас Jira интегрирована с GitLab, а в коммите указан номер задачи, то прямо в вашем changelog появится активная ссылка на задачу в Jira, позволяющая детально изучить контекст изменений буквально в один клик.

Подробнее ознакомиться с инструментом semantic-release вы можете на официальном сайте semantic-release.

Автор статьи – AJIb63PT.

Semantic-release в GitLab: автоматизируем CHANGELOG