runner の registration token とは？runner の登録

runner の registration token とは、新しい runner エージェントがリポジトリまたは組織に登録することを認可する、短命の認証情報です。

runner が job を拾えるようになる前に、登録が必要です。registration token は、runner を追加している人物が許可されていることを GitHub が検証する手段です。漏洩した場合の被害を限定するため、意図的に短命になっています。

何をするのか

runner をセットアップすると、GitHub は registration token を発行します。runner は登録時にそれを提示し、リポジトリや組織に参加する権限があることを証明します。登録されると、runner は独自の認証情報を使って job を受け取ります。

なぜ期限切れになるのか

registration token は短命です（1 時間ほどのオーダー）。1 つが漏洩しても、悪用できる期間は小さいです。自動化された runner システムは、1 つを cache するのではなく、マシンを登録するたびに新しい token を取得します。

token 登録 vs JIT

registration token は有効期間内に runner を繰り返し登録でき、これは複数のマシンを事前登録する warm pool に適しています。JIT 設定は runner ごとに使い捨てで、これは単発の cold start マシンに適しています。多くのプラットフォームは両方を使います。

よくある token のエラー

期限切れの token: token が失効したため登録に失敗する - 新しいものを取得する。
誤ったスコープ: repo の token は org の runner を登録できず、逆も同様。
クロックのずれ: runner のクロックが大きく狂っていると、有効な token が期限切れに見えることがある。

扱う必要のない token

マネージドプラットフォームでは、runner がプロビジョニング・破棄されるにつれて登録と token のローテーションが自動的に行われます。Latchkey があなたに代わって runner を登録・退役させるため、期限切れ token や誤ったスコープのエラーは、そもそもあなたが管理するものではありません。

重要なポイント

registration token は、runner がリポジトリや組織に登録することを認可します。
漏洩の影響を限定するため短命です。
token は複数の runner を登録できますが、JIT 設定は使い捨てです。
期限切れ、誤ったスコープ、クロックのずれが一般的な障害モードです。