gh-migration-monitor

README

GitHub Migration Monitor

A GitHub CLI extension that monitors GitHub Organization migrations with a real-time terminal dashboard.

Quick Start

# Install
gh extension install mona-actions/gh-migration-monitor

# Run
gh migration-monitor --organization myorg

What You'll See

┌ Migration Status - myorg ─────────────────────────────────────────┐
│ Repository Name    Migration ID     Status        Created At      │
│ ─────────────────────────────────────────────────────────────────│
│ frontend-app      mig_123456       ✅ SUCCEEDED   2025-11-05 14:30│
│ backend-api       mig_123457       🔄 IN_PROGRESS 2025-11-05 14:25│
│ mobile-app        mig_123458       📋 QUEUED      2025-11-05 14:20│
│ legacy-system     mig_123459       ❌ FAILED      2025-11-05 14:15│
└─────────────────────────────────────────────────────────────────┘
Commands: r Refresh  / Search  x Exit  Filters: a All  q Queued  i In Progress  s Succeeded  f Failed
                                                    Last updated: 14:35:42

Features

• 🔄 Real-time monitoring with automatic 30-second refresh intervals
• 📊 Multi-state tracking (Queued, In Progress, Succeeded, Failed)
• 🔍 Advanced filtering with status-based views and search functionality
• 🎯 Live search with real-time repository name filtering
• 📋 Comprehensive table showing Repository Name, Migration ID, Status, and Created At
• 🔧 Legacy support for both GEI and legacy migrations
• ⌨️ Interactive UI with intuitive keyboard navigation
• 🎨 Color-coded status indicators for quick visual assessment
• ⚡ Optimized performance with efficient data filtering and updates

Usage

# Basic usage
gh migration-monitor --organization myorg

# With custom token
gh migration-monitor --organization myorg --github-token ghp_xxxxxxxxxxxx

# Monitor legacy migrations
gh migration-monitor --organization myorg --legacy

Options

Flag	Short	Description	Required
--organization	-o	GitHub organization	Yes
--github-token	-t	GitHub token	No*
--legacy	-l	Monitor legacy migrations	No

*Can use GHMM_GITHUB_TOKEN environment variable instead.

Configuration

Environment Variables

export GHMM_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export GHMM_GITHUB_ORGANIZATION="myorg"
export GHMM_ISLEGACY="true"  # for legacy migrations

Config File

Create ~/.gh-migration-monitor/config.yaml:

github:
  token: 'ghp_xxxxxxxxxxxx'
  organization: 'myorg'
migration:
  is_legacy: false
output:
  format: 'table'      # Output format (reserved for future use)
  quiet: false         # Quiet mode (reserved for future use)

Controls

Navigation & Actions

Key	Action
r	Refresh data
/	Open search modal
x	Exit application

Status Filters

Key	Filter
a	Show All migrations
q	Show Queued only
i	Show In Progress
s	Show Succeeded
f	Show Failed

Search Modal

Key	Action
Enter	Close search modal
Escape	Close search modal
Clear Button	Clear search term
Close Button	Close search modal

Note: Search filtering happens in real-time as you type and works in combination with status filters.

Dashboard Layout

The terminal dashboard displays a comprehensive migration table with the following columns:

Column	Description
Repository Name	Name of the repository being migrated
Migration ID	Unique identifier for the migration
Status	Current migration state (color-coded)
Created At	When the migration was initiated

Status Color Coding

• 🔵 Blue: Queued states (QUEUED, WAITING)
• 🟡 Yellow: In Progress (IN_PROGRESS, PREPARING, PENDING, MAPPING, IMPORTING, etc.)
• 🟢 Green: Succeeded (SUCCEEDED, UNLOCKED, IMPORTED)
• 🔴 Red: Failed (FAILED, FAILED_IMPORT)

Smart Filtering & Search

• Status Filters: Instantly filter by migration state
• Live Search: Real-time repository name filtering
• Combined Filtering: Search works within selected status filters
• Dynamic Title: Shows organization name and active filter

Performance & Optimization

Recent Improvements

• Optimized UI Code: Refactored following KISS principles for better maintainability
• Efficient Filtering: Streamlined filter logic with single-responsibility functions
• Memory Optimization: Reduced object overhead and cleaner lifecycle management
• Enhanced Search: Real-time search with minimal performance impact
• Faster Refresh: Improved from 60-second to 30-second refresh intervals

Technical Features

• Separation of Concerns: Clean architecture with focused, testable components
• Event-Driven Updates: Efficient handling of user interactions and data updates
• Responsive Design: Non-blocking UI updates and smooth animations
• Error Resilience: Graceful handling of API failures and network issues

Requirements

• GitHub CLI installed and authenticated
• GitHub token with permissions:
  • GEI migrations: read:org, repo
  • Legacy migrations: read:org, repo, admin:org

User Interface Guide

Getting Started

1. Launch with gh migration-monitor --organization myorg
2. The dashboard loads automatically with a 30-second refresh interval
3. Use keyboard shortcuts to navigate and filter data
4. Press / to search for specific repositories
5. Use status filters (a, q, i, s, f) to focus on specific migration states

Search Functionality

• Open: Press / to open the search modal
• Type: Start typing a repository name for real-time filtering
• Clear: Click "Clear" button or manually delete text
• Close: Press Enter, Escape, or click "Close" button
• Combine: Search works with status filters for precise results

Visual Indicators

• Loading Animation: Spinning indicator during data refresh
• Last Updated: Timestamp showing when data was last refreshed
• Active Filter: Current filter displayed in table title
• Color Status: Immediate visual status recognition

Troubleshooting

Token required: Set GHMM_GITHUB_TOKEN or use --github-token flag

Organization not found: Check organization name and token permissions

Rate limit: Wait a few minutes - the tool automatically refreshes every 30 seconds

Search not working: Ensure you're in the main dashboard view (not in a modal)

Keyboard shortcuts not responding: Try pressing Escape to ensure you're not in search mode

Contributing

Contributions are welcome! Here's how to get started:

Development Setup

# Fork and clone
gh repo fork mona-actions/gh-migration-monitor --clone
cd gh-migration-monitor

# Build and test
go mod download
go build -o gh-migration-monitor
gh extension install .

Making Changes

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes and add tests
3. Follow KISS principles for clean, maintainable code
4. Submit a pull request

Project Structure

├── cmd/               # CLI commands (Cobra framework)
│   └── root.go       # Main command and application entry
├── internal/
│   ├── api/          # GitHub API clients (REST & GraphQL)
│   ├── config/       # Configuration management (Viper)
│   ├── models/       # Domain models and data structures
│   ├── services/     # Business logic and migration handling
│   └── ui/           # Terminal UI components (tview)
│       ├── ui.go     # Dashboard and interaction logic
│       └── table.go  # Migration table display
├── go.mod            # Go module definition
├── main.go           # Application entry point
└── README.md         # This documentation

Architecture Highlights

• Clean Architecture: Separation of concerns with clear boundaries
• Interface-Based Design: Testable and modular components
• Real-time Updates: Efficient background refresh with visual feedback
• Responsive UI: Optimized keyboard navigation and search functionality

License

This project is licensed under the MIT License.

---

Note: This tool is inspired by github-migration-monitor and provides enhanced functionality with a modern terminal UI.

Documentation

Overview

Package main provides the entry point for the gh-migration-monitor GitHub CLI extension.

gh-migration-monitor is a terminal-based dashboard for monitoring GitHub organization migrations in real-time. It supports both legacy migrations and the new GitHub Enterprise Importer (GEI) migrations, providing an interactive interface to track migration progress across different states.

The application follows clean architecture principles with clear separation of concerns:

• cmd/: Command-line interface and CLI parsing
• internal/api/: GitHub API client implementations
• internal/config/: Configuration management
• internal/models/: Domain models and business entities
• internal/services/: Business logic services
• internal/ui/: Terminal user interface components

Usage:

go run main.go --organization myorg
go run main.go --organization myorg --legacy --github-token token