Skip to content

github-mcp-guide.md

Latest commit

 

History

History
582 lines (475 loc) · 15 KB

github-mcp-guide.md

File metadata and controls

582 lines (475 loc) · 15 KB

GitHub MCP Guide for Development Workflow

Version: 2.0 - Unified Documentation System Last Updated: 2025-09-06 Purpose: Optimize GitHub MCP usage for repository management and CI/CD integration

🎯 GitHub MCP Overview

GitHub MCP server provides comprehensive repository management and CI/CD monitoring capabilities. It's the most heavily used MCP server and serves as the backbone for development workflow integration.

Current Usage Statistics

  • Current Usage: 90 tool uses (heavily utilized)
  • Usage Pattern: Primarily CI/CD monitoring and artifact analysis
  • Primary Value: Development workflow automation and monitoring

🔍 GitHub MCP Capabilities

Repository Management

File Operations

// Read repository files
get_file_contents({
  owner: "ElliotBadinger",
  repo: "echo",
  path: "build.gradle.kts"
})

// Create/update files (USE CAUTION - see synchronization rules)
create_or_update_file({
  owner: "ElliotBadinger",
  repo: "echo",
  path: "docs/project-state/current-status.md",
  content: "...",
  message: "Update project status documentation"
})

Repository Information

// Get repository details
get_repository({
  owner: "ElliotBadinger",
  repo: "echo"
})

// List repository contents
list_repository_contents({
  owner: "ElliotBadinger",
  repo: "echo",
  path: "docs"
})

CI/CD Integration

Workflow Monitoring

// Monitor CI workflow status
list_workflow_runs({
  owner: "ElliotBadinger",
  repo: "echo",
  workflow_id: "android-ci.yml",
  per_page: 5
})

// Get specific workflow run details
get_workflow_run({
  owner: "ElliotBadinger",
  repo: "echo",
  run_id: 12345
})

Job Analysis

// Analyze failed jobs
get_job_logs({
  owner: "ElliotBadinger",
  repo: "echo",
  run_id: 12345,
  failed_only: true,
  return_content: true
})

// Get job timing information
get_workflow_run_usage({
  owner: "ElliotBadinger",
  repo: "echo",
  run_id: 12345
})

Artifact Management

// Download test artifacts
download_workflow_run_artifact({
  owner: "ElliotBadinger",
  repo: "echo",
  artifact_id: 67890
})

// List workflow artifacts
list_workflow_run_artifacts({
  owner: "ElliotBadinger",
  repo: "echo",
  run_id: 12345
})

🛠️ Development Workflow Integration

Remote-First TIER 1 Policy (Critical)

  • Always check remote CI/CD status first and address failures before beginning local TIER 1 work.
  • Why: Remote CI validates a clean environment and protects the mainline; resolving remote failures first prevents divergence and wasted local effort.

Remote TIER 1 Checklist

  1. list_workflows → identify CI workflow(s)
  2. list_workflow_runs → inspect latest run(s)
  3. If failure: get_job_logs (failed_only=true, return_content=true) → identify error
  4. Fix or open an issue/PR to address the failure
  5. Re-run failed jobs or workflow as needed

Once remote CI is green, proceed to local TIER 1 (build/test on your machine).

CI/CD Monitoring Strategy

Pre-Implementation Validation

// Check current CI status before making changes
list_workflow_runs({
  owner: "ElliotBadinger",
  repo: "echo",
  workflow_id: "android-ci.yml",
  per_page: 3
})

Post-Implementation Validation

// Monitor CI after pushing changes
const monitorCI = async () => {
  const runs = await list_workflow_runs({
    owner: "ElliotBadinger",
    repo: "echo",
    workflow_id: "android-ci.yml",
    per_page: 1
  });
  
  const latestRun = runs[0];
  if (latestRun.status === 'completed') {
    if (latestRun.conclusion === 'success') {
      console.log('✅ CI passed successfully');
    } else {
      // Get failure details
      const logs = await get_job_logs({
        owner: "ElliotBadinger",
        repo: "echo",
        run_id: latestRun.id,
        failed_only: true,
        return_content: true
      });
      console.log('❌ CI failed:', logs);
    }
  }
};

Performance Monitoring

// Track CI performance over time
get_workflow_run_usage({
  owner: "ElliotBadinger",
  repo: "echo",
  run_id: 12345
})
// Returns: billable time, run duration, etc.

Repository Management Best Practices

Safe File Operations

// ✅ SAFE: Read operations
get_file_contents({
  owner: "ElliotBadinger",
  repo: "echo",
  path: "README.md"
})

// ❌ AVOID: Direct write operations (use manual git)
create_or_update_file({
  owner: "ElliotBadinger",
  repo: "echo",
  path: "source.kt",
  content: "..."
})

Synchronization Rules

  • NEVER use GitHub MCP push_files() - Creates commits bypassing local git
  • ALWAYS coordinate with user before using GitHub MCP write operations
  • Use manual git commands for all commits and pushes
  • Document any GitHub MCP usage for transparency

📊 GitHub MCP Effectiveness Optimization

Usage Tracking and Metrics

Current Usage Analysis

  • Primary Usage: CI/CD monitoring and artifact analysis
  • Secondary Usage: Repository content reading
  • Effectiveness: High for workflow monitoring, variable for content management
  • Integration Rate: Well-integrated into development workflow

Optimization Opportunities

  • Increase Read Operations: Use more for repository analysis
  • Improve CI Monitoring: Automate CI status tracking
  • Enhance Artifact Analysis: Better utilization of test artifacts
  • Workflow Optimization: Use insights for CI/CD improvements

CI/CD Integration Patterns

Automated CI Monitoring

// Implement automated CI status checking
const monitorImplementation = async (commitSha) => {
  // Wait for CI to start
  await waitForWorkflowStart(commitSha);
  
  // Monitor progress
  const status = await pollWorkflowStatus(commitSha);
  
  // Analyze results
  if (status === 'success') {
    await analyzeSuccessfulBuild(commitSha);
  } else {
    await analyzeFailedBuild(commitSha);
  }
};

Failure Analysis Workflow

// Comprehensive failure analysis
const analyzeBuildFailure = async (runId) => {
  // Get job logs
  const logs = await get_job_logs({
    owner: "ElliotBadinger",
    repo: "echo",
    run_id: runId,
    failed_only: true,
    return_content: true
  });
  
  // Download artifacts
  const artifacts = await list_workflow_run_artifacts({
    owner: "ElliotBadinger",
    repo: "echo",
    run_id: runId
  });
  
  // Analyze and report
  const analysis = analyzeLogsAndArtifacts(logs, artifacts);
  return analysis;
};

🔄 Integration with Development Frameworks

Research Framework Integration

CI Validation of Research

// Use GitHub MCP to validate research implementation
const validateResearchImplementation = async () => {
  // Push research-based changes
  // Monitor CI for validation
  const ciResult = await monitorCI();
  
  // Analyze performance impact
  if (ciResult.success) {
    const performance = await get_workflow_run_usage({
      owner: "ElliotBadinger",
      repo: "echo",
      run_id: ciResult.runId
    });
    
    // Document research effectiveness
    documentResearchImpact(research, performance);
  }
};

Kotlin Migration Framework Integration

Migration Validation

// Validate Kotlin migration through CI
const validateKotlinMigration = async (convertedFile) => {
  // Push converted Kotlin file
  // Monitor CI compilation
  const compilationResult = await monitorCI();
  
  // Check for Kotlin-specific issues
  if (compilationResult.success) {
    // Verify Kotlin best practices
    const kotlinAnalysis = analyzeKotlinCode(convertedFile);
    
    // Update migration progress
    updateMigrationStatus(convertedFile, kotlinAnalysis);
  }
};

Performance Framework Integration

Performance Benchmarking

// Use CI for performance validation
const validatePerformanceOptimizations = async () => {
  // Run performance tests in CI
  const performanceResults = await runPerformanceTests();
  
  // Download performance artifacts
  const artifacts = await download_workflow_run_artifact({
    owner: "ElliotBadinger",
    repo: "echo",
    artifact_id: performanceResults.artifactId
  });
  
  // Analyze performance improvements
  const analysis = analyzePerformanceData(artifacts);
  
  // Update performance metrics
  updatePerformanceMetrics(analysis);
};

🚀 Advanced GitHub MCP Techniques

Workflow Automation

Automated Status Monitoring

// Implement comprehensive CI monitoring
class CIMonitor {
  constructor(owner, repo) {
    this.owner = owner;
    this.repo = repo;
  }
  
  async monitorWorkflow(workflowId) {
    const runs = await list_workflow_runs({
      owner: this.owner,
      repo: this.repo,
      workflow_id: workflowId,
      per_page: 10
    });
    
    return runs.map(run => ({
      id: run.id,
      status: run.status,
      conclusion: run.conclusion,
      created_at: run.created_at,
      updated_at: run.updated_at
    }));
  }
  
  async getFailureDetails(runId) {
    const logs = await get_job_logs({
      owner: this.owner,
      repo: this.repo,
      run_id: runId,
      failed_only: true,
      return_content: true
    });
    
    return parseFailureLogs(logs);
  }
}

Repository Analysis

Code Quality Assessment

// Analyze repository structure and quality
const analyzeRepository = async () => {
  // Get repository contents
  const contents = await list_repository_contents({
    owner: "ElliotBadinger",
    repo: "echo",
    path: ""
  });
  
  // Analyze structure
  const structure = analyzeProjectStructure(contents);
  
  // Check for quality indicators
  const quality = assessCodeQuality(structure);
  
  return { structure, quality };
};

Branch Management

// Monitor branch status and activity
const monitorBranches = async () => {
  const branches = await list_branches({
    owner: "ElliotBadinger",
    repo: "echo"
  });
  
  const branchStatus = await Promise.all(
    branches.map(async (branch) => {
      const commits = await list_commits({
        owner: "ElliotBadinger",
        repo: "echo",
        sha: branch.commit.sha,
        per_page: 5
      });
      
      return {
        name: branch.name,
        last_commit: commits[0],
        status: analyzeBranchHealth(commits)
      };
    })
  );
  
  return branchStatus;
};

🔧 Troubleshooting GitHub MCP Issues

Common Issues and Solutions

Synchronization Conflicts

  • Issue: GitHub MCP commits bypass local git
  • Solution: Always coordinate with user before GitHub MCP operations
  • Prevention: Use manual git for all commits and pushes

API Rate Limits

  • Issue: GitHub API rate limiting
  • Solution: Implement request throttling and caching
  • Prevention: Monitor usage and implement efficient querying

Workflow Not Triggering

  • Issue: CI workflow not starting after push
  • Solution: Check workflow configuration and trigger conditions
  • Prevention: Validate workflow setup before pushing changes

Artifact Download Failures

  • Issue: Unable to download CI artifacts
  • Solution: Check artifact retention policies and availability
  • Prevention: Download artifacts immediately after CI completion

Performance Optimization

  • Batch Requests: Group related API calls to reduce overhead
  • Cache Results: Cache frequently accessed repository data
  • Selective Monitoring: Monitor only relevant workflows and branches
  • Efficient Queries: Use specific filters to reduce result sets

📊 Measuring GitHub MCP Effectiveness

Success Metrics

Quantitative Metrics

  • CI Monitoring Coverage: Percentage of builds monitored
  • Failure Detection Speed: Time to detect and analyze failures
  • Artifact Utilization: Percentage of available artifacts downloaded
  • Workflow Optimization: Improvements in CI/CD efficiency

Qualitative Metrics

  • Development Velocity: Impact on development speed
  • Issue Resolution: Effectiveness in debugging and fixing issues
  • Process Automation: Level of workflow automation achieved
  • Team Productivity: Overall impact on development productivity

Usage Optimization

Monitoring Dashboard

// Implement comprehensive monitoring
const createMonitoringDashboard = async () => {
  const dashboard = {
    ci_status: await monitorCIStatus(),
    repository_health: await analyzeRepositoryHealth(),
    workflow_performance: await analyzeWorkflowPerformance(),
    artifact_utilization: await trackArtifactUsage()
  };
  
  return dashboard;
};

Automated Reporting

// Generate weekly GitHub MCP usage reports
const generateWeeklyReport = async () => {
  const report = {
    period: getCurrentWeek(),
    ci_runs_monitored: await countCIMonitored(),
    failures_analyzed: await countFailuresAnalyzed(),
    artifacts_downloaded: await countArtifactsDownloaded(),
    time_saved: calculateTimeSaved(),
    effectiveness_rating: calculateEffectiveness()
  };
  
  return report;
};

📚 GitHub MCP Best Practices

Workflow Integration Guidelines

  1. Read Operations First: Use read operations extensively for analysis
  2. Coordinate Write Operations: Always coordinate with user for write operations
  3. Monitor CI Actively: Implement comprehensive CI monitoring
  4. Analyze Failures Thoroughly: Use detailed job logs and artifacts
  5. Track Performance: Monitor workflow performance and optimization opportunities

Quality Assurance Practices

  1. Validate Results: Always verify GitHub MCP results
  2. Handle Errors Gracefully: Implement proper error handling
  3. Document Usage: Record GitHub MCP usage for transparency
  4. Optimize Queries: Use efficient querying patterns
  5. Monitor API Limits: Track and manage API usage

Integration Best Practices

  1. Framework Integration: Use GitHub MCP across all development frameworks
  2. Automation Focus: Automate repetitive monitoring and analysis tasks
  3. Quality Metrics: Track and improve effectiveness metrics
  4. Process Documentation: Document successful integration patterns
  5. Continuous Improvement: Regularly review and optimize usage

🎯 GitHub MCP Integration Roadmap

Immediate Actions (Week 1-2)

  • Optimize CI monitoring workflows
  • Implement automated failure analysis
  • Improve artifact utilization
  • Enhance repository analysis capabilities

Medium-term Goals (Month 1-3)

  • Achieve comprehensive CI coverage
  • Implement automated performance tracking
  • Develop advanced workflow analytics
  • Create repository health monitoring

Long-term Vision (Month 3+)

  • GitHub MCP as central development workflow tool
  • Comprehensive automation of development processes
  • Advanced analytics and predictive insights
  • Seamless integration with all development frameworks

This guide optimizes GitHub MCP usage for development workflow integration. For Brave Search research, see docs/mcp-integration/brave-search-guide.md. For general MCP integration, see docs/mcp-integration/mcp-optimization.md.