Project 10: “The GitHub Project Manager” — Workflow Automation

Attribute Value
File KIRO_CLI_LEARNING_PROJECTS.md
Main Programming Language JSON (Config)
Coolness Level Level 2: Practical
Difficulty Level 2: Intermediate
Knowledge Area Workflow Automation

What you’ll build: Integrate @modelcontextprotocol/server-github and generate issue summaries and PR drafts.

Why it teaches Tool Integration: Kiro bridges code and project management without context switching.

Success criteria:

  • Kiro can summarize open issues with a label filter.

Real World Outcome

You’ll configure the GitHub MCP server so Kiro can list issues, search PRs, read file contents, and draft pull request descriptions—all without leaving the terminal. This turns Kiro into a project manager that understands both your code and your issue tracker.

Configuration (.kiro/settings/mcp.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}

When you ask Kiro to manage issues:

$ kiro chat

You: "Summarize all open bugs with the 'critical' label"

Kiro: [Tool: github/search_issues]
  Query: repo:your-org/your-repo is:issue is:open label:critical

[Tool: github/get_issue] (for each result)

**Critical Bugs Summary** (3 open)

1. **Database connection pool exhausted** (#342)
   - Opened: 2 days ago by @alice
   - Last updated: 4 hours ago
   - Symptom: Production app crashes after ~1000 concurrent users
   - No PR linked yet

2. **Payment gateway timeout on Stripe webhook** (#338)
   - Opened: 5 days ago by @bob
   - PR #340 (in review)
   - Root cause: Missing retry logic in webhook handler

3. **Data corruption in user preferences migration** (#335)
   - Opened: 1 week ago by @charlie
   - Assigned to: @dave
   - Rollback already deployed, fix in progress

**Priority Order Recommendation:**
- Fix #342 first (production outage risk)
- Merge PR #340 for #338 (already has solution)
- #335 can wait (rollback mitigates)

You: "Draft a PR description for fixing #342"

Kiro: [Tool: github/get_issue] (reads #342 full details)
[Tool: github/search_code] (finds connection pool config)

**Pull Request Draft:**

---
**Title:** Fix database connection pool exhaustion under high load

**Fixes:** #342

**Problem:**
The application crashes when concurrent user count exceeds ~1,000 due to database connection pool exhaustion. Current pool size is hardcoded to 10 connections.

**Root Cause:**
`config/database.js` sets `max: 10` without considering production load. Under load testing, connection wait time exceeded timeout threshold.

**Solution:**
- Increase connection pool size to 50 (based on DB max_connections=100)
- Add connection timeout of 5 seconds with retry logic
- Implement connection pool monitoring via Prometheus metrics

**Changes:**
- `config/database.js` - Updated pool configuration
- `lib/metrics.js` - Added pool health gauges
- `tests/load/connection-pool.test.js` - Load test validation

**Testing:**
- Load test with 2,000 concurrent users (sustained 10 min)
- Verified connection pool metrics in Grafana
- No connection timeouts observed

**Checklist:**
- [ ] Updated documentation (deployment guide)
- [ ] Added monitoring alerts for pool >80% utilization
- [ ] Tested rollback scenario
---

You: "Create the PR on branch 'fix/db-pool' targeting 'main'"

Kiro: [Tool: github/create_pull_request]

PR created: https://github.com/your-org/your-repo/pull/345

The power: Kiro read issue history, searched the codebase, and drafted a production-ready PR description without you switching between GitHub UI, terminal, and code editor.

The Core Question You’re Answering

“How do I integrate my issue tracker and code repository so I can manage projects conversationally without context switching?”

Traditional workflows require:

  1. Open GitHub in browser
  2. Read issue
  3. Switch to terminal
  4. Grep codebase for relevant files
  5. Switch back to browser
  6. Draft PR description (copying from terminal)

This project eliminates the context-switching tax by giving Kiro unified access to both code and project management.

Concepts You Must Understand First

Stop and research these before coding:

  1. GitHub Personal Access Tokens (PAT)
    • What scopes does the GitHub MCP server require (repo, read:org)?
    • How do you create a fine-grained token with minimal permissions?
    • Where should you store tokens securely (never in git)?
    • Web Reference: GitHub - Creating a Personal Access Token
  2. GitHub Search Syntax
    • How do you filter issues by label, state, author, and date?
    • What’s the difference between searching issues vs code?
    • How do you use qualifiers like is:pr, is:open, label:bug?
    • Web Reference: GitHub - Searching Issues and Pull Requests
  3. MCP Tools vs Resources
    • What’s the difference between calling a tool and loading a resource?
    • How do MCP tools return structured data (JSON schemas)?
    • How do you handle pagination in GitHub API responses?
    • Web Reference: Model Context Protocol - Tools

Questions to Guide Your Design

Before implementing, think through these:

  1. Token Permissions
    • Should you use a classic PAT or fine-grained token?
    • What’s the minimum scope needed (read-only issues, or also write PRs)?
    • How do you rotate tokens without breaking the MCP server?
    • Should you use organization-level tokens or personal tokens?
  2. Workflow Automation
    • What tasks should Kiro handle automatically (summarize) vs require approval (create PR)?
    • How do you prevent Kiro from creating duplicate issues?
    • Should Kiro be able to close issues, or only comment?
    • How do you audit all actions Kiro takes on GitHub?
  3. Context Boundaries
    • How much issue history should Kiro load (all comments, or just descriptions)?
    • Should Kiro analyze linked PRs and commits?
    • How do you prevent Kiro from leaking private repo data in logs?

Thinking Exercise

Scenario: Triaging a Bug Report

Given this GitHub issue:

Title: App crashes on iOS 14 when uploading photos

Body:
Steps to reproduce:
1. Open app on iPhone 8 (iOS 14.8)
2. Tap "Upload Photo"
3. Select image from camera roll
4. App crashes immediately

Expected: Photo uploads successfully
Actual: App crashes, no error message

Environment:
- iPhone 8, iOS 14.8
- App version 2.3.1

Questions Kiro should investigate:

  1. Search for similar issues:
    • Query: repo:your-org/your-app is:issue label:ios "upload" "crash"
    • Are there duplicates or related bugs?
  2. Analyze codebase:
    • Where is photo upload logic? (grep -r "upload.*photo" src/)
    • What changed in version 2.3.1? (git diff v2.3.0..v2.3.1)
  3. Check iOS version compatibility:
    • Does the app support iOS 14? (check package.json or podfile)
    • Were there recent iOS SDK changes?
  4. Draft response:
    • If it’s a duplicate: link to existing issue
    • If it’s new: suggest debug steps (enable logging, check memory usage)
    • If it’s a known limitation: explain iOS 14 support status

Kiro’s workflow should be:

  1. Search issues → 2. Search code → 3. Check git history → 4. Draft comment

The Interview Questions They’ll Ask

  1. “How would you design an AI assistant that can triage GitHub issues without creating spam or incorrect closures?”

  2. “Explain the security implications of granting an AI write access to your GitHub repository. What guardrails would you implement?”

  3. “How do you prevent an AI from leaking private repository information when generating responses?”

  4. “Describe how you would implement approval workflows for AI-generated pull requests in a team environment.”

  5. “What strategies would you use to keep GitHub integration working across API version changes and rate limits?”

Hints in Layers

Hint 1: Create a GitHub Personal Access Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Set repository access (all repos or specific ones)
  3. Grant permissions: Contents: Read, Issues: Read/Write, Pull Requests: Read/Write
  4. Copy token and store in .env file (never commit to git)

Hint 2: Configure MCP Server

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"  // Loaded from environment
      }
    }
  }
}

Hint 3: Test GitHub Integration

kiro chat

You: "List the 5 most recently updated issues in my repo"

# Kiro should call: github/search_issues
# You should see a list of issues with titles, numbers, and states

Hint 4: Draft a PR Description Template Create a steering file (.kiro/steering/github-pr-template.md):

# Pull Request Template

Always include these sections when drafting PRs:
- **Problem:** What issue does this solve?
- **Solution:** High-level approach
- **Changes:** Files modified
- **Testing:** How to verify
- **Checklist:** Deployment steps

Books That Will Help

Topic Book Chapter
GitHub Workflow “Pro Git” by Scott Chacon Ch. 6 (GitHub)
API Integration “Designing Data-Intensive Applications” by Martin Kleppmann Ch. 4 (Encoding)
Automation Best Practices “The DevOps Handbook” by Gene Kim et al. Part III (Flow)

Common Pitfalls & Debugging

Problem 1: “MCP server fails with ‘Bad credentials’“

  • Why: GitHub token is invalid or expired
  • Fix: Regenerate token with correct scopes, update .env file
  • Quick test: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

Problem 2: “Kiro can read issues but cannot create PRs”

  • Why: Token lacks Pull Requests: Write permission
  • Fix: Edit token permissions in GitHub settings
  • Quick test: gh pr create --title "Test" --body "Test" (using GitHub CLI)

Problem 3: “Rate limit exceeded errors”

  • Why: GitHub API has rate limits (5,000 requests/hour for authenticated)
  • Fix: Implement caching or reduce query frequency
  • Quick test: Check remaining quota: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit

Problem 4: “Kiro creates PR with wrong base branch”

  • Why: Default branch is not ‘main’ in your repo (might be ‘master’ or ‘develop’)
  • Fix: Specify base branch explicitly in steering file or prompt
  • Quick test: git remote show origin | grep "HEAD branch"

Definition of Done

  • Created GitHub Personal Access Token with appropriate scopes
  • Configured github-mcp in .kiro/settings/mcp.json with secure token
  • Verified Kiro can list and search issues/PRs successfully
  • Kiro can read file contents from repository
  • Drafted at least one PR description using issue context + codebase search
  • Tested that token has minimal required permissions (no admin access)
  • Created steering file with PR description template
  • Documented all GitHub integration workflows in README