This guide explains how to use Phantom's GitHub integration features to streamline your development workflow with pull requests and issues.

• Overview
• Features
• Authentication
• Commands
  • Checkout PR/Issue
  • List PRs
• Usage Examples
• Workflows
• Configuration
• Troubleshooting

Phantom's GitHub integration allows you to quickly checkout pull requests and issues as worktrees, making it easy to review code, test changes, and work on issues without disrupting your current work.

• Direct PR Checkout: Create a phantom from any pull request
• Issue Checkout: Start working on issues with a single command
• Automatic Fetch: Fetches PR branches automatically
• Smart Naming: Creates phantoms with meaningful names
• Clean Workflow: No need to manage remote branches manually

Phantom uses your existing Git credentials for GitHub operations. Ensure you have access to the repository:

git remote -v
# Should show: [email protected]:owner/repo.git

git remote -v  
# Should show: https://github.com/owner/repo.git

If you have GitHub CLI installed, Phantom can use its authentication:

gh auth status

Create a phantom from a GitHub pull request or issue:

phantom github checkout <number> [options]

Parameters:

• <number>: PR or issue number (required)

Options:

• --name <name>: Custom name for the phantom (default: pr-<number> or issue-<number>)
• --base <branch>: Base branch for issues (default: repository default branch)

Examples:

# Checkout pull request #123
phantom github checkout 123

# Checkout with custom name
phantom github checkout 123 --name review-auth-fix

# Checkout issue #456 based on develop branch
phantom github checkout 456 --base develop

While Phantom doesn't have a built-in PR list command, you can use it with GitHub CLI:

# List open PRs
gh pr list

# Checkout a PR after listing
gh pr list
phantom github checkout 789

# List open PRs
gh pr list

# Checkout PR #234 for review
phantom github checkout 234

# Enter the phantom to review
phantom shell pr-234

# Or run tests directly
phantom exec pr-234 npm test

# View issue details
gh issue view 567

# Create phantom for the issue
phantom github checkout 567 --name fix-memory-leak

# Start working
phantom shell fix-memory-leak
git checkout -b fix/memory-leak-567

# Use your team's naming convention
phantom github checkout 123 --name john/feature-123-auth

# Or automate with a script
PR_NUM=123
FEATURE="auth-system"
phantom github checkout $PR_NUM --name "$(whoami)/$FEATURE-$PR_NUM"

1. List and Select PR:

   gh pr list --limit 10

2. Checkout PR as Phantom:

   phantom github checkout 345

3. Review Changes:

   # Enter phantom
   phantom shell pr-345
   
   # View changes
   git log --oneline main..HEAD
   git diff main...HEAD

4. Test Changes:

   # Run tests in phantom
   phantom exec pr-345 npm test
   phantom exec pr-345 npm run lint

5. Cleanup:

   phantom delete pr-345

1. View Issue:

   gh issue view 678 --comments

2. Create Phantom:

   phantom github checkout 678 --name feature-notifications

3. Create Feature Branch:

   phantom shell feature-notifications
   git checkout -b feature/678-notifications

4. Development and Testing:

   # Make changes
   # Test in isolation
   npm test

5. Push and Create PR:

   git push origin feature/678-notifications
   gh pr create --title "Fix #678: Add notifications" --body "Closes #678"

Test multiple PRs simultaneously:

# Checkout multiple PRs
phantom github checkout 123 --name pr-123-auth
phantom github checkout 124 --name pr-124-ui  
phantom github checkout 125 --name pr-125-api

# Run tests in parallel
phantom exec pr-123-auth npm test &
phantom exec pr-124-ui npm test &
phantom exec pr-125-api npm test &
wait

# Check results
echo "All tests completed"

Use in CI pipelines to test PRs:

# .github/workflows/pr-test.yml
name: PR Test
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Phantom
        run: npm install -g @aku11i/phantom
        
      - name: Checkout PR
        run: phantom github checkout ${{ github.event.pull_request.number }}
        
      - name: Run Tests
        run: |
          phantom exec pr-${{ github.event.pull_request.number }} npm install
          phantom exec pr-${{ github.event.pull_request.number }} npm test

Combine GitHub checkout with automatic setup:

{
  "postCreate": {
    "copyFiles": [".env.test"],
    "commands": [
      "npm install",
      "npm run build"
    ]
  }
}

Now when you checkout a PR:

phantom github checkout 456
# Automatically runs npm install and build

Create wrapper scripts for your workflow:

#!/bin/bash
# scripts/review-pr.sh

PR_NUMBER=$1
phantom github checkout $PR_NUMBER --name "review-$PR_NUMBER"
phantom exec "review-$PR_NUMBER" npm install
phantom exec "review-$PR_NUMBER" npm test
phantom shell "review-$PR_NUMBER"

Combine with GitHub CLI for rich workflows:

# Get PR details and checkout
PR=789
gh pr view $PR
phantom github checkout $PR

# Get PR author
AUTHOR=$(gh pr view $PR --json author -q .author.login)
phantom github checkout $PR --name "$AUTHOR-pr-$PR"

Script to test all PRs with a specific label:

#!/bin/bash
# Test all PRs labeled "ready-for-review"

for pr in $(gh pr list --label "ready-for-review" --json number -q .[].number); do
  echo "Testing PR #$pr"
  phantom github checkout $pr --name "test-pr-$pr"
  
  if phantom exec "test-pr-$pr" npm test; then
    echo "✅ PR #$pr passed"
  else
    echo "❌ PR #$pr failed"
  fi
  
  phantom delete "test-pr-$pr" --force
done

Add to your .gitconfig:

[alias]
  pr-checkout = "!f() { phantom github checkout $1; }; f"
  pr-test = "!f() { phantom github checkout $1 && phantom exec pr-$1 npm test; }; f"
  pr-shell = "!f() { phantom github checkout $1 && phantom shell pr-$1; }; f"

Usage:

git pr-checkout 123
git pr-test 123
git pr-shell 123

Error: "Pull request #XXX not found"

Solutions:

1. Verify PR number exists:

   gh pr view XXX

2. Check repository:

   git remote -v

3. Ensure you have access to the PR

Error: "Failed to fetch PR branch"

Solutions:

1. Check network connection
2. Verify Git credentials:

   git fetch origin

3. Try manual fetch:

   git fetch origin pull/XXX/head:pr-XXX

Error: "Authentication failed"

Solutions:

1. Setup SSH keys:

   ssh -T [email protected]

2. Or use HTTPS with token:

   git config --global credential.helper store

3. Or use GitHub CLI:

   gh auth login

Error: "Branch already exists"

Solutions:

1. Use custom name:

   phantom github checkout 123 --name review-123-v2

2. Delete existing phantom:

   phantom delete pr-123
   phantom github checkout 123

Use consistent naming for easy identification:

• PRs: pr-<number> or review-<number>
• Issues: issue-<number> or fix-<number>
• Features: feature-<description>-<number>

Clean up phantoms after PR reviews:

# List all PR phantoms
phantom list | grep "pr-"

# Delete merged PR phantoms
phantom delete pr-123

Add to .git/hooks/post-checkout:

#!/bin/bash
# Auto-fetch when checking out PR phantoms
if [[ "$GIT_DIR" == *"phantom/worktrees/pr-"* ]]; then
  git fetch origin
fi

Share phantom names in PR comments:

I'm reviewing this in phantom `review-pr-456`.
To test: `phantom shell review-pr-456`

Phantom's GitHub integration streamlines PR and issue workflows by:

• Quick Checkout: Single command to start working on PRs/issues
• Isolation: Each PR/issue in its own environment
• Parallel Work: Review multiple PRs simultaneously
• Clean Workflow: No branch pollution in main worktree
• Automation Ready: Integrate with CI/CD and scripts

This integration makes code review, testing, and issue development more efficient and organized.