GitHub 連携

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

連携の概要

Takumi Runner は、GitHub の GitHub App として実装されています。Organization に GitHub App をインストールすると、GitHub はワークフロージョブが発生するたびに workflow_job Webhook を Takumi Runner に送信します。

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

GitHub App の権限

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

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

ランナーが払い出されるまでの流れ

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

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