gogg 0.2.0

Gitlab Open Graph Generator

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)

Option	Description
--headline	Headline text (default: group path from API)
--description	Description text (default: entity description from API)
--icon	Custom icon URL or local file path
--pat	Personal access token for private repositories
--format	Image format: png, jpg, webp (default: inferred from --output, or jpg)
--output	Output file path

Repo Subcommand Options

Option	Description
--group	Repository group including subgroups (required)
--no-contributors	Hide contributors count
--no-issues	Hide issues count
--no-stars	Hide stars count
--no-forks	Hide forks count

🛠️ 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.