# GitHub 連携 {#github-integration}

Takumi Runner は、**GitHub App** を介して GitHub Organization と連携します。このページでは、連携の仕組みとランナーが払い出されるまでの流れを説明します。

## 連携の概要 {#github-app}

Takumi Runner は、GitHub の [GitHub App](https://docs.github.com/en/apps) として実装されています。Organization に GitHub App をインストールすると、GitHub はワークフロージョブが発生するたびに `workflow_job` Webhook を Takumi Runner に送信します。

Takumi Runner はこの Webhook を受信し、`runs-on` ラベルに `takumi-runner` が含まれているジョブだけを処理対象として拾い上げます。それ以外のラベル（`ubuntu-latest` など）を持つジョブは無視されるため、既存のワークフローに影響を与えません。

## GitHub App の権限 {#permissions}

Takumi Runner GitHub App は、ランナーの登録・解除やジョブステータスの報告に必要な最小限の権限のみを要求します。

| 権限                | スコープ     | アクセスレベル | 用途                             |
| ------------------- | ------------ | -------------- | -------------------------------- |
| Actions             | Repository   | Read & Write   | ワークフロージョブイベントの受信 |
| Checks              | Repository   | Read & Write   | ジョブステータスの報告           |
| Metadata            | Repository   | Read           | リポジトリメタデータへのアクセス |
| Self-hosted runners | Organization | Read & Write   | セルフホストランナーの登録・解除 |

## ランナーが払い出されるまでの流れ {#jit-runner}

Takumi Runner は、**JIT（Just-In-Time）パターン** でランナーを管理します。従来のセルフホストランナーのように常時起動しておくのではなく、ジョブが発生したタイミングでランナーを動的に生成し、完了後に自動的に破棄します。

以下の図は、ジョブが実行されるまでの流れを示しています。

```mermaid
sequenceDiagram
    participant Dev as 開発者
    participant GH as GitHub

    box rgb(230, 240, 255) Takumi Runner
        participant CP as Control Plane
        participant DP as Data Plane (VM)
    end

    Dev->>GH: git push
    GH->>GH: ワークフローをトリガー
    GH->>CP: workflow_job Webhook (queued)
    CP->>CP: runs-on ラベルを確認
    CP->>GH: JIT ランナー設定を要求
    GH-->>CP: JIT 設定トークンを返却
    CP->>DP: VM を起動（JIT 設定を注入）
    DP->>GH: ランナーとして登録
    GH->>DP: ジョブを割り当て
    DP->>DP: ジョブを実行（eBPF トレース収集）
    DP->>GH: 完了を報告
    GH->>CP: workflow_job Webhook (completed)
    CP->>DP: トレースデータをフェッチ
    CP->>CP: トレースを保存
    CP->>DP: VM を破棄
```