Skip to content

CoOre/glping

BranchesTags

Repository files navigation

GitLab Ping

Python Version License Code Style Tests CI/CD PyPI Version Docker GitHub Sponsors

CLI-утилита для отслеживания событий в GitLab с push-уведомлениями.

Функциональность

  • Отслеживание событий во всех проектах GitLab
  • Поддержка коммитов, Merge Requests, Issues, Pipeline и комментариев
  • Кроссплатформенные push-уведомления с правильным стекированием
  • Работа в режиме демона или однократный запуск
  • Унифицированная система кэширования для предотвращения дублирования уведомлений
  • Асинхронный режим для улучшенной производительности

Установка

Требования

  • Python 3.9+
  • GitLab personal access token

Быстрая установка с помощью Makefile

Для конечных пользователей:

git clone https://github.com/CoOre/glping.git
cd glping
make prod-setup

Для разработчиков:

git clone https://github.com/CoOre/glping.git
cd glping
make dev-setup

Ручная установка

git clone https://github.com/CoOre/glping.git
cd glping
pip install -e .

Установка зависимостей

pip install -r requirements.txt

Установка бинарника

# Установка пакета в системную директорию
pip install -e .

Установка для macOS (рекомендуется)

Для правильной работы уведомлений на macOS установите terminal-notifier:

# Через 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. Скопируйте файл конфигурации:
cp .env.example .env
  1. Отредактируйте .env файл:
GITLAB_URL=https://gitlab.example.com
GITLAB_TOKEN=your_private_token_here
CHECK_INTERVAL=60
CACHE_FILE=glping_cache.json
  1. Создайте GitLab personal access token:
    • Перейдите в Settings → Access Tokens
    • Создайте токен с правами read_api и read_repository

Использование

Основные команды

# Запуск в режиме демона (по умолчанию)
glping

# Однократная проверка
glping --once

# Запуск с детальным логированием
glping --verbose

# Изменить интервал проверки
glping --interval 120

# Отслеживать только конкретный проект
glping --project 12345

# Сбросить кеш
glping --reset-cache

# Тестовое уведомление
glping --test-notification

# Тест стекирования уведомлений
glping --test-stacking

Примеры использования

# Мониторинг всех проектов с интервалом 30 секунд
glping --daemon --interval 30 --verbose

# Проверка конкретного проекта один раз
glping --once --project 12345 --verbose

# Тестирование уведомлений
glping --test-notification

# Тестирование стекирования уведомлений
glping --test-stacking

Автоматический запуск

Рекомендуемый способ: launchd (macOS)

Для macOS рекомендуется использовать встроенную систему launchd вместо crontab:

# Быстрая настройка
./launchd_setup.sh

# Проверить статус
launchctl list | grep glping

# Посмотреть логи
tail -f ~/glping/logs/glping.log

Преимущества launchd:

  • ✅ Идеальные уведомления без "редактора скриптов"
  • ✅ Автоматический перезапуск при сбоях
  • ✅ Встроенное логирование
  • ✅ Нативный для macOS

Альтернатива: crontab

Для использования в crontab указывайте полный путь к команде:

# Редактирование crontab
crontab -e

# Добавить строку (используйте полный путь):
* * * * * /usr/local/bin/glping --async --optimized --once --verbose >> ~/glping.log 2>&1

Важно: crontab использует ограниченное окружение, поэтому уведомления могут появляться "от редактора скриптов". Для правильных уведомлений используйте launchd.

Управление сервисом (launchd)

# Запустить сервис
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 предоставляет удобные скрипты для установки и управления:

# Показать доступные команды
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:

./launchd_setup.sh

Linux: нет уведомлений в cron

Убедитесь что установлен notify2:

pip install notify2
sudo apt-get install libnotify-bin

Разработка

Запуск в режиме разработки

python -m glping.main --once --verbose

Тестирование

# Тестирование уведомлений
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

./launchd_cleanup.sh

Переход с crontab на launchd

# 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 inosovvv@gmail.com

Репозиторий

https://github.com/CoOre/glping

Дополнительная документация

Установка через PyPI

pip install glping

Скачивание бинарных файлов

Готовые бинарные файлы доступны в релизах GitHub:

  • glping-linux - для Linux
  • glping-macos - для macOS
  • glping-windows.exe - для Windows

About

No description or website provided.

Topics

notifications gitlab

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v0.1.0 Latest
Oct 8, 2025
+ 2 releases

Sponsor this project

Packages

No packages published

Contributors 2

  •  
  •  

Languages