GitHub Copilot Integration Guide

Complete guide to using GitHub Copilot Workspace with the Agentic AI Development Framework.

Overview
Quick Start
How It Works
Workflow Commands
Configuration
Best Practices
Examples
Troubleshooting
Advanced Usage

Overview

This repository is configured to work seamlessly with GitHub Copilot Workspace, enabling CODEOWNERS to assign issues to GitHub Copilot for automated implementation. When an issue is approved, GitHub Copilot can:

✅ Analyze the full issue context (description, comments, related code)
✅ Generate a detailed implementation plan
✅ Write production-ready code following repository conventions
✅ Create comprehensive tests (>=75% coverage requirement)
✅ Open a pull request with complete documentation

Key Features

Permission-Based: Only CODEOWNERS can trigger implementation
Context-Aware: Copilot reads all issue comments and repository conventions
Automated Validation: GitHub Actions validates permissions and collects context
Labeled Tracking: Issues are automatically labeled for tracking
Flexible Configuration: Customize branch names and models per issue

Quick Start

Prerequisites

GitHub Copilot License: Organization or individual subscription
Repository Access: Must be listed in /CODEOWNERS
Issue Ready: Well-written issue with clear acceptance criteria

Basic Usage

Create or find an issue that needs implementation
Review and refine the issue description with team
Trigger implementation (CODEOWNERS only):
```
/implement-plan
```
Open in Copilot Workspace: Click the button or URL provided in the confirmation comment
Review the plan generated by Copilot
Approve execution to generate code
Review the PR created by Copilot
Merge after CI passes and code review

How It Works

Workflow Diagram

┌─────────────────────────────────────────────────────────────┐
│  Step 1: Issue Creation                                     │
│  Developer creates issue with problem statement             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 2: Discussion & Refinement                            │
│  Team adds context, requirements, constraints               │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 3: CODEOWNER Approval                                 │
│  Comment: /implement-plan [options]                         │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 4: Automated Validation (GitHub Actions)              │
│  ✅ Verify commenter is CODEOWNER                           │
│  ✅ Parse command parameters                                │
│  ✅ Collect full issue context                              │
│  ✅ Add tracking labels                                     │
│  ✅ Post confirmation comment                               │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 5: GitHub Copilot Workspace                           │
│  Open issue in Copilot Workspace (manual or automatic)      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 6: Plan Generation                                    │
│  Copilot analyzes repo and generates implementation plan    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 7: Developer Review                                   │
│  Review plan, provide feedback, approve execution           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 8: Code Generation                                    │
│  Copilot creates code, tests, docs                          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 9: Pull Request                                       │
│  Copilot opens PR on configured branch                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 10: CI/CD Validation                                  │
│  Tests, linters, coverage checks run automatically          │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Step 11: Code Review & Merge                               │
│  Team reviews, approves, merges to dev                      │
└─────────────────────────────────────────────────────────────┘

What Happens Automatically

When you comment /implement-plan:

Permission Check: GitHub Actions validates you're a CODEOWNER
Context Collection: All issue data is collected (title, body, comments, labels)
Label Addition: copilot-implementing and approved labels are added
Branch Configuration: Default or custom branch name is set
Model Configuration: Default or custom model is set
Confirmation Comment: Detailed instructions posted to issue
Context Comment: Full implementation context posted for Copilot

Workflow Commands

Basic Command

/implement-plan

Defaults:

Branch: copilot/issue-{number} (e.g., copilot/issue-42)
Model: gpt-oss:20b

Command with Parameters

# Custom branch name
/implement-plan branch=feature/user-authentication

# Custom model (for complex tasks)
/implement-plan model=gpt-4.1

# Both parameters
/implement-plan branch=feature/password-reset model=gpt-4.1

Parameter Reference

Parameter	Description	Example	Default
`branch`	Target branch name	`feature/login`	`copilot/issue-N`
`model`	LLM model to use	`gpt-4.1`	`gpt-oss:20b`

Supported Models

Model	Best For	Context Window
`gpt-oss:20b`	Standard features (default)	8K tokens
`gpt-4.1`	Complex logic, large codebase	128K tokens
`llama3.1:8b`	Simple fixes, quick iterations	8K tokens

Configuration

Repository Configuration

1. CODEOWNERS File

Located at: /CODEOWNERS

# Global code owners for entire repository
* @vibhatsrivastava @teammember

# Specific project owners
/projects/04_github_issue_reporter/ @github-team

Add New CODEOWNER:

Edit /CODEOWNERS
Add GitHub username with @ prefix
Commit and push
New CODEOWNER can trigger /implement-plan

2. Copilot Instructions

Located at: .github/copilot-instructions.md

This file contains repository-wide instructions for GitHub Copilot. Already configured with:

Repository structure overview
Environment setup requirements
Coding conventions (LCEL, LangGraph patterns)
Testing requirements (75% coverage minimum)
Common pitfalls and solutions

Customization: Edit this file to add project-specific conventions that Copilot should follow.

3. Workflow Configuration

Located at: .github/workflows/copilot-implement.yml

Key Settings:

permissions:
  issues: write          # Required for labels and comments
  contents: write        # Required for branch creation
  pull-requests: write   # Required for PR creation

Triggers:

on:
  issue_comment:
    types: [created]     # Runs when issue comment is posted

Customization:

Modify default branch pattern
Add additional validation steps
Customize confirmation message format
Add notifications (Teams, Slack, etc.)

Issue Labels

When /implement-plan is triggered, these labels are automatically added:

Label	Meaning	When Added
`copilot-implementing`	Copilot is working on this	On approval
`approved`	CODEOWNER approved implementation	On approval

Custom Labels: Add more labels in the workflow file at line 183-184:

labels: ['copilot-implementing', 'approved', 'your-custom-label']

Best Practices

1. Writing Copilot-Friendly Issues

✅ Good Example:

## Problem Statement
Users cannot export reports to PDF format, which is frequently requested.

## Current Behavior
- Reports only available as HTML
- No export button visible
- Print functionality is poor (cuts off content)

## Expected Behavior
- "Export to PDF" button on report page
- Generates PDF with proper formatting
- Includes all charts and tables
- Downloads automatically

## Technical Context
- Reports generated in `projects/03_reporting/src/report_generator.py`
- We use the `reportlab` library (already installed)
- Report data is in JSON format (example below)

## Acceptance Criteria
- [ ] Export button visible on all report pages
- [ ] PDF includes all data from HTML version
- [ ] Charts render correctly in PDF
- [ ] File naming: `report_{type}_{date}.pdf`
- [ ] Tests cover PDF generation (>=75% coverage)

## Security Considerations
- Validate report ID to prevent unauthorized access
- Limit file size (max 10MB)
- Sanitize filenames to prevent path traversal

## Example Report Data
\`\`\`json
{
  "title": "Monthly Sales Report",
  "date": "2026-05-21",
  "data": [...]
}
\`\`\`

Why This Works:

Clear problem and solution description
Technical context provided
Acceptance criteria are measurable
Security considerations mentioned
Example data included

❌ Bad Example:

Add PDF export

Users want PDF reports. Please implement.

Problems:

Too vague
No technical context
No acceptance criteria
No examples

2. Providing Context in Comments

When team discusses the issue, add technical details:

@copilot For the PDF generation, please:
1. Use the existing `ReportService` class in `common/services/report.py`
2. Follow the same error handling pattern as CSV export (see line 145)
3. Store generated PDFs in S3 bucket (credentials in `.env`)
4. Add async generation for reports >100 pages

Edge cases to handle:
- Reports with no data (show "No data available" message)
- Very large reports (>500 pages) - add pagination
- Special characters in report titles (sanitize for filename)

3. Reviewing Copilot-Generated PRs

Focus Areas:

Logic Correctness ⭐⭐⭐
- Does it solve the problem?
- Are edge cases handled?
- Are error conditions covered?
Security ⭐⭐⭐
- Input validation present?
- No hardcoded secrets?
- Proper authentication/authorization?
Tests ⭐⭐
- Coverage >= 75%?
- Edge cases tested?
- Integration tests included?
Code Quality ⭐
- Follows repository conventions?
- Readable and maintainable?
- Documentation adequate?

Don't Nitpick:

Minor style differences (linters handle this)
Variable naming (if consistent with codebase)
Comment style (if adequate)

Request Changes For:

Security vulnerabilities
Missing error handling
Insufficient test coverage
Doesn't meet acceptance criteria
Breaking changes without migration plan

4. Iterating on Implementation

If the first PR needs changes:

Option 1: Comment on PR (Recommended)

@copilot The error handling needs improvement:

Current code (line 45):
\`\`\`python
result = api_call()
\`\`\`

Please add try-except with specific error handling:
\`\`\`python
try:
    result = api_call()
except ConnectionError:
    logger.error("API connection failed")
    return {"error": "Service unavailable"}
except Timeout:
    logger.error("API timeout")
    return {"error": "Request timed out"}
\`\`\`

Copilot can regenerate based on your feedback.

Option 2: Manual Edits (Small Changes)

# Pull the branch
git fetch origin copilot/issue-42
git checkout copilot/issue-42

# Make targeted changes
vim src/file.py

# Commit and push
git add src/file.py
git commit -m "Add specific error handling"
git push origin copilot/issue-42

Option 3: Reject & Retry (Major Problems)

Close the PR
Update issue with clarifications
Trigger /implement-plan again

Examples

Example 1: Standard Feature Implementation

Issue:

## Add Redis Caching for API Responses

Cache frequently accessed API responses in Redis to reduce database load.

## Current Behavior
- Every API call queries the database
- Slow response times (500ms avg)
- High database CPU usage

## Expected Behavior
- API responses cached in Redis (TTL: 5 minutes)
- First call queries DB, subsequent calls use cache
- Response time < 100ms for cached data

## Technical Context
- Redis server: localhost:6379 (dev), AWS ElastiCache (prod)
- Use `redis-py` library (already installed)
- Connection config in `common/redis_client.py`

## Acceptance Criteria
- [ ] Cache hit rate > 80% for repeated requests
- [ ] TTL configurable via environment variable
- [ ] Cache invalidation on data updates
- [ ] Tests with mocked Redis connection

Command:

/implement-plan branch=feature/redis-caching

Expected PR:

New file: common/cache_service.py (Redis wrapper)
Modified: API endpoints to use caching
Tests: Unit tests with mocked Redis, integration tests
Documentation: Updated README with Redis setup
Configuration: Added REDIS_TTL to .env.example

Example 2: Bug Fix

Issue:

## Fix: Token Counter Returns Negative Values

The `count_tokens()` function returns negative values for empty strings.

## Steps to Reproduce
\`\`\`python
from common.utils import count_tokens
result = count_tokens("")
print(result)  # Output: -1 (expected: 0)
\`\`\`

## Root Cause (Suspected)
Line 78 in `common/utils.py`:
\`\`\`python
return len(tokens) - 1  # Bug: shouldn't subtract for empty input
\`\`\`

## Expected Behavior
- Empty string should return 0
- Single token should return 1
- Multiple tokens should return count

## Acceptance Criteria
- [ ] Fix returns 0 for empty strings
- [ ] Add test case for empty string
- [ ] Add test cases for edge cases (whitespace, unicode)
- [ ] Ensure existing tests still pass

Command:

/implement-plan branch=bugfix/token-counter model=llama3.1:8b

Expected PR:

Modified: common/utils.py (fix the bug)
Tests: Added edge case tests
Documentation: None needed (bug fix)

Example 3: Complex Feature (Multiple Files)

Issue:

## Implement User Authentication System

Add JWT-based authentication with login, logout, and token refresh.

## Requirements
1. **Login Endpoint**
   - POST `/api/auth/login`
   - Body: `{"email": "...", "password": "..."}`
   - Returns: `{"access_token": "...", "refresh_token": "..."}`

2. **Token Refresh Endpoint**
   - POST `/api/auth/refresh`
   - Body: `{"refresh_token": "..."}`
   - Returns: `{"access_token": "..."}`

3. **Logout Endpoint**
   - POST `/api/auth/logout`
   - Headers: `Authorization: Bearer <token>`
   - Returns: `{"message": "Logged out"}`

## Technical Context
- Use `PyJWT` library (not yet installed, add to requirements.txt)
- Store hashed passwords with `bcrypt`
- JWT secret from environment variable `JWT_SECRET`
- Access token TTL: 15 minutes
- Refresh token TTL: 7 days

## Security Requirements
- Passwords must be hashed (never stored plain text)
- Tokens must be signed with strong secret
- Implement rate limiting (5 attempts per minute)
- Log all authentication events
- Validate email format before lookup

## Acceptance Criteria
- [ ] All three endpoints implemented and tested
- [ ] Passwords hashed with bcrypt
- [ ] JWT tokens properly signed and validated
- [ ] Rate limiting prevents brute force
- [ ] Test coverage >= 75%
- [ ] Documentation updated with API examples

Command:

/implement-plan branch=feature/authentication model=gpt-4.1

Expected PR:

New files:
- common/auth/jwt_handler.py (JWT logic)
- common/auth/password_handler.py (hashing logic)
- projects/api/src/routes/auth.py (endpoints)
- Tests for all modules
Modified files:
- requirements-base.txt (add PyJWT, bcrypt)
- .env.example (add JWT_SECRET)
- projects/api/README.md (API documentation)
Tests: Comprehensive unit and integration tests
Documentation: API usage examples

Troubleshooting

Issue: `/implement-plan` Not Working

Symptom: No response after commenting /implement-plan

Possible Causes:

Not a CODEOWNER
- Check /CODEOWNERS file
- Verify your username is listed
- Solution: Ask existing CODEOWNER to add you
Command Format Wrong
- Must be on its own line
- Must start with / (no spaces before)
- Solution: Use exact format: /implement-plan
Workflow Disabled
- Check repository settings
- Actions may be disabled
- Solution: Settings → Actions → Enable workflows
Permissions Issue
- Workflow needs write permissions
- Solution: Settings → Actions → Workflow permissions → Read and write

Debug Steps:

# 1. Check if you're a CODEOWNER
cat CODEOWNERS | grep your-username

# 2. Check workflow runs
# Go to: Actions tab → Copilot Auto-Implementation

# 3. View workflow logs
# Click failed run → View logs → Check error message

Issue: Copilot Doesn't Understand Context

Symptom: Generated code doesn't match expectations

Possible Causes:

Issue Too Vague
- Missing technical details
- No examples provided
- Solution: Update issue with more context
Conventions Not Clear
- Copilot doesn't know project patterns
- Solution: Add details to .github/copilot-instructions.md
Missing References
- Referenced files not accessible
- Solution: Include code snippets in issue

Fix Steps:

1. Update issue description with:
   - Specific file paths to modify
   - Code patterns to follow
   - Examples of desired output

2. Add clarifying comment:
   @copilot Please use the existing pattern from 
   `projects/03_example/src/handler.py` lines 45-60
   for error handling.

3. Re-trigger if needed:
   Close PR, clarify issue, comment /implement-plan again

Issue: Generated Code Fails Tests

Symptom: CI fails on Copilot-generated PR

Common Failures:

Linting Errors
- Code style doesn't match
- Quick Fix: Run black and flake8 locally, push fixes
Test Coverage Below 75%
- Missing test cases
- Solution: Comment on PR requesting additional tests
Integration Tests Fail
- Missing mocked dependencies
- Solution: Update tests to mock external services
Import Errors
- Missing dependencies
- Solution: Add to requirements.txt or requirements-base.txt

Fix Process:

# Pull the PR branch
git fetch origin copilot/issue-N
git checkout copilot/issue-N

# Run tests locally
pytest --cov --cov-report=term-missing

# Fix issues
vim src/file.py

# Push fixes
git add .
git commit -m "Fix linting and test coverage"
git push origin copilot/issue-N

Issue: "Open in Copilot Workspace" Button Missing

Symptom: Can't open issue in Copilot Workspace

Possible Causes:

No Copilot License
- Copilot subscription required
- Solution: Get GitHub Copilot license
Issue Already Assigned
- Can't use Copilot if assigned to someone
- Solution: Unassign issue first
Repository Not Enabled
- Copilot not enabled for repo
- Solution: Settings → GitHub Copilot → Enable

Alternative: Use manual workflow:

Read confirmation comment on issue
Follow implementation context
Implement manually or in VS Code with Copilot

Advanced Usage

Custom Workflows

You can create custom workflows for specific scenarios:

Example: Auto-Assign High-Priority Issues

Create .github/workflows/auto-assign-copilot.yml:

name: Auto-Assign High Priority to Copilot

on:
  issues:
    types: [labeled]

jobs:
  auto-assign:
    if: github.event.label.name == 'priority-high'
    runs-on: ubuntu-latest
    steps:
      - name: Add Copilot comment
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `🚨 High priority issue detected. CODEOWNERS, please review and trigger implementation with \`/implement-plan\` if appropriate.`
            });

Metrics and Tracking

Track Copilot implementation metrics:

# Count Copilot-implemented issues
gh issue list --label "copilot-implementing" --state closed --json number,closedAt

# Average time from approval to PR merge
# (Requires custom script to analyze GitHub API data)

# Success rate (PRs merged vs closed)
gh pr list --label "copilot-implementing" --state merged --json number

Integration with Project Management

Jira Integration:

# .github/workflows/copilot-jira-sync.yml
name: Sync Copilot Status to Jira

on:
  issues:
    types: [labeled]

jobs:
  sync:
    if: github.event.label.name == 'copilot-implementing'
    runs-on: ubuntu-latest
    steps:
      - name: Update Jira ticket
        run: |
          # Update corresponding Jira ticket status
          # "In Progress - Copilot Implementing"

Summary

Key Takeaways

Only CODEOWNERS can trigger /implement-plan
Clear issues get better results from Copilot
Review carefully - Copilot is good but not perfect
Iterate quickly - Use comments to refine implementation
Follow conventions - Documented in .github/copilot-instructions.md

Quick Reference

Task	Command/Action
Trigger implementation	`/implement-plan`
Custom branch	`/implement-plan branch=feature/name`
Custom model	`/implement-plan model=gpt-4.1`
Check CODEOWNERS	View `/CODEOWNERS` file
View workflow runs	Actions tab → Copilot Auto-Implementation
Update conventions	Edit `.github/copilot-instructions.md`

Getting Help

Documentation: Quick Reference, CI/CD Guide
Quick Reference: GitHub Copilot Workspace Guide
Workflow Logs: Actions tab → Copilot Auto-Implementation workflow
Support: Create issue and tag @vibhatsrivastava

Additional Resources

Official GitHub Documentation

Repository Documentation

Related Files

Last Updated: 2026-05-21
Version: 1.0

FilesExpand file tree

github-copilot-integration.md

Latest commit

History

github-copilot-integration.md

File metadata and controls

GitHub Copilot Integration Guide

Table of Contents

Overview

Key Features

Quick Start

Prerequisites

Basic Usage

How It Works

Workflow Diagram

What Happens Automatically

Workflow Commands

Basic Command

Command with Parameters

Parameter Reference

Supported Models

Configuration

Repository Configuration

1. CODEOWNERS File

2. Copilot Instructions

3. Workflow Configuration

Issue Labels

Best Practices

1. Writing Copilot-Friendly Issues

2. Providing Context in Comments

3. Reviewing Copilot-Generated PRs

4. Iterating on Implementation

Examples

Example 1: Standard Feature Implementation

Example 2: Bug Fix

Example 3: Complex Feature (Multiple Files)

Troubleshooting

Issue: /implement-plan Not Working

Issue: Copilot Doesn't Understand Context

Issue: Generated Code Fails Tests

Issue: "Open in Copilot Workspace" Button Missing

Advanced Usage

Custom Workflows

Metrics and Tracking

Integration with Project Management

Summary

Key Takeaways

Quick Reference

Getting Help

Additional Resources

Official GitHub Documentation

Repository Documentation

Related Files

Issue: `/implement-plan` Not Working