GitLab Wrapped

中文版本 (Chinese Version)

A modern, "Spotify Wrapped" style annual contribution statistics tool specifically designed for private, self-hosted GitLab instances (Internal GitLab), including support for legacy versions. It is intended to run inside your corporate intranet so it can access your company's self-hosted GitLab service.

Important

This project was developed and extensively tested on a legacy GitLab v8.0.1 instance. As of late 2025, GitLab has reached v18.7+. We warmly welcome users of newer GitLab versions to test this tool and contribute compatibility fixes or enhancements. Our ultimate goal is to provide universal support across all GitLab versions.

💡 Inspiration

This project was inspired by the popular git-wrapped.com in the developer community. While that tool is excellent for public GitHub statistics, the reality is that the vast majority of a developer's daily contributions occur within private, corporate, and self-hosted GitLab instances (Internal GitLab).

We built this tool to allow developers working behind corporate firewalls to celebrate their year-long hard work and achievements within their private office environments.

✨ Features

• 📊 Annual Overview: Total commits, active projects, merge requests, and contributor profile.
• 🕒 Peak Contribution Hours: Visualize your most productive times of day with configurable timezone support (UTC+8, etc.).
• 📉 Monthly Trends: Detailed bar charts showing your activity distribution throughout the year.
• 🔥 Activity Heatmap: A full-width, 52-week horizontal contribution grid inspired by GitHub.
• ⚡ SQLite Local Cache: Instant loading for repeat visits using a fast local database layer.
• 🧪 Historical Optimization: Intelligent scanning that skips irrelevant projects and stops early for historical years (e.g., 2014).
• 📧 Multi-Identity Support: Attribute commits from multiple email addresses to a single report.
• 🏆 Achievement System: Unlock badges like "Code Machine", "Persistence Paid Off", and more.
• 🎨 Themes: Multiple theme styles with a strong, tech-forward vibe.

🚀 Tech Stack

• Frontend: React + Vite + Tailwind CSS
• Charts: Chart.js + react-chartjs-2
• Backend (Caching): Node.js + Express + SQLite3
• GitLab Integration: GitLab API v3/v4 compatibility (optimized for legacy 8.x instances)

📦 Getting Started

Prerequisites

• Node.js (v16+)
• A personal access token from your GitLab instance

Installation

1. Clone the repository

   git clone https://github.com/slyang-git/gitlab-wrapped.git
   cd gitlab-wrapped

2. Install dependencies

   npm install

3. Configure Environment Create a .env file in the root directory (refer to .env.example):

   VITE_GITLAB_BASE_URL=https://your-gitlab.com/api/v3(or v4)
   VITE_GITLAB_SECONDARY_EMAILS=email1@example.com,email2@example.com
   VITE_GITLAB_TIMEZONE_OFFSET=8

Running Locally

To enable the local caching layer, you need to run both the frontend and the cache server:

# Run both frontend and backend concurrently
npm run dev:full

Or run them separately:

• Frontend: npm run dev (starts on port 5173)
• Cache Server: node server.js (starts on port 3001)

🛡️ Privacy & Security

• Private Tokens: Your GitLab token is used only for the current session and is never stored on the server or in the database.
• Local Data: The optional SQLite cache is stored entirely on your local machine (gitlab-wrapped.db).

🛠️ Calibration

• Paging: The app supports 0-indexed paging for legacy GitLab v3 compatibility.
• Timezones: Adjust VITE_GITLAB_TIMEZONE_OFFSET in .env to match your local time.

📄 License

MIT License