GitPulse

About The Project

GitPulse is a full-stack GitHub audience tracker built with FastAPI and MongoDB. On every sync it fetches your followers and following from the GitHub REST API, diffs them against the stored snapshot in MongoDB, and logs every change as a timestamped event. The event log is append-only so the full history is always preserved.

The dashboard has three views — current followers newest first, current following in GitHub order, and lost followers built from a MongoDB aggregation that deduplicates by user and excludes anyone who has re-followed. A daily cron job via GitHub Actions keeps everything up to date automatically.

Library Requirements

• FastAPI
• Uvicorn
• PyMongo
• Requests
• Python-dotenv
• APScheduler

Getting Started

This will help you understand how to set up GitPulse to track your own GitHub followers. To get a local copy up and running follow these simple steps.

Installation Steps

Option 1: Installation from GitHub

1. Clone the Repository

   git clone https://github.com/KalyanM45/GitPulse.git
   cd GitPulse
   

2. Create a Virtual Environment

   python -m venv backend/venv
   

3. Activate the Virtual Environment

   Windows:

   backend\venv\Scripts\activate
   

   macOS / Linux:

   source backend/venv/bin/activate
   

4. Install Dependencies

   pip install -r backend/requirements.txt
   

5. Configure Environment Variables

   cp backend/.env.example backend/.env
   

   Open backend/.env and fill in your values — see the API Key Setup section below.

6. Run the Backend

   cd backend
   uvicorn app.main:app --reload
   

7. Open the Frontend

   Open frontend/index.html directly in your browser. No build step or dev server needed.

   Click Sync Now to pull in your GitHub followers for the first time.

API Key Setup

GitPulse needs two credentials to run — a GitHub token and a MongoDB connection string.

1. GitHub Personal Access Token (GITHUB_TOKEN)

This is required. Without it, GitHub blocks the following list endpoint entirely (authentication required) and applies strict rate limits on all other endpoints.

Steps to create one:

1. Go to github.com/settings/tokens
2. Click Generate new token (classic)
3. Set a name like gitpulse and choose an expiration
4. Select the following scope:
   • read:user — to read your profile and your own following list
5. Click Generate token and copy it immediately — you cannot see it again

Add it to backend/.env:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Note: Keep your token private. Never commit it to a public repository.

2. MongoDB Connection URI (MONGODB_URI)

GitPulse stores all follower snapshots and event history in MongoDB.

For local development, a local MongoDB instance works:

MONGODB_URI=mongodb://localhost:27017

For production (required for GitHub Actions nightly sync), use MongoDB Atlas:

1. Create a free account at cloud.mongodb.com
2. Create a free M0 cluster
3. Go to Database Access → create a user with read/write access
4. Go to Network Access → Add IP 0.0.0.0/0 (allow from anywhere — needed for GitHub Actions dynamic IPs)
5. Go to your cluster → Connect → Drivers → copy the URI

MONGODB_URI=mongodb+srv://db-user:password@cluster0.xxxxx.mongodb.net/?appName=Cluster0

Complete .env file

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_USERNAME=your-github-username
MONGODB_URI=mongodb+srv://db-user:password@cluster0.xxxxx.mongodb.net/?appName=Cluster0
DB_NAME=github_analytics
SYNC_INTERVAL_MINUTES=60

Deployment

Backend → Render

1. Go to render.com → New + → Web Service → connect your repo

2. Fill in the form:

   Field	Value
   Runtime	Python 3
   Build Command	pip install -r backend/requirements.txt
   Start Command	cd backend && uvicorn app.main:app --host 0.0.0.0 --port $PORT
   Instance Type	Free

3. Add environment variables: GITHUB_TOKEN, GITHUB_USERNAME, MONGODB_URI, DB_NAME

4. Deploy — copy the URL you receive (e.g. https://gitpulse-api.onrender.com)

Frontend → Vercel

1. Open frontend/js/config.js and set your Render URL:

   window.API_BASE = 'https://gitpulse-api.onrender.com'
   

2. Push the change to GitHub
3. Go to vercel.com → New Project → import your repo → Deploy

Nightly Sync → GitHub Actions

The workflow at .github/workflows/auto_sync.yml syncs at 11:45 PM IST daily. It imports the backend Python code directly and talks to MongoDB Atlas — the Render server does not need to be awake.

Go to your repo → Settings → Secrets and variables → Actions → add:

Secret Name	Value
GH_ANALYTICS_TOKEN	Your GitHub personal access token
GH_USERNAME	Your GitHub username
MONGODB_URI	Your MongoDB Atlas URI
DB_NAME	github_analytics

Use GH_ANALYTICS_TOKEN — not GITHUB_TOKEN, which is reserved by GitHub Actions itself.

To test immediately: Actions tab → GitPulse — Nightly Sync → Run workflow.

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

• Report bugs: Open an issue and describe the problem clearly.
• Contribute code: Follow the steps below to get started.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

• Suggestions: Have ideas for new features? Open an issue and describe what you'd like to see!

Don't forget to give the project a star! Thanks again!

License

This project is licensed under the MIT License.

Acknowledgements

Thanks to the GitHub REST API for making follower data accessible, MongoDB Atlas for a generous free tier, Render and Vercel for free hosting, and the open-source community for the libraries that power this project.