GitHub Integration
The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.
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
Takumi Runner is implemented as a GitHub App. 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
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
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: