gh-pm

README

gh-pm

A GitHub CLI extension for project management with GitHub Projects (v2) and Issues. Streamline requirements definition, prioritization, task decomposition, and progress tracking from the command line.

Features

• 📊 Project Management - Manage GitHub Projects v2 directly from CLI
• 🔄 Issue Workflow - Create, update, and track issues with rich metadata
• 🏗️ Task Decomposition - Break down issues into manageable sub-tasks
• 🎯 Priority Management - Set and track priorities across issues
• 📈 Progress Tracking - Monitor task completion and project status
• 🔗 Cross-repository Support - Manage issues across multiple repositories
• 🎨 Multiple output formats (TTY, table, JSON, CSV)

Installation

gh extension install yahsan2/gh-pm

Update

gh extension upgrade pm

Requirements

• GitHub CLI 2.0.0 or later
• GitHub account with repository and project permissions
• Access to GitHub Projects (v2)

Quick Start

Initialize Configuration

The init command creates a .gh-pm.yml configuration file with automatic project detection and metadata caching for faster operations.

# Interactive initialization (auto-detects current repository and lists available projects)
gh pm init

# Select from all available projects
gh pm init --list

# Specify project and repositories
gh pm init --project "My Project" --repo owner/repo1,owner/repo2

# Organization project
gh pm init --project "Team Project" --org my-organization

# Skip metadata caching (for simpler config)
gh pm init --skip-metadata

Features:

• 🔍 Auto-detection - Automatically detects current repository and associated projects
• 📊 Project selection - Interactive selection from available projects
• 🚀 Metadata caching - Caches project/field/option IDs for faster API operations
• 🔧 Smart field mapping - Automatically maps common status/priority values (e.g., "Backlog" → "todo", "P0" → "critical")
• ✅ Validation - Verifies project access and field availability

Basic Workflow

# List all issues in project
gh pm list

# Create a new issue with priority
gh pm create --title "Implement authentication" --priority high --label "backend"

# Move issue to In Progress status
gh pm move 123 --status in_progress

# Add sub-task to an issue
gh pm add-task 123 --title "Design database schema"

# Track progress
gh pm status

Core Commands

Initialization

gh pm init

Initialize a new configuration file with automatic project detection and field mapping.

Options:

• --project <name> - Specify project name or number
• --org <name> - Organization name (for org projects)
• --repo <owner/repo> - Repository (can be specified multiple times)
• --list - List all available projects to choose from
• --skip-metadata - Skip fetching project metadata (creates simpler config)
• --interactive - Interactive mode (default: true)

What it does:

1. Detects current repository - Automatically identifies the current Git repository
2. Lists available projects - Shows all projects associated with the repository or organization
3. Fetches project fields - Retrieves Status and Priority fields from the selected project
4. Maps field values - Automatically maps values like "Backlog" → "todo", "P0" → "critical"
5. Caches metadata - Stores project and field IDs for faster API operations
6. Creates config file - Generates .gh-pm.yml with all settings

Example workflow:

$ gh pm init
Detecting projects for repository yahsan2/gh-pm...

Available projects from repository yahsan2/gh-pm:
----------------------------------------------------------------------
 1. gh-pm project                            #8     
    URL: https://github.com/users/yahsan2/projects/8
----------------------------------------------------------------------

Select a project (0-1): 1
✓ Selected project: gh-pm project (#8)

Fetching project fields...
✓ Project metadata captured for faster operations

Found Status field with the following options:
  1. Backlog
  2. Ready
  3. In progress
  4. In review
  5. Done

Found Priority field with the following options:
  1. P0
  2. P1
  3. P2

✓ Configuration saved to .gh-pm.yml

Project Management

List Issues

# List all issues in current project
gh pm list

# Filter by status
gh pm list --status "In Progress"

# Filter by priority
gh pm list --priority high,critical

# JSON output
gh pm list --json number,title,priority,status

Create Issue

# Basic creation
gh pm create --title "Add user dashboard"

# With full details
gh pm create \
  --title "Implement REST API" \
  --body "Create RESTful endpoints for user management" \
  --priority high \
  --assignee "@me" \
  --label "api,backend" \
  --milestone "v1.0"

Move Issue (Update Project Fields)

# Update single field
gh pm move 123 --status in_review

# Update multiple fields
gh pm move 123 --status in_progress --priority p0

# Available status values (based on your project configuration)
gh pm move 15 --status ready
gh pm move 42 --status done

# Available priority values (based on your project configuration)
gh pm move 123 --priority p1  # High priority
gh pm move 456 --priority p2  # Medium priority

# Quiet mode (minimal output)
gh pm move 123 --status done --quiet

# Specify repository explicitly
gh pm move 123 --status ready --repo owner/repo

Available Field Values: The exact field values depend on your project configuration (.gh-pm.yml):

• Status: backlog, ready, in_progress, in_review, done
• Priority: p0 (Critical), p1 (High), p2 (Medium), etc.

Important Notes:

• The issue must already be added to the configured project
• Field values are case-sensitive and must match your project configuration
• Use gh pm init to see available values for your project

Task Decomposition

Add Sub-tasks

# Add a single task
gh pm add-task 123 --title "Write unit tests"

# Add multiple tasks from file
gh pm add-tasks 123 --file tasks.md

# Interactive task creation
gh pm add-task 123 --interactive

List Tasks

# List all sub-tasks
gh pm tasks 123

# Show completed tasks only
gh pm tasks 123 --completed

# Tree view
gh pm tasks 123 --tree

Complete Tasks

# Mark task as complete
gh pm complete-task 123 456

# Bulk complete
gh pm complete-tasks 123 --ids 456,457,458

Priority Management

Set Priority

# Set single issue priority using move command
gh pm move 123 --priority p0  # Critical priority

# Set priority with status update
gh pm move 123 --status in_progress --priority p1

# Note: Bulk priority updates coming in future releases
# gh pm set-priority 123,124,125 --level critical  # Coming soon

Priority Matrix

# View priority matrix
gh pm priority-matrix

# Export as CSV
gh pm priority-matrix --output csv > priorities.csv

Progress Tracking

Project Status

# Overall project status
gh pm status

# Detailed progress report
gh pm status --detailed

# Specific milestone
gh pm status --milestone "v1.0"

Burndown

# Sprint burndown (when sprint support is added)
gh pm burndown

# Custom date range
gh pm burndown --from 2024-01-01 --to 2024-01-31

Configuration

Project Configuration (.gh-pm.yml)

# Project settings
project:
  name: "My Project"
  number: 1  # or project ID
  org: "my-organization"  # optional

# Repository settings
repositories:
  - owner/repo1
  - owner/repo2

# Default values
defaults:
  priority: medium
  status: "Todo"
  labels:
    - "pm-tracked"

# Custom fields mapping (automatically populated from project)
fields:
  priority:
    field: "Priority"
    values:
      low: "Low"        # or "P3"
      medium: "Medium"  # or "P2"
      high: "High"      # or "P1"
      critical: "Critical"  # or "P0"
  
  status:
    field: "Status"
    values:
      todo: "Backlog"         # or "Todo"
      ready: "Ready"          # if available
      in_progress: "In Progress"
      in_review: "In Review"
      done: "Done"

# Metadata cache (auto-generated by init command)
metadata:
  project:
    id: "PVT_kwHOAAlRwM4BBvYB"  # Project node ID for API calls
  fields:
    status:
      id: "PVTSSF_lAHOAAlRwM4BBvYBzg0KEU0"
      options:
        todo: "f75ad846"
        ready: "61e4505c"
        in_progress: "47fc9ee4"
        in_review: "df73e18b"
        done: "98236657"
    priority:
      id: "PVTSSF_lAHOAAlRwM4BBvYBzg0KEX4"
      options:
        critical: "79628723"
        high: "0a877460"
        medium: "da944a9c"

Global Configuration

# Set default project
gh pm config set default-project "My Project"

# Set default output format
gh pm config set output-format json

# View all settings
gh pm config list

Advanced Usage

Cross-Repository Operations

# Create issue in specific repo
gh pm create --repo owner/other-repo --title "Cross-repo task"

# List issues from multiple repos
gh pm list --repo owner/repo1,owner/repo2

# Move issue between repos
gh pm move 123 --to owner/other-repo

Bulk Operations

# Bulk update from CSV
gh pm bulk-update --file updates.csv

# Export issues to CSV
gh pm export --format csv --output issues.csv

# Import issues from JSON
gh pm import --file issues.json

Templates

# Create issue from template
gh pm create --template bug-report

# List available templates
gh pm templates list

# Create custom template
gh pm templates create --name "feature-request"

Automation

# Watch for status changes
gh pm watch --interval 30s

# Run webhook on changes
gh pm watch --webhook https://example.com/hook

# Generate daily report
gh pm report daily --email team@example.com

Output Formats

Table (Default)

┌─────┬──────────────────────┬──────────┬────────────┬──────────┐
│ #   │ Title                │ Priority │ Status     │ Assignee │
├─────┼──────────────────────┼──────────┼────────────┼──────────┤
│ 123 │ Implement auth       │ High     │ In Progress│ @johndoe │
│ 124 │ Add user dashboard   │ Medium   │ Todo       │ @janedoe │
└─────┴──────────────────────┴──────────┴────────────┴──────────┘

JSON

{
  "issues": [
    {
      "number": 123,
      "title": "Implement auth",
      "priority": "high",
      "status": "in_progress",
      "assignee": "johndoe"
    }
  ]
}

CSV

number,title,priority,status,assignee
123,"Implement auth",high,in_progress,johndoe
124,"Add user dashboard",medium,todo,janedoe

Integration

GitHub Actions

name: Project Management
on:
  issues:
    types: [opened, edited]

jobs:
  update-project:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Update project
        run: |
          gh pm update ${{ github.event.issue.number }} \
            --status "Todo" \
            --priority medium

Git Hooks

# .git/hooks/post-commit
#!/bin/bash
# Auto-update issue status on commit
if [[ $(git log -1 --pretty=%B) =~ "#([0-9]+)" ]]; then
  gh pm update "${BASH_REMATCH[1]}" --status "In Review"
fi

Troubleshooting

Authentication Issues

# Check authentication
gh auth status

# Re-authenticate
gh auth login

# Use specific token
export GH_TOKEN=your_token_here

Project Access

# List accessible projects
gh pm projects list

# Check permissions
gh pm debug permissions

Performance

# Enable caching
gh pm config set cache true

# Clear cache
gh pm cache clear

# Verbose output for debugging
gh pm list --verbose

Contributing

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

Development Setup

# Clone repository
git clone https://github.com/yahsan2/gh-pm.git
cd gh-pm

# Install dependencies
npm install  # or appropriate package manager

# Run tests
npm test

# Build
npm run build

Roadmap

✅ Completed Features

• Issue creation with project metadata (gh pm create)
• Project initialization with auto-detection (gh pm init)
• Issue status & priority updates (gh pm move)
• Configuration management with field mapping
• Multiple output formats (table, JSON, CSV)

🚧 In Development / Planned

• Issue listing and filtering (gh pm list)
• Bulk operations and CSV import/export
• Task decomposition (gh pm add-task)
• Progress tracking and reporting (gh pm status)

🔮 Future Features

• Sprint management (gh pm sprint ...)
• Gantt chart visualization
• Time tracking integration
• Custom workflow automation
• AI-powered task suggestions
• Mobile companion app
• Slack/Discord integration

License

MIT License - see LICENSE file for details

Acknowledgments

• Built on GitHub CLI
• Inspired by modern project management best practices
• Thanks to all contributors and users

Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Read documentation
• 💬 Join discussions

---

Made with ❤️ for GitHub project managers