Эффективная модель разработки с использованием Gitlab и Битрикс24

Про Битрикс24 и Gitlab

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

Вместе с тем у отдела разработки есть специфичные потребности, на которые Битрикс24 никак не рассчитан. Для этих потребностей мы используем Gitlab.

Это сервис для разработчиков, который позволяет:

• Хранить и работать с исходниками проектов;
• Разграничивать доступы к разным проектам;
• Работать над проектом сразу нескольким разработчикам;
• Проводить ревью реализации задачи при приёме работы;
• Автоматизировать процессы тестирования через Gitlab CI;
• Автоматизировать деплой проектов через Gitlab CD;
• Вести техническую документацию по проектам;
• Мониторить состояние проектов через Prometheus… и это не весь функционал, там ещё много всего.

Вы ранее могли не сталкиваться с Gitlab’ом, но точно слышали про Github или Bitbucket. Если их приближённо сравнивать, то все эти сервисы решают схожую задачу.

Как и Битрикс24, Gitlab бывает облачным и коробочным. Мы предпочитаем коробочную редакцию, как более контролируемый и стабильный вариант установки. Хотя в отличие от Битрикс24, разница между этими двумя редакциями не такая значительная и можно было бы пользоваться любой из них.

Про Gitlab Flow

Gitlab Flow — модель работы с Git, разработанная и поддерживаемая тем же сообществом, которое делает Gitlab. Про то, в чём она заключается можно прочесть в официальном источнике, есть даже перевод на русский. За исключением некоторых особенностей, модель не особо отличается от всем известного GitFlow. Будем считать, что вы с ней уже знакомы и рассмотрим, как это работает на нашем примере.

У нас несколько видов репозиториев:

• Исходники клиентских сайтов на техподдержке.
• Исходники клиентских корпоративных порталов.
• Исходники тиражных модулей и приложений.
• Инструменты и библиотеки для внутреннего использования.

У каждого репозитория один или несколько мейнтейнеров с правами на принятие изменений в ветку master. Ветка master всегда стабильна и соответствует той версии исходников, которые сейчас на продакте, если мы про сайты или корпорталы, либо самой последней версии модуля или библиотеки, если мы о них. В модулях и библиотеках дополнительно используются теги для обозначения версий.

Каждому репозиторию на Gitlab соответствует отдельный проект в Битрикс24:

В участниках проекта на Битрикс24, кроме разработчиков, все сотрудники, которые к этому проекту относятся. Все документы, макеты, задачи по разработке функционала или исправлению ошибок — тоже храним и ведём в этом проекте.
В почти каждой задаче по разработке как минимум три участника:

1. Постановщик, который отвечает за описание задачи, контроль сроков её выполнения и приём функциональной части реализации.
2. Разработчик, который собственно и занимается реализацией задачи, её тестированием и подготовкой к релизу.
3. Ревьюер, который контролирует техническую часть реализации и является мейнтейнером того репозитория, к которому относится задача.

Когда разработчик приступает к работе над задачей, он создаёт на Gitlab отдельную ветку под эту задачу в репозитории соответствующего проекта. Название ветки пишет например так: 15704-new-catalog-design, где 15704 — ID Задачи в Битрикс24, оставшаяся часть — мнемоника, помогающая различать ветки, когда их много.

После создания ветки — приступает к выполнению задачи. В зависимости от проекта демонстрирует постановщику промежуточные и финальные результаты: либо на тестовом сервере, либо со своего компьютера. Если у постановщика есть какие-либо корректировки или замечания к функциональной части, они сразу же исправляются на этом этапе. Всё общение по задаче при этом происходит в комментариях на Битрикс24, либо вербально.

Когда вся работа сделана, протестирована и показана постановщику — разработчик создаёт на Gitlab’е Merge Request (далее MR) и заполняет его по правилам:

• Дублирует в название заголовок задачи из Битрикс24.
• Ставит в описание ссылку на задачу из Битрикс24.
• Назначает ответственным по задаче одного из мейнтейнеров репозитория.

После чего разработчик может проверить сам себя, перейдя на вкладку “Changes” и просмотрев дифф внесённых изменений:

MR проверяется в несколько этапов:

1. Сначала ревьюер тестирует функционал по описанию базовой задачи. Несмотря на то, что к моменту ревью функционал уже ранее тестировался постановщиком и разработчиком, всё равно могут всплывать неочевидные ошибки. Если функционал не работает, MR сразу возвращается на доработку.
2. Затем просматривает статус тестов и внесённые в код изменения. Если тесты не прошли, или в коде есть очевидные проблемы, которые нужно исправлять – MR также сразу возвращается на доработку.
3. Наконец, ревьюер внимательно проверяет внесённые изменения, детально разбирается в происходящем и оставляет замечания, если видит, что что-то можно улучшить.

Иногда получается, что MR несколько раз возвращается на доработку сразу после первого этапа ревью. С точки зрения календарных сроков получается долго, но это окупается за счёт того, что время ревьюера в среднем дороже, чем разработчика, и тратить его на детальное ревью при неработающем функционале нецелесообразно.

Основные аспекты, проверяемые во время ревью:

1. Очевидно, добавляемый функционал должен работать.
2. Ранее имеющийся функционал тоже должен работать.
3. Соответствие кода стандартам оформления.
4. Успешность прошедшего тестирования и сборки.
5. Не должно быть изменений, не относящихся к задаче.
6. Можно ли что-то упростить или улучшить.
7. Общее качество исходного кода.

Кроме технических проверок есть и чисто административные моменты: разработчик может забыть обновить ченжлог, либо не описать в документации добавленные классы и методы. У нас техническая документация хранится в файлах в директории /docs/ проекта и тоже является частью MR.

Если необходимо что-то исправить, ревьюер оставляет комментарии прямо в коде:

После чего переназначает MR обратно на разработчика:

По принятому внутри компании соглашению — так мы обозначаем, кто в текущий момент отвечает за то, чтобы работа по MR двигалась дальше. Так, когда MR нужно проверять, ответственным ставится ревьюер, когда нужно дорабатывать — разработчик.

Каждый MR может пройти по 2-3 итерации переназначений туда и обратно, пока не будет принят. Их,  впрочем, бывает и больше: для объёмных задач, сложного функционала или вредных ревьюеров.

В конечном счёте, когда по MR больше не осталось неразрешённых комментариев, ревьюер принимает MR и изменения оказываются в ветке master.

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

Когда изменения попадают на боевой сайт, задача на Битрикс24 считается сделанной и разработчик может её закрыть. Если после переноса возникают новые правки или хотелки, они оформляются отдельными задачами.

Проблемы

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

1. Не всегда понятно, сколько реально времени уходит на работу над задачами в срезе всего отдела. Были случаи, когда ревью по задаче суммарно занимало больше времени, чем сама задача, от них нужно было избавляться.
2. Время, потраченное на ревью размазывалось по всему Битриксу и рабочему дню ревьюера. Для учёта времени что только не делали: кто-то создавал себе единую на все проекты задачу, кто-то по одной задаче в каждый проект, кто-то по одной задаче на каждый MR. Об едином именовании таких задач речи тоже не шло, и визуально они почти ничем не отличались от нормальных.
3. Как ревьюер, так и разработчик должны были постоянно мониторить Gitlab, чтобы видеть, за какие MR они в текущий момент являются ответственными. Также ревьюер не мог нормально спланировать завтрашний день при формировании ежедневного отчёта, так как задачи про ревью вроде как и не задачи, но время на них уходит.
4. Нам нужно было определиться, сколько времени на ревью нам закладывать при оценке работы, но мы не могли посчитать этот коэффициент, потому что толкового отчёта при имеющихся на тот момент данных не построишь.
5. После того, как задача отправлялась на ревью постановщик терял над ней всякий контроль и понимание происходящего, т.к. разработчики уходили на Gitlab, где кроме них никого нет, и могли общаться там несколько дней, ничего не отписывая в задаче.
6. Нужно было раз и навсегда решить конфликты между ревьюером и разработчиком в вопросе соблюдения крайних сроков. Разработчик обязан закрывать задачи к тому крайнему сроку, который у них поставлен, но для этого ему нужно участие ревьюера, которого этот крайний срок будто и не касается. Разработчики тоже, конечно, любят открывать MR за 2 часа до крайнего срока и затем пытаться перекладывать ответственность на ревьюера, но это был уже вторичный вопрос.
7. На ревьюере помимо задач по ревью стоят и обычные задачи, в которых он является разработчиком. Нужно было как-то научиться балансировать в соотношении этих двух типов, чтобы ревьюер успевал в каждом из них.

Интеграция

Все перечисленные проблемы можно было бы решить, если бы у нас была интеграция между Битрикс24 и Gitlab. От неё нам потребовалось бы всего две вещи:

Каждому MR на Gitlab должна соответствовать задача на ревьюера на Битрикс24. Она должна быть подзадачей задачи, над которой работает разработчик и иметь тот же проект, теги, крайний срок, что и базовая задача. В описании задачи должна быть ссылка на MR, который нужно проверить.

Каждое изменение статуса MR на Gitlab должно сопровождаться комментарием к базовой задаче от имени системного пользователя с пояснением, что именно сейчас произошло.

Расскажем, как мы её делали.

Способ интеграции

Первый вопрос, который нужно решить: как передавать информацию в Битрикс24? Встроенной интеграции между Gitlab и Битрикс24 в настоящий момент нет, зато есть механизм веб-хуков.
С его помощью можно указать в настройках репозитория ссылку на обработчик, который будет вызываться каждый раз, когда на Gitlab происходят интересующие нас события. В нашем случае все события, связанные с MR:

Чтобы на стороне Битрикс24 можно было убедиться в том, что запрос пришёл из доверенного источника,  предусмотрен механизм секретных токенов. Токеном может быть произвольная строка, которая будет пересылаться в каждом отправляемом запросе в заголовке “X-Gitlab-Token”. В нашем случае, в качестве этой строки используется рандомно сгенерированный uuid.

Также нам нужно понимать, к какому проекту и какой задаче относится MR из веб-хука, чтобы правильно заполнить поля задачи про ревью. С этим особых сложностей не возникло, так как к тому моменту у нас уже было соглашение об именовании веток: для выяснения ID-задачи было достаточно прочесть его из начала имени ветки.

Сопоставление пользователей

Нужно как-то сопоставлять пользователей Битрикс24 с аккаунтами на Gitlab. У этих двух сервисов несколько разные модели хранения пользователей, общим знаменателем которых можно считать e-mail пользователя.

У Gitlab’а в структуре исходящих веб-хуков не предусмотрена передача полной информации о пользователе. В момент вызова обработчика всё, что мы достоверно о нём знаем — логин. Поэтому для работы модуля нам ещё понадобится токен для доступа к API, выписанный от имени администратора Gitlab:

Имея логин пользователя и токен для доступа к API, можем запросить информацию о публичных мейлах, привязанных к аккаунту пользователя на Gitlab’е, и с их помощью определить профиль на Битрикс24.
Успех.

Настройки проектов

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

В настоящий момент в Gitlab есть возможность определить системные веб-хуки, которые применяются глобально ко всем существующим репозиториям. Однако возможность задать системный веб-хук для MR появилась только в феврале 2018-го в версии 10.5.0, а на момент разработки модуля её не было, поэтому пришлось искать обходной путь.

Поискав в интернете, нашли такой инструмент: https://github.com/egnyte/gitlabform. С его помощью можно декларативно описать желаемые настройки проектов и применить их на все проекты одной командой.

Минимально рабочий конфиг, добавляющий к проектам веб-хук на MR – выглядит так:

gitlab:
url: "https://gitlab.magnifico.pro"
token: "auth_token_for_gitlabform"
api_version: 4
common_settings:
hooks:
"https://in.bizprofi.ru/bitrix/tools/bizprofi.gitlab/gitlab.php":
token: "secret_token_for_webhook"
push_events: false
merge_requests_events: true

Теперь мы можем получить то, что хотели, выполнив такую команду:

$ gitlabform -c /etc/gitlab-form.yml ALL

Чтобы команда автоматически применяла настройки к новым проектам, прописываем её выполнение раз в 10 минут в кронтабе на сервере с Gitlab’ом:

*/10 * * * * gitlabform -c /etc/gitlab-form.yml ALL &>> /var/log/gitlabform.log

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

Доработка Битрикс24

Создаём отдельный модуль, называем его “Интеграция с Gitlab”. Прописываем в установщике копирование служебного файла на URL, который мы ранее использовали в настройках репозиториев на Gitlab’е

Создаём отдельного пользователя для добавления комментариев, называем его “Gitlab Bot”. Прописываем идентификатор созданного пользователя и токены доступов в настройках модуля:

После чего садимся и пишем в виде ТЗ все возможные сценарии, которые могут произойти при вызове этого обработчика:

1. Что делать при открытии MR
2. Что делать при закрытии MR
3. Что делать при удалении MR
4. Что делать при мёрже MR
5. Что делать при переназначении MR
6. Что если не нашли задачу в Битрикс24
7. Что если не нашли пользователя в Битрикс24
8. Что если у пользователя нет прав на создание задач
9. Что если в настройках модуля задан некорректный токен … и ещё несколько десятков “что если” в таком духе.

Перенести все сценарии из текста в PHP — самая рутинная часть работы. Сложной логики в модуле особо нет и получается практически литературное программирование по тексту ТЗ.

Как в итоге выглядит работа модуля

Когда разработчик создаёт MR, на ревьюера ставится такая подзадача:

Любое изменение по MR отображается в комментариях базовой задачи:

Задача, поставленная на ревьюера, выглядит так:

Если к одной задаче относится больше, чем 1 MR (например, когда один — в репозиторий клиентского проекта, второй — в репозиторий переиспользуемой библиотеки), то они все перечисляются в описании задачи.

Задачи по ревью, которыми ревьюер занимался в течение дня попадают в ежедневный отчёт. Мы используем модуль расширенных отчётов, и у нас они выглядят так:

И также их можно видеть в плане на завтрашний день:

И даже двигать в личном плане либо канбане соответствующей группы:

Правило про комментарии

Поработав некоторое время с автоматическими комментариями, мы приняли дополнительное правило: каждое изменение статуса MR на Gitlab’е должно сопровождаться поясняющим комментарием к базовой задаче от того сотрудника, который стал причиной этого изменения.

Теперь, при возврате MR на доработку – нужно пояснить, в чём она состоит:

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

Доработав MR и вернув на ревью, прописать об этом явно:

+Товарищ Ревьюер, я всё исправил, посмотри сейчас.

Приняв MR описать, был ли он перенесён, или что с ним дальше стало.

+Товарищ Проект-менеджер, принято, перенесено на продакт.
+Товарищ Проект-менеджер, принято, будет перенесено на продакт завтра утром.

Всё же комментарий, написанный человеком, более понятен, чем комментарий, оставленный системным пользователем. Кроме того, упоминая другого сотрудника в комментарии, комментирующий за счёт модуля реагирования получает более быструю обратную связь.

Если подумать, то можно было бы принять это правило ещё в самом начале, до разработки интеграции, но исторически сложилось по-другому.

Итоги интеграции

В конечном счёте у нас получилось добиться, чтобы процесс разработки по описанной модели был системным и контролируемым:

1. Мы можем видеть все MR’ы в задачах на Битрикс24, планировать их выполнение, ставить им крайние сроки и напоминания, оставлять комментарии — в общем делать всё что угодно, что можно сделать с задачей.
2. Можем построить отчёт и проанализировать количество уходящего на ревью времени, видеть отклонения и понимать реальный объём работы по каждому проекту и каждой задаче в отдельности.
3. Весь процесс работы от момента постановки задачи до самого деплоя стал прозрачнее для всех участников.

Самая забавная часть процесса во всей этой истории про разработку модуля интеграции — это его оформление, как тиражного решения.

Чтобы модуль появился в маркетплейсе Битрикса, он должен пройти модерацию. Модерацию проводит специалист уровня первой линии техподдержки, ни про какие Gitlab’ы и MR’ы никогда не слышавший.

Более того, у модуля практически нет визуальной части, если не считать страницу с настройками в админке. Мы несколько раз созванивались с модератором и объясняли, в чём суть модуля, как его поставить и настроить, что он вообще делает и зачем он это делает, это было довольно трудно.

У меня осталось ощущение, что в итоге нам одобрили публикацию, просто поверив на слово. В общем мы поняли, что короткое описание к модулю на маркетплейсе скорее всего не впечатляет и написали этот материал. Теперь вы тоже можете поставить наш модуль у себя на портале и попробовать использовать его так же, как это делаем мы.