# GitHub Integration {#github-integration}

Takumi Runner integrates with GitHub Organizations via a **GitHub App**. This page explains the integration mechanism and the flow from job submission to runner provisioning.

## Integration Overview {#github-app}

Takumi Runner is implemented as a [GitHub App](https://docs.github.com/en/apps). When the GitHub App is installed on an Organization, GitHub sends a `workflow_job` webhook to Takumi Runner whenever a workflow job is triggered.

Takumi Runner receives this webhook and picks up only jobs whose `runs-on` label includes `takumi-runner`. Jobs with other labels (such as `ubuntu-latest`) are ignored, so existing workflows are unaffected.

## GitHub App Permissions {#permissions}

The Takumi Runner GitHub App requests only the minimum permissions needed to register/deregister runners and report job status.

| Permission          | Scope        | Access Level | Purpose                                     |
| ------------------- | ------------ | ------------ | ------------------------------------------- |
| Actions             | Repository   | Read & Write | Receive workflow job events                 |
| Checks              | Repository   | Read & Write | Report job status                           |
| Metadata            | Repository   | Read         | Access repository metadata                  |
| Self-hosted runners | Organization | Read & Write | Register and deregister self-hosted runners |

## Runner Provisioning Flow {#jit-runner}

Takumi Runner uses a **JIT (Just-In-Time) pattern** for runner management. Rather than keeping runners running at all times like traditional self-hosted runners, runners are dynamically created when a job is triggered and automatically destroyed upon completion.

The following diagram shows the flow from job submission to execution:

```mermaid
sequenceDiagram
    participant Dev as Developer
    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: Trigger workflow
    GH->>CP: workflow_job webhook (queued)
    CP->>CP: Check runs-on label
    CP->>GH: Request JIT runner config
    GH-->>CP: Return JIT config token
    CP->>DP: Launch VM (inject JIT config)
    DP->>GH: Register as runner
    GH->>DP: Assign job
    DP->>DP: Execute job (eBPF trace collection)
    DP->>GH: Report completion
    GH->>CP: workflow_job webhook (completed)
    CP->>DP: Fetch trace data
    CP->>CP: Store traces
    CP->>DP: Destroy VM
```