Как связать Gitlab с задачами в Shtab
Интеграция с GitLab помогает видеть, что происходит с кодом по задаче напрямую в Shtab. Можно посмотреть связанные запросы на слияние изменений (merge requests), проверить результаты сборки и тестов, а также узнать, кто и когда добавил изменения.
При этом задачи, описания, исполнители и сроки остаются в Shtab, а работа с кодом продолжается в GitLab.
Дополнительно можно настроить автоматизацию, чтобы события в GitLab меняли статус карточки. Например, после слияния MR задача будет переходить в нужный статус. В этой инструкции разберем, как подключить GitLab, связать репозиторий с проектом и пользоваться вкладкой Git в задачах.
Как получить токен GitLab
Для подключения понадобится Personal Access Token — токен, с помощью которого Shtab будет обращаться к GitLab. Интеграция использует права владельца токена, поэтому у этого пользователя должен быть доступ к нужным проектам.
В GitLab нажмите на аватар, выберите Edit profile и перейдите в Access → Personal access tokens. В меню Generate token выберите Legacy token.
Укажите название токена, например Shtab (1), задайте срок его действия (2) и выберите область доступа API (3).
Затем нажмите Create personal access token (4) и обязательно скопируйте созданный токен. После закрытия или обновления страницы посмотреть его повторно не получится.
Как подключить GitLab к Shtab
В Shtab в настройках компании перейдите в раздел Интеграции, нажмите на кнопку Подключить в правом верхнем углу и выберите GitLab.
В окне подключения необходимо:
- В поле Название подключения указать его название. Технически ни на что не влияет, просто поможет вам отличать разные соединения между собой.
- В поле URL git-сервера оставить https://gitlab.com или указать адрес собственного сервера GitLab. Здесь нужен адрес самого сервера, без пути к репозиторию и без окончания /api/v4.
- Вставить ранее созданный токен в поле Personal Access Token.
После этого нажмите на кнопку Подключить, дабы перейти к следующему шагу.
В следующем окне обязательно скопируйте Webhook URL и Webhook Secret, эти поля нам будут нужны в дальнейшем, чтобы Shtab мог проверять входящие события от GitLab.
Как настроить отправку событий из GitLab
Теперь осталось настроить вебхук, именно через него GitLab будет сообщать системе о коммитах, мердж-реквестах и результатах проверок.
Откройте нужный проект в GitLab и пройдите по пути Settings -> Webhooks -> Add new webhook.
В поле URL вставьте адрес из Shtab, а в Secret Token ранее скопированное значение Webhook Secret.
В разделе Trigger включите Push events и Merge request events. Эти события нужны нам, чтобы Shtab получал сведения об изменениях в ветках, коммитах и MR.
Если вы используете автоматические сборки и тесты, дополнительно включите Pipeline events и Job events. Первое событие передаст состояние пайплайна, а второе его отдельных заданий. Чтобы передавать комментарии к MR, включите Comment events. Для автоматизаций по результатам развертывания также нужно включить Deployment events.
Как только все будет готово, нажмите на кнопку Add Webhook. На каждый репозиторий нужен будет отдельный вебхук.
После сохранения можно проверить доставку событий через Test -> Push events. Для такой проверки в репозитории должен быть хотя бы один коммит. Успешный ответ подтвердит, что тестовый запрос дошел до нас. Если тест не проходит, проверьте адрес вебхука, совпадение секрета в GitLab и Shtab, а также активность подключения. Историю запросов и ответы от нашей системы можно посмотреть в Recent events при редактировании вебхука. Подробнее о проверке вебхуков.
Для появления MR в карточке также понадобится привязать репозиторий к проекту и указать номер задачи, об этом расскажем дальше.
Как привязать репозиторий к проекту Shtab
После подключения нужно указать, с каким проектом Shtab будет работать репозиторий.
Откройте нужный проект в справочнике, перейдите во вкладку Интеграции, выберите Git и нажмите на кнопку Привязать репозиторий.
Здесь можно настроить, как будут создаваться ветки и merge requests из карточек задач. В форме уже заполнены шаблоны, вы можете их оставить как есть или изменить под принятые в вашей команде правила. Значения в фигурных скобках Shtab будет заменять данными задачи.
Поле Шаблон имени ветки определит название ветки, которую вы создаете из карточки. По умолчанию используется {key}-{title}, где {key} — полный номер задачи, а {title} — ее название. Сохраните {key} в шаблоне, так как номер задачи будет нужен, чтобы связывать с ней последующие события из GitLab.
Поле Шаблон названия MR определяет название создаваемого merge request. По умолчанию используется {{ KEY }}: {{ task.title }}, где {{ KEY }} — ключ проекта, а {{ task.title }} — название задачи.
Важно: {{ KEY }} в этом шаблоне содержит только ключ проекта, без номера задачи. Поэтому полный номер задачи должен сохраняться в имени ветки.
В поле Шаблон описания MR можно настроить текст, который будет добавляться в описание создаваемого merge request. По умолчанию туда подставляются ссылка на карточку через {{ task.url }} и описание задачи через {{ task.description }}.
В поле Целевая ветка по умолчанию укажите ветку, в которую команда будет направлять изменения через MR, например, main или develop. Если оставить поле пустым, будет использоваться ветка репозитория по умолчанию.
Настройку Автопривязка по KEY в commit/MR нужно оставить включнной. С ее помощью Shtab сможет находить номер задачи в событиях из GitLab и связывать изменения с карточкой.
Для этого указывайте полный номер задачи, например PAY-42, в имени ветки, сообщении коммита или названии MR. Буквы в номере обязательно должны быть заглавными.
Когда все будет готово, нажмите «Привязать репозиторий» внизу формы. Созданная привязка появится в списке на этой странице.
Как связать изменения с задачей
Чтобы Shtab понял, к какой задаче относятся изменения, указывайте ключ этой задачи при работе в GitLab.
Например, для задачи PAY-42 можно создать ветку feature/PAY-42-card-payment, а в начале названия MR указать PAY-42.
Shtab ищет номер в имени ветки, сообщении коммита, названии и описании MR. Рекомендуем сохранять его как в имени ветки, так и в названии MR, чтобы последующие события также автоматом связывались с нужной задачей.
При обработке открытия MR Shtab добавляет в его описание ссылку на задачу, если у токена есть права на изменение MR. Это поможет из GitLab сразу переходить по ссылке к требованиям и обсуждению в карточке.
После настройки проверьте связь на новом MR с номером существующей задачи. Откройте эту карточку в Shtab и перейдите во вкладку Git, там должен появиться связанный с ней MR.
Вкладка Git в задачах
Откройте карточку задачи и нажмите Git в правой панели (1). Слева сверху будет отображен ключ задачи (2), а связанные с задачей MR будут отображены справа (3).
Вкладка Git показывает данные вокруг merge requests. Если вы создали только ветку или отправили коммит, но еще не открыли MR, отдельной строки для них здесь не будет.
Рядом с каждым MR будут показаны его название, ветки и состояние (Открыт, Влит, Закрыт). Рядом может отображаться статус пайплайна, например, Выполняется или Успешно. Это отдельные состояния, так как MR может все равно оставаться открытым, даже если все проверки уже прошли успешно.
Если с задачей связаны изменения из нескольких репозиториев, используйте фильтр в верхней части вкладки. Выберите нужный репозиторий, чтобы оставить только его MR, или вывод всех репозиториев, чтобы вернуться к общему списку.
Нажмите на стрелку слева от MR, чтобы раскрыть подробности, именно там можно будет информацию по коммитам и активности.
В коммитах можно посмотреть полученные изменения, их авторов и даты. Раскройте коммит, а затем его пайплайн, чтобы увидеть отдельные задания и результаты их выполнения.
Если MR отображается, но результатов проверок нет, убедитесь, что в GitLab настроен и запускался пайплайн, а в вебхуке включены Pipeline events и Job events.
У одного коммита может быть несколько запусков пайплайна. Они выводятся отдельно, поэтому можно увидеть и неудачный запуск, и последующий успешный.
В списке активности будут собраны полученные события по мердж-реквестам: открытие, одобрение, добавление коммитов и другие изменения.
Некоторые действия в GitLab можно выполнить прямо из задачи. Для этого нажмите + в верхней части вкладки Git и выберите нужное действие:
- Создать ветку создаст ветку в связанном репозитории для работы над задачей. Имя ветки сформируется по шаблону, который задан в настройках привязки.
- Создать MR создаст запрос на слияние и сразу свяжет его с карточкой. Даже если MR создан из Shtab, сохраняйте полный номер задачи в имени исходной ветки, так как он будет нужен в дальнейшем для связи будущих событий.
- Запустить pipeline запускает пайплайн для целевой ветки по умолчанию, указанной в настройках привязки. Важно не забывать об этом перед запуском, так как она может отличаться от ветки, в которой сейчас идет работа над задачей.
- Скопировать имя ветки копирует имя, сформированное для задачи по шаблону.
Как автоматически менять статус задачи
Чтобы после события в GitLab карточка переходила в другой статус, настройте автоматизацию для проекта.
Откройте раздел автоматизаций, нажмите + Автоматизация в правом верхнем углу и в списке автоматизаций создайте новую.
В поле Когда выберите триггер "Git: merge request влит".
Если по одной задаче создаются несколько MR и переход нужен только после слияния всех, добавьте условие "Все связанные MR влиты".
Затем выберите действие Изменить статус карточки и укажите статус, в который задача должна переходить после слияния.
Это не единственные триггеры и условия, связанные с Git, более подробно о работе автоматизации можно будет узнать в отдельной документации.
Ivan Savelyev