v2.1.0

Release v2.1.0 Secure Token Storage & Testing Improvements

Overview

This release introduces secure token storage using OS-native keyring and improves the testing infrastructure with Docker-based CI environment parity. All previously skipped tests have been fixed and are now passing.

🎯 Key Features

Secure Token Storage

• OS-Native Keyring Support: Store GitLab tokens securely using your OS keyring
  • macOS: Keychain
  • Linux: Secret Service API (GNOME Keyring, KWallet)
  • Windows: Windows Credential Manager
• Automatic Token Retrieval: Tokens are automatically retrieved if no CLI token is provided
• Token Resolution Priority: CLI → Stored → Environment Variable
• Optional Dependency: Keyring is an optional dependency (pip install gitlabber[keyring])

Testing Infrastructure

• Docker Testing Setup: Test on Ubuntu environment matching CI

📝 Changes

Added

• TokenStorage class for secure token storage using OS keyring
• --store-token CLI flag to store tokens securely
• Automatic token retrieval from secure storage
• Docker testing infrastructure (Dockerfile.test, docker-compose.test.yml)
• Helper script scripts/test-docker.sh for running tests in Docker
• Comprehensive documentation for token storage feature
• Docker testing documentation in DEVELOPMENT.md

Changed

• Token resolution now includes secure storage as a source
• Updated README.md and README.rst with token storage documentation
• Updated DEVELOPMENT.md with Docker testing guide

🔧 Technical Details

Token Storage Implementation

• Module: gitlabber/token_storage.py
• Storage Backend: OS keyring (via keyring library)
• Graceful Fallback: If keyring unavailable, falls back to environment variables
• Security: Tokens stored encrypted at rest by OS keyring

Testing Improvements

• Docker Environment: Python 3.11 on Ubuntu (matching CI)
• Cross-Platform: Verified on both macOS (local) and Ubuntu (Docker/CI)

📚 Usage

Storing a Token

# Install with keyring support (optional)
pip install gitlabber[keyring]

# Store token securely (one-time setup)
gitlabber --store-token -u https://gitlab.com
Enter token: [hidden input]
Token stored securely in keyring for https://gitlab.com ✓

Using Stored Token

# Automatically uses stored token (no -t flag needed)
gitlabber -u https://gitlab.com .

# Override with CLI token if needed
gitlabber -t <token> -u https://gitlab.com .

Docker Testing

# Run tests in Docker (Ubuntu environment)
docker-compose -f docker-compose.test.yml run --rm test

# Or use the helper script
./scripts/test-docker.sh

🔄 Migration Guide

No migration required! This is a backward-compatible release.

• Existing workflows continue to work unchanged
• Environment variables (GITLAB_TOKEN) still work
• CLI arguments (-t/--token) still work
• Token storage is completely optional

🧪 Testing

All tests pass in both local and Docker environments:

# Local tests
pytest

# Docker tests (Ubuntu/CI environment)
docker-compose -f docker-compose.test.yml run --rm test

📦 Dependencies

New Optional Dependency

• keyring>=24.0.0 - For secure token storage (optional)

Install with:

pip install gitlabber[keyring]

📖 Documentation

• Updated README.md with token storage usage
• Updated README.rst with token storage usage
• Added Docker testing guide to DEVELOPMENT.md
• Added token storage examples and best practices

🔍 Testing Checklist

• All unit tests pass locally
• All integration tests pass locally
• All tests pass in Docker (Ubuntu)
• Token storage works on macOS
• Token storage works on Linux (Docker)
• Token storage gracefully falls back when keyring unavailable
• Documentation updated
• No breaking changes

🙏 Credits

This release improves the developer experience with secure token storage and better testing infrastructure, making gitlabber more secure and easier to develop.

---

Ready for Review ✅

Full Changelog: v2.0.0...v2.1.0

v2.0.0

Release v2.0.0 - Major Release

🎉 Overview

This release represents a comprehensive change of the Gitlabber codebase, focusing on code quality, performance, user experience, and maintainability. This is a major version bump due to breaking changes (Python 3.11+ requirement) and significant architectural improvements.

🚀 Major Features

⚡ Parallel API Calls (4-6x Performance Improvement)

• New --api-concurrency option for parallel API calls during tree building
• Dramatically speeds up tree discovery for large GitLab instances (e.g., 96s → 16-21s)
• Features:
  • Parallel group processing at the top level
  • Parallel subgroup detail fetching (batch processing)
  • Parallel subgroups and projects fetching within each group
  • Automatic connection pool sizing to prevent urllib3 warnings
  • Thread-safe rate limiting to respect GitLab API limits
  • Configurable via --api-concurrency N (default: 5, range: 1-20) or GITLABBER_API_CONCURRENCY environment variable
  • Optional --api-rate-limit to set custom rate limits (default: 2000 requests/hour)

🎨 Modern CLI with Rich UI

• Migrated from argparse to Typer for modern option parsing and better help output
• Replaced tqdm with Rich for beautiful progress bars with:
  • Estimated time remaining (ETA)
  • Current operation details (cloning, pulling, fetching, processing)
  • Multiple progress bars support
  • Better visual feedback

📝 Enhanced Error Messages

• Actionable error messages with context-specific suggestions
• Custom exception hierarchy for better error handling
• Error messages now include:
  • Clear description of what went wrong
  • 💡 Suggestion section with actionable steps
  • Links to relevant documentation where applicable
  • Specific command examples to resolve issues

⚙️ Configuration Management

• Pydantic-based configuration with automatic validation
• Environment variable support for all configuration options
• Better type safety and validation
• Configuration file support (via pydantic-settings)

🔧 Code Quality Improvements

Modern Python Features

• ✅ Python 3.11+ required (dropped Python 3.9 and 3.10)
• ✅ Modern type hints (list[str] instead of List[str])
• ✅ Converted enums to enum.StrEnum for clearer string semantics
• ✅ Consistent use of pathlib.Path throughout
• ✅ Converted GitAction to @dataclass
• ✅ F-strings used consistently

Code Architecture

• ✅ Separated concerns: Split GitlabTree into smaller, focused components:
  • GitlabTreeBuilder: Builds tree structure
  • TreeFilter: Handles filtering logic (functional approach)
  • UrlBuilder: Centralized URL construction
• ✅ Extracted git operations into separate classes:
  • GitRepository: Wraps git operations for a single repo
  • GitActionCollector: Collects git actions
  • GitSyncManager: Manages concurrent git operations
• ✅ Improved tree filtering: Functional approach with predicate composition
• ✅ Custom exception hierarchy for better error handling

Documentation

• ✅ Module-level docstrings added to all modules
• ✅ Comprehensive API documentation for all public classes and methods
• ✅ Created DEVELOPMENT.md with architecture documentation
• ✅ Enhanced CONTRIBUTING.md with development guidelines

Testing

• ✅ Test coverage improved from 92% to 97%
• ✅ Added comprehensive test utilities and helpers
• ✅ Improved test organization with better fixtures
• ✅ Added e2e tests and performance tests
• ✅ Better mocking strategies

📦 Dependency Updates

Removed

• ❌ typing (built-in since Python 3.5+)
• ❌ docopt (unused)

Updated

• ✅ anytree: 2.12.1 → 2.13.0
• ✅ GitPython: 3.1.44 → 3.1.45
• ✅ python-gitlab: 5.6.0 → 7.0.0
• ✅ PyYAML: 6.0.2 → 6.0.3
• ✅ tqdm: 4.67.1 → latest (replaced with rich)

Added

• ✅ rich: Modern terminal UI library
• ✅ typer: Modern CLI framework
• ✅ pydantic: Data validation library
• ✅ pydantic-settings: Settings management

🛠️ Developer Experience

Code Quality Tools

• ✅ Pre-commit hooks with:
  • black for code formatting
  • ruff for linting
  • mypy for type checking
  • isort for import sorting

Code Cleanup

• ✅ Removed all refactoring-related comments
• ✅ Clean, informative code comments
• ✅ Consistent code style throughout

📊 Performance Improvements

• 4-6x speedup for large GitLab instances with parallel API calls
• Better progress reporting with ETA
• Optimized connection pool management

🔒 Security & Robustness

• ✅ Enhanced input validation
• ✅ Better URL validation with urllib.parse
• ✅ Improved error handling with specific exceptions
• ✅ Token handling verified (no logging of sensitive data)

📋 Breaking Changes

1. Python 3.11+ required (dropped Python 3.9 and 3.10)
2. CLI argument parsing changed (migrated from argparse to Typer)
   • Some argument formats may have changed
   • Help output format is different (improved)
3. Progress bar output changed (migrated from tqdm to Rich)
   • Different visual appearance
   • JSON output format may differ slightly

🧪 Testing

• All existing tests pass
• New tests added for:
  • API concurrency functionality
  • Performance benchmarks
  • Error handling improvements
  • Configuration validation
• E2E tests updated and documented

📚 Documentation

• ✅ Updated README.md and README.rst with new features
• ✅ Created DEVELOPMENT.md with architecture docs
• ✅ Enhanced CONTRIBUTING.md
• ✅ Comprehensive API documentation

🎯 Migration Guide

For Users

1. Upgrade Python: Ensure you're using Python 3.11 or newer

   python --version  # Should be 3.11+

2. Update Installation:

   pip install --upgrade gitlabber

3. Try the New Performance Feature:

   gitlabber --api-concurrency 10  # For large instances

4. Environment Variables: All options can now be set via environment variables:

   export GITLABBER_API_CONCURRENCY=10
   export GITLABBER_API_RATE_LIMIT=3000

For Developers

1. Update Python Version: Ensure your development environment uses Python 3.11+
2. Install Pre-commit Hooks:

   pre-commit install

3. Review New Architecture: See DEVELOPMENT.md for architecture changes

📈 Statistics

• Commits: 20+ commits
• Files Changed: 50+ files
• Lines Added: ~2000+
• Lines Removed: ~500+
• Test Coverage: 92% → 97%
• Dependencies Updated: 5 major updates
• New Dependencies: 4 (rich, typer, pydantic, pydantic-settings)

🙏 Acknowledgments

This release represents a significant effort to modernize the codebase while maintaining backward compatibility where possible. Special attention was paid to:

• Performance improvements for large GitLab instances
• Better user experience with improved error messages and progress reporting
• Code quality and maintainability
• Comprehensive testing

🔗 Related Issues/PRs

• Addresses comprehensive codebase improvements from IMPROVEMENTS.md
• Implements all high-priority recommendations
• Modernizes codebase for Python 3.11+.

What's Changed

• Update release.yml by @ezbz in #144
• add types by @ezbz in #145
• Sync code_improvements to main by @ezbz in #147
• document gitlabber behaviour on remote branch deletion not being able… by @ezbz in #152

Full Changelog: v1.2.8...v2.0.0

v1.2.6

What's Changed

• Added ability to provide git options to the GitPython clone/update me… by @ezbz in #130

Full Changelog: v1.2.5...v1.2.6

v1.2.5

What's Changed

• add exception testing by @ezbz in #84
• Collection of PRs from this project, fixes for #110 and compliance fix for not storing tokens in .git/config by @arnvid in #111
• Various fixes to the README by @waldyrious in #104
• feat: use token for cloning repos by @syphernl in #98
• Bump gitpython from 3.1.31 to 3.1.37 by @dependabot in #114
• Fix name typo by @aloisdg in #77
• Force python-gitlab to retrieve all objects instead of the first 20 by @flolauck in #119
• Bump gitpython from 3.1.37 to 3.1.41 by @dependabot in #121
• Bump tqdm from 4.65.0 to 4.66.3 by @dependabot in #125
• Fix tests consolidate prs by @ezbz in #126
• Update CONTRIBUTING.md by @ezbz in #127
• Added ability to clone the gitlab user's personal projects by @ezbz in #129

New Contributors

• @arnvid made their first contribution in #111
• @waldyrious made their first contribution in #104
• @syphernl made their first contribution in #98
• @dependabot made their first contribution in #114
• @aloisdg made their first contribution in #77
• @flolauck made their first contribution in #119

Full Changelog: v1.1.9...v1.2.5