Доработка документации
This commit is contained in:
parent
e0939ef5f9
commit
690b39797f
GPG Key ID:
D3018BE7BA428CA6
@ -0,0 +1,27 @@
|
||||
# Общая архитектура
|
||||
|
||||
Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7.
|
||||
|
||||
## Схема БД
|
||||
Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab.
|
||||
|
||||
<figure markdown>
|
||||
{ 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.
|
||||
|
||||
## Отслеживание репозиториев
|
||||
Ключевым (рутовым) элементом являются репозитории.
|
||||
BIN
documentation/ru/docs/architecture/img/schema-database.png
Normal file
BIN
documentation/ru/docs/architecture/img/schema-database.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 754 KiB |
@ -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
|
||||
Команда для запуска выглядит следующим образом:
|
||||
|
||||
|
||||
@ -0,0 +1 @@
|
||||
# Создание токена GitLab
|
||||
@ -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>
|
||||
5
documentation/ru/docs/getting-started/first-start.md
Normal file
5
documentation/ru/docs/getting-started/first-start.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Инициализация бота
|
||||
|
||||
<video controls>
|
||||
<source id="mp4" src="../mp4/init-start.mp4" type="video/mp4">
|
||||
</videos>
|
||||
Binary file not shown.
BIN
documentation/ru/docs/getting-started/mp4/init-start.mp4
Normal file
BIN
documentation/ru/docs/getting-started/mp4/init-start.mp4
Normal file
Binary file not shown.
@ -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 }
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# :ninja: Конфиденциальность
|
||||
|
||||
|
||||
|
||||
Мое решение сфокусировано на приватности и прозрачности. Код и используемые зависимости полностью открыты и доступны для изучения и самостоятельной сборки.
|
||||
|
||||
Для работы бота токен доступа устанавливается в переменные среды и никуда не передается, кроме запросов в GitLab.
|
||||
@ -7,3 +9,17 @@
|
||||
Некоторые уведомления могут содержать чуствительную информацию. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о ваших репозиториях Телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
|
||||
|
||||
Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом коментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске.
|
||||
|
||||
## Несанкционированный доступ
|
||||
==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.==
|
||||
|
||||
Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает:
|
||||
|
||||
1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить.
|
||||
2. Когда бот получает сообщение, он проверяет идентификатор отправителя
|
||||
3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду
|
||||
4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры.
|
||||
|
||||
> Уведомления от GitLab всегда отправляются только указанному в конфигурации пользователю.
|
||||
|
||||
Демонстрация работы системы защиты:
|
||||
@ -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);
|
||||
|
||||
@ -1 +1,2 @@
|
||||
*[MR]: Merge Request
|
||||
*[БД]: База данных
|
||||
@ -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
|
||||
|
||||
1
documentation/ru/overrides/main.html
Normal file
1
documentation/ru/overrides/main.html
Normal file
@ -0,0 +1 @@
|
||||
{% extends "base.html" %}
|
||||
Loading…
Reference in New Issue
Block a user