GitHub Release Monitor: A Friendly, End-to-End Guide to Never Missing an Open-Source Release Again

Imagine waking up to a concise e-mail that reads:
“React 18.3.0 stable is out—changelog here.”
No browser tabs, no frantic Twitter scrolling, no missed security patches.
This post shows you—step by step—how to make that happen.

Table of Contents

  1. What Exactly Is GitHub Release Monitor?
  2. Core Features at a Glance
  3. Tech Stack for the Curious
  4. Docker-Compose Deployment (Recommended)
  5. Single-Container Quick Start
  6. Manual Installation
  7. First-Time Tour of the Interface
  8. Configuration Recipes for Common Scenarios
  9. Troubleshooting Checklist
  10. Frequently Asked Questions
  11. Extending the Tool
  12. Final Thoughts

1. What Exactly Is GitHub Release Monitor?

GitHub Release Monitor is a small, self-hosted web application that:

  • Watches any public GitHub repository for new releases
  • Sends you an e-mail the moment a release (or pre-release, or draft) appears
  • Lets you decide—globally or per repo—which types of releases matter to you
  • Runs happily on a $5 VPS, a home NAS, or your laptop inside Docker

Think of it as a specialized newsreader that speaks only one language: “Hey, your tracked repo just shipped v2.4.0.”

2. Core Features at a Glance

Benefit How It Helps Day-to-Day
Automatic polling Checks GitHub in the background; no cron jobs to maintain
Instant e-mail alerts Arrive within minutes of a new tag
Fine-grained filters Ignore alphas, watch only betas, or track everything
Responsive UI Works on phones, tablets, and desktops
Import/export Move your list of repos between machines in seconds
Built-in diagnostics One click to test GitHub API connectivity and SMTP
Simple login Just username + password; no OAuth dance

3. Tech Stack for the Curious

Layer Technology
Framework Next.js (App Router)
Language TypeScript
Styling Tailwind CSS + ShadCN UI
Internationalisation next-intl (English & German out of the box)
Auth iron-session (encrypted cookies)
E-mail Nodemailer

All of this ships as a single container image (~250 MB).

4. Docker-Compose Deployment (Recommended)

This method gives you:

  • Automatic HTTPS via Let’s Encrypt
  • A local SMTP relay so you don’t need external mail credentials
  • Restart policies, log rotation, and a single docker-compose down to clean up

4.1 Prerequisites

  • Docker + Docker Compose installed
  • A domain you control (e.g. releases.example.com) pointing to your server
  • Ports 80 and 443 free

4.2 Grab the Sample Files

git clone https://github.com/iamspido/github-release-monitor.git
cd github-release-monitor/example

You will see three folders:

  • traefik/ – reverse proxy and certificate manager
  • smtp/ – optional local mail server
  • github-release-monitor/ – the main application

4.3 Configure the Main App

cd github-release-monitor
cp env.example .env
nano .env

Fill in the blanks:

# 1. Auth (required)
AUTH_SECRET=GENERATE_WITH: openssl rand -base64 32
AUTH_USERNAME=yourUser
AUTH_PASSWORD=yourPass

# 2. GitHub (optional but highly recommended)
GITHUB_ACCESS_TOKEN=ghp_xxxxxxxxxxxx  # no scopes needed for public repos

# 3. E-mail (the local SMTP defaults are fine)
MAIL_FROM_ADDRESS=notify@example.com
MAIL_TO_ADDRESS=you@example.com

Leave MAIL_HOST=smtp and MAIL_PORT=25 untouched if you use the bundled SMTP relay.

4.4 Point Traefik to Your Domain

Edit example/traefik/compose.yaml:

command:
  - "--certificatesresolvers.letsencrypt.acme.email=you@example.com"

4.5 Optional – Customise the SMTP Relay

Edit example/smtp/compose.yaml:

environment:
  - POSTFIX_myhostname=example.com
  - OPENDKIM_DOMAINS=example.com=mail

These lines reduce the chance that your mail lands in spam.

4.6 Create the Host Data Directory

cd github-release-monitor
mkdir -p data
sudo chown -R 1001:1001 data   # match container user

4.7 Start Everything in Order

# 1. Reverse proxy network
docker compose -f traefik/compose.yaml up -d

# 2. Mail server
docker compose -f smtp/compose.yaml up -d

# 3. Main app
docker compose -f github-release-monitor/compose.yaml up -d

Visit https://releases.example.com and log in with the credentials you set earlier.

5. Single-Container Quick Start

Perfect for local testing or when you already have an external SMTP server.

mkdir -p data && sudo chown -R 1001:1001 data
docker run -d \
  -p 8080:3000 \
  -v "$PWD/data:/app/data" \
  --env-file .env \
  --name github-release-monitor \
  ghcr.io/iamspido/github-release-monitor:latest

Open http://localhost:8080.

6. Manual Installation

Choose this route if you want to hack on the code or run on exotic hardware.

6.1 Clone and Install

git clone https://github.com/iamspido/github-release-monitor.git
cd github-release-monitor
npm install

6.2 Prepare the Data Folder

mkdir data
sudo chown $(whoami) data

6.3 Create Your .env

cp .env.example .env
# edit to match the variables in section 4.3

6.4 Run

Development (hot-reload):

npm run dev

Production:

npm run build
npm run start

7. First-Time Tour of the Interface

  1. Add Your First Repository
    Dashboard → “Add Repository” → type facebook/react → Save.
    The app fetches releases on the spot; if one is new, an e-mail is sent immediately.

  2. Global Filters
    Settings → Global Filters → toggle Stable, Pre-release, Draft as desired.

  3. Per-Repository Override
    Repository card → Edit → Override Global → pick tags like beta or rc.

  4. Test E-mail
    Settings → Diagnostics → Send Test E-mail. Check your inbox.

  5. Export/Import
    Settings → Data → Export JSON.
    Copy the file to another instance → Import JSON → done.

8. Configuration Recipes for Common Scenarios

8.1 “I Only Care About Stable Releases”

  • Global Filters → Stable = ON, Pre-release = OFF, Draft = OFF
  • Leave all repos on “Use Global”
  • Result: inbox stays quiet until a full semantic version appears

8.2 “Frontend Team Wants Next.js Canary Builds”

  • Add vercel/next.js
  • Edit → Override → Pre-release = ON → Tag filter = canary
  • Ignore alphas and betas

8.3 “Sharing a Curated List Internally”

  1. Maintainer adds 30 repos
  2. Settings → Export JSON → upload to shared drive
  3. New teammate: Import JSON → 10 seconds to parity

9. Troubleshooting Checklist

Symptom Quick Check
Site unreachable docker ps shows container exited? docker logs <container>
Certificate warning Traefik logs: docker logs traefik → search acme
E-mail in spam Align POSTFIX_myhostname with DNS A/AAAA records; add SPF/DKIM
API 403 Token expired? Private repo needs repo scope
German UI Browser language priority; append ?locale=en to URL
Duplicate e-mails App stores sent IDs in ./data; wipe the folder only if you want a resend

10. Frequently Asked Questions

Q1: Can I run this without a domain?
Yes. Use the single-container command and visit http://localhost:8080. HTTPS is skipped.

Q2: Is the GitHub token mandatory?
No, but unauthenticated requests are limited to 60 per hour. A token raises the limit to 5,000.

Q3: My e-mail never arrives.
Run the diagnostic test first. Then verify firewall rules for ports 25, 587, or 465.

Q4: Multiple recipients?
The current version supports one MAIL_TO_ADDRESS. Work-around: create a mailing list or alias.

Q5: DingTalk / Slack notifications?
The app only speaks SMTP. Community users forward mails to webhook bridges.

Q6: How do I upgrade?
Docker: docker pull … && docker compose up -d
Manual: git pull && npm ci && npm run build

Q7: Where is data stored?
Docker: ./data/settings.json on the host. Back it up.
Manual: same location.

Q8: Forgotten password?
Stop the container → edit .env → restart.

Q9: Private repositories?
Create a token with repo scope and add the full https://github.com/your-org/private-repo URL.

Q10: ARM servers (Raspberry Pi)?
The official image is multi-arch (linux/arm64). Manual builds work too.

Q11: How to read logs?
Docker: docker logs github-release-monitor
Manual: ./data/logs/

Q12: Will it spam me?
No. Each release ID is stored; you only get one mail per release unless you delete the data folder.

11. Extending the Tool

  • Change brand colors – edit tailwind.config.js and rebuild
  • Add new notification channel – fork, extend src/lib/notifications.ts
  • ARMv6 or OpenWrt – run Node 18+ and build from source
  • Webhook bridge – use the exported JSON as input for your own service

12. Final Thoughts

GitHub Release Monitor turns a repetitive, error-prone task—manually checking for new releases—into a quiet, reliable background process. Whether you choose the one-liner Docker run or the full Compose stack with SSL, the setup cost is under 30 minutes and the time saved compounds daily.

Back up your data folder occasionally, update the image when convenient, and let the inbox tell you when your favorite open-source projects move forward.