JA GitHub Integration - aku11i/phantom GitHub Wiki

GitHub統合

このガイドでは、PhantomのGitHub統合機能について説明します。この機能により、GitHubのプルリクエスト（PR）やissueを直接phantom worktreeにチェックアウトできます。

目次

概要

Phantom v2.0のGitHub統合により、以下が可能になります：

  • プルリクエストのチェックアウト: PR番号を指定してworktreeを作成
  • Issueのチェックアウト: issue番号を指定してworktreeを作成
  • 自動命名: phantom名の自動生成
  • GitHub CLIとの統合: 既存のGitHub認証を使用

前提条件

GitHub CLI（gh）

GitHub統合を使用するには、GitHub CLIがインストールされ、認証されている必要があります。

インストール

# macOS (Homebrew)
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows (Chocolatey)
choco install gh

# または手動インストール
# https://github.com/cli/cli/releases

認証

# GitHubでの認証
gh auth login

# 認証状態の確認
gh auth status

リポジトリへのアクセス

使用するGitHubリポジトリに対する適切なアクセス権限が必要です：

  • 読み取り権限: PRやissueを読み取るため
  • 書き込み権限: 新しいブランチを作成するため（issueの場合）

基本的な使用法

プルリクエストのチェックアウト

# PRをphantomにチェックアウト
phantom github checkout 123

# 上記のコマンドは以下と同等：
# 1. PR #123の詳細を取得
# 2. PRのブランチでphantomを作成
# 3. 適切にフェッチとチェックアウトを実行

Issueのチェックアウト

# issueをphantomにチェックアウト
phantom github checkout 456

# 上記のコマンドは以下と同等：
# 1. Issue #456の詳細を取得
# 2. issue用の新しいブランチを作成
# 3. そのブランチでphantomを作成

命名規則

Phantomは自動的に意味のある名前を生成します：

  • PR: phantom-pr-123
  • Issue: phantom-issue-456

この命名により、以下が可能になります：

  • GitHubで元のPR/issueを簡単に特定
  • 複数のPR/issueを同時に作業
  • 明確なワークスペース整理

コマンドリファレンス

phantom github checkout

GitHub PRまたはissueをphantom worktreeにチェックアウトします。

構文

phantom github checkout <number> [--base <branch>]

パラメータ

  • <number>: PRまたはissue番号（必須）
  • --base <branch>: issueの場合のベースブランチ（オプション）

オプション

  • --base <branch>: issueから新しいブランチを作成する際のベースブランチを指定
    • デフォルト: リポジトリのデフォルトブランチ
    • 例: --base develop, --base main

例

# PR #123をチェックアウト
phantom github checkout 123

# Issue #456をdevelopブランチベースでチェックアウト
phantom github checkout 456 --base develop

# 番号のみ指定（PRかissueかは自動判別）
phantom github checkout 789

ワークフローの例

コードレビューワークフロー

# 複数のPRを同時にレビュー
phantom github checkout 101  # feature-auth PR
phantom github checkout 102  # bugfix-login PR
phantom github checkout 103  # refactor-api PR

# 各PRをテスト
phantom exec phantom-pr-101 "npm test"
phantom exec phantom-pr-102 "npm run e2e"
phantom exec phantom-pr-103 "npm run lint"

# インタラクティブレビュー
phantom shell phantom-pr-101
# レビュー完了後
exit

# クリーンアップ
phantom delete phantom-pr-101
phantom delete phantom-pr-102
phantom delete phantom-pr-103

バグ修正ワークフロー

# バグreportのissueをチェックアウト
phantom github checkout 234

# phantom内でバグ修正ブランチを作成
phantom shell phantom-issue-234
git checkout -b fix-issue-234
# ... バグ修正作業 ...
git commit -m "Fix issue #234: Memory leak in user sessions"
git push origin fix-issue-234

# PRを作成
gh pr create --title "Fix issue #234" --body "Fixes #234"

exit

# クリーンアップ
phantom delete phantom-issue-234

機能開発ワークフロー

# 機能リクエストのissueをチェックアウト
phantom github checkout 345 --base develop

# 機能開発
phantom shell phantom-issue-345
git checkout -b feature-issue-345
# ... 開発作業 ...
git commit -m "Implement feature requested in #345"
git push origin feature-issue-345

# PRを作成
gh pr create --base develop --title "Implement feature from issue #345"

exit

並列開発

# 複数のissueを並列で作業
phantom github checkout 111  # Frontend issue
phantom github checkout 222  # Backend issue
phantom github checkout 333  # Documentation issue

# 各phantom worktreeで独立して作業
phantom exec phantom-issue-111 "npm run dev" &      # フロントエンド開発サーバー
phantom exec phantom-issue-222 "npm run api" &     # API開発サーバー
phantom shell phantom-issue-333                     # ドキュメント編集

トラブルシューティング

一般的な問題

1. GitHub CLI認証エラー

Error: not authenticated with GitHub

解決方法:

gh auth login
gh auth refresh

2. リポジトリが見つからない

Error: repository not found

解決方法:

  • 正しいリポジトリにいることを確認
  • GitHub CLIで正しいリポジトリが設定されていることを確認：
gh repo view

3. PR/Issueが見つからない

Error: pull request #123 not found

解決方法:

  • PR/issue番号が正しいことを確認
  • 削除されたPR/issueでないことを確認
  • アクセス権限があることを確認

4. ブランチの競合

Error: branch already exists

解決方法:

  • 同じPRが既にチェックアウトされていないか確認：
phantom list
  • 必要に応じて既存のphantomを削除：
phantom delete phantom-pr-123

デバッグ方法

GitHub CLI状態の確認

# 認証状態
gh auth status

# リポジトリ情報
gh repo view

# PR一覧
gh pr list

# Issue一覧
gh issue list

Phantom状態の確認

# すべてのphantomを表示
phantom list

# 特定のphantomの場所
phantom where phantom-pr-123

# Gitステータス
phantom exec phantom-pr-123 "git status"

高度な使用法

スクリプトでの自動化

#!/bin/bash
# すべてのオープンPRを自動的にチェックアウトしてテスト

# オープンPRの番号を取得
gh pr list --state open --json number --jq '.[].number' | while read pr_number; do
    echo "チェックアウト中: PR #$pr_number"
    phantom github checkout "$pr_number"
    
    echo "テスト中: PR #$pr_number"
    if phantom exec "phantom-pr-$pr_number" "npm test"; then
        echo "✅ PR #$pr_number: テスト合格"
    else
        echo "❌ PR #$pr_number: テスト失敗"
    fi
done

設定との組み合わせ

phantom.config.jsonと組み合わせて自動セットアップ：

{
  "postCreate": {
    "copyFiles": [".env", ".env.test"],
    "commands": [
      "npm install",
      "npm run build",
      "echo 'GitHub PRの準備完了！'"
    ]
  }
}

これにより、GitHub経由でチェックアウトしたPRやissueでも自動的に環境がセットアップされます。

CI/CDとの統合

# CI環境でのPRテスト
for pr in $(gh pr list --state open --json number --jq '.[].number'); do
    phantom github checkout "$pr"
    phantom exec "phantom-pr-$pr" "npm ci && npm test && npm run build"
    phantom delete "phantom-pr-$pr"
done

チーム開発での活用

# チーム内でレビュー待ちのPRを分散してチェック
team_members=("alice" "bob" "charlie")
pr_list=($(gh pr list --state open --json number --jq '.[].number'))

for i in "${!pr_list[@]}"; do
    pr=${pr_list[$i]}
    reviewer=${team_members[$((i % ${#team_members[@]}))]}
    echo "PR #$pr を $reviewer にアサイン"
    # 各開発者が自分の担当PRをチェックアウト
    phantom github checkout "$pr"
done

まとめ

Phantom v2.0のGitHub統合により：

  1. 効率的なレビュー: 複数のPRを並列でレビュー可能
  2. 簡単なセットアップ: 1コマンドでPR/issueをチェックアウト
  3. ワークフロー統合: 既存のGitHub CLIワークフローと連携
  4. 自動化サポート: スクリプトやCI/CDでの活用
  5. チームコラボレーション: チーム開発での並列作業

この機能により、GitHubベースの開発ワークフローがさらに効率的になります。

⚠️ **GitHub.com Fallback** ⚠️