SonarQube в GitLab CI: анализ веток и merge request в Community Build

Бесплатный SonarQube Community Build анализирует только одну основную ветку. Ветки и merge request из коробки доступны лишь в платных редакциях. Связку sonarqube gitlab для основной ветки поднимают за вечер, а для остальных веток есть неофициальный плагин со своими рисками. Ниже: job для GitLab CI, Quality Gate, установка плагина по шагам и выбор между тремя путями.

TL;DR: В Community Build ветки и merge request не анализируются, это функция Developer Edition. Обойти ограничение можно неофициальным плагином mc1arke, но версия плагина жестко привязана к версии SonarQube, а поддержки от SonarSource нет. В статье: рабочий job для GitLab CI, токен без утечек, Quality Gate и таблица выбора из трех вариантов.

Почему в Community Build нет анализа веток и merge request?

Анализ веток и pull request SonarSource оставила платным редакциям. В Community Build сервер хранит один поток результатов на проект, поэтому feature-ветки не с чем сравнивать.

В бесплатной сборке SonarQube проект хранит историю только по основной ветке. Вы запускаете сканер из feature-ветки, и результат все равно перезаписывает основной. Ни отдельной страницы ветки, ни комментария в merge request не появится.

На практике разработчик узнает о проблеме уже после слияния, когда код в main. Отчет есть, но реагировать на него поздно.

Официальный путь один: перейти на Developer Edition, где анализ веток и pull request встроен. Есть и неофициальный: плагин, который добавляет эти функции в Community. О нем ниже, вместе с ценой такого решения.

Как подключить SonarQube к GitLab CI за один вечер?

Нужен образ sonar-scanner-cli, токен в переменных CI/CD и один job в .gitlab-ci.yml. Для основной ветки этого хватает без всяких плагинов.

Начинаем с базовой связки. Сервер SonarQube у вас уже работает, в нем создан проект и сгенерирован токен. Дальше остается описать job.

sonarqube-check:
  stage: test
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
    GIT_DEPTH: "0"
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - sonar-scanner
      -Dsonar.projectKey=my-group_my-project
      -Dsonar.sources=.
      -Dsonar.host.url=${SONAR_HOST_URL}
      -Dsonar.qualitygate.wait=true
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Три детали, на которых обычно спотыкаются. GIT_DEPTH: "0" нужен, чтобы сканер видел всю историю и считал новый код. Пустой entrypoint позволяет GitLab запустить shell внутри образа. А latest на боевом пайплайне лучше заменить конкретной версией образа.

Токен сканер берет из переменной окружения SONAR_TOKEN, отдельно в командной строке его передавать не надо.

Где хранить токен и как не слить его в репозиторий?

Токен живет только в переменных CI/CD GitLab с флагом Masked. В .gitlab-ci.yml, в Dockerfile и в коде его быть не должно.

Заходите в проект GitLab: Settings, CI/CD, Variables. Создайте SONAR_TOKEN и SONAR_HOST_URL. Для токена включите Masked, тогда GitLab замажет его в логах job. Если у вас общий сервер SonarQube на много проектов, переменные удобнее положить на уровень группы.

Есть нюанс с Protected. Переменная с этим флагом доступна только защищенным веткам и тегам, поэтому job для feature-веток и merge request ее просто не увидит. Для теста на незащищенных ветках флаг придется отключить или завести отдельный токен с узкими правами.

Токен с правами на анализ выдавайте отдельно для CI, не личный. Уйдет человек из команды, а pipeline продолжит работать. Если токен все же засветился в логе или коммите, отзывайте его сразу и выпускайте новый. Чистить историю git недостаточно.

Как заставить pipeline падать при плохом Quality Gate?

Добавьте sonar.qualitygate.wait=true. Сканер дождется расчета гейта и вернет ненулевой код, job станет красным, а merge заблокируется при включенном условии pipeline must succeed.

Без этого параметра сканер отправляет отчет и завершается успешно. Сервер потом считает гейт в фоне, а pipeline давно зеленый. Получается проверка для галочки.

С параметром sonar.qualitygate.wait=true job ждет результата. Пока гейт красный, pipeline не проходит. Время ожидания регулируется через sonar.qualitygate.timeout, по умолчанию оно ограничено, и на тяжелых проектах его стоит увеличить.

Чтобы блокировка реально работала, в настройках merge request проекта GitLab включите «Pipelines must succeed». Иначе красный job виден, но слить код никто не запрещает.

Максим: «Мог просто засесть до пяти ночи и править одну функцию, которая не работала. В моменте я уже испотел, и хотелось все закрыть. Но я понимал, что это можно решить и нужно решить, чтобы идти дальше». С Quality Gate так же: настроил один раз через боль, потом он экономит часы.

Как включить анализ веток и merge request через неофициальный плагин?

Плагин sonarqube-community-branch-plugin добавляет в Community анализ веток и оформление pull request. Ставится jar-файлом плюс javaagent для web и ce, а версия строго под ваш SonarQube.

Проект mc1arke/sonarqube-community-branch-plugin поддерживает сообщество, а не SonarSource. Версия плагина совпадает с версией SonarQube по мажорной и минорной части: плагин 25.4.0 рассчитан на SonarQube 25.4.x. Смотрите README на теге нужного релиза, инструкции у версий отличаются.

Шаги установки вручную

Скачайте со страницы релизов jar плагина и sonarqube-webapp.zip своей версии. Затем:

1. Положите jar в extensions/plugins/.
2. В conf/sonar.properties добавьте sonar.web.javaAdditionalOpts=-javaagent:./extensions/plugins/sonarqube-community-branch-plugin-${version}.jar=web.
3. Там же добавьте sonar.ce.javaAdditionalOpts=-javaagent:./extensions/plugins/sonarqube-community-branch-plugin-${version}.jar=ce.
4. Замените содержимое каталога web содержимым архива webapp.
5. Запустите SonarQube и подтвердите предупреждение о сторонних плагинах.

Если вы на Docker, есть готовый образ mc1arke/sonarqube-with-community-branch-plugin с версиями, совпадающими с официальным образом. Но если вы задаете SONAR_WEB_JAVAADDITIONALOPTS или SONAR_CE_JAVAADDITIONALOPTS сами, javaagent из Dockerfile придется добавить в свои значения.

Как разделить ветки и merge request в GitLab CI

Для основной ветки передаем sonar.branch.name. Для merge request отдельные параметры, и sonar.branch.* там быть не должно, иначе SonarQube примет запуск за анализ ветки и не оформит merge request.

sonarqube-branch:
  stage: test
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: "0"
  script:
    - sonar-scanner
      -Dsonar.projectKey=my-group_my-project
      -Dsonar.host.url=${SONAR_HOST_URL}
      -Dsonar.branch.name=${CI_COMMIT_REF_NAME}
      -Dsonar.qualitygate.wait=true
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_PIPELINE_SOURCE != "merge_request_event"

sonarqube-mr:
  stage: test
  image:
    name: sonarsource/sonar-scanner-cli:latest
    entrypoint: [""]
  variables:
    GIT_DEPTH: "0"
  script:
    - sonar-scanner
      -Dsonar.projectKey=my-group_my-project
      -Dsonar.host.url=${SONAR_HOST_URL}
      -Dsonar.pullrequest.key=${CI_MERGE_REQUEST_IID}
      -Dsonar.pullrequest.branch=${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}
      -Dsonar.pullrequest.base=${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}
      -Dsonar.qualitygate.wait=true
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Сначала прогоните анализ целевой ветки, иначе оформлять merge request будет не с чем. По документации плагина, для комментариев в GitLab в проекте SonarQube нужна настройка интеграции с GitLab, а в sonar.core.serverBaseURL должен стоять правильный адрес сервера.

Этот конфиг собран по README плагина и переменным GitLab, но на вашем проекте его нужно проверить: имена переменных, правила запуска и версия образа у всех свои. Черновик можно набросать в Claude Code, а потом сверить с документацией.

Чем рискует команда, которая поставила плагин?

Плагин не поддерживается SonarSource, ломается при обновлении SonarQube и не имеет пути миграции на коммерческие редакции. Данные при переходе могут потеряться частично или целиком.

Разберем риски по порядку, потому что от них зависит выбор.

Первый: поддержка. Автор плагина прямо пишет, что SonarSource с проблемами не помогает, а запросы на официальном форуме Sonar, скорее всего, закроют. Помощь только через issues в GitHub и сторонние площадки.

Второй: обновления. Community Build выходит регулярно, новые версии выпускаются примерно раз в месяц. Плагин привязан к минорной версии, значит после каждого апдейта сервера нужен свежий релиз плагина и свежий webapp. Не подождали релиз и обновились, получили сломанный сервер.

Третий: миграция. Совместимость плагина со встроенными функциями веток не тестировалась. Переход на Developer Edition может стоить вам части истории или всей.

Честная позиция такая: для внутреннего инструмента команды в 5-10 человек риск приемлем, для критичного контура нет.

Что выбрать: плагин, Developer Edition или только основная ветка?

Плагин дает ветки бесплатно ценой рисков, Developer Edition стоит денег, но работает официально, а анализ только main проще всего и тоже закрывает часть задач.

Все три пути рабочие. Разница в том, что вы готовы терять: деньги, время на поддержку или охват проверок.

Мы в VibeCoderz начинаем с третьего варианта, потому что он не ломается. Плагин подключаем, когда команда уже привыкла смотреть отчеты, а платная редакция все еще не оправдана. Если пайплайнами занимается отдельный инженер, посмотрите агента для DevOps: он подскажет по типовым конфигам.

Частые вопросы

Можно ли анализировать merge request в бесплатном SonarQube?

Из коробки нет. В Community Build анализируется только основная ветка. Анализ веток и merge request встроен в платные редакции, начиная с Developer Edition. В бесплатной версии это возможно только через неофициальный плагин, который SonarSource не поддерживает.

Где хранить токен SonarQube в GitLab CI?

В переменных CI/CD проекта или группы: Settings, CI/CD, Variables. Включите Masked. Если job запускается на ветках без защиты, флаг Protected отключите. В репозиторий и в .gitlab-ci.yml токен не попадает никогда.

Что делает параметр sonar.qualitygate.wait?

Со значением true сканер ждет, пока сервер посчитает Quality Gate, и завершается с ошибкой, если гейт не пройден. Job в GitLab становится красным, pipeline не идет дальше. Без параметра сканер отправляет результаты и сразу выходит.

Подойдет ли любая версия плагина к моему SonarQube?

Нет. Мажорная и минорная версии плагина совпадают с версией SonarQube: плагин 25.4.0 рассчитан на SonarQube 25.4.x. Старые версии плагина не гарантируют работу, новые версии SonarQube тоже могут его сломать.

Что будет с данными при переходе на Developer Edition?

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

Нужно ли задавать sonar.branch.name для merge request?

Нет, для merge request этот параметр нельзя задавать. Если он есть, SonarQube решит, что анализируется ветка, и оформление merge request не сработает. Для MR нужны sonar.pullrequest.key, sonar.pullrequest.branch и sonar.pullrequest.base.

Глоссарий

SonarQube Community Build это бесплатная сборка сервера статического анализа кода. Анализирует основную ветку.

Quality Gate это набор условий, по которым код считается годным: покрытие, дубли, число уязвимостей на новом коде.

sonar-scanner это утилита, которая запускается в CI, читает код и отправляет результаты на сервер SonarQube.

javaagent это параметр запуска Java, с помощью которого плагин подключается к процессам web и ce (Compute Engine) SonarQube.

Merge request это запрос на слияние в GitLab. В терминах SonarQube он называется pull request.

Что делать дальше

Начните с job для основной ветки и Quality Gate, это занимает вечер. Потом решите, нужны ли вам ветки настолько, чтобы принять риски плагина или заплатить за Developer Edition. Больше инструментов для разработки и вайбкодинга смотрите в каталоге AI-инструментов. Хотите разобрать свой пайплайн на живом примере? Запишитесь на консультацию к Максиму.

Источники: репозиторий плагина mc1arke, официальный образ sonarqube на Docker Hub, релизный цикл SonarQube Community на endoflife.date.

Обновлено: сентябрь 2026