Skip to content
/ sage-github-manager Public

🐙 A comprehensive GitHub Issues management tool for SAGE project with AI-powered features

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

intellistream/sage-github-manager

BranchesTags

Repository files navigation

GitHub Issues Manager

🐙 A comprehensive GitHub Issues management tool with AI-powered features for downloading, analyzing, organizing, and managing GitHub Issues.

Features

  • 📥 Download & Sync: Download and synchronize GitHub Issues with full metadata
  • 📊 Statistics & Analytics: Generate comprehensive statistics and reports
  • 🤖 AI-Powered Analysis: Intelligent issue categorization, deduplication, and priority assessment
  • 👥 Team Management: Team member tracking and automated assignment
  • 📋 Project Management: Auto-organize issues based on status and timeline
  • 🔄 Bidirectional Sync: Sync changes between local and GitHub
  • 📝 Multiple Views: Support for JSON, Markdown, and metadata views

Installation

Quick Install (Recommended)

Run the automated installation script:

git clone https://github.com/intellistream/sage-github-manager.git
cd sage-github-manager
bash quickstart.sh

The script will:

  • ✓ Check Python 3.10+ installation
  • ✓ Install package and dependencies
  • ✓ Set up virtual environment (optional)
  • ✓ Configure GitHub credentials
  • ✓ Install pre-commit hooks
  • ✓ Verify installation

Manual Installation

# Clone repository
git clone https://github.com/intellistream/sage-github-manager.git
cd sage-github-manager

# Install with dev dependencies
pip install -e ".[dev]"

# Set up environment variables
export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="intellistream"
export GITHUB_REPO="SAGE"

From PyPI (coming soon)

pip install sage-github-manager

Quick Start

1. Set up GitHub Token

You need a GitHub Personal Access Token with repo scope to access the GitHub API.

# Set environment variable
export GITHUB_TOKEN="your_github_token"

# Or create a file
echo "your_github_token" > ~/.github_token

2. Configure Repository

You can set the target repository via environment variables:

export GITHUB_OWNER="your-org"
export GITHUB_REPO="your-repo"

Or pass them as parameters in your code.

3. Basic Usage

Use the quick start script for automatic setup:

# One-line installation and setup
bash quickstart.sh

Or manually:

# Check status
github-manager status

# Download issues
github-manager download

# List open issues
github-manager list

# Show statistics
github-manager analytics

# Export to CSV
github-manager export issues.csv

# Team analysis
github-manager team

# Create new issue
github-manager create

CLI Commands

Status & Configuration

# Show current configuration and status
github-manager status

# Show detailed configuration
github-manager config

Download & Sync

# Download all issues
github-manager download

# Download only open issues
github-manager download --state open

# Force re-download
github-manager download --force

# Sync to GitHub
github-manager sync --direction upload

# Bidirectional sync
github-manager sync --direction both

List Issues ✨ NEW

Flexibly list and filter issues with rich formatting:

# Basic listing
github-manager list                                # List all open issues
github-manager list --state all                    # List all issues
github-manager list --state closed                 # List closed issues

# Filter by labels (multiple labels = AND)
github-manager list --label bug
github-manager list --label bug --label priority:high

# Filter by assignee
github-manager list --assignee shuhao
github-manager list --assignee @me                 # Your own issues

# Filter by milestone
github-manager list --milestone "v2.0"

# Filter by author
github-manager list --author shuhao

# Sorting options
github-manager list --sort created                 # Sort by creation time
github-manager list --sort updated                 # Sort by last update
github-manager list --sort comments                # Sort by comment count

# Limit results
github-manager list --limit 10                     # Show top 10

# Combined filters
github-manager list --state open --label bug \
  --assignee shuhao --sort comments --limit 20

# Show issue body preview
github-manager list --body

Output: Color-coded table with issue number, title, state, labels, assignee, and statistics.

Export Issues ✨ NEW

Export issues to various formats for reporting and analysis:

# CSV Export (for Excel/Google Sheets)
github-manager export issues.csv
github-manager export bugs.csv --state open --label bug

# JSON Export (structured data)
github-manager export issues.json --format json
github-manager export open.json -f json --state open

# Markdown Export (for documentation)
github-manager export ROADMAP.md --format markdown
github-manager export ROADMAP.md -f markdown --template roadmap
github-manager export REPORT.md -f markdown --template report

# Combined filtering
github-manager export sprint.csv \
  --state open --milestone "v2.0" --label priority:high

# Export with custom filters
github-manager export release_notes.md \
  -f markdown --template report \
  --state closed --milestone "v1.5"

Supported Formats:

  • CSV: Excel-compatible spreadsheet
  • JSON: Structured data with all fields
  • Markdown: Three templates:
    • default: Detailed list with metadata
    • roadmap: Grouped by milestone
    • report: Concise summary

Batch Operations ✨ NEW

Efficiently manage multiple issues at once:

# Batch close issues (with dry-run preview)
github-manager batch-close --label wontfix --dry-run
github-manager batch-close --label duplicate
github-manager batch-close --state open --milestone old-sprint

# Batch add labels
github-manager batch-label --add priority:high --label bug
github-manager batch-label --add reviewed --state closed
github-manager batch-label --add needs-docs --assignee shuhao

# Batch remove labels
github-manager batch-label --remove needs-review --state closed
github-manager batch-label --remove stale --milestone "v2.0"

# Batch assign issues (multiple assignees supported)
github-manager batch-assign --assignee shuhao --label p0
github-manager batch-assign --assignee alice,bob --label bug

# Batch set milestone
github-manager batch-milestone "v3.0" --state open
github-manager batch-milestone "v2.5" --label priority:high

Safety Features:

  • --dry-run: Preview changes without executing
  • Confirmation prompts before batch operations
  • Detailed logs of all changes

AI-Powered Features ✨ NEW

Leverage AI for intelligent issue management:

# Summarize long issue discussions
github-manager summarize --issue 123
github-manager summarize --issue 456 --model gpt-4

# Detect duplicate issues automatically
github-manager detect-duplicates
github-manager detect-duplicates --threshold 0.8

# Auto-suggest labels based on content
github-manager suggest-labels --issue 789
github-manager suggest-labels --issue 123 --model claude

# Comprehensive AI analysis
github-manager ai --action analyze       # Overall analysis
github-manager ai --action dedupe        # Find duplicates
github-manager ai --action optimize      # Optimize labels
github-manager ai --action report        # Generate AI report

Setup: Requires OpenAI or Anthropic API key:

# OpenAI (GPT-3.5/GPT-4)
export OPENAI_API_KEY=sk-...

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...

Use Cases:

  • 📝 Summarize: Quick insights from 100+ comment threads
  • 🔍 Detect Duplicates: Find similar issues automatically
  • 🏷️ Suggest Labels: Consistent labeling
  • 📊 Analyze: Identify patterns and trends

Statistics & Analysis

# Show statistics
github-manager analytics

# Team analysis
github-manager team

# Update team information from GitHub
github-manager team --update

# Combined analysis
github-manager team --update --analysis

Organization & Management

# Organize issues by status
github-manager organize --preview

# Execute organization plan
github-manager organize --apply --confirm

# Project management (detect and fix misassignments)
github-manager project

Testing

# Run test suite
github-manager test

Python API

Basic Usage

from sage_github import IssuesManager, IssuesConfig

# Create manager
config = IssuesConfig(
    github_owner="intellistream",
    github_repo="SAGE"
)
manager = IssuesManager()

# Load and analyze issues
issues = manager.load_issues()
manager.show_statistics()
manager.team_analysis()

Custom Configuration

from sage_github import IssuesConfig
from pathlib import Path

# Custom configuration
config = IssuesConfig(
    project_root=Path("/path/to/project"),
    github_owner="your-org",
    github_repo="your-repo"
)

# Test connection
if config.test_github_connection():
    print("Connected to GitHub successfully!")

# Get repository info
repo_info = config.get_repo_info()
print(f"Repository: {repo_info['full_name']}")
print(f"Stars: {repo_info['stargazers_count']}")

Directory Structure

After initialization, the tool creates the following directory structure:

.github-manager/
├── workspace/          # Raw data storage
│   ├── data/          # JSON data files
│   ├── views/         # Different views (markdown, metadata, summaries)
│   └── cache/         # Temporary cache
├── output/            # Generated reports and statistics
└── metadata/          # Configuration and tracking files
    ├── settings.json
    ├── team_config.py
    ├── boards_metadata.json
    ├── ai_analysis_summary.json
    ├── update_history.json
    └── assignments.json

Advanced Features

AI Analysis

The AI analysis feature supports multiple engines and actions:

# Comprehensive analysis
github-manager ai --action analyze --engine openai

# Find duplicate issues
github-manager ai --action dedupe

# Optimize labels and categories
github-manager ai --action optimize

# Generate detailed report
github-manager ai --action report

Team Management

# Show team info and statistics
github-manager team

# Update from GitHub API
github-manager team --update

# Combined update and analysis
github-manager team --update --analysis

Project Organization

Automatically organize closed issues based on their closure time:

  • Done: Issues closed within the last week
  • Archive: Issues closed 1 week to 1 month ago
  • History: Issues closed more than 1 month ago
# Preview organization plan
github-manager organize --preview

# Execute organization
github-manager organize --apply --confirm

Environment Variables

Variable Description Default
GITHUB_TOKEN GitHub Personal Access Token (required)
GH_TOKEN Alternative name for GitHub token -
GIT_TOKEN Alternative name for GitHub token -
GITHUB_OWNER Repository owner/organization intellistream
GITHUB_REPO Repository name SAGE

Development

Setup Development Environment

# Clone repository
git clone https://github.com/intellistream/sage-github-manager.git
cd sage-github-manager

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
black src/ tests/
isort src/ tests/
mypy src/

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=sage_github --cov-report=html

# Run specific test
pytest tests/test_config.py -v

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

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

Acknowledgments

  • Original implementation from SAGE project
  • Inspired by GitHub CLI and project management best practices

Support

Related Projects

  • SAGE - AI/LLM data processing pipeline framework
  • GitHub CLI - Official GitHub command-line tool

Changelog

See CHANGELOG.md for a list of changes.

About

🐙 A comprehensive GitHub Issues management tool for SAGE project with AI-powered features

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages