diff --git a/documentation/ru/docs/architecture/concept.md b/documentation/ru/docs/architecture/concept.md index 56edb59..8064d3f 100644 --- a/documentation/ru/docs/architecture/concept.md +++ b/documentation/ru/docs/architecture/concept.md @@ -2,7 +2,8 @@ Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7. -## Схема БД +## Схема БД { id="schema-database" } + Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab.
diff --git a/documentation/ru/docs/features/img/notify-new-project.png b/documentation/ru/docs/features/img/notify-new-project.png new file mode 100644 index 0000000..f7bf54f Binary files /dev/null and b/documentation/ru/docs/features/img/notify-new-project.png differ diff --git a/documentation/ru/docs/features/img/notify-update-status-mr.png b/documentation/ru/docs/features/img/notify-update-status-mr.png new file mode 100644 index 0000000..289c766 Binary files /dev/null and b/documentation/ru/docs/features/img/notify-update-status-mr.png differ diff --git a/documentation/ru/docs/features/notify.md b/documentation/ru/docs/features/notify.md index 5a4fc27..c52fc2d 100644 --- a/documentation/ru/docs/features/notify.md +++ b/documentation/ru/docs/features/notify.md @@ -1,38 +1,108 @@ # :bell: Уведомления Основное предназначение бота - это уведомления от GitLab. Вы будете получать только те уведомления, которые касаются вас непосредственно. -## Новый репозиторий +## Новый репозиторий { id="new-repository" } +Если во время первичной настройки вы указали, что хотите получать уведомления о новых репозиториях, то при появлении нового репозитория получите соответствующее уведомление: +
+![notify about new merge request](img/notify-new-project.png){ loading=lazy width="500" } +
+ +Уведомление содержит: + +- Project name — название репозитория. +- Project description — описание репозитория. Опционально, может быть пусто. +- Struchkov Mark — имя создателя репозитория в GitLab + +Доступно три быстрых действия: + +- :link: — ссылка на новый репозиторий в GitLab. +- :bell: — поставить на отслеживание. Вы начнете получать уведомления о событиях в MR, тредах и сборках. +- :no_bell: — не получать уведомления. Используется по умолчанию, по факту просто удаляет сообщение уведомления. + +!!! warning "" + + Пока вы явно не нажмете :bell:, вы не будете получать никаких уведомлений. Более того, приложение даже не будет запрашивать MR и прочие сущности репозитория, не будет сохранять их в БД. + +## Новый MR { id="new-mr" } +Это уведомление приходит, когда вас назначают ответственным и/или ревьювером. -## Новый MR -Когда кто-то создает MR и назначает вас ответственным и/или ревьювером, то вам приходит уведомление. Из этого уведомления можно узнать название, короткое описание, теги, из какой ветки в какую открыт MR, кто его автор и кто ответственный.
![notify about new merge request](img/notify-new-mr.png){ loading=lazy width="500" }
-## Конфликт в MR +Уведомление содержит: + +- Название MR. +- Описание MR. Опционально. +- Labels. Метки репозитория. +- Имя проекта. +- Ветки откуда куда мержим. +- Автор MR. +- Ответственный/Ревьюверы MR. Заполнение зависит от вашей позиции в этом MR. Если вы ответственный, то вам покажут ревьюверов. Если вы ревьювер, то ответственного. + +Доступные быстрые действия: + +- :eyes: — прочитано. Удаляет сообщение. +- :link: — ссылка на MR. +- :no_bell: — не получать уведомления по MR. + +!!! warning "" + + Учтите, что отключение уведомлений отключает только уведомления об изменениях в MR. Например, обновление статуса MR. Но уведомления по пайплайнам проекта, по тредам MR продолжат приходить. + +## Конфликт в MR { id="conflict-mr" } Если в вашем MR возник конфликт, то вы будете своевременно оповещены. В этом уведомлении указывается название MR, проект и ветка.
![notify about conflict in merge request](img/notify-conflict-mr.png){ loading=lazy width="500" }
-## Обновление MR -Когда кто-то делает коммиты в MR, в котором вы ответственный или ревьювер, вам сразу же приходит уведомление. Вы также сразу можете увидеть сколько задач еще не решено, и сколько созданных вами задач не было решено. +Доступные быстрые действия: + +- :eyes: — прочитано. Удаляет сообщение. +- :link: — ссылка на MR. +- :no_bell: — не получать уведомления по этому MR. + +## Обновление MR { id="update-mr" } +Если в MR, в котором вы являетесь ответственным/ревьювером, добавляются коммиты, вы получаете уведомление.
![notify about update in merge request](img/notify-update-mr.png){ loading=lazy width="500" }
+Уведомление содержит: + +- Название MR. +- Отношение количества закрытых тредов к общему количеству созданных тредов. +- Отношение количества закрытых вами созданных тредов к общему количеству созданных вами тредов. +- Название репозитория. +- Имя создателя MR. + +Доступные быстрые действия: + +- :eyes: — прочитано. Удаляет сообщение. +- :link: — ссылка на MR. +- :no_bell: — не получать уведомления по этому MR. + ## Изменение статуса MR Когда статус вашего MR меняется, вы получаете уведомление. +
+![notify about update status in merge request](img/notify-update-status-mr.png){ loading=lazy width="500" } +
+ +Доступные быстрые действия: + +- :eyes: — прочитано. Удаляет сообщение. +- :link: — ссылка на MR. + ## Новый тред в MR -В GitLab можно создавать не просто комментарии, а обсуждения (Discussions). Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете. +В GitLab можно создавать не просто комментарии, а треды. Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете. ## Упоминание в треде Допустим, кто-то упомянул вас в MR, нужен ваш совет. Автор этого MR не вы, ответственным назначали тоже не вас. Даже в этом случае вам придет уведомление, так вы не пропустите сообщения с вашим упоминанием. -## Ответ в дискусии +## Ответ в треде Важно оставаться в теме обсуждения, поэтому при появлении новых ответов в дискуссия, в которых вы участвовали, вы получите уведомление. Оно будет содержать начальное сообщение обсуждения, ваше последнее сообщение в нем, а также два последних комментария. Таким образом вы будете понимать о чем идет речь. \ No newline at end of file diff --git a/documentation/ru/docs/privacy.md b/documentation/ru/docs/privacy.md deleted file mode 100644 index 029b66e..0000000 --- a/documentation/ru/docs/privacy.md +++ /dev/null @@ -1,25 +0,0 @@ -# :ninja: Конфиденциальность - - - -Мое решение сфокусировано на приватности и прозрачности. Код и используемые зависимости полностью открыты и доступны для изучения и самостоятельной сборки. - -Для работы бота токен доступа устанавливается в переменные среды и никуда не передается, кроме запросов в GitLab. - -Некоторые уведомления могут содержать чуствительную информацию. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о ваших репозиториях Телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений. - -Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом коментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске. - -## Несанкционированный доступ -==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.== - -Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает: - -1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить. -2. Когда бот получает сообщение, он проверяет идентификатор отправителя -3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду -4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры. - -> Уведомления от GitLab всегда отправляются только указанному в конфигурации пользователю. - -Демонстрация работы системы защиты: \ No newline at end of file diff --git a/documentation/ru/docs/privacy/index.md b/documentation/ru/docs/privacy/index.md new file mode 100644 index 0000000..47c897b --- /dev/null +++ b/documentation/ru/docs/privacy/index.md @@ -0,0 +1,40 @@ +# :ninja: Конфиденциальность + +Я разработчик, и это приложение должно помогать мне работать, оптимизируя мое время взаимодействия с GitLab. В какой-то момент я решил подлиться своими наработками со всеми желающими. Часто в GitLab содержится множество конфиденциальной информации, которую не хотелось бы раскрывать. Эта страница пытается ответить на все вопросы, которые могут вас смущать. + +!!! tip "Доверие" + + Вы не должны верить мне на слово. Вы можете [самостоятельно изучить код, он открыт и не сложен.](https://github.com/uPagge/gitlab-notification) После проверки можно самостоятельно собрать jar и упаковать его в Docker. Либо запускать код прямо из Idea. + +## Защита токена GitLab +Для работы ассистента необходим персональный токен GitLab. Он указывается в переменные среды и нигде дополнительно не дублируется. Таким образом токен не попадает в Telegram и хранится только у вас на компьютере и в контейнере приложения. + +Токен используется только при обращении к указанному GitLab, и только для выполнения описанных в документации возможностей. Никакой скрытой работы не выполняется, по возможности обо всех взаимодействиях с GitLab дополнительно сообщается во время настройки. + +## Уровни конфиденциальности + +Некоторые уведомления могут содержать множество чувствительной информации. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о вашей разработке телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений. + +Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом комментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске. + +## Сохранение в БД +Для работы ассистента ему нужно сохранять предыдущее состояние GitLab сущностей. Для этого используется БД. Приложение старается не хранить в БД больше данных, чем необходимо. Как только необходимость в данных теряется, например MR мержится, данные из БД удаляются. + +Прочитать подробнее можно в разделе: [Работа с базой данных](../architecture/concept.md#schema-database) + +## Несанкционированный доступ +==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.== + +Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает: + +1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить. +2. Когда бот получает сообщение, он проверяет идентификатор отправителя +3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду +4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры. + +
+ ![unauth-access.png](unauth-access.png){ loading=lazy width="500" } +
уведомление о несанкционированном доступе
+
+ +Для злоумышленника все выглядит так, как будто бот не работает. Никаких ответных сообщений ему не отправляется. \ No newline at end of file diff --git a/documentation/ru/docs/privacy/unauth-access.png b/documentation/ru/docs/privacy/unauth-access.png new file mode 100644 index 0000000..263a505 Binary files /dev/null and b/documentation/ru/docs/privacy/unauth-access.png differ diff --git a/documentation/ru/docs/stylesheets/extra.css b/documentation/ru/docs/stylesheets/extra.css index 441dc22..89da677 100644 --- a/documentation/ru/docs/stylesheets/extra.css +++ b/documentation/ru/docs/stylesheets/extra.css @@ -1,13 +1,11 @@ -.md-typeset .admonition, -.md-typeset details { - border-width: 0; - border-left-width: 4px; -} - .md-typeset .admonition, .md-typeset details { font-size: 0.75rem; } +.md-typeset h1, .md-typeset h2 { + font-weight: 500; +} + @keyframes heart { 0%, 40%, 80%, 100% { transform: scale(1); diff --git a/documentation/ru/includes/abbreviations.md b/documentation/ru/includes/abbreviations.md index 8fc676c..b6cc5eb 100644 --- a/documentation/ru/includes/abbreviations.md +++ b/documentation/ru/includes/abbreviations.md @@ -1,2 +1,3 @@ *[MR]: Merge Request -*[БД]: База данных \ No newline at end of file +*[БД]: База данных +*[Idea]: IDE IntelliJ IDEA \ No newline at end of file diff --git a/documentation/ru/mkdocs.yml b/documentation/ru/mkdocs.yml index f3f38b9..c97a395 100644 --- a/documentation/ru/mkdocs.yml +++ b/documentation/ru/mkdocs.yml @@ -7,7 +7,7 @@ edit_uri: edit/develop/documentation/ru/docs nav: - О проекте: index.md - - Конфиденциальность: privacy.md + - Конфиденциальность: privacy/index.md - Возможности: - Уведомления: features/notify.md - Быстрые действия: features/interaction-gitlab.md