gitlab2md

Convert GitLab profile data to clean Markdown files - the ideal format for LLM analysis.

Why Markdown?

Markdown is the lingua franca of AI tools. Once your GitLab data is in .md format, you can:

• Upload to NotebookLM and have conversations about your development history
• Use Claude Projects to analyze patterns across your contributions
• Feed to Obsidian with AI plugins for a personal developer knowledge base
• Run local LLMs (Ollama, LM Studio) for completely private analysis

Example Prompts

Once your GitLab data is in an LLM, try asking:

Installation

Recommended (using pipx - installs in isolated environment):

pipx install gitlab2md

Or with pip (in a virtual environment):

pip install gitlab2md

Note: On modern Linux systems (Debian, Ubuntu 23.04+, Fedora), use pipx to avoid the "externally-managed-environment" error.

Prerequisites

• GitLab CLI (glab) installed and authenticated
• Python 3.13+

Installing glab

# macOS
brew install glab

# Ubuntu/Debian
sudo apt install glab

# Or via pipx
pipx install glab

Then authenticate:

glab auth login

Usage

# Use authenticated user
gitlab2md

# Specify a username
gitlab2md juanmanueldaza

# Include group contributions
gitlab2md juanmanueldaza --groups colmena-project,another-group

# Custom output directory
gitlab2md juanmanueldaza -o ./my_gitlab_data

Then drag the output folder into your favorite AI tool.

Options

LLM Tools That Work Great With This

Output Files

Creates 13 markdown files in the output directory:

Profile & Projects

• profile.md - User profile (name, bio, job title, organization, website)
• projects.md - Owned projects with stars, forks, visibility, topics
• member_projects.md - Projects where user is a member (excludes own)
• contributed_projects.md - Projects user has contributed to

Activity & Contributions

• merge_requests.md - MR history with state, labels, and status breakdown
• issues.md - Issues created with state and labels
• events.md - Recent activity summary and action types
• groups.md - Group memberships and commit contributions

Network & Social

• starred.md - Starred projects
• memberships.md - Groups and projects with access levels
• snippets.md - Code snippets with visibility

Security

• ssh_keys.md - SSH key titles and expiration dates
• gpg_keys.md - GPG key IDs and creation dates

Architecture

This project follows SOLID principles for maintainability:

• Single Responsibility: Each parser/formatter handles one data section
• Open/Closed: Add new parsers via @register_parser decorator without modifying core code
• Liskov Substitution: All parsers implement the SectionParser protocol
• Interface Segregation: Focused protocols for extractors, parsers, formatters, and writers
• Dependency Inversion: Converter depends on abstractions, not implementations

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

GPL-2.0 - see LICENSE for details.