git-activity-merger/README.md

git-activity-merger

Small self-hosted FastAPI service that merges GitHub + Gitea contribution data and returns embeddable contribution heatmap images.

Example for GitHub profile README:

![Activity](https://example.com/activity.svg)

What It Does

• Fetches contribution data from:
  • GitHub GraphQL API (GITHUB_USERNAME, optional GITHUB_TOKEN)
  • Gitea heatmap API ({GITEA_BASE_URL}/api/v1/users/{GITEA_USERNAME}/heatmap)
• Normalizes into date-based counts:
  • github
  • gitea
  • total
• Caches source responses and rendered images on disk.
• Returns:
  • merged JSON
  • GitHub-style SVG heatmap
  • PNG heatmap

API Routes

• GET /health
• GET /activity.json
• GET /activity.svg
• GET /activity.png

Supported query params:

• year=YYYY or days=365 (mutually exclusive)
• theme=dark|light
• source=all|github|gitea

Examples:

curl "http://localhost:8000/activity.json?days=365&source=all"
curl "http://localhost:8000/activity.svg?year=2026&theme=dark"
curl "http://localhost:8000/activity.png?days=180&source=gitea"

Setup

1. Install

python -m venv .venv
. .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

2. Configure

Copy .env.example to .env and edit values.

Required:

• GITHUB_USERNAME
• GITEA_BASE_URL
• GITEA_USERNAME

Optional:

• GITHUB_TOKEN
• GITEA_TOKEN
• CACHE_TTL_SECONDS and CACHE_DIR enable caching when both are set
• DEFAULT_THEME (light or dark, default: light)
• SERVICE_TITLE (default: git-activity-merge)

If you leave CACHE_TTL_SECONDS and CACHE_DIR undefined, the app skips caching entirely.

3. Run

uvicorn app.main:app --reload --port 8000

Docker

Build and run the container image directly:

docker build -t registry.reversed.dev/registry/git-activity-merger:latest .
docker run --rm -p 8000:8000 \
  --env-file .env \
  registry.reversed.dev/registry/git-activity-merger:latest

Or use Compose:

docker compose up --build

Container serves on port 8000. Compose mounts a named cache volume at /app/cache.

Reverse Proxy Example (Nginx)

server {
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then embed directly:

![Activity](https://example.com/activity.svg?days=365&theme=dark)

Notes

• GitHub GraphQL without token is possible but lower-rate/less reliable. Set GITHUB_TOKEN for stability.
• Gitea instances may require GITEA_TOKEN for private activity or stricter rate limits.
• If upstream APIs fail and stale cache exists, /activity.json includes "stale": true and stale data is served.