GitHub Integration

​

Overview

​

Key Capabilities

​

Issue Investigation

// From src-tauri/src/projects/github_issues.rs
interface GitHubIssue {
  number: u32
  title: string
  body: Option<string>
  state: string             // "open", "closed"
  labels: Vec<GitHubLabel>
  created_at: string
  author: GitHubAuthor
}

interface GitHubIssueListResult {
  issues: Vec<GitHubIssue>
  total_count: u32          // For pagination
}

1. Click GitHub icon in project sidebar
2. Browse open issues (up to 100)
3. Filter by state (open, closed, all)
4. Click “Investigate” on any issue
5. Jean creates worktree with issue context
6. AI analyzes issue and proposes solution

interface IssueContext {
  number: u32
  title: string
  body: Option<string>
  comments: Vec<GitHubComment>
}

<worktree>/.jean/contexts/issue-<number>.md

# Issue #123: Bug title

**Author:** @username
**Created:** 2024-01-15
**State:** open
**Labels:** bug, priority:high

## Description

[Issue body content]

## Comments

### @commenter1 (2024-01-16)
[Comment body]

### @commenter2 (2024-01-17)
[Comment body]

​

Pull Request Workflows

interface GitHubPRDetail {
  number: u32
  title: string
  body: Option<string>
  state: string
  headRefName: string       // Source branch
  baseRefName: string       // Target branch
  author: GitHubAuthor
  comments: Vec<GitHubComment>
  reviews: Vec<GitHubReview>
  diff: Option<string>      // Full PR diff
}

1. Find PR in GitHub panel
2. Click “Checkout PR”
3. Jean creates worktree on PR branch
4. Loads PR context (description, reviews, comments)
5. AI analyzes changes and review feedback
6. Proposes addressing reviewer comments

<worktree>/.jean/contexts/pr-<number>.md

• Malicious or obfuscated code
• Suspicious dependency changes
• Hardcoded secrets
• Backdoors or unauthorized access
• Injection vulnerabilities
• Weakened auth/permissions

​

PR Creation

// Toolbar → Open PR button
interface CreatePrResponse {
  pr_number: number
  pr_url: string
  title: string             // AI-generated
  existing: boolean         // Already existed?
}

1. Click “Open PR” in chat toolbar
2. Jean collects:
   • Current branch and target branch
   • Commit history since divergence
   • Full diff
3. AI generates title and body
4. Creates PR via gh pr create
5. Links PR to worktree
6. Opens PR URL in browser

• Toast notification for progress
• Success toast with “Open” action
• Worktree updated with PR metadata

​

PR Status Tracking

interface Worktree {
  pr_number?: number
  pr_url?: string
  cached_pr_status?: string       // draft, open, review, merged, closed
  cached_check_status?: string    // success, failure, pending, error
  cached_status_at?: number       // Last check timestamp
}

• PR status (draft, open, merged, etc.)
• CI check status (passing, failing, pending)
• Behind/ahead commit counts
• Uncommitted changes count

// Settings → Worktrees
remote_poll_interval: number  // Default: 60 seconds (1 minute)
                              // Range: 30-600 seconds

• Polls GitHub via gh pr view
• Polls CI via gh pr checks
• Caches results to reduce API calls
• Updates badges in real-time

​

Auto-Archive on PR Merge

interface AppPreferences {
  auto_archive_on_pr_merged: boolean  // Default: true
}

1. Polling detects PR status changed to “merged”
2. Jean archives associated worktree
3. Toast notification confirms archiving
4. Worktree moves to archive view
5. Subject to retention policy

• Automatic cleanup after merging
• Keeps active worktrees focused on open work
• Reduces manual cleanup effort

​

Workflow Investigation

interface WorkflowRun {
  id: number
  name: string
  head_branch: string
  display_title: string
  status: string
  conclusion: string
  html_url: string
}

1. Worktree shows failed check badge
2. Click “Investigate” on workflow
3. Jean creates session with workflow context
4. AI fetches logs: gh run view {runId} --log-failed
5. Analyzes error output
6. Explores relevant code
7. Determines issue type:
   • Code bug
   • CI configuration issue
   • Flaky test
8. Proposes fix

# Failed Workflow: CI Tests

**Branch:** feature-branch
**Commit:** abc123 - Add new feature
**Run URL:** https://github.com/.../runs/123456
**Status:** failure

## Logs

[Error output from failed jobs]

​

Git Status Integration

interface Worktree {
  // Uncommitted changes
  cached_uncommitted_added?: number
  cached_uncommitted_removed?: number
  
  // Branch diff vs base
  cached_branch_diff_added?: number
  cached_branch_diff_removed?: number
  
  // Sync status
  cached_behind_count?: number      // Commits behind base
  cached_ahead_count?: number       // Commits ahead of base
  cached_unpushed_count?: number    // Commits not pushed
  
  // Base branch sync
  cached_base_branch_ahead_count?: number
  cached_base_branch_behind_count?: number
  cached_worktree_ahead_count?: number
}

git_poll_interval: number  // Default: 60 seconds
                          // Range: 10-600 seconds

• Uncommitted changes badge
• Behind/ahead counts
• Push/pull reminders
• Conflict warnings

​

How to Use

​

Setting Up GitHub CLI

1. Install GitHub CLI: brew install gh (macOS)
2. Authenticate: gh auth login
3. Verify: gh auth status

• Automatically locates gh binary
• Checks common installation paths
• Falls back to system PATH

​

Browsing Issues

1. Click GitHub icon in project sidebar
2. Or press configured keyboard shortcut

• State dropdown: Open, Closed, All
• Search bar: Filter by text
• Label filters: Click labels to filter

• Shows up to 100 issues
• Total count displayed
• Scroll to load more (future)

​

Investigating Issues

1. Click “Investigate” button on issue
2. Jean creates worktree automatically
3. Issue context loads in chat
4. AI starts analysis immediately
5. Review AI’s findings and proposal

1. Create worktree manually
2. Use magic command to load issue
3. Chat with AI about implementation
4. Reference issue context as needed

​

Working with Pull Requests

1. Browse PRs in GitHub panel
2. Click “Checkout PR”
3. Worktree created on PR branch
4. PR context loaded
5. AI reviews changes and feedback

1. Complete work in worktree
2. Commit changes
3. Click “Open PR” in toolbar
4. Review AI-generated title/body
5. Confirm to create
6. PR opens in browser

1. Make additional changes
2. Commit normally
3. Push to update PR automatically
4. Jean tracks PR status

​

Monitoring CI/CD

• Check badge in worktree list
• Green: All checks passing
• Red: Some checks failed
• Yellow: Checks pending
• Gray: No checks configured

1. Click failed check badge
2. Select workflow to investigate
3. AI analyzes logs and proposes fix
4. Implement fix
5. Push and monitor new run

​

Managing PR Lifecycle

• Draft → Open → Review → Merged
• Status badge updates automatically
• CI status shown alongside

• Worktree auto-archives (if enabled)
• Manual cleanup if disabled
• Archive retention policy applies

​

Configuration Options

​

Polling Intervals

git_poll_interval: number
// Default: 60 seconds
// Range: 10-600 seconds
// Affects: Local git status checks

remote_poll_interval: number
// Default: 60 seconds  
// Range: 30-600 seconds
// Affects: GitHub API calls (PR status, checks)

• Active development: 30-60 seconds
• Background projects: 300-600 seconds
• Rate limit concerns: 300+ seconds

​

Auto-Archive Settings

auto_archive_on_pr_merged: boolean
// Default: true
// Location: Settings → Worktrees

archive_retention_days: number
// Default: 7 days
// Options: 0 (never), 7, 14, 30, 60, 90

​

GitHub Authentication

# Login
gh auth login

# Check status
gh auth status

# Switch accounts
gh auth switch

# Refresh token
gh auth refresh

​

Best Practices

​

Issue Investigation

• Complex bugs requiring codebase exploration
• Feature requests needing architecture decisions
• Regressions requiring git history analysis
• Issues with unclear reproduction steps

• Simple, well-understood fixes
• Documentation updates
• Typo fixes
• Duplicate issues

​

PR Workflows

1. Commit all changes
2. Run tests locally
3. Review diff yourself
4. Let AI generate PR content
5. Edit if needed

• All commits pushed
• Tests passing
• AI code review clean
• PR description accurate
• Linked to issue (if applicable)

​

CI/CD Monitoring

Active development: 30-60s
PR in review: 120-300s
Merged work: 600s or disable

• Investigate using workflow investigation
• Fix root cause, don’t just retry
• Document flakiness patterns
• Use AI to suggest stability improvements

​

Performance Optimization

• Increase poll intervals
• Disable auto-archive if not needed
• Archive finished work promptly
• Close unused worktrees

• GitHub API: 5,000 requests/hour (authenticated)
• Jean caches aggressively
• Increase poll intervals if hitting limits
• Monitor gh api rate_limit

​

Security

• Always review AI’s security findings
• Don’t blindly trust AI approval
• Check dependencies manually
• Verify credential handling
• Review permission changes

• GitHub CLI handles token storage
• Tokens stored in OS keychain
• Never commit tokens to repository
• Rotate tokens regularly

​

Workflow Organization

1. Browse issues → Find work
2. Investigate issue → Understand problem
3. Implement fix → Write code
4. Commit → AI-generated messages
5. Review → AI code review
6. Open PR → AI-generated content
7. Address feedback → Update PR
8. Merge → Auto-archive

1. Checkout PR → Review someone's code
2. Investigate → AI analyzes changes
3. Comment → Provide feedback
4. Test locally → Verify functionality
5. Approve or request changes

​

Team Collaboration

• Customize magic prompts for team style
• Configure commit message format
• Set PR description template
• Document review criteria

• Use AI review as first pass
• Human review for architecture
• Security review for sensitive changes
• Performance review for critical paths

​

Troubleshooting

# Check installation
which gh
gh --version

# Re-authenticate
gh auth logout
gh auth login

# Test API access
gh api user

• Check repository visibility
• Verify authentication
• Confirm permissions
• Check filters/search

• Check poll interval settings
• Verify internet connection
• Check GitHub status
• Review app logs

• Ensure branch pushed
• Check remote exists
• Verify gh CLI works: gh pr create
• Check for existing PR