gogg 0.1.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 repositories.

✨ Features

• Fetches repository metadata from the GitLab API (stars, forks, issues, contributors, languages)
• Generates styled OG images with project name, description, and metrics
• Supports custom group icons
• 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

If you have installed the package, you can use it with python as follows:

python -m gogg.cli --repo my-project --group my-group

You can also use uvx to directly run the tool as a command without installing it:

uvx gogg --repo my-project --group my-group

For private repositories, use a personal access token:

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

You can also customize the output:

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

Options

The following options are available:

Option	Description
--repo	Repository name (required)
--group	Repository group including subgroups (required)
--headline	Headline text (default: group path from API)
--description	Description text (default: repo description from API)
--group-icon	Custom group icon URL or local file path
--pat	Personal access token for private repositories
--format	Image format: png, jpg, webp (default: jpg)
--output	Output file path
--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 License 2.0. See the LICENSE file for details.