GitPulse -Measure what matters.

GitPulse is an open-source dashboard designed to analyze and contextualize developer activity and contribution trends within a GitHub organization.

I started building it as a CTO because I couldn't find a tool that was simple and reliable enough to truly understand the work of my teams and products. Most analytics tools are focused on superficial vanity metrics and risk turning into tools for surveillance. GitPulse is different. It’s an analytical tool to drive a culture of performance, not a tracking tool for surveillance. It’s built to foster transparency and dialogue, and to help teams grow by valuing real impact over simple activity.

GitPulse is a personal project, developed during my free time. It will evolve based on my availability and interests. Unlike most solutions that focus on repository-level data, GitPulse lets you group multiple repositories into a single logical project—reflecting how real software is built and delivered. This holistic approach is perfect for tracking large apps, microservices, or monorepo-like architectures.

I'm currently building GitPulse solo, with no QA team. If you encounter bugs or unexpected behavior, contributions are welcome—as long as they stay aligned with the spirit of the project: useful, readable, and not overengineered.

🚨 GitPulse is under alpha dev process, i can introduce breaking changes

🚀 Quick Start

Option 1: Docker (Recommended)

Prerequisites: Docker and Docker Compose, 16GB RAM recommended

1. Clone and start

   git clone https://github.com/assiadialeb/gitpulse.git
   cd GitPulse
   cp env.example .env
   docker-compose up -d --build

2. Access the application

   • Open http://localhost:8000

Note: First startup may take 5-10 minutes as Ollama downloads the gemma3:4b model (~3.3GB).

📖 See Docker Quick Start for detailed instructions

Option 2: Local Installation

Prerequisites:

• Python 3.12+
• PostgreSQL
• MongoDB
• 16GB RAM recommended

1. Clone the repository

   git clone https://github.com/assiadialeb/gitpulse.git
   cd GitPulse

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment

   cp env.example .env
   # Edit .env with your database settings

5. Run migrations

   python manage.py migrate

6. Start the server

   python manage.py runserver

7. Access the application

   • Open http://localhost:8000
   • Login with your superuser credentials (created automatically)

📚 Documentation

Comprehensive documentation is available at: https://assiadialeb.github.io/gitpulse/

Local Documentation Development

# Install MkDocs
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

# Deploy to GitHub Pages
./deploy-docs.sh

⚙️ Environment Configuration

GitPulse uses python-decouple to manage configuration through environment variables. All settings can be configured via the .env file.

Key Configuration Variables

Django Core

• DEBUG: Enable/disable debug mode (default:True)
• SECRET_KEY: Django secret key for security
• ALLOWED_HOSTS: Comma-separated list of allowed hosts
• LANGUAGE_CODE: Language code (default:en-us)
• TIME_ZONE: Timezone (default:Europe/Paris)

Database Configuration

• MONGODB_HOST: MongoDB host (default:localhost)
• MONGODB_PORT: MongoDB port (default:27017)
• MONGODB_NAME: MongoDB database name (default:gitpulse)
• POSTGRES_DB: PostgreSQL database name (default:gitpulse_new)
• POSTGRES_USER: PostgreSQL username (default:gitpulse_user)
• POSTGRES_PASSWORD: PostgreSQL password (default:gitpulse_password)
• POSTGRES_HOST: PostgreSQL host (default:localhost)
• POSTGRES_PORT: PostgreSQL port (default:5432)

GitPulse Configuration

• GITHUB_API_RATE_LIMIT_WARNING: Rate limit warning threshold (default:10)
• GITHUB_API_TIMEOUT: API timeout in seconds (default:30)

Ollama Configuration

• OLLAMA_HOST: Ollama server URL (default:http://localhost:11434)
• OLLAMA_MODEL: Ollama model name (default:gemma3:4b)

Django-Q Configuration

• Q_WORKERS: Number of worker processes (default:4)
• Q_RECYCLE: Worker recycle count (default:500)
• Q_TIMEOUT: Task timeout in seconds (default:3600)
• Q_RETRY: Retry count (default:4000)
• Q_SAVE_LIMIT: Save limit (default:250)
• Q_QUEUE_LIMIT: Queue limit (default:500)
• Q_CPU_AFFINITY: CPU affinity (default:1)

Cache Configuration

• CACHE_TIMEOUT: Cache timeout in seconds (default:3600)
• CACHE_MAX_ENTRIES: Maximum cache entries (default:1000)
• ANALYTICS_CACHE_TIMEOUT: Analytics cache timeout (default:3600)
• PR_METRICS_CACHE_TIMEOUT: PR metrics cache timeout (default:1800)
• COMMIT_METRICS_CACHE_TIMEOUT: Commit metrics cache timeout (default:7200)

Example .env file

# Copy env.example to .env and customize as needed
cp env.example .env

🏗️ Architecture

• Backend: Django (Python 3.12+)
• Database: PostgreSQL (user data) + MongoDB (analytics data)
• Frontend: Django templates + DaisyUI
• Authentication: Django auth + GitHub OAuth2
• API: GitHub REST API v3
• AI: Ollama with gemma3:4b model

📁 Project Structure

GitPulse/
├── config/           # Django settings and URL routing
├── users/            # Authentication and user management
├── repositories/     # Repository management
├── analytics/        # Analytics and indexing services
├── github/           # GitHub OAuth2 integration
├── templates/        # HTML templates
├── static/           # Static files
├── docs/             # Documentation
├── docker-compose.yml # Docker services configuration
├── Dockerfile        # Application container
├── Dockerfile.ollama # Ollama container
├── manage.py         # Django management script
└── setup_github_app.py  # GitHub App setup script

🔧 Development

Running Tests

python manage.py test

Creating Migrations

python manage.py makemigrations
python manage.py migrate

Accessing Admin

• URL: http://localhost:8000/admin/
• Use your superuser credentials

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📝 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

🆘 Support

If you encounter any issues:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information
4. Discuss with the community