GitHub Repository Monitor

A Python-based service that monitors GitHub repositories for new commits and sends notifications to a Gotify server. This tool is designed to help you stay informed about updates to public repositories without requiring webhooks or authentication.

Features

• Multiple Repository Tracking: Monitor any number of public GitHub repositories
• Real-time Notifications: Receive push notifications via Gotify when new commits are detected
• Dynamic Configuration: Add or remove tracked repositories without restarting the service
• GitHub Authentication: Optional Personal Access Token (PAT) support for higher API rate limits
• Docker Support: Run as a lightweight, containerized service
• Low Resource Usage: Efficient polling system with configurable intervals
• Persistent State: Maintains state across restarts to prevent duplicate notifications

Prerequisites

• Docker and Docker Compose
• A running Gotify server with an application token
• Optional: GitHub Personal Access Token for higher rate limits

Quick Start

1. Clone this repository:

   git clone https://github.com/jagrit007/gotify-github_repo_change_tracker.git
   cd gotify-github_repo_change_tracker

2. Configure your repositories and Gotify settings in config/config.json:

   {
     "repositories": [
       "microsoft/vscode",
       "tensorflow/tensorflow",
       "kubernetes/kubernetes"
     ],
     "gotify": {
       "url": "https://your-gotify-instance.com",
       "token": "your-gotify-token"
     },
     "github": {
       "token": "your-github-personal-access-token"  
     },
     "check_interval": 300
   }

3. Build and start the service:

   docker-compose up -d

4. Check the logs:

   docker-compose logs -f

Configuration Options

The config.json file supports the following options:

Option	Description	Default
repositories	Array of repositories to monitor in owner/name format	[]
gotify.url	URL of your Gotify server	Required
gotify.token	Application token from your Gotify server	Required
github.token	GitHub Personal Access Token for API authentication	Optional
check_interval	Time between checks in seconds	300 (5 minutes)

GitHub Authentication

Using a GitHub Personal Access Token (PAT) is highly recommended as it increases your API rate limit from 60 requests per hour (unauthenticated) to 5,000 requests per hour (authenticated).

Creating a GitHub PAT:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Click "Generate new token"
3. Give it a descriptive name
4. Select the public_repo scope (or repo for private repositories if needed)
5. Click "Generate token" and copy the token
6. Add it to your config.json file

The service will automatically detect and use the token if provided, but will work without it with reduced rate limits.

How It Works

1. The service periodically checks the GitHub API for each configured repository
2. When a new commit is detected, it sends a notification to your Gotify server
3. The notification includes details about the commit (author, message, timestamp, URL)
4. The service stores the last seen commit to avoid duplicate notifications
5. Rate limits are monitored and logged to help avoid hitting GitHub API limits

Directory Structure

github-repo-monitor/
├── config/               # Configuration files
│   └── config.json       # Main configuration
├── data/                 # Persistent state storage
├── github_monitor.py     # Main Python script
├── Dockerfile            # Docker image definition
├── docker-compose.yml    # Docker Compose configuration
└── requirements.txt      # Python dependencies

Advanced Usage

Manual Installation (without Docker)

If you prefer not to use Docker:

1. Install Python 3.9 or higher
2. Install dependencies: pip install -r requirements.txt
3. Create the data directory: mkdir -p data
4. Configure config.json
5. Run the script: python github_monitor.py

Modifying Check Frequency

The default check interval is 5 minutes (300 seconds). You can change this by updating the check_interval value in your config.json.

With GitHub authentication, you can safely reduce this interval to check more frequently. Without authentication, be careful not to set it too low to avoid hitting rate limits.

Rate Limit Considerations

• Without Authentication: Limited to 60 requests per hour
• With Authentication: Up to 5,000 requests per hour

The script logs remaining rate limits with each API call, helping you monitor usage and adjust your check interval accordingly.

Updating the Service

To update to a newer version:

git pull
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Troubleshooting

No Notifications

1. Verify your Gotify URL and token are correct
2. Check if the repository has had new commits since starting the service
3. Examine the logs: docker-compose logs -f

GitHub API Rate Limiting

If you see errors related to rate limiting:

1. Add a GitHub Personal Access Token to your configuration
2. Increase the check interval
3. Reduce the number of repositories being monitored

High CPU or Memory Usage

If the service is using too many resources:

1. Increase the check_interval in the configuration
2. Reduce the number of repositories being monitored

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• GitHub API
• Gotify
• All the awesome open source projects we're helping you monitor!