GitHub 連携

GitHub 連携を使うと、GitHub から離れずに作業を記録できます。

• コメントから — Issue や Pull Request に @spantail 2h yesterday とコメントすると、 マッピングされたプロジェクトに作業が記録されます。ボットは 👍 でリアクションし、その Issue の累計時間を返信します。
• Claude Code から — /spantail:log-work #123 2h で GitHub Issue に対して記録します。 サーバーが Issue の件名とラベルを補完し、関連するエージェントセッションを紐づけます。

セットアップは 4 段階です: App の登録（インスタンス管理者、1 回）、インストール （リポジトリ所有者、アカウント/組織ごとに 1 回）、リポジトリのマッピング（ワークスペース 管理者）、各メンバーの GitHub 連携（セルフサービス）。

1. App を登録する（インスタンス管理者）

設定 → システム → GitHub。 各 Spantail インスタンスは自分専用の GitHub App を 登録します。webhook はインスタンスの URL を向く必要があるため、共有の中央 App はありません。

1. 所有者を選びます: 個人アカウント、または所属する組織。所有者によって、後で App を インストールできるリポジトリの範囲が決まります。
2. GitHub で登録をクリックします。GitHub に App Manifest フロー で作成される App が表示されるので、承認します。
3. 新しい App の資格情報（秘密鍵・webhook シークレット・クライアントシークレット）は GitHub からインスタンスへ自動で送られ、暗号化して保存されます。コピー & ペーストは 不要です。

App は常に所有者のプライベート App として登録され、連携に必要な権限（Issue/PR の 読み書き、メタデータの読み取り）だけを要求し、webhook はこのインスタンスに固定されます。

2. インストールする

登録直後に GitHub が App のインストール先を尋ねます。作業を記録したいアカウントまたは 組織を選び、リポジトリを選択してください。後からのインストールは App の GitHub ページ （設定画面からリンク）で行えます。インストールは webhook の到着に伴い 設定 → システム → GitHub に表示されます。

3. リポジトリをプロジェクトにマッピングする（ワークスペース管理者）

設定 → ワークスペース → 連携。 マッピングは「このリポジトリから記録された作業は このプロジェクトのもの」という対応付けです。マッピングが唯一の真実であり、Claude Code プラグインはプロジェクト ID を持ちません。

• インストールから — App が到達できるリポジトリは「未マッピングのリポジトリ」に 表示されるので、必要なものにプロジェクトを割り当てます。
• 手動で — owner/repo を名前で追加します。これは App なしでも機能します: #N 形式の作業エントリはそのまま動きます（エントリは件名・ラベルなしの Issue リンクのみに なります）。コメントコマンドには App が必要です。

1 つのリポジトリはインスタンス全体で 1 つのプロジェクトに対応します。

4. GitHub アカウントを連携する（各メンバー）

設定 → アカウント → 認証 → 作業エントリ用の GitHub 連携。 @spantail … コメントで作業が 記録されるのは、その GitHub アカウントがどのユーザーのものか Spantail が知っている 場合だけです。各メンバーが一度 GitHub を連携をクリックして GitHub 上で承認します。 この認可はアカウントの所有確認だけを行い、リポジトリへのアクセス権は付与されず、サイン イン手段にもなりません。未連携のリポジトリメンバーが初めてコマンドを投稿すると、ボットが 連携リンクを返信します。

使い方

マッピング済みリポジトリの Issue や PR に、次の形式でコメントします。

@spantail <duration> [date]

• duration: 30m、2h、1h30m、3.5h、または分の数値（90）。
• date（省略可）: today / yesterday / 今日 / 昨日、2026-07-05（ISO）、 7/5 や 7月5日（月/日。年は今日以前になる直近の年に補完）。省略時は今日 — あなたの アカウント設定のタイムゾーンで解釈されます。

エントリには Issue の件名が説明として、ラベルがタグとして入り、Issue へのリンクが付き ます。ブランチ名や PR がその Issue を指している直近のエージェントセッションは自動で紐づき ます。

コマンドを実行できるのは連携済みのワークスペースメンバーだけです。public リポジトリでは、 それ以外の投稿者をボットは意図的に無視します（部外者への返信はありません）。

解除するとき

• アンインストール / 停止（GitHub 側） — 対象リポジトリのコメントコマンドは止まり ますが、マッピングと履歴は残ります。
• App 設定の削除（設定 → システム → GitHub） — マッピングは残るため、#N 形式の 作業エントリはリンクのみの縮退モードで動き続けます。
• GitHub 連携の解除（メンバー） — 再連携するまで、そのメンバーのコメントは記録され ません。