SkillAgentSearch skills...

Alerthub

AlertHub is a simple tool written with NodeJS to get alerted from new GitHub and GitLab repository events.

GenerateConvertImprove

Install / Use

/learn @Ardakilic/Alerthub
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

AlertHub

   _   _           _                _
  /_\ | | ___ _ __| |_  /\  /\_   _| |__
 //_\\| |/ _ \ '__| __|/ /_/ / | | | '_ \
/  _  \ |  __/ |  | |_/ __  /| |_| | |_) |
\_/ \_/_|\___|_|   \__\/ /_/  \__,_|_.__/

AlertHub is a simple tool written with NodeJS to get alerted from GitHub and GitLab releases, tags and commits.

When you watch a release over GitHub, you also auto watch the issues and comments etc., however if you want to only follow new releases, or only commits or tags, there isn't a way to achieve this from GitHub directly.

There's been a service called sibbell.com, but they shut down on 15th May, 2018. That's why, I decided to make one for myself.

This simple cli tool watches the releases set in config, and notifies you with E-mail or PushBullet, and provides you an aggregated RSS feed which you can use in IFTTT or your personal feed reader.

Update 2018.11.28: GitHub now supports following the repositories' releases, however, it's still buggy for me, and they still don't cover the push notification feature which this tool offers.

Features

Some people still wonder why this tool, which was released before GitHub release feature announced, yet exists, so I wanted to list the features as a bullet list:

  • You can watch GitHub releases, tags, commits and issues
  • ~~You can also watch private GitHub repositories by providing an access token~~
  • You can watch GitLab tags and commits
  • You can watch 3rd party releases which are neither from GitHub nor GitLab
  • You can get notified with e-mail when a new update to your watch list is published
  • You can also get notified with push notification, using services PushBullet and / or PushOver
  • You can also get notified using Telegram bots. Just put your bot to the channels, or get your chat id, provide the bot token and your updates will be carried through the Telegram bot.
  • You can generate an aggreagated RSS feed with this tool for all your watches, which is sorted by date, and use this aggregated feed to source to your favorite news reader application, or to pipe to services such as IFTTT etc.
  • Self-hosted. Also, no GUI. You can simply set it and forget it

Requirements

  • NodeJS 20.x or newer
  • (Optional) PushBullet Api Key
  • (Optional) PushOver Api Key
  • (Optional) SMTP credentials to dispatch e-mail
  • (Optional) Telegram API key and Chat ID for the messages to be dispatched.

Installation

You can install and run AlertHub with some simple steps:

  1. Clone this repository or get the latest release version.
  2. Navigate to the repository's folder, and run npm install to install dependencies.
  3. Copy .env.example to .env and fill in your configuration values.

Development with Docker

AlertHub includes a comprehensive Makefile that runs all commands through Docker, ensuring a consistent development environment across different systems.

Prerequisites

  • Docker installed on your system
  • No need for Node.js locally - everything runs in containers

Quick Start

# Clone the repository
git clone https://github.com/Ardakilic/alerthub.git
cd alerthub

# Install dependencies
make install

# Initialize environment file
make init

# Run tests
make test

# Run tests with coverage
make test-coverage

# Run linting
make lint

# Fix linting issues automatically
make lint-fix

# Start the application
make start

Available Make Commands

| Command | Description | Docker Equivalent | |---------|-------------|-------------------| | make help | Show all available commands | - | | make install | Install dependencies | docker run ... npm install | | make test | Run all tests | docker run ... npm test | | make test-watch | Run tests in watch mode | docker run ... npm run test:watch | | make test-coverage | Run tests with coverage report | docker run ... npm run test:coverage | | make lint | Run code linting | docker run ... npm run lint | | make lint-fix | Auto-fix linting issues | docker run ... npm run lint:fix | | make start | Start the application | docker run ... npm start | | make init | Initialize .env file | docker run ... npm run init | | make clean | Clean node_modules and coverage | docker run ... rm -rf node_modules coverage | | make shell | Open interactive shell in container | docker run -it ... /bin/bash | | make check | Run lint + test | make lint test | | make check-all | Run lint + test with coverage | make lint test-coverage |

Testing

The project includes comprehensive test suites for all utilities:

# Run all tests
make test

# Run tests with detailed coverage report
make test-coverage

# Watch mode for development
make test-watch

# Run specific test files (using shell)
make shell
npm test rssGenerator.test.js
npm test rssMonitor.test.js

Code Quality

The project uses Biome for fast linting and formatting:

# Check code quality
make lint

# Automatically fix issues
make lint-fix

# Check everything (lint + test + coverage)
make check-all

Docker Details

All commands run in a Node.js 22 container with:

  • Image: node:22
  • Working Directory: /app (mapped to your project folder)
  • Environment: NODE_OPTIONS="--experimental-vm-modules" for ES modules support
  • Volume Mount: Your project directory is mounted for live development

Manual Docker Commands

If you prefer running Docker commands directly:

# Run tests with coverage
docker run --rm -v "$(pwd)":/app -w /app -e NODE_OPTIONS="--experimental-vm-modules" node:22 npm run test:coverage

# Run linting
docker run --rm -v "$(pwd)":/app -w /app -e NODE_OPTIONS="--experimental-vm-modules" node:22 npm run lint

# Start the application
docker run --rm -v "$(pwd)":/app -w /app -e NODE_OPTIONS="--experimental-vm-modules" node:22 npm start

# Interactive shell for debugging
docker run --rm -it -v "$(pwd)":/app -w /app -e NODE_OPTIONS="--experimental-vm-modules" node:22 /bin/bash

CI/CD Integration

For continuous integration, use the CI-specific targets:

# Run complete test suite with coverage for CI
make ci-test

# Run linting for CI
make ci-lint

These generate coverage reports in the ./coverage/ directory that can be uploaded to coverage services. 4. Run npm start or something like pm2 start npm -- start and run the application.

Configuration

AlertHub now uses environment variables for configuration. Copy the .env.example file to .env and modify the values according to your needs:

cp .env.example .env

Environment Variables

The configuration supports the following environment variables:

Application Settings

  • INTERVAL: Feed check interval in milliseconds (default: 60000)
  • USER_AGENT: User agent string for HTTP requests
  • GITHUB_TOKEN: GitHub token to bypass rate limits and access private repos
  • LOG_LEVEL: Logging level (debug, info, warn, error) (default: info)

Notification Settings

PushBullet:

  • PUSHBULLET_ENABLED: Enable PushBullet notifications (true/false)
  • PUSHBULLET_ACCESS_TOKEN: Your PushBullet access token

PushOver:

  • PUSHOVER_ENABLED: Enable PushOver notifications (true/false)
  • PUSHOVER_USER: PushOver user key
  • PUSHOVER_TOKEN: PushOver application token

Email:

  • EMAIL_ENABLED: Enable email notifications (true/false, default: true)
  • EMAIL_HOST: SMTP server hostname
  • EMAIL_PORT: SMTP server port (default: 465)
  • EMAIL_SECURE: Use secure connection (true/false, default: true)
  • EMAIL_AUTH_USER: SMTP username
  • EMAIL_AUTH_PASS: SMTP password
  • EMAIL_FROM: From email address
  • EMAIL_TO: Recipient email address(es)
  • EMAIL_SUBJECT_PREFIX: Subject line prefix

Telegram:

  • TELEGRAM_ENABLED: Enable Telegram notifications (true/false)
  • TELEGRAM_TOKEN: Telegram bot token
  • TELEGRAM_CHAT_ID: Telegram chat ID

RSS Feed Settings

  • RSS_ENABLED: Enable RSS feed server (true/false, default: true)
  • RSS_PORT: RSS server port (default: 3444)
  • RSS_TITLE: RSS feed title
  • RSS_DESCRIPTION: RSS feed description
  • RSS_INCLUDE_FROM_EACH_REPOSITORY: Number of releases per repository (default: 10)
  • RSS_COUNT: Total number of items in feed (default: 50)
  • RSS_SITE_URL: Site URL for the RSS feed
  • RSS_FEED_URL: Feed URL for self-reference

Repository Configuration

For repositories, you can use JSON format in environment variables:

  • GITHUB_RELEASES: JSON array of GitHub repositories for releases
  • GITHUB_TAGS: JSON array of GitHub repositories for tags
  • GITHUB_COMMITS: JSON object mapping repositories to branch arrays
  • GITHUB_ISSUES: JSON object mapping repositories to issue filter objects
  • GITLAB_TAGS: JSON array of GitLab repositories for tags
  • GITLAB_COMMITS: JSON object mapping repositories to branch arrays
  • EXTRAS: JSON array of direct RSS feed URLs

Example:

GITHUB_RELEASES='["Ardakilic/alerthub","expressjs/express"]'
GITHUB_COMMITS='{"laravel/laravel":["*"],"acikkaynak/acikkaynak":["master"]}'

Docker Container

Using Environment Variables (Recommended)

Create a .env file with your configuration and run:

docker run --name alerthub -d --env-file .env -p 3444:3444 ghcr.io/ardakilic/alerthub:2

Using Individual Environment Variables

docker run --name alerthub -d \
  -e GITHUB_RELEASES='["Ardakilic/alerthub","expressjs/express"]' \
  -e EMAIL_ENABLED=true \
  -e EMAIL_HOST=smtp.example.com \
  -e EMAIL_AUTH_USER=your@email.com \
  -e EMAIL_AUTH_PASS=yourpassword \
  -e EMAIL_TO=recipient@email.com \
  -p 3444:3444 \
  ghcr.io/ardakilic/alerthub:2

Changelog

I'll keep track of each release in the CHANGELOG.md.

Upgrading

Please refer to UPGRADING.md.

TODOs / Plans

  • ~~Telegram Notifications~~
  • ~~Following GitLab releases~~
  • Following BitBucket releases
  • Multi user feature
  • Per-repository webhooks
  • ~~Aggregated RSS~~
  • ~~Following commits and tags in additio

Ardakilic

View profile

View on GitHub
GitHub Stars223
CategoryDevelopment
Updated2mo ago
Forks10
Ardakilic/alerthub

Languages

JavaScript

Security Score

95/100

Audited on Jan 10, 2026

No findings