Forgejo Heatmap Generator

Generate a GitHub-style contribution heatmap from your Forgejo activity on SourceTube (or any Forgejo instance really).

Forgejo Actions Setup

This repository includes a workflow to automatically generate and update your heatmap.

1. Enable Actions

Go to your repository Settings > Units > Overview and ensure the Actions checkbox is ticked.

2. Add Repository Variables

Go to your repository Settings > Actions > Variables and add:

• FORGEJO_URL: Forgejo instance URL (default: https://source.tube)
• FORGEJO_USERNAME: Your Forgejo username

3. Add Repository Secret

Go to your repository Settings > Actions > Secrets and add:

• FORGEJO_TOKEN: Your Forgejo personal access token with read permissions for user activity

Generating a Forgejo Personal Access Token

1. Go to your Forgejo instance's Settings
2. Navigate to Applications
3. Name your new token
4. Give it a name ("Heatmap Generator")
5. Select the following scopes:
   • read:user - to read your user profile
   • read:repository - to read repository activity
6. Click "Generate token"
7. Copy the token!

4. Run the Workflow

The workflow can be triggered manually:

• Go to the Actions tab
• Select the "Generate Heatmap" workflow
• Click "Run workflow"

You can also enable scheduled runs by editing .forgejo/workflows/heatmap.yml and uncommenting the schedule section.

Troubleshooting

Lessons learned from trial and error. Don't make my mistake people.

Error: FORGEJO_USERNAME not set

Ensure you've set FORGEJO_USERNAME in your .env file for local development, or as the FORGEJO_USERNAME repository variable in Forgejo Actions.

Error: Invalid or missing FORGEJO_TOKEN

• Verify your token is correctly set as FORGEJO_TOKEN in your .env file for local development, or as the FORGEJO_TOKEN secret in Forgejo Actions
• Ensure the token has the required scopes (read:user, read:repository)
• Regenerate the token if it's expired

Error: API returned empty data

• Verify your username is correct (it happens ok?)
• Check that your token has the correct permissions

Error: Connection refused / timeout

• Verify FORGEJO_URL is correct and accessible
• Ensure the Forgejo instance is running and accessible

Local Development

Prerequisites

• uv - Python package installer
• Python 3.12 or later

Quick Setup

1. Clone this repository

2. Copy .env.example to .env and configure your settings:

   cp .env.example .env
   

3. Run using uv:

   uv run generate_heatmap.py
   

4. Format and Lint using Ruff:

   uv run ruff format --check
   uv run ruff check --check
   

CLI Options

Override environment variables with command-line arguments:

uv run generate_heatmap.py [OPTIONS]

Options:
  --user, -u          Forgejo username
  --instance, -i       Forgejo instance URL
  --token, -t          API token
  --output, -o          Output file path
  --weeks               Number of weeks to display (default: 52)
  --pretty-print        Format SVG with line breaks
  --bg-color           Background color (hex or 'transparent')
  --text-color         Text color for labels (hex, default: #000000)
  --padding            Inner padding in pixels (default: 5)
  --color-scheme       Color scheme: 'green' or 'purple' (default: green)