GitLab OG Image Generator

Open Graph images for your Gitlab repositories.

A CLI tool to generate Open Graph images for GitLab entities.

✨ Features

• Subcommand-based CLI (gogg repo ...) for extensibility
• Fetches repository metadata from the GitLab API (stars, forks, issues, contributors, languages)
• Generates styled OG images with project name, description, and metrics
• Supports custom icons (URL or local file path)
• Configurable metric visibility (contributors, issues, stars, forks)
• Output formats: PNG, JPG, WebP
• Language color bar based on repository language breakdown

📋 Requirements

• Python 3.11 or higher

📦 Installation

Using pip

pip install gitlab-og-image-generator

Using uv

uv add gitlab-og-image-generator

🚀 Usage

Repository OG Image

Generate an OG image for a public repository:

gogg repo my-project --group my-group

With a personal access token for private repositories:

gogg repo my-project --group my-group/subgroup --pat glpat-xxxx

Customize the output:

gogg repo my-project --group my-group \
  --headline "My Organization" \
  --description "A custom description for the OG image" \
  --icon ./logo.png \
  --format png \
  --output my-image.png \
  --no-contributors \
  --no-issues

Options

Shared Options (available on all subcommands)

Repo Subcommand Options

🛠️ Development

Check out our Contribution Guide for details on setting up your development environment, running tests, and submitting pull requests.

The project uses uv for dependency management, ruff for linting, and tox for multi-environment testing.

📜 Changelog

See the CHANGELOG.md for a history of changes.

👥 Contributors

See our list of contributors.

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.