GitHub Watcher 使用ガイド

このドキュメントでは、IGNITEのGitHubイベント監視システム（GitHub Watcher）の使い方を説明します。

概要

GitHub Watcherは、GitHubリポジトリのイベント（Issue、PR、コメント）を監視し、検知したイベントをIGNITEシステムに自動投入する機能です。

主な機能

Issue/PRイベントの監視: 新規作成、更新を検知
コメント監視: Issue/PRへのコメントを検知
トリガー機能: メンション（@ignite-gh-app）でタスクを自動起動
Bot判別: 自身のBot投稿には反応しない
重複防止: 処理済みイベントを記録して重複処理を防止

アーキテクチャ

flowchart TB
    subgraph IGNITE["IGNITE System"]
        GW[GitHub Watcher]
        Leader[Leader<br/>伊羽ユイ]
        SubLeaders[Sub-Leaders / IGNITIANs]

        GW -->|"github_event_*.mime<br/>workspace/.ignite/queue/leader/"| Leader
        Leader -->|既存フロー| SubLeaders
    end

    subgraph External["External"]
        GitHubAPI[GitHub API]
    end

    GW -->|"gh api<br/>ポーリング"| GitHubAPI
    SubLeaders -->|Bot応答| GitHubAPI

    style GW fill:#4ecdc4,color:#fff
    style Leader fill:#ff6b6b,color:#fff
    style SubLeaders fill:#ffeaa7,color:#333
    style GitHubAPI fill:#dfe6e9,color:#333

前提条件

GitHub Watcherを使用するには、以下の設定が必要です:

GitHub CLI (gh) がインストールされ、認証済みであること
GitHub App の設定が完了していること（Bot応答を使用する場合）

GitHub Appの設定については github-app-setup.md を参照してください。

設定

1. 設定ファイルの作成

cp config/github-watcher.yaml.example config/github-watcher.yaml

ワークスペース固有設定

複数のワークスペースで異なる監視設定を使用する場合、ワークスペースディレクトリ内に設定ファイルを配置できます。

# ワークスペース初期化時に自動作成される
ignite init -w /path/to/workspace

# または手動でコピー
cp config/github-watcher.yaml.example /path/to/workspace/.ignite/github-watcher.yaml

設定解決の優先順位:

優先度	設定ソース	パス
1（最高）	環境変数	`IGNITE_WATCHER_CONFIG`
2	ワークスペース固有	`<workspace>/.ignite/github-watcher.yaml`
3（最低）	プロジェクトデフォルト	`config/github-watcher.yaml`

ワークスペース指定での起動:

ignite start -w /path/to/workspace --with-watcher

⚠️ 注意: 複数のワークスペースで同一リポジトリを監視すると、同じイベントが重複処理されるリスクがあります。リポジトリの監視は1つのワークスペースに限定することを推奨します。

2. 監視対象リポジトリの設定

watcher:
  # 監視対象リポジトリ
  repositories:
    - owner/repo1
    - owner/repo2
    - organization/repo3

  # ポーリング間隔（秒）
  interval: 60

  # 監視するイベントタイプ
  events:
    issues: true
    issue_comments: true
    pull_requests: true
    pr_comments: true

  # Bot投稿を無視
  ignore_bot: true

3. トリガー設定

メンションで自動タスクを起動（タスク分類は Leader が自然言語で判断）:

triggers:
  # メンションパターン
  mention_pattern: "@ignite-gh-app"

  # タスク分類は Leader（LLM）に委譲
  # Watcher はメンション検出 + メッセージ転送に専念し、
  # trigger_comment の内容から意図を判断する処理は Leader が行う

  # 自動トリガーラベル
  auto_labels:
    - "ignite-auto"
    - "help-wanted"

使用方法

基本的な起動

# デーモンモード（継続監視）
./scripts/utils/github_watcher.sh

# バックグラウンドで起動
./scripts/utils/github_watcher.sh &

# 単発実行
./scripts/utils/github_watcher.sh --once

オプション

オプション	説明
`-d, --daemon`	デーモンモードで起動（デフォルト）
`-o, --once`	単発実行
`-c, --config <file>`	設定ファイルを指定
`-h, --help`	ヘルプを表示

IGNITEシステムとの統合起動

IGNITEシステム起動時に、GitHub Watcherも一緒に起動することができます。

オプション指定での起動

# Watcherも一緒に起動
ignite start --with-watcher

# Watcherを起動しない（設定で有効でも）
ignite start --no-watcher

設定ファイルでの自動起動

config/github-watcher.yaml で自動起動を設定できます:

# 自動起動設定
auto_start:
  # ignite start 時に自動起動するか
  # --with-watcher / --no-watcher オプションで上書き可能
  enabled: true

この設定を有効にすると、ignite start だけでWatcherも自動起動します。

状態確認

# Watcherの状態を含むシステム状態を表示
ignite status

停止

ignite stop を実行すると、Watcherも自動的に停止します。

注意事項:

セッションごとにWatcherが起動されます（各ワークスペースにPIDとログを保存）
同じリポジトリを複数セッションで監視すると重複処理の可能性があります（設定ファイルで異なるリポジトリを指定推奨）

手動でのWatcher起動

IGNITEとは別に手動でWatcherを起動する場合:

# ターミナル1: IGNITEシステム起動
ignite start

# ターミナル2: GitHub Watcher起動
./scripts/utils/github_watcher.sh

イベントメッセージ形式

通常イベント（github_event）

GitHub Watcherが検知したイベントは、以下の形式でメッセージファイルとして保存されます:

Issue作成時:

type: github_event
from: github_watcher
to: leader
timestamp: "2026-02-03T12:00:00+09:00"
priority: normal
payload:
  event_type: issue_created
  repository: owner/repo
  issue_number: 123
  issue_title: "ログイン機能のバグ修正"
  author: human-user
  author_type: User
  body: |
    ログイン時にエラーが発生します。
    再現手順: ...
  url: "https://github.com/owner/repo/issues/123"

Issueコメント時:

type: github_event
from: github_watcher
to: leader
timestamp: "2026-02-03T12:05:00+09:00"
priority: normal
payload:
  event_type: issue_comment
  repository: owner/repo
  issue_number: 123
  comment_id: 456789
  author: human-user
  author_type: User
  body: |
    この問題について追加情報があります。
  url: "https://github.com/owner/repo/issues/123#issuecomment-456789"

タスクメッセージ（github_task）

メンショントリガーが検知された場合:

type: github_task
from: github_watcher
to: leader
timestamp: "2026-02-03T12:10:00+09:00"
priority: high
payload:
  trigger: "auto"
  repository: owner/repo
  issue_number: 123
  issue_title: "ログイン機能のバグ修正"
  issue_body: |
    ログイン時にエラーが発生します。
  requested_by: human-user
  trigger_comment: |
    @ignite-gh-app このIssueを実装して
  branch_prefix: "ignite/"
  url: "https://github.com/owner/repo/issues/123#issuecomment-456789"

トリガーの使い方

メンションによるタスク起動

GitHubのIssue/PRコメントで以下のようにメンションすると、IGNITEが自動でタスクを開始します:

@ignite-gh-app このIssueを実装して

@ignite-gh-app fix this issue

@ignite-gh-app PRを作成して

タスク分類

Watcher は全てのメンションを trigger: "auto" で Leader に転送します。Leader が trigger_comment の内容から意図を判断し、以下のアクションを選択します:

アクション	説明	コメント例
実装・修正	Issue/機能の実装、バグ修正	実装して, fix this, 修正して
レビュー・確認	コードレビュー	レビューして, review, 確認して
説明	説明・解説	説明して, explain, 教えて
分析・インサイト	メモリ分析	インサイト, 分析して
GitHub 操作	Issue/PR の操作	閉じて, ラベルを付けて
複合リクエスト	複数アクションの逐次実行	レビューして問題があれば修正して

Issue → PR 自動作成フロー

トリガー検知: ユーザーが @ignite-gh-app 実装して とコメント
タスクメッセージ生成: GitHub Watcherが github_task メッセージを作成（trigger: "auto"）
IGNITE処理: Leader が意図を判断 → Strategist → IGNITIANs の流れでタスク実行
PR作成: 実装完了後、create_pr.sh でBot名義でPR作成
通知: PRリンクをIssueにコメント

PR作成スクリプト

# Issue #123 に対するPRを作成
./scripts/utils/create_pr.sh 123 --repo owner/repo

# Bot名義で作成
./scripts/utils/create_pr.sh 123 --repo owner/repo --bot

# ドラフトPRとして作成
./scripts/utils/create_pr.sh 123 --repo owner/repo --draft

work-onコマンド

ignite コマンドから直接Issueに対する作業を開始できます:

# Issue番号で指定
ignite work-on 123 --repo owner/repo

# Issue URLで指定
ignite work-on https://github.com/owner/repo/issues/123

ステート管理

処理済みイベント

処理済みイベントは workspace/.ignite/state/github_watcher_state.json に記録されます:

{
  "processed_events": {
    "issue_12345": "2026-02-03T12:00:00+09:00",
    "issue_comment_67890": "2026-02-03T12:05:00+09:00"
  },
  "last_check": {
    "owner/repo_issues": "2026-02-03T12:10:00+09:00",
    "owner/repo_issue_comments": "2026-02-03T12:10:00+09:00"
  }
}

クリーンアップ

24時間以上前の処理済みイベントは自動的にクリーンアップされます。

トラブルシューティング

イベントが検知されない

gh CLI認証確認
```
gh auth status
```
リポジトリへのアクセス確認
```
gh api /repos/owner/repo/issues
```
設定ファイルの確認
```
cat config/github-watcher.yaml
```

Bot応答が動作しない

GitHub App設定確認

./scripts/utils/get_github_app_token.sh --check

トークン取得テスト

BOT_TOKEN=$(./scripts/utils/get_github_app_token.sh --repo owner/repo)
echo $BOT_TOKEN

メッセージが重複する

ステートファイルをリセット:

rm workspace/.ignite/state/github_watcher_state.json

APIレート制限

GitHub APIのレート制限に注意してください:

認証済み: 5000 requests/hour
推奨間隔: 60秒以上

レート制限状況の確認:

gh api /rate_limit

ログの確認

# Watcherのログを確認
tail -f workspace/.ignite/logs/github_watcher.log

# 生成されたメッセージを確認
ls -la workspace/.ignite/queue/leader/github_*.mime

セキュリティに関する注意

認証情報の管理: GitHub Appの設定は安全に管理してください
リポジトリアクセス: 監視対象は信頼できるリポジトリのみに限定
Bot投稿の無視: ignore_bot: true を維持して無限ループを防止

Bot応答機能

コメント投稿ユーティリティ

IGNITEには、Issueへのコメント投稿を簡単に行うためのユーティリティスクリプトが用意されています。

# 直接メッセージ投稿
./scripts/utils/comment_on_issue.sh 123 --repo owner/repo --body "コメント内容"

# Bot名義で投稿
./scripts/utils/comment_on_issue.sh 123 --repo owner/repo --bot --body "Bot応答"

# テンプレート使用
./scripts/utils/comment_on_issue.sh 123 --repo owner/repo --bot --template acknowledge
./scripts/utils/comment_on_issue.sh 123 --repo owner/repo --bot --template success --context "完了しました"
./scripts/utils/comment_on_issue.sh 123 --repo owner/repo --bot --template error --context "エラー発生"

テンプレートタイプ

テンプレート	説明	用途
`acknowledge`	タスク受付時の応答	Issue/PRを確認したことを通知
`success`	処理完了時の応答	PR作成完了、レビュー完了など
`error`	エラー発生時の応答	処理失敗時の報告
`progress`	進捗報告	処理中の状況報告

ignite watcher コマンド

# コメント投稿
ignite watcher comment 123 --repo owner/repo --bot --body "メッセージ"

# 受付応答を投稿（テンプレート使用）
ignite watcher ack 123 owner/repo

外部リポジトリでの作業

リポジトリ管理スクリプト

外部リポジトリをcloneして作業するためのユーティリティスクリプトです。

# リポジトリをclone
./scripts/utils/setup_repo.sh clone owner/repo

# 特定のブランチを指定してclone
./scripts/utils/setup_repo.sh clone owner/repo develop

# パス取得
REPO_PATH=$(./scripts/utils/setup_repo.sh path owner/repo)
echo $REPO_PATH  # workspace/.ignite/repos/owner_repo

# Issue用ブランチ作成
./scripts/utils/setup_repo.sh branch "$REPO_PATH" 123
# → ignite/issue-123 ブランチが作成される

作業フロー

リポジトリをセットアップ

REPO_PATH=$(./scripts/utils/setup_repo.sh clone owner/repo)

Issue用ブランチを作成

./scripts/utils/setup_repo.sh branch "$REPO_PATH" 123

ファイルを編集（IGNITIANsが実行）
```
cd "$REPO_PATH"
# 編集作業
```

PR作成

./scripts/utils/create_pr.sh 123 --repo owner/repo --bot

完了報告

./scripts/utils/comment_on_issue.sh 123 --repo owner/repo --bot \
  --template success --context "PR #456 を作成しました"

PR修正フロー

PRにレビューコメントが付いた場合の修正対応:

# リベース
./scripts/utils/update_pr.sh rebase "$REPO_PATH" main

# コンフリクト発生時
# → IGNITIANsがコンフリクトを解決
./scripts/utils/update_pr.sh continue "$REPO_PATH"

# コンフリクト解決できない場合
./scripts/utils/update_pr.sh abort "$REPO_PATH"

# 追加コミット
./scripts/utils/update_pr.sh commit "$REPO_PATH" "fix: address review comments"

# プッシュ
./scripts/utils/update_pr.sh push "$REPO_PATH"

# Force push（リベース後）
./scripts/utils/update_pr.sh force-push "$REPO_PATH"

ベースブランチ設定

リポジトリごとにベースブランチを設定できます:

# config/github-watcher.yaml
watcher:
  repositories:
    - repo: owner/repo1
      base_branch: main
    - repo: owner/repo2
      base_branch: develop
    - repo: owner/repo3
      # base_branch 未指定 → リポジトリのデフォルトブランチを使用

ワイルドカードパターン指定

pattern: キーを使うと、Organization内のリポジトリをglobパターンで一括指定できます:

repositories:
  # 固定指定
  - repo: myorg/specific-repo

  # ワイルドカード指定（Organization APIで自動展開）
  - pattern: "myorg/backend-*"
  - pattern: "myorg/frontend-app-*"

動作:

起動時にパターンを展開し、マッチするリポジトリを監視対象に追加します
デーモンモードでは定期的にパターンを再展開し、新しく追加されたリポジトリも自動検知します
リフレッシュ間隔は pattern_refresh_interval（デフォルト: 60サイクル ≈ 1時間）で設定可能です
新リポジトリのイベントはWatcher起動時刻以降が対象となるため、起動後に追加されたリポジトリのイベントも漏れなく取得されます

パターン構文:

* は任意の文字列にマッチします（bash glob準拠）
? は任意の1文字にマッチします

API:

Organization API (/orgs/{org}/repos) でリポジトリ一覧を取得し、パターンでフィルタします
Organization でなくユーザーの場合は /users/{user}/repos にフォールバックします

その他:

固定指定 (repo:) とパターン指定 (pattern:) は混在可能です
重複するリポジトリは自動的に除外されます

FilesExpand file tree

github-watcher.md

Latest commit

History