GitHub Integration

🐙 GitHub Integration (Θ)

Integrate GitHub directly into your CursorRIPER♦Σ workflow for seamless repository management, code collaboration, and version control.

🎯 Overview

GitHub integration enables:

• 🔍 Repository search and discovery
• 📁 Repository creation and management
• 🔄 File operations and commits
• 🔀 Pull request workflows
• 🐛 Issue tracking
• 🌿 Branch management

🚀 Setup

1. Install GitHub MCP Server

npm install -g @modelcontextprotocol/server-github

2. Configure Authentication

# Create a GitHub Personal Access Token
# Go to: GitHub → Settings → Developer settings → Personal access tokens

# Set environment variable
export GITHUB_TOKEN=ghp_your_token_here

3. Update MCP Configuration

In .cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

4. Enable in Framework

Uncomment GitHub section in your framework rules.

📋 Command Reference

Repository Operations

Command	Function	Example
!gr	Search repositories	!gr oauth2 typescript
!gc	Create repository	!gc my-new-project
!gf	Fork repository	!gf torvalds/linux
!ginfo	Get repo info	!ginfo owner/repo

File Operations

Command	Function	Example
!gp	Push files	!gp
!gget	Get file contents	!gget README.md
!gcf	Create/update file	!gcf src/new.js

Pull Request Operations

Command	Function	Example
!gpr	Create pull request	!gpr
!gpl	List pull requests	!gpl
!gpm	Merge pull request	!gpm 123
!gprr	Review pull request	!gprr 123

Issue Operations

Command	Function	Example
!gi	Create issue	!gi "Bug in auth"
!gil	List issues	!gil
!giu	Update issue	!giu 45
!gic	Comment on issue	!gic 45 "Fixed"

Branch Operations

Command	Function	Example
!gb	Create branch	!gb feature/auth
!gbl	List branches	!gbl
!gco	Checkout branch	!gco develop

🔐 Mode Permissions

GitHub Operations by Mode

Operation	Research	Innovate	Plan	Execute	Review
Search repos	✓	✓	✓	✓	✓
Read files	✓	✓	✓	✓	✓
Create repo	✗	✗	✗	✓	✗
Push files	✗	✗	✗	✓	✗
Create PR	✗	✗	✗	✓	✗
Create issue	✗	✗	✓	✓	✗
Merge PR	✗	✗	✗	✓	✗

💡 Workflow Examples

1. Research Workflow

/research
!gr "authentication best practices"    # Search for examples
!gget owner/repo auth/README.md       # Read implementation
!gil owner/repo                       # Check known issues

2. Feature Development

/plan
!gb feature/user-auth                 # Plan branch

/execute  
!gco feature/user-auth               # Switch branch
# ... implement feature ...
!gp                                  # Push changes
!gpr                                 # Create pull request

3. Code Review

/review
!gpl                                 # List open PRs
!gget PR#123 src/auth.js            # Review specific file
!gprr 123 "LGTM"                    # Approve PR

4. Issue Management

/research
!gil label:bug                       # Find bug reports

/plan
!gi "Plan: Fix authentication bug"   # Create planning issue

/execute
!gic 45 "Fixed in commit abc123"    # Update issue
!giu 45 --close                      # Close issue

🎨 Integration Patterns

Repository Search Pattern

Use in RESEARCH mode to find examples:

// Symbol: Θ₁
operation: search_repositories
command: !gr
permissions: All modes

// Example usage
!gr "jwt authentication nodejs"
// Returns: List of relevant repositories

Collaborative Development Pattern

// In EXECUTE mode
1. Create feature branch
   !gb feature/new-feature
   
2. Implement changes
   // ... code implementation ...
   
3. Push changes
   !gp
   
4. Create pull request
   !gpr --title "Add new feature" --body "Implements [↗️σ₁:R₅]"

Code Review Pattern

// In REVIEW mode
1. List pull requests
   !gpl --state open
   
2. Get PR details
   !gget PR#123
   
3. Review changes
   // Analyze implementation
   
4. Add review
   !gprr 123 --approve "Meets requirements [↗️σ₁:R₅]"

🛡️ Security Considerations

Token Permissions

Recommended scopes for Personal Access Token:

• repo - Full repository access
• workflow - GitHub Actions (if needed)
• read:org - Organization read (if needed)

Best Practices

1. Never commit tokens

   # .gitignore
   .env
   *.token

2. Use environment variables

   # .env (local only)
   GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. Rotate tokens regularly

   • Set expiration dates
   • Revoke unused tokens
   • Monitor token usage

📊 Advanced Usage

Batch Operations

// Push multiple files
!gp --files "src/*.js" --message "Update all services"

// Create multiple issues
!gi --bulk issues.json

// Update multiple PRs
!gpm --auto-merge label:ready

Search Filters

// Complex repository search
!gr "language:typescript stars:>100 authentication"

// Issue search with filters
!gil "is:open label:bug assignee:@me"

// PR search
!gpl "is:open review:required base:main"

Automation

// Auto-merge approved PRs
!gpm --auto label:approved checks:passing

// Bulk close stale issues
!giu --close "is:open updated:<2024-01-01"

// Create release
!gt v1.0.0 --notes "Release notes [↗️σ₅:M₁]"

🚨 Common Issues

Authentication Failed

Error: Bad credentials

Solution:

• Check GITHUB_TOKEN is set
• Verify token hasn't expired
• Ensure token has required scopes

Repository Not Found

Error: Not found

Solution:

• Check repository name format: owner/repo
• Verify repository exists
• Check access permissions

Rate Limit Exceeded

Error: API rate limit exceeded

Solution:

• Wait for rate limit reset
• Use authenticated requests
• Implement caching

Permission Denied in Mode

⚠️ GitHub push not allowed in RESEARCH mode

Solution:

• Switch to EXECUTE mode
• Follow mode workflow

🎯 Best Practices

1. Mode-Appropriate Usage

• RESEARCH: Search and read only
• PLAN: Create issues for planning
• EXECUTE: Full repository operations
• REVIEW: Read and review only

2. Commit Message Standards

feat: Add user authentication [↗️σ₁:R₃]
fix: Resolve login timeout [↗️σ₅:I₁₂]
docs: Update API documentation

3. Branch Naming

feature/user-authentication
bugfix/login-timeout
refactor/auth-service

4. PR Templates

## Description
Implements user authentication as specified in [↗️σ₁:R₃]

## Changes
- Added JWT authentication
- Created login endpoint
- Added tests

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing complete

📈 Metrics & Monitoring

Track GitHub Activity

// Weekly metrics
!gstats --period week
- Commits: 47
- PRs merged: 3
- Issues closed: 5
- Code reviews: 8

Repository Health

!ghealth owner/repo
- Open issues: 12
- Open PRs: 3
- Last commit: 2 hours ago
- Contributors: 5

🔗 Integration with Framework

Memory Updates

GitHub operations automatically update:

• σ₄ (activeContext.md) - Current PR/issue
• σ₅ (progress.md) - Completed PRs/issues
• σ₆ (protection.md) - Protected branches

Cross-References

Use in commits and PRs:

Implements [↗️σ₁:R₅]      # Requirement reference
Fixes [↗️σ₅:I₁₂]          # Issue reference
Updates [↗️σ₂:P₃]         # Pattern reference

📚 Related Topics

• MCP Overview
• Web Search Integration
• Git References
• Team Collaboration

---

← MCP Overview | Home | Web Search →