https://github.com/coore/glping
https://github.com/coore/glping
gitlab notifications
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/coore/glping
- Owner: CoOre
- License: mit
- Created: 2025-09-26T16:10:05.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-04T12:32:45.000Z (9 months ago)
- Last Synced: 2025-10-04T14:30:49.298Z (9 months ago)
- Topics: gitlab, notifications
- Language: Python
- Homepage:
- Size: 247 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# GitLab Ping
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/psf/black)
[](tests/)
[](.github/workflows/ci.yml)
[](https://pypi.org/project/glping/)
[](https://hub.docker.com/r/coore/glping)
[](https://github.com/sponsors/CoOre)
CLI-утилита для отслеживания событий в GitLab с push-уведомлениями.
## Функциональность
- Отслеживание событий во всех проектах GitLab
- Поддержка коммитов, Merge Requests, Issues, Pipeline и комментариев
- Кроссплатформенные push-уведомления с правильным стекированием
- Работа в режиме демона или однократный запуск
- Унифицированная система кэширования для предотвращения дублирования уведомлений
- Асинхронный режим для улучшенной производительности
## Установка
### Требования
- Python 3.9+
- GitLab personal access token
### Быстрая установка с помощью Makefile
**Для конечных пользователей:**
```bash
git clone https://github.com/CoOre/glping.git
cd glping
make prod-setup
```
**Для разработчиков:**
```bash
git clone https://github.com/CoOre/glping.git
cd glping
make dev-setup
```
### Ручная установка
```bash
git clone https://github.com/CoOre/glping.git
cd glping
pip install -e .
```
### Установка зависимостей
```bash
pip install -r requirements.txt
```
### Установка бинарника
```bash
# Установка пакета в системную директорию
pip install -e .
```
### Установка для macOS (рекомендуется)
Для правильной работы уведомлений на macOS установите `terminal-notifier`:
```bash
# Через Homebrew
brew install terminal-notifier
# Или вручную
curl -L https://github.com/julienXX/terminal-notifier/releases/download/2.0.0/terminal-notifier-2.0.0.zip -o terminal-notifier.zip
unzip terminal-notifier.zip
sudo cp terminal-notifier-2.0.0/terminal-notifier.app/Contents/MacOS/terminal-notifier /usr/local/bin/
```
## Конфигурация
1. Скопируйте файл конфигурации:
```bash
cp .env.example .env
```
2. Отредактируйте `.env` файл:
```env
GITLAB_URL=https://gitlab.example.com
GITLAB_TOKEN=your_private_token_here
CHECK_INTERVAL=60
CACHE_FILE=glping_cache.json
```
3. Создайте GitLab personal access token:
- Перейдите в Settings → Access Tokens
- Создайте токен с правами `read_api` и `read_repository`
## Использование
### Основные команды
```bash
# Запуск в режиме демона (по умолчанию)
glping
# Однократная проверка
glping --once
# Запуск с детальным логированием
glping --verbose
# Изменить интервал проверки
glping --interval 120
# Отслеживать только конкретный проект
glping --project 12345
# Сбросить кеш
glping --reset-cache
# Тестовое уведомление
glping --test-notification
# Тест стекирования уведомлений
glping --test-stacking
```
### Примеры использования
```bash
# Мониторинг всех проектов с интервалом 30 секунд
glping --daemon --interval 30 --verbose
# Проверка конкретного проекта один раз
glping --once --project 12345 --verbose
# Тестирование уведомлений
glping --test-notification
# Тестирование стекирования уведомлений
glping --test-stacking
```
### Автоматический запуск
#### Рекомендуемый способ: launchd (macOS)
Для macOS рекомендуется использовать встроенную систему launchd вместо crontab:
```bash
# Быстрая настройка
./launchd_setup.sh
# Проверить статус
launchctl list | grep glping
# Посмотреть логи
tail -f ~/glping/logs/glping.log
```
**Преимущества launchd:**
- ✅ Идеальные уведомления без "редактора скриптов"
- ✅ Автоматический перезапуск при сбоях
- ✅ Встроенное логирование
- ✅ Нативный для macOS
#### Альтернатива: crontab
Для использования в crontab указывайте полный путь к команде:
```bash
# Редактирование crontab
crontab -e
# Добавить строку (используйте полный путь):
* * * * * /usr/local/bin/glping --async --optimized --once --verbose >> ~/glping.log 2>&1
```
**Важно:** crontab использует ограниченное окружение, поэтому уведомления могут появляться "от редактора скриптов". Для правильных уведомлений используйте launchd.
### Управление сервисом (launchd)
```bash
# Запустить сервис
launchctl start com.glping.daemon
# Остановить сервис
launchctl stop com.glping.daemon
# Перезапустить сервис
launchctl kickstart -k gui/$(id -u)/com.glping.daemon
# Удалить сервис
./launchd_cleanup.sh
# Просмотр логов
tail -f ~/glping/logs/glping.log
tail -f ~/glping/logs/glping.error.log
```
### Использование Makefile
Makefile предоставляет удобные скрипты для установки и управления:
```bash
# Показать доступные команды
make help
# Проверить системные требования
make check-reqs
# Установка для конечных пользователей
make prod-setup
# Установка для разработчиков
make dev-setup
# Запустить все тесты
make test
# Тестировать уведомления
make test-notif
# Тестировать стекирования уведомлений
make test-stacking
# Удалить приложение
make uninstall
# Очистить артефакты сборки
make clean
```
## Поддерживаемые события
- **Коммиты** - новые коммиты и сообщения
- **Merge Requests** - создание, обновление, комментарии, закрытие, мёрдж
- **Issues** - создание, комментарии, закрытие, reopen
- **Pipeline** - успешное выполнение и падение
- **Комментарии** - ко всем сатегориям сущностей
## Архитектура
```
glping/
├── __init__.py # Пакетная информация и версия
├── main.py # Точка входа CLI
├── config.py # Конфигурация из .env
├── cache.py # Унифицированная система кэширования
├── lock.py # Утилиты файловой блокировки
├── base_gitlab_api.py # Базовый класс GitLab API
├── base_watcher.py # Базовый класс наблюдателя
├── gitlab_api.py # Синхронная обёртка для GitLab API
├── async_gitlab_api.py # Асинхронная обёртка для GitLab API
├── notifier.py # Push-уведомления с поддержкой стекирования
├── optimized_notifier.py # Оптимизированные уведомления
├── watcher.py # Синхронная основная логика
├── async_watcher.py # Асинхронная основная логика
├── assets/ # Ресурсы приложения
│ ├── glping-icon.png # Основная иконка
│ ├── glping-icon-128.png # Иконка 128px
│ └── glping-icon-256.png # Иконка 256px
├── utils/ # Утилиты
│ ├── __init__.py # Пакет утилит
│ ├── date_utils.py # Работа с датами и временем
│ ├── event_utils.py # Обработка событий
│ └── url_utils.py # Обработка URL
├── requirements.txt # Зависимости
├── setup.py # Установка пакета
├── pyproject.toml # Современная конфигурация проекта
├── .env.example # Пример конфигурации
├── com.glping.daemon.plist # launchd конфигурация для macOS
├── launchd_setup.sh # Скрипт настройки launchd
├── launchd_cleanup.sh # Скрипт очистки launchd
└── ~/glping/logs/ # Директория для логов launchd
```
### Ключевые компоненты
- **Базовые классы**: `BaseGitLabApi` и `BaseWatcher` обеспечивают переиспользование кода
- **Утилиты**: Модуль `utils` содержит функции для работы с датами, событиями и URL
- **Асинхронная поддержка**: Полная поддержка асинхронных операций для улучшенной производительности
- **Оптимизированные уведомления**: Умная система фильтрации и стекирования уведомлений
## Кэширование
Утилита использует унифицированный JSON файл (`glping_cache.json`) для хранения:
- Метаданных (дата установки, время последней проверки)
- ID последнего обработанного события для каждого проекта
- Времени последней активности проектов
Это предотвращает дублирование уведомлений и позволяет отслеживать только новые события. Система автоматически мигрирует данные из старых форматов кэша.
## Уведомления
Поддерживаются кроссплатформенные уведомления:
- **macOS** - системные уведомления с правильным стекированием через terminal-notifier
- **Linux** - notify2/libnotify с автоматическим определением DISPLAY
- **Windows** - win10toast
### Особенности реализации:
- **Стекирование уведомлений** на macOS - все уведомления остаются видимыми
- **Уникальные группы** для каждого уведомления предотвращают замену
- **Поддержка URL** - при клике на уведомление открывается соответствующая страница в GitLab
- **Кроссплатформенность** - единый API для всех операционных систем
- **Умное определение окружения** - автоматически адаптируется для cron/launchd
- **Оптимизация для macOS** - в cron окружении использует Finder вместо Terminal
### Устранение неполадок с уведомлениями
#### macOS: уведомления "от редактора скриптов"
Используйте launchd вместо crontab:
```bash
./launchd_setup.sh
```
#### Linux: нет уведомлений в cron
Убедитесь что установлен notify2:
```bash
pip install notify2
sudo apt-get install libnotify-bin
```
## Разработка
### Запуск в режиме разработки
```bash
python -m glping.main --once --verbose
```
### Тестирование
```bash
# Тестирование уведомлений
python -m glping.main --test-notification
# Тестирование стекирования уведомлений
python tests/test_notification_stacking.py
# Тестирование подключения
python -m glping.main --once --verbose
# Запуск всех тестов
make test
```
## Лицензия
MIT License - Copyright (c) 2025 Vladimir Nosov
## Управление сервисом
### Остановка и удаление launchd
```bash
./launchd_cleanup.sh
```
### Переход с crontab на launchd
```bash
# 1. Сохраните текущую crontab
crontab -l > crontab_backup.txt
# 2. Удалите glping из crontab
crontab -e
# Удалите строку с glping
# 3. Настройте launchd
./launchd_setup.sh
# 4. Проверьте работу
tail -f ~/glping/logs/glping.log
```
## Автор
Vladimir Nosov
## Репозиторий
https://github.com/CoOre/glping
## Дополнительная документация
- [LAUNCHD_SETUP.md](LAUNCHD_SETUP.md) - Подробная инструкция по настройке launchd
- [DEVELOPMENT.md](DEVELOPMENT.md) - Руководство для разработчиков
- [CONTRIBUTING.md](CONTRIBUTING.md) - Как внести вклад в проект
- [CHANGELOG.md](CHANGELOG.md) - Список изменений
- [ARCHITECTURE.md](ARCHITECTURE.md) - Архитектура проекта
## Установка через PyPI
```bash
pip install glping
```
## Скачивание бинарных файлов
Готовые бинарные файлы доступны в [релизах GitHub](https://github.com/CoOre/glping/releases):
- `glping-linux` - для Linux
- `glping-macos` - для macOS
- `glping-windows.exe` - для Windows