162 lines
3.4 KiB
Markdown
162 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```dotenv
|
|
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
|
|
|
|
```bash
|
|
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](#deploy).
|
|
|
|
---
|
|
|
|
## Embedding in a README
|
|
|
|
```markdown
|
|
<!-- Dark theme (default) -->
|
|
|
|
|
|
<!-- Light theme -->
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```bash
|
|
# 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
|