⌯⌲ gitnot

A lightweight Python tool to watch GitHub repositories for activity and send instant alerts to your favorite service (Telegram, Slack, Pushover, Twilio, etc.) using Apprise.

1. Configuration

1. Rename .env.example to .env.
2. Open .env and fill in your details:
   • NOTIFICATION_URLS: A comma-separated list of Apprise service URLs.
     • Telegram: tgram://BOT_TOKEN/CHAT_ID
     • Discord: discord://WEBHOOK_ID/WEBHOOK_TOKEN
     • Slack: slack://TOKEN/A/B/C
     • Email: mailto://user:password@smtp.gmail.com
     • Pushover: pover://USER_KEY@TOKEN
     • Pushbullet: pbul://ACCESS_TOKEN
     • Twilio SMS: twilio://ACCOUNT_SID:AUTH_TOKEN@FROM_PHONE/TO_PHONE
     • For a full list of 100+ supported services and their URL formats, see the Apprise Wiki.
   • GITHUB_TOKEN: (Optional but recommended) Generate a Personal Access Token on GitHub (Settings -> Developer Settings -> Personal access tokens).
   • GITHUB_REPOS: Comma-separated list of repositories to watch (e.g., torvalds/linux, google/guava).
   • GITHUB_USER: (Optional) Set this to a GitHub username to automatically monitor all their public repositories.
   • EXCLUDE_ARCHIVED: (Optional) Set to Y to ignore archived repositories.
   • EXCLUDE_REPOS: (Optional) Comma-separated list of repositories to exclude from monitoring.
   • CHECK_INTERVAL: Time in seconds between checks (default 600).

2. Running the gitnot

Run the gitnot using uv:

uv run monitor.py

3. Running with Docker

Using Docker Compose (Recommended)

1. Make sure you have docker and docker-compose installed.

2. Run the container in detached mode:

   docker-compose up -d

3. Check the logs:

   docker-compose logs -f

Using Docker CLI

1. Build the image:

   docker build -t gitnot .

2. Run the container (mounting state.json for persistence):

   docker run -d \
     --name gitnot \
     --env-file .env \
     -v $(pwd)/state.json:/app/state.json \
     gitnot

Running as a Cron Job

If you prefer to schedule the execution yourself (e.g., via cron), you can use the --no-sleep flag. This will make the script check for updates once and then exit immediately.

# Run once and exit
uv run monitor.py --no-sleep

Example Crontab (every 10 minutes):

*/10 * * * * cd /path/to/gitnot && uv run monitor.py --no-sleep >> /var/log/gitnot.log 2>&1

4. What to Expect

1. First Run: The gitnot will log "First run detected" and initialize state.json with the latest event IDs for your repos. No notifications will be sent to avoid spamming old events.
2. Subsequent Runs: The gitnot will continuously check for new events.
3. Testing:
   • Star one of your watched repos (or unstar and star again).
   • Wait for the CHECK_INTERVAL (default 60s).
   • You should receive a Telegram message!

5. Maintenance

• state.json stores the progress. If you want to reset the gitnot to fetch "everything new" again (or just reset history), delete this file.
• Logs are printed to the console.

6. FAQ

What happens if I provide both GITHUB_REPOS and GITHUB_USER?

The script will combine them:

1. Union: It monitors repositories listed in GITHUB_REPOS PLUS all public repositories found for GITHUB_USER.
2. No Duplicates: If a repository exists in both, it is only monitored once.
3. Exclusions Apply Last: Any repositories listed in EXCLUDE_REPOS (or archived ones if EXCLUDE_ARCHIVED=Y) are removed from the final list.