Настройка документации

This commit is contained in:
Struchkov Mark 2023-02-26 18:37:28 +03:00
parent 1a2a0779ed
commit 56750a8219
Signed by: upagge
GPG Key ID: D3018BE7BA428CA6
10 changed files with 127 additions and 42 deletions

View File

@ -2,7 +2,8 @@
Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7.
## Схема БД
## Схема БД { id="schema-database" }
Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab.
<figure markdown>

Binary file not shown.

After

Width:  |  Height:  |  Size: 161 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

View File

@ -1,38 +1,108 @@
# :bell: Уведомления
Основное предназначение бота - это уведомления от GitLab. Вы будете получать только те уведомления, которые касаются вас непосредственно.
## Новый репозиторий
## Новый репозиторий { id="new-repository" }
Если во время первичной настройки вы указали, что хотите получать уведомления о новых репозиториях, то при появлении нового репозитория получите соответствующее уведомление:
<figure markdown>
![notify about new merge request](img/notify-new-project.png){ loading=lazy width="500" }
</figure>
Уведомление содержит:
- Project name — название репозитория.
- Project description — описание репозитория. Опционально, может быть пусто.
- Struchkov Mark — имя создателя репозитория в GitLab
Доступно три быстрых действия:
- :link: — ссылка на новый репозиторий в GitLab.
- :bell: — поставить на отслеживание. Вы начнете получать уведомления о событиях в MR, тредах и сборках.
- :no_bell: — не получать уведомления. Используется по умолчанию, по факту просто удаляет сообщение уведомления.
!!! warning ""
Пока вы явно не нажмете :bell:, вы не будете получать никаких уведомлений. Более того, приложение даже не будет запрашивать MR и прочие сущности репозитория, не будет сохранять их в БД.
## Новый MR { id="new-mr" }
Это уведомление приходит, когда вас назначают ответственным и/или ревьювером.
## Новый MR
Когда кто-то создает MR и назначает вас ответственным и/или ревьювером, то вам приходит уведомление. Из этого уведомления можно узнать название, короткое описание, теги, из какой ветки в какую открыт MR, кто его автор и кто ответственный.
<figure markdown>
![notify about new merge request](img/notify-new-mr.png){ loading=lazy width="500" }
</figure>
## Конфликт в MR
Уведомление содержит:
- Название MR.
- Описание MR. Опционально.
- Labels. Метки репозитория.
- Имя проекта.
- Ветки откуда куда мержим.
- Автор MR.
- Ответственный/Ревьюверы MR. Заполнение зависит от вашей позиции в этом MR. Если вы ответственный, то вам покажут ревьюверов. Если вы ревьювер, то ответственного.
Доступные быстрые действия:
- :eyes: — прочитано. Удаляет сообщение.
- :link: — ссылка на MR.
- :no_bell: — не получать уведомления по MR.
!!! warning ""
Учтите, что отключение уведомлений отключает только уведомления об изменениях в MR. Например, обновление статуса MR. Но уведомления по пайплайнам проекта, по тредам MR продолжат приходить.
## Конфликт в MR { id="conflict-mr" }
Если в вашем MR возник конфликт, то вы будете своевременно оповещены. В этом уведомлении указывается название MR, проект и ветка.
<figure markdown>
![notify about conflict in merge request](img/notify-conflict-mr.png){ loading=lazy width="500" }
</figure>
## Обновление MR
Когда кто-то делает коммиты в MR, в котором вы ответственный или ревьювер, вам сразу же приходит уведомление. Вы также сразу можете увидеть сколько задач еще не решено, и сколько созданных вами задач не было решено.
Доступные быстрые действия:
- :eyes: — прочитано. Удаляет сообщение.
- :link: — ссылка на MR.
- :no_bell: — не получать уведомления по этому MR.
## Обновление MR { id="update-mr" }
Если в MR, в котором вы являетесь ответственным/ревьювером, добавляются коммиты, вы получаете уведомление.
<figure markdown>
![notify about update in merge request](img/notify-update-mr.png){ loading=lazy width="500" }
</figure>
Уведомление содержит:
- Название MR.
- Отношение количества закрытых тредов к общему количеству созданных тредов.
- Отношение количества закрытых вами созданных тредов к общему количеству созданных вами тредов.
- Название репозитория.
- Имя создателя MR.
Доступные быстрые действия:
- :eyes: — прочитано. Удаляет сообщение.
- :link: — ссылка на MR.
- :no_bell: — не получать уведомления по этому MR.
## Изменение статуса MR
Когда статус вашего MR меняется, вы получаете уведомление.
<figure markdown>
![notify about update status in merge request](img/notify-update-status-mr.png){ loading=lazy width="500" }
</figure>
Доступные быстрые действия:
- :eyes: — прочитано. Удаляет сообщение.
- :link: — ссылка на MR.
## Новый тред в MR
В GitLab можно создавать не просто комментарии, а обсуждения (Discussions). Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете.
В GitLab можно создавать не просто комментарии, а треды. Если кто-то создаст такое обсуждение в вашем MR, то вы сразу об этом узнаете.
## Упоминание в треде
Допустим, кто-то упомянул вас в MR, нужен ваш совет. Автор этого MR не вы, ответственным назначали тоже не вас. Даже в этом случае вам придет уведомление, так вы не пропустите сообщения с вашим упоминанием.
## Ответ в дискусии
## Ответ в треде
Важно оставаться в теме обсуждения, поэтому при появлении новых ответов в дискуссия, в которых вы участвовали, вы получите уведомление.
Оно будет содержать начальное сообщение обсуждения, ваше последнее сообщение в нем, а также два последних комментария. Таким образом вы будете понимать о чем идет речь.

View File

@ -1,25 +0,0 @@
# :ninja: Конфиденциальность
Мое решение сфокусировано на приватности и прозрачности. Код и используемые зависимости полностью открыты и доступны для изучения и самостоятельной сборки.
Для работы бота токен доступа устанавливается в переменные среды и никуда не передается, кроме запросов в GitLab.
Некоторые уведомления могут содержать чуствительную информацию. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о ваших репозиториях Телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом коментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске.
## Несанкционированный доступ
==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.==
Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает:
1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить.
2. Когда бот получает сообщение, он проверяет идентификатор отправителя
3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду
4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры.
> Уведомления от GitLab всегда отправляются только указанному в конфигурации пользователю.
Демонстрация работы системы защиты:

View File

@ -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, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры.
<figure markdown>
![unauth-access.png](unauth-access.png){ loading=lazy width="500" }
<figcaption>уведомление о несанкционированном доступе</figcaption>
</figure>
Для злоумышленника все выглядит так, как будто бот не работает. Никаких ответных сообщений ему не отправляется.

Binary file not shown.

After

Width:  |  Height:  |  Size: 91 KiB

View File

@ -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);

View File

@ -1,2 +1,3 @@
*[MR]: Merge Request
*[БД]: База данных
*[Idea]: IDE IntelliJ IDEA

View File

@ -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