GitHub Workflows

Integrate with GitHub issues, pull requests, and CI/CD

Overview

Jean deeply integrates with GitHub to streamline issue-driven development. You can browse issues, create worktrees from issues, open PRs, track CI status, and investigate workflow failures—all without leaving Jean.

Prerequisites:

• Repository must have a GitHub remote
• GitHub CLI (gh) must be installed and authenticated
• (Optional) github MCP server for enhanced API access

Setting Up GitHub Integration

1. Install GitHub CLI

   If not already installed:

   Mac (Homebrew):

   brew install gh
   

   Windows (Scoop):

   scoop install gh
   

   Linux (apt):

   sudo apt install gh
   
2. Authenticate

   Run gh auth login and follow the prompts to authenticate with GitHub.

   Choose:

   • GitHub.com (or GitHub Enterprise if applicable)
   • HTTPS protocol
   • Login with web browser

   Verify authentication with gh auth status.

3. (Optional) Enable GitHub MCP Server

   For enhanced GitHub API access, install the GitHub MCP server:

   Add to ~/.claude.json:

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

   Create a personal access token at https://github.com/settings/tokens with scopes:

   • repo (full control of private repositories)
   • read:org (read org and team membership)

   Enable the server in Preferences → MCP Servers.

4. Verify Integration

   Press Cmd+M and navigate to the Issues or Pull Requests tab. If you see your repository’s issues/PRs, integration is working.

   If you see an error, check:

   • gh auth status shows you’re logged in
   • The current project has a GitHub remote (git remote -v)
   • You have access to the repository

Issue-Driven Development Workflow

This is the recommended workflow for feature development and bug fixes.

1. Browse Issues

   Press Cmd+M → Issues tab to see all open issues in your repository.

   You can:

   • Filter by label, milestone, or assignee
   • Search by title or number
   • Sort by created date, updated date, or comment count
2. Select an Issue

   Click an issue to view:

   • Title and number
   • Full description
   • All comments in chronological order
   • Labels (bug, enhancement, etc.)
   • Assignees and milestone
3. Create Worktree from Issue

   Click Investigate Issue. Jean will:

   1. Generate a branch name from the issue title (e.g., fix-login-timeout-#123)
   2. Create a worktree from the default branch
   3. Save issue context to .github/issues/<number>.json
   4. Start a chat session with a prompt to investigate the issue
   5. Link the issue number to the worktree (for later PR creation)
4. Work on the Issue

   Claude will:

   • Analyze the issue description and comments
   • Explore the codebase to find relevant code
   • Identify the root cause (or where to implement the feature)
   • Propose a solution with specific file changes

   You can iterate in the chat to refine the approach.

5. Implement the Fix

   Ask Claude to implement the solution. Claude will:

   • Make code changes
   • Run tests
   • Verify the fix works

   Review the changes with Cmd+G (git diff viewer).

6. Commit Changes

   Press Cmd+Shift+C to open the commit dialog.

   Click Generate with AI to create a commit message. The message will reference the issue number automatically (e.g., “Fix login timeout (#123)”).

   Commit and push the changes.

7. Create Pull Request

   Press Cmd+M → Open PR. Jean will:

   1. Analyze commits and diff
   2. Generate a PR title and description
   3. Include “Fixes #123” in the PR body (to auto-close the issue on merge)
   4. Create the PR on GitHub
   5. Link the PR to your worktree

   The PR appears in the sidebar with status indicators.

8. Address Review Feedback

   If reviewers request changes:

   1. Press Cmd+M → Investigate PR
   2. Jean will load the PR context (including review comments)
   3. Claude will summarize feedback and suggest fixes
   4. Implement changes, commit, and push
   5. PR updates automatically on GitHub
9. Merge and Clean Up

   Once approved:

   1. Merge the PR on GitHub (or use Cmd+M → Merge for local merge)
   2. Jean will auto-archive the worktree (if enabled in Preferences)
   3. The issue closes automatically (due to “Fixes #123” in PR body)

Pull Request Review Workflow

Jean helps you review PRs from others (or your own PRs from a different perspective).

1. Browse Pull Requests

   Press Cmd+M → Pull Requests tab to see all open PRs.

   Filter by:

   • Status (draft, open, approved, changes requested)
   • Author
   • Base branch
   • CI check status (passing, failing, pending)
2. Check Out PR

   Click a PR and select Investigate PR. Jean will:

   1. Check out the PR branch (if not already)
   2. Create a worktree (if you don’t have one for this branch)
   3. Save PR context to .github/pulls/<number>.json
   4. Start a chat session with a prompt to review the PR
3. AI-Assisted Review

   Claude will:

   • Analyze what the PR is trying to accomplish
   • Review the code changes
   • Check for security issues (see Security Review Checklist)
   • Summarize reviewer feedback (if any)
   • Identify action items to get the PR merged
4. Run Code Review

   Press Cmd+M → Review Code to get structured feedback.

   The review panel shows:

   • Summary: Overview of changes
   • Findings: Issues by severity (critical, warning, suggestion, praise)
   • Approval Status: Approved, Changes Requested, or Needs Discussion
5. Test the Changes

   Run the jean.json run script (Cmd+R) to start the dev server or tests.

   Manually test the feature or bug fix.

6. Leave Review Comments

   If you find issues:

   • Ask Claude to explain specific code sections
   • Request alternative implementations
   • Add review comments on GitHub (via web UI or gh pr review)
7. Approve or Request Changes

   Once satisfied (or if changes are needed):

   Approve:

   gh pr review <number> --approve
   

   Request Changes:

   gh pr review <number> --request-changes --body "Please address XYZ"
   

Security Review Checklist

When reviewing PRs (especially from external contributors), Jean’s PR investigation includes a security checklist:

Security Checklist Details

Malicious or Obfuscated Code

• eval(), Function(), or other code execution
• Base64-encoded strings or hex-encoded data
• Hidden network calls or data exfiltration

Suspicious Dependency Changes

• New dependencies with few downloads or recent creation
• Version changes to compromised packages (check npm advisories)
• Typosquatting (lodash vs. lodahs)

Hardcoded Secrets

• API keys, tokens, passwords in code
• Credentials in config files (not .env.example)
• Private keys or certificates

Backdoors or Unauthorized Access

• Reverse shells or remote access code
• Debug endpoints left in production code
• Disabled authentication checks

Injection Vulnerabilities

• SQL injection (unescaped user input in queries)
• Command injection (user input in shell commands)
• XSS (unescaped user input in HTML/JS)
• Path traversal (user input in file paths)

Weakened Security

• Removed authentication or authorization checks
• Broadened permissions or access levels
• Disabled input validation or sanitization

Suspicious System Access

• File system writes to unexpected locations
• Environment variable access for sensitive data
• Process spawning with user-controlled arguments

Always run security review for:

• PRs from external contributors
• Dependency updates (especially major version bumps)
• Changes to authentication or authorization code
• Any code handling user input or external data

CI/CD Integration

Jean tracks GitHub Actions status and helps debug failures.

1. View CI Status

   Worktrees linked to PRs show CI check status in the sidebar:

   • Green checkmark: All checks passing
   • Red X: One or more checks failing
   • Yellow dot: Checks pending/running
   • Gray dash: No checks configured
2. Open GitHub Dashboard

   Press Cmd+Shift+D to open the GitHub Dashboard.

   This shows:

   • All open PRs across all projects
   • CI check status for each PR
   • Security alerts (Dependabot, advisories)
   • Recent workflow runs
3. Investigate Failed Workflows

   Click a failed workflow run and select Investigate Run.

   Jean will:

   1. Fetch workflow logs via gh run view --log-failed
   2. Send logs to Claude with a prompt to analyze the failure
   3. Claude will:
      • Identify the failure cause
      • Determine if it’s code, config, or a flaky test
      • Propose a fix
4. Fix and Re-run

   Implement the suggested fix, commit, and push.

   Re-run the workflow:

   gh run rerun <run-id>
   

   Or re-run from the GitHub Actions UI.

Release Notes Generation

Jean can generate release notes by analyzing commits since the last release.

1. Open Magic Modal

   Press Cmd+M → Release Notes.

2. Select Previous Release

   Jean shows all existing releases (fetched via gh release list).

   Select the previous release to use as the starting point (e.g., v1.2.0).

3. Generate Notes

   Jean will:

   1. Run git log <previous-tag>..HEAD to get all commits
   2. Send commits to a model (Haiku by default)
   3. Generate release notes with:
      • Features: New functionality
      • Fixes: Bug fixes
      • Improvements: Enhancements to existing features
      • Breaking Changes: API changes requiring user action
4. Create Release

   Copy the generated notes and create a release:

   Via GitHub CLI:

   gh release create v1.3.0 --title "Version 1.3.0" --notes "$(pbpaste)"
   

   Via GitHub UI: Go to Releases → Draft a new release, paste the notes.

Dependabot and Security Alerts

Jean helps you investigate and fix security vulnerabilities.

1. View Security Alerts

   Press Cmd+Shift+D to open the GitHub Dashboard.

   The Security tab shows:

   • Dependabot alerts (vulnerable dependencies)
   • Repository security advisories
   • Alert severity (critical, high, medium, low)
2. Investigate Alert

   Click an alert and select Investigate Alert.

   Jean will:

   1. Load alert details (CVE, affected versions, severity)
   2. Search the codebase for usage of the vulnerable package
   3. Assess actual impact (is the vulnerable function used?)
   4. Evaluate remediation options (patched version, workarounds, etc.)
   5. Propose a fix
3. Apply Fix

   Common fixes:

   • Upgrade dependency: npm update <package> or bun update <package>
   • Remove dependency: If not needed, uninstall it
   • Apply workaround: Disable vulnerable feature or add input validation

   Test the fix to ensure it doesn’t break functionality.

4. Commit and Close Alert

   Commit the fix with a message referencing the alert:

   fix: upgrade lodash to fix CVE-2023-12345
   

   Push the changes. Dependabot will automatically close the alert once the vulnerable version is no longer in use.

Common Pitfalls

GitHub CLI Not Authenticated: If you see “gh: command not found” or “authentication required”:

Solution: Run gh auth login and follow the prompts.

PR Creation Fails with “No commits”: You must have at least one commit before creating a PR.

Solution: Make a commit first, or use git commit --allow-empty -m "Initial commit" to create an empty commit.

CI Status Not Updating: Jean polls GitHub every 60 seconds (configurable in Preferences → General → Remote Poll Interval).

Solution: Wait a minute, or click the worktree to force a refresh.

Issue Context Not Loading: If issue investigation fails to load context, check:

• The issue exists and is not closed/deleted
• You have read access to the repository
• GitHub API rate limits (check gh api rate_limit)

Solution: Wait for rate limit reset, or use a personal access token with higher limits.

Best Practices

Always Create Worktrees from Issues: This links the issue to your work and makes PR creation seamless. The PR will automatically reference the issue and close it on merge.

Use Draft PRs for WIP: When you open a PR early (to get CI feedback), mark it as draft. This signals reviewers that it’s not ready for review.

Review Your Own PRs: Before requesting review from others, use Review Code to catch obvious issues. This reduces review cycles.

Keep PRs Small: Smaller PRs are easier to review and faster to merge. If a feature is large, break it into multiple PRs (one per issue).

Monitor Security Alerts: Check the GitHub Dashboard (Cmd+Shift+D) regularly for new Dependabot alerts. Address critical and high-severity alerts immediately.

Next Steps

• Using Magic Commands - Deep dive into PR and issue automation
• Managing Sessions - Organize work within issue-driven worktrees
• Customization - Customize magic prompts for your team’s workflow