GitLab уведомления в Telegram

Важно своевременно получать уведомления о том, что вы ответственный за ревью Merge Request, или что в вашем MR конфликт. Также важно оперативно замечать комментарии от коллег-ревьюверов.

В таких системах как GitLab, BitBucket, GitHub уведомления реализуются чаще всего через email. Что на мой взгляд не удобно, и только создает помойку в рабочей почте, из-за чего можно пропустить важные письма.

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

Мне не удалось найти достойных аналогов. Есть похожие приложения, но обычно вас просят куда-то передать токен доступа от GitLab, или установить webhook на внешний сервис. Такие решение не допустимы в корпоративной разработке.

Мое решение сфокусировано на приватности и прозрачности. Код полностью открыт и доступен для изучения, а готовое приложение запускается у вас на ПК.

Возможности

Коротко опишу имеющиеся на данный момент возможности. Они актуальны как для облачной версии GitLab, так и для self-host инстанса, который может стоять у вас на работе.

Уведомление о новых MegeRequest

Когда кто-то создает MR и назначает вас ответственным, то вам приходит уведомление. Из этого уведомления можно узнать название, короткое описание, теги, из какой ветки в какую открыт MR, и кто его автор.

Уведомление о конфликте в вашем MergeRequests

Если в вашем MR возник конфликт, то вы будете своевременно оповещены. В этом уведомлении указывается название MR, проект и ветка.

Уведомление об обновлении MergeRequests

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

Уведомление об изменении статуса вашего MR

Когда статус вашего MR меняется, вы получаете уведомление.

Уведомление о новых задачах в ваших MR

В GitLab можно создавать не просто комментарии, а обсуждения (Discussions). Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете.

Уведомление при упоминаниях в комментариях

Допустим, кто-то упомянул вас в MR, нужен ваш совет. Автор этого MR не вы, ответственным назначали тоже не вас. Даже в этом случае вам придет уведомление, так вы не пропустите сообщения с вашим упоминанием.

Уведомления при ответах в дискуссии, в которой вы писали

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

Оно будет содержать начальное сообщение обсуждения, ваше последнее сообщение в нем, а также два последних комментария. Таким образом вы будете понимать о чем идет речь.

Отвечайте на комментарии прямо из Telegram

И киллер-фича. Допустим вас упомянули в обсуждении, сразу знаете что ответить? Не тратьте время, отвечайте прямо из телеграм. Для этого просто ответьте на сообщение и напишите ваш комментарий. Да да, спер идею из бота вастрика.

Общие моменты реализации

Бот изначально писался для уведомлений из BitBucket. Но BitBucket прикрыти свое self-host решение, поэтому все рабочие проекты переехали на GitLab и появилась необходимость в боте для GitLab.

Реализация простая, как доска. Раз в минуту по персональному токену из GitLab ходим в API с персональным токеном пользователя, и сохраняем данные по MR, Pipeline и прочем сущностям. Делается это чтобы знать, какие сущности новые, а какие уже были. Также загруженные данные испоьзуются для того, чтобы приложение могло отдавать какие-то данные не запрашивая GitLab, например бот может вернуть вам все MR, за которые вы отвечаете.

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

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

Дальнешие планы

Еще до того, как Apple выкатила свои «сводки уведомлений» и режимы фокусировки, у меня была идея сделать подобный функционал для бота. Чтобы можно было получать уведомления не моментально, а раз в час допустим, и вам приходила бы короткая сводка. Вот это в планах.

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

Также планирую добавить поддержку уведомлений по Issue, мы на проектах пользуемся Jira, но мне не сложно 🙂

Варинты запуска

Актуальное описание: https://struchkov.dev/blog/gitlab-telegram-bot/
GitHub: https://github.com/uPagge/gitlab-notification
Docker Hub: https://hub.docker.com/r/upagge/gitlab-telegram-notify

Какие варианты запуска поддерживаются:

1. Склонировать проект и запустить его прямо в Idea

2. Скачать Jar-файл релиза с GitHub и запустить его.

3. Запустить образ Docker

4. Запустить Docker Compose

Но сперва необходимо создать бота в Telegram, который будет отправлять вам уведомления

1. Создаем бота в Telegram, который будет посылать вам уведомления. Делается это тут.

2. После создания вы получите токен, сохраните его. Пример: 34534050345:FlfrleflerferfRE-ergerFLREF9ERF-NGjM

3. Теперь необходимо получить персональный токен в вашем GitLab. В правом верхнем углу нажмите на иконку своего аккаунта, далее Settings –> Personal Access Tokens. Укажите Scopes: api и нажмите Create a token.

Теперь разберемся, какие переменные нам понадобятся.

• TELEGRAM_BOT_TOKEN — токен, который вы получили при создании бота.

• TELEGRAM_BOT_USERNAME — название, которое вы дали боту. Оканчивается на bot.

• GITLAB_PERSONAL_TOKEN — токен, который вы получили в GitLab

• TELEGRAM_PERSON_ID — ваш id в telegram, можно узнать у этого бота

• GITLAB_URL — url на gitlab, локальный или облачный

• DATASOURCE_URL — ссылка на базу данных Postgres, в следующем формате: jdbc:postgresql://localhost:5432/bitbucket_bot_local

• DATASOURCE_USERNAME — пользователь БД

• DATASOURCE_PASSWORD — пароль от БД

Docker

Для примера, рассмотрим самый простой вариант запуска, испльзуя Docker.

sudo docker run --name gitlab-notify  \   --env TELEGRAM_BOT_TOKEN=value \   --env TELEGRAM_BOT_USERNAME=value \   --env GITLAB_PERSONAL_TOKEN=value \   --env TELEGRAM_PERSON_ID=value \   --env GITLAB_URL=value \   --env DATASOURCE_URL=jdbc:postgresql://localhost:5432/gitlab_bot \   --env DATASOURCE_USERNAME=postgres \   --env DATASOURCE_PASSWORD=value \   --network="host" upagge/gitlab-telegram-notify:latest

Заключение

Этот бот позволяет мне держать руку на пульсе, и не пропускать важные события в GitLab. Надеюсь, что он будет полезен кому-то еще.