Skip to content

Latest commit

Β 

History

History
418 lines (322 loc) Β· 9.64 KB

github-workflow-examples.md

File metadata and controls

418 lines (322 loc) Β· 9.64 KB

GitHub Workflow Examples - Real-World Usage Guide

This guide provides practical examples and patterns for using the GitHub integration to work through issues systematically.

πŸ“‹ Table of Contents

πŸš€ Initial Setup

Before starting your issue remediation session, set up your repository context:

# Set repository context (required once per session)
"Switch to repository owner/repo-name"

# Verify connection
"Check GitHub health status"

# Optional: Set default repository in .env
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=your-repository

πŸ“ Working Through Issues One by One

Step-by-Step Issue Remediation

Here's the recommended workflow for addressing individual issues:

1. Discovery Phase

# List all open issues
"Show me all open issues"

# Filter by labels
"Show me open issues with bug label"
"Fetch issues with enhancement label"

# Get specific issue details
"Get details for issue #5"

2. Analysis Phase

# Analyze issue with RAG search
"Analyze issue #5"

# This will:
# - Extract key patterns from the issue
# - Search your codebase for relevant files
# - Identify potential root causes
# - Map issue to specific code locations

3. Solution Generation

# Generate fix suggestions
"Generate fix suggestions for issue #5"

# Returns:
# - Multiple fix approaches with confidence scores
# - Specific code changes needed
# - Risk assessment for each approach
# - Implementation complexity

4. Preview Phase (Dry Run)

# Preview what would happen
"Resolve issue #5 in dry-run mode"

# Shows:
# - Branch name that would be created
# - Files that would be modified
# - Exact changes to be applied
# - Pull request description
# - Safety check results

5. Communication

# Keep stakeholders informed
"Add comment to issue #5: 'Analyzing this issue with RAG system. Found relevant files: src/indexers/code_indexer.py'"

# Progress updates
"Add comment to issue #5: 'Root cause identified - regex pattern issue. Testing fix now.'"

6. Implementation

# Apply the fix (creates PR)
"Resolve issue #5"

# Or with explicit dry-run disabled
"Resolve issue #5 with dry_run=false"

# This will:
# - Create a new branch
# - Apply the code changes
# - Commit with descriptive message
# - Push to remote
# - Create pull request
# - Link PR to issue

πŸ”„ Batch Processing Multiple Issues

Systematic Issue Processing

For handling multiple issues efficiently:

# Example workflow for processing all bugs

1. "Show me all open issues with bug label"
   
2. For each high-priority bug:
   a. "Analyze issue #X"
   b. Review analysis results
   c. "Generate fix suggestions for issue #X"
   d. If confidence > 80%:
      - "Resolve issue #X in dry-run mode"
      - Review changes
      - "Resolve issue #X"
   e. If confidence < 80%:
      - "Add comment to issue #X: 'Needs manual review - confidence too low'"

3. "Show me all open issues with enhancement label"
   # Repeat process for enhancements

Priority-Based Processing

# Process by severity
"Show me issues with label critical"
# Handle these first

"Show me issues with label high-priority"
# Handle these second

"Show me issues with label good-first-issue"
# Good for testing the workflow

πŸ“Š Common Workflow Patterns

Pattern 1: Bug Triage and Fix

# 1. Identify the bug
"Get issue #123 details"

# 2. Understand impact
"Analyze issue #123"

# 3. Verify the fix approach
"Generate fix suggestions for issue #123"

# 4. Test safely
"Resolve issue #123 in dry-run mode"

# 5. Apply if confident
"Resolve issue #123"

Pattern 2: Feature Request Implementation

# 1. Understand requirements
"Get issue #456 with comments"

# 2. Analyze codebase for integration points
"Analyze issue #456"

# 3. Design implementation
"Generate fix suggestions for issue #456"

# 4. Create draft PR for discussion
"Create pull request titled 'Draft: Feature #456' with body 'Initial implementation for discussion'"

Pattern 3: Documentation Issues

# 1. Identify documentation gaps
"Show me issues with label documentation"

# 2. For each doc issue:
"Analyze issue #789"

# 3. Generate documentation updates
"Generate fix suggestions for issue #789"

# 4. Apply changes
"Resolve issue #789"

Pattern 4: Security Fixes

# 1. Handle with extra caution
"Get issue #999 details"

# 2. Thorough analysis
"Analyze issue #999"

# 3. Always dry-run first
"Resolve issue #999 in dry-run mode"

# 4. Add security review comment
"Add comment to issue #999: 'Security fix prepared. Requires security team review before merge.'"

# 5. Create draft PR
"Create pull request as draft for security review"

βœ… Best Practices

1. Always Analyze First

  • Never skip the analysis phase
  • RAG search provides crucial context
  • Helps avoid duplicate work

2. Use Dry-Run Mode

  • Preview changes before applying
  • Verify file modifications are correct
  • Check branch naming conventions

3. Communicate Progress

  • Add comments for transparency
  • Link related issues
  • Update status regularly

4. Monitor Confidence Scores

Confidence > 85%: Usually safe to auto-apply
Confidence 70-85%: Review carefully, test thoroughly
Confidence < 70%: Consider manual intervention

5. Batch Similar Issues

  • Group by label or component
  • Apply similar fixes together
  • Test as a cohesive unit

6. Review Generated PRs

  • Even high-confidence fixes need review
  • Check for unintended side effects
  • Ensure code style consistency

πŸ“š Command Reference

Repository Management

"List my repositories"
"Switch to repository owner/repo"
"Check GitHub health status"

Issue Discovery

"Show me all open issues"
"Show me closed issues"
"Show issues with label [label-name]"
"Show issues assigned to me"
"Get issue #[number] details"
"Get issue #[number] with comments"

Issue Analysis

"Analyze issue #[number]"
"Search codebase for [pattern]"  # Uses RAG
"Find files related to issue #[number]"

Fix Generation

"Generate fix suggestions for issue #[number]"
"Suggest improvements for issue #[number]"

Implementation

"Resolve issue #[number] in dry-run mode"
"Resolve issue #[number]"
"Resolve issue #[number] with dry_run=false"

Communication

"Add comment to issue #[number]: '[message]'"
"Create issue titled '[title]' with body '[description]'"
"Create issue with labels bug,urgent"

Pull Requests

"Create pull request titled '[title]' with body '[description]'"
"Create PR from branch [branch-name]"

πŸ” Advanced Examples

Multi-Issue Dependencies

# When issues depend on each other
"Get issue #100 details"  # Parent issue
"Analyze issue #100"

"Get issue #101 details"  # Dependent issue
"Add comment to issue #101: 'Blocked by #100. Will address after #100 is resolved.'"

# After fixing #100
"Resolve issue #100"
"Add comment to issue #101: 'Blocker #100 resolved. Starting work on this issue.'"
"Resolve issue #101"

Handling Large Changes

# For issues requiring multiple files
"Analyze issue #200"
"Generate fix suggestions for issue #200"

# If many files affected
"Resolve issue #200 in dry-run mode"
# Review carefully

# Consider breaking into smaller PRs
"Add comment to issue #200: 'This requires extensive changes. Breaking into smaller PRs for easier review.'"

Emergency Hotfixes

# For critical production issues
"Get issue #911 details"
"Analyze issue #911"

# Skip dry-run for emergencies (use cautiously)
"Resolve issue #911 with dry_run=false"

# Immediately notify
"Add comment to issue #911: 'Emergency fix applied. PR #X created. Please review ASAP.'"

πŸ“ˆ Tracking Progress

Session Summary Pattern

# At start of session
"Show me all open issues"
# Note the count

# After working through issues
"Show me all open issues"
# Compare count

# Check your work
"Show me closed issues from today"
"Show me my recent pull requests"

Metrics Commands

# See what's been accomplished
"List pull requests created today"
"Show issues closed this week"
"Show issues with linked PRs"

🚨 Troubleshooting Common Scenarios

Issue Not Found

"Get issue #999 details"
# Error: Issue not found

# Verify repository context
"Check current repository"
"Switch to repository owner/repo"

Low Confidence Fixes

"Generate fix suggestions for issue #50"
# All suggestions have low confidence

# Get more context
"Add comment to issue #50: 'Automated analysis shows low confidence. Needs manual review for context.'"

# Try more specific analysis
"Search codebase for specific patterns mentioned in issue #50"

PR Creation Fails

"Resolve issue #75"
# Error: Branch already exists

# Check existing PRs
"Show pull requests for issue #75"

# Use different branch name
"Create PR with branch name 'fix-issue-75-v2'"

πŸ’‘ Pro Tips

  1. Start Small: Test with good-first-issue labels
  2. Build Confidence: Use dry-run extensively at first
  3. Create Templates: Save common comment patterns
  4. Track Patterns: Notice which issues resolve well automatically
  5. Iterate: The system learns from your codebase patterns

Remember: The GitHub integration is a powerful tool, but human oversight ensures quality. Use automation to accelerate your workflow, not replace careful review.