Home

GitHub Authentication Library (githubauthlib)

Welcome to the githubauthlib wiki! This library provides a secure and cross-platform solution for retrieving GitHub tokens from system keychains.

Quick Links

• Installation Guide
• Usage Guide
• Configuration
• API Reference
• Architecture
• Development Setup
• Contributing Guidelines
• Troubleshooting
• PyPI Package

Overview

githubauthlib is a Python library designed to securely retrieve GitHub tokens from system-specific secure storage:

• macOS: Uses Keychain Access
• Windows: Uses Credential Manager
• Linux: Uses libsecret

Key Features

• ✅ Cross-platform support (macOS, Windows, Linux)
• 🔒 Secure token retrieval with validation
• ✨ Token format validation (personal, organization, fine-grained)
• 🛡️ Comprehensive exception hierarchy for precise error handling
• 📝 Structured logging support
• 🔐 Robust credential parsing and sanitization

System Requirements

• Python 3.9 or higher
• Git with configured credentials
• Platform-specific dependencies:
  • Linux: libsecret-tools
  • macOS: No additional requirements
  • Windows: No additional requirements

Breaking Changes in v2.0.1

⚠️ Important: Version 2.0.1 introduces breaking changes from v1.x.x:

• get_github_token() now raises specific exceptions instead of returning None
• All error handling now uses structured logging instead of print statements
• Token validation is now strict and validates format
• Python 3.6, 3.7, and 3.8 support has been removed (EOL)
• Added support for organization tokens (gho_ prefix)

Migration Guide

Before (v1.x.x):

token = get_github_token()
if token:
    print("Success!")
else:
    print("Failed!")

After (v2.0.1):

try:
    token = get_github_token()
    print("Success!")
except TokenNotFoundError:
    print("No token found!")
except GitHubAuthError as e:
    print(f"Error: {e}")

Getting Started

Check out our Installation Guide to get started with githubauthlib.

Support

If you encounter any issues or have questions:

1. Check the Troubleshooting guide
2. Search existing GitHub Issues
3. Create a new issue if needed

License

This project is licensed under the MIT License. See the LICENSE file for details.