git-contribution-graph

A self-hosted Symfony service that merges contribution data from GitHub, GitLab and Gitea into a single GitHub-style heatmap SVG you can embed anywhere.

https://your-host/graph.svg?theme=dark

---

Features

• Three platforms — GitHub, GitLab (cloud or self-hosted), Gitea (self-hosted)
• Merged heatmap — contributions from all sources are summed per day
• GitHub colour palette — exact dark/light theme tokens
• Embeddable — returns image/svg+xml, works in any <img> tag or Markdown
• Cached — responses cached for 1 hour, safe to embed in public READMEs
• Graceful degradation — if one platform fails, the others still render

---

Deploy

Requirements

• Docker + Docker Compose

1. Clone and configure

git clone https://git.arthurerlich.de/haylan/git-contribution-graph.git
cd git-contribution-graph
cp .env .env.local

Edit .env.local with your credentials:

APP_SECRET=<generate with: openssl rand -hex 16>

# GitHub
GITHUB_USER=your-github-username
GITHUB_TOKEN=ghp_…

# GitLab (omit GITLAB_URL to use gitlab.com)
GITLAB_USER=your-gitlab-username
GITLAB_TOKEN=glpat-…
GITLAB_URL=

# Gitea
GITEA_USER=your-gitea-username
GITEA_TOKEN=…
GITEA_URL=https://git.example.com

# Optional: restrict to specific hostnames (comma-separated), leave empty to allow all
ALLOWED_HOSTS=

Only configure the platforms you use — unused ones are silently skipped.

2. Start

docker compose up -d

The service listens on port 8080 by default. Put Traefik or nginx in front of it for HTTPS.

3. Health check

GET /health  →  {"status":"ok"}

---

API

GET /graph.svg

Parameter	Required	Description
theme	✗	dark (default) or light

All credentials are configured via environment variables — see Deploy.

---

Embedding in a README

<!-- Dark theme (default) -->
![Contribution Graph](https://your-host/graph.svg)

<!-- Light theme -->
![Contribution Graph](https://your-host/graph.svg?theme=light)

---

Token setup

GitHub

1. Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Set Resource owner to your account
3. Under Permissions → Account permissions, set Contribution activity → Read-only
4. Generate and copy the token

GitLab

1. Go to User Settings → Access Tokens
2. Add a token with scopes: read_user, read_api
3. Generate and copy the token

Gitea

1. Go to Settings → Applications → Manage Access Tokens
2. Add a token with permission: user → Read
3. Generate and copy the token

---

Development

# Install deps
composer install

# Run dev server
APP_ENV=dev php -S localhost:8080 -t public

# Test endpoint
curl "http://localhost:8080/graph.svg" -o graph.svg

---

Architecture

GET /graph.svg
      │
      ├─ GitHubProvider  →  GitHub GraphQL API (contributionCalendar)
      ├─ GitLabProvider  →  GitLab REST API    (/users/:id/events)
      └─ GiteaProvider   →  Gitea REST API     (/users/:user/heatmap)
                │
          merge by date (sum counts)
                │
          SvgRenderer
                │
          image/svg+xml  (cached 1h)

---

License

MIT