Доработка документации

This commit is contained in:
Struchkov Mark 2023-02-26 13:56:57 +03:00
parent e0939ef5f9
commit 690b39797f
Signed by: upagge
GPG Key ID: D3018BE7BA428CA6
14 changed files with 172 additions and 17 deletions

View File

@ -0,0 +1,27 @@
# Общая архитектура
Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7.
## Схема БД
Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab.
<figure markdown>
![schema-database.png](img/schema-database.png){ loading=lazy }
<figcaption>Схема приложения версия 1.0.0</figcaption>
</figure>
Важно подчеркнуть, что приложение не сохраняет все бездумно в БД. Во время первого запуска вам будет задан ряд вопросов, ответы на которые повлияют на наполнение БД.
Также приложение старается не хранить лишние данные. Например, если MR был вмержен или закрыт, то нет смысла хранить информацию об этом MR, поэтому при следующем сканировании запись об этом MR, а также обо всех связанных сущностях этого MR (пайплайны, треды...) будут удалены.
## Сканирование GitLab
Раз в 1 минуту происходит обращение к GitLab API с вашим персональным токеном. Получаемые от GitLab данные сверяются с имеющимися в БД, после чего формируются уведомления, если обнаружены изменения.
!!! question "Почему не использовать Webhook?"
Не везде имется возможность установить произвольные Webhook. Например, вряд ли кто-то позволит вам установить Webhook из корпоративного GitLab во внешнюю сеть. Переодическое обращение к GitLab API можно выполнять прямо с рабочей машины.
В будущем планирую добавить поддержку и Webhook.
## Отслеживание репозиториев
Ключевым (рутовым) элементом являются репозитории.

Binary file not shown.

After

Width:  |  Height:  |  Size: 754 KiB

View File

@ -1,24 +1,89 @@
Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4.
# Первый запуск ассистента
## Создание бота в Telegram
Перед запуском необходимо создать бота в Telegram. Для этого перейдите в официального бота [@GodFather](https://t.me/BotFather) и выполните команду `/newbot`.
Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4.
Первым делом вам предложат ввести имя для бота.
## Конфигурация
Несмотря на то, какой вариант запуска вы виберете, необходимо будет указать следующие переменные среды:
Несмотря на то, какой вариант запуска вы вберете, необходимо указать следующие переменные среды:
* `TELEGRAM_BOT_TOKEN` — токен, который вы получили при создании бота.
* `TELEGRAM_BOT_TOKEN` — токен, который вы получили при [создании бота](creating-telegram-bot.md).
* `TELEGRAM_BOT_USERNAME` — название, которое вы дали боту. Оканчивается на bot.
* `GITLAB_PERSONAL_TOKEN` — токен, который вы получили в GitLab
* `TELEGRAM_PERSON_ID` — ваш id в telegram, можно узнать тут.
* `GITLAB_URL` — url на gitlab. Локальный или облачный.
* `DATASOURCE_URL` — ссылка на базу данных Postgres, в следующем формате: jdbc:postgresql://localhost:5432/gitlab_bot
* `GITLAB_PERSONAL_TOKEN` — токен, который вы [получили в GitLab.](create-gitlab-token.md)
* `TELEGRAM_PERSON_ID` — ваш идентификатор в telegram, можно узнать в боте [@myidbot](@myidbot).
* `GITLAB_URL` — url на GitLab. Локальный или облачный.
* `DATASOURCE_URL` — ссылка на базу данных Postgres, в следующем формате: `jdbc:postgresql://databasehost:5432/gitlab_bot`
* `DATASOURCE_USERNAME` — пользователь БД
* `DATASOURCE_PASSWORD` — пароль от БД
## Запуск Docker Compose
Самый простой способ запустить ассистента, - это docker compose. Создайте файлы `docker-compose.yml` и `.env`. Не забудьте в `.env` указать все необходимые для запуска переменные.
=== ":simple-docker: docker-compose.yml"
``` yaml
version: '3.8'
services:
gitlab-bot-database:
image: postgres:15.1-alpine
restart: always
hostname: gitlab-bot-database
container_name: gitlab-bot-database
networks:
gitlab-bot:
environment:
POSTGRES_DB: "gitlab_bot"
POSTGRES_USER: "postgres"
POSTGRES_PASSWORD: ${DATASOURCE_PASSWORD}
volumes:
- gitlab-bot-database:/var/lib/postgresql/data/
gitlab-bot:
image: upagge/gitlab-telegram-notify:latest
hostname: gitlab-bot
container_name: gitlab-bot
networks:
gitlab-bot:
depends_on:
- gitlab-bot-database
environment:
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME}
GITLAB_PERSONAL_TOKEN: ${GITLAB_PERSONAL_TOKEN}
TELEGRAM_PERSON_ID: ${TELEGRAM_PERSON_ID}
GITLAB_URL: ${GITLAB_URL}
DATASOURCE_URL: "jdbc:postgresql://gitlab-bot-database:5432/gitlab_bot"
DATASOURCE_USERNAME: ${DATASOURCE_USERNAME}
DATASOURCE_PASSWORD: ${DATASOURCE_PASSWORD}
volumes:
gitlab-bot-database:
networks:
gitlab-bot:
```
=== ":octicons-file-16: .env"
``` properties
TELEGRAM_BOT_TOKEN=
TELEGRAM_BOT_USERNAME=
GITLAB_PERSONAL_TOKEN=
TELEGRAM_PERSON_ID=
GITLAB_URL=
DATASOURCE_USERNAME=
DATASOURCE_PASSWORD=
```
Теперь запустите композ:
``` shell
docker compose up -d
```
## Запуск Docker
Команда для запуска выглядит следующим образом:

View File

@ -0,0 +1 @@
# Создание токена GitLab

View File

@ -0,0 +1,18 @@
# Регистрируем бота в Telegram
Перед первым запуском необходимо создать бота в Telegram. Для этого перейдите в официального бота [@GodFather](https://t.me/BotFather) и выполните команду `/newbot`.
!!! warning "Имя бота"
Первые два пункта диалогового меню будет про название бота. Учтите, что это называние общедоступно и случайноы пользователь Telegram сможет найти вашего бота.
Не переживайте, приложение имеет встроенную защиту от несанкционарованного доступа к боту. Но не смотря на это, ==не рекомендуется использовать в названии бота название организации, или вашу фамилию. Лучше использовать случайное имя.==
После регистрации вам будет выдан токен доступа. Он будет использоваться при запуске ассистента.
Видео процесса:
<figure>
<video width="70%" controls>
<source id="mp4" src="../mp4/create-telegram-bot.mp4" type="video/mp4">
</videos>
</figure>

View File

@ -0,0 +1,5 @@
# Инициализация бота
<video controls>
<source id="mp4" src="../mp4/init-start.mp4" type="video/mp4">
</videos>

View File

@ -7,10 +7,24 @@ hide:
---
# GitLab Notification Персональный Telegram бот для GitLab
Персональный ассистент для взаимодействия с GitLab. Получайте уведомления о событиях в GitLab: новые MR, где вы ревьювер, конфликты в ваших MR, уведомления о новых сообщениях в тредах, где вы являетесь участником, и многое другое.
Персональный ассистент для упрощения работы с GitLab. Получайте персональные уведомления о событиях в GitLab: новый MR на ревью, новый ответ в треде и многое другое.
Бота можно запустить как для облачного GitLab, так и для Self-host решений.
!!! info "GodFather Telegram"
Данный проект использует другой мой проект GodFather Telegram для создания Tlegram ботов различной сложности.
[:material-robot: Создать бота ассистента](getting-started/configuration.md){ .md-button .md-button--primary }
## Основные возможности
- Уведомление о появлении нового репозитория.
- Уведомление о новых MR.
- Уведомление о возникновении конфликта в MR.
- Уведомление о смене статуса вашего MR.
- Уведомление о треде, в которых вас упоминают в формате @nickname.
- Уведомит о новом треде в вашем MR.
- Уведомит о закрытии вашего треда в чужом MR.
- Уведомление о результате сборки.
***
[:material-robot: Создать персонального ассистента](getting-started/configuration.md){ .md-button .md-button--primary }

View File

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

View File

@ -4,6 +4,10 @@
border-left-width: 4px;
}
.md-typeset .admonition, .md-typeset details {
font-size: 0.75rem;
}
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);

View File

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

View File

@ -12,9 +12,12 @@ nav:
- Уведомления: features/notify.md
- Быстрые действия: features/interaction-gitlab.md
- Быстрый старт:
- Запуск: getting-started/configuration.md
# - Архитектура:
# - Концепт: architecture/concept.md
- getting-started/create-gitlab-token.md
- getting-started/creating-telegram-bot.md
- getting-started/configuration.md
- getting-started/first-start.md
- Архитектура:
- Общее: architecture/concept.md
# - Блог:
# - blog/index.md
- "Поддержать разработку":
@ -111,9 +114,9 @@ markdown_extensions:
- md_in_html
- footnotes
- toc:
permalink: true
toc_depth: 3
title: Содержание
permalink: ⚓︎
extra_css:
- stylesheets/extra.css

View File

@ -0,0 +1 @@
{% extends "base.html" %}