認証のセットアップと最小権限

English

GitHub.com のリポジトリ・Organization の target 用に認証情報を発行する手順です。常駐サービスには GitHub App、小規模な構成には fine-grained personal access token（PAT）を推奨します。type: gh は GitHub CLI のトークンを再利用する方式であり、追加の権限を付与するものではありません。

その他の GitHub ホストでは、そのホストの API ドキュメントとポリシーを確認してください。

認証方式の選び方

共有・長期運用には専用の App、単純な専用構成には fine-grained PAT、既存の対話環境で試す場合には gh を使います。GitHub の PAT ガイド 、App の概要 、installation 認証ガイド も参照してください。

どの方式でも、ジョブの OS ユーザーが読める認証情報からジョブを隔離するものではありません。信頼できるホストの境界 を守ってください。

最小権限

workflow の保存先ではなく、target の scope に合わせて権限を選びます。リポジトリと Organization の target では必要権限が異なります。

自動で付くリポジトリの Metadata: Read-only はそのままにします。Organization の target だけに使う App には、リポジトリの Administration は不要です。リポジトリと Organization の両方を扱う場合は両方の必要権限を付けるか、認証情報を分けて権限を分離してください。

この最小権限は、固定バージョンの Scale Set SDK が利用するリポジトリ ・Organization の登録トークン発行 API に基づきます。SDK はそのトークンを Actions サービス用の認証情報に交換し、Scale Set、runner group、runner を管理します。

ghalet の管理用認証情報に Contents、Workflows、Actions の権限は不要です。ジョブの GITHUB_TOKEN や workflow の permissions は別のものであり、そちらの権限を増やしても ghalet の認証は通りません。有効期間の短い runner 登録トークンを直接指定する認証方式には対応していません。

PAT は発行者の権限を超えて操作できません。リポジトリの target にはそのリポジトリの管理者、Organization の target には Organization の owner を使ってください。Organization のポリシーによってトークンや App の利用制限・承認が必要な場合があります。

リポジトリの Administration や repo は runner 専用ではない広い権限です。Fine-grained PAT や App のインストール範囲で、影響するリポジトリを限定してください。

Organization の runner 権限は Organization 全体に及び、リポジトリの選択では制限できません。runner group のリポジトリ利用許可は GitHub 側で別途設定します。ghalet は既存 group を参照し、そのポリシーは変更しません。

Fine-grained PAT の作成

GitHub の PAT 作成ガイド に沿って作成します。

1. 個人の Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token を開きます。
2. 用途の分かる名前と有効期限を設定し、Resource owner にリポジトリの所有者または対象 Organization を選びます。Fine-grained PAT 一つで扱える resource owner は一つだけなので、異なる所有者には別のトークンを用意します。
3. リポジトリの target では Only select repositories で対象だけを選び、リポジトリの Administration: Read and write を付けます。Organization の target では Organization の Self-hosted runners: Read and write を付けます。Organization 単位の runner のためだけにリポジトリの権限を追加する必要はありません。
4. その他の権限は付けずにトークンを生成します。Organization の承認が必要な場合は、承認後に利用してください。
5. 表示された値を安全に保存します。Linux パッケージのサービスでは、PAT の暗号化登録 を使ってください。

Linux / macOS で直接起動する場合は、デーモンの実行ユーザーが読める、所有者のみアクセス可能な通常ファイルに PAT を保存し、値を YAML に書かずに参照します。ghalet credential set でファイルを取り込むと、この参照を自動で設定できます。

chmod 600 /absolute/path/to/ghalet.pat

defaults:
  credential:
    type: pat
    tokenFile: /absolute/path/to/ghalet.pat

targets:
  - scaleSet: project
    scope: OWNER/REPO

Classic PAT も type: pat で利用できますが、新規設定では fine-grained PAT または GitHub App を推奨します。

tokenEnv は tokenFile の代替であり、併記はできません。パッケージのサービスでは環境変数によるシークレット保存を避けてください。トークンの値をコマンド引数、シェル履歴、コミットするファイル、runner の環境設定に書かないでください。

GitHub CLI

type: gh ではデーモンの実行ユーザーでログインします。既存のログインが GitHub CLI の OAuth トークンを使っている場合は、必要な scope を要求します。

# Repository targets.
gh auth refresh --hostname github.com --scopes repo
# Organization targets; include repo as well when required for private repositories.
gh auth refresh --hostname github.com --scopes admin:org

これは既存の CLI ログインに scope を追加する操作であり、専用の最小権限トークンを作るものではありません。既に他の scope が付いている場合もあります。

GitHub CLI に PAT を渡している場合は、その PAT の権限を変更するか再発行してください。OAuth の scope 更新で PAT の権限は増えません。GitHub CLI の scope 更新リファレンス と、キーチェーンやサービス環境についてのサービスユーザーの認証 を参照してください。

GitHub App の作成とインストール

作成・鍵の保存・インストールの検出を案内するghalet app setup --scope OWNER/REPO --scale-set project を利用できます。パッケージのサービスでは ghalet systemd app setup を使います。手動で登録する場合は以下の手順に従ってください。

GitHub の App 登録ガイド に沿って作成します。

1. App を所有するアカウントの Settings → Developer settings → GitHub Apps → New GitHub App を開きます。Organization の runner には、Organization 所有の App を使ってください。
2. 一意の名前と Homepage URL（このプロジェクトのリポジトリ URL など）を設定します。Callback URL と Setup URL は空欄にし、ユーザー認可や device flow は有効にしません。ghalet は installation 認証を使います。
3. Webhook の Active を外します。Webhook URL、公開リスナー、イベントの購読設定は不要です。
4. 上の表から対象 scope に必要な権限だけを設定します。それ以外は、自動で付く Metadata の読み取り権限を除いて No access のままにします。所有アカウント内だけで使う App では、インストール可能な範囲に Only on this account を選び、App を作成します。
5. App の設定ページにある Client ID を控え、ghalet の clientId に使います。Client secret や installation ID とは別の値です。Client secret は不要です。Credentials → Key pairs → New key（旧設定画面では Private keys → Generate a private key）で秘密鍵を生成し、ダウンロードした PEM ファイルを安全に保存します。
6. Install App から、target を所有するアカウントにインストールします。リポジトリの target では Only select repositories で対象だけを選びます。Organization の target はその Organization へのインストールが必要です。リポジトリの選択で Organization 全体の runner 管理権限は制限できません。
7. インストールの設定ページを開き、URL 末尾の数値を installation ID として控えます。例は https://github.com/organizations/ORG/settings/installations/12345678 または https://github.com/settings/installations/12345678 です。このインストールの credential 内に installationId: 12345678 を設定します。

直接起動する場合は、ダウンロードした秘密鍵を所有者のみ読み取り可能にし（chmod 600 /absolute/path/to/ghalet-app.pem）、次のように設定します。

defaults:
  credential:
    type: github-app
    clientId: Iv1.REPLACE_WITH_CLIENT_ID
    privateKeyFile: /absolute/path/to/ghalet-app.pem
    installationId: 12345678

targets:
  - scaleSet: project
    scope: OWNER/REPO

Organization の target では scope を ORG に変更し、その Organization の installation ID を使います。複数のインストールで App の client ID と鍵を共有できますが、各 credential には所有者に対応する installation ID が必要です。Installation token の取得・更新は ghalet の SDK が自動で行います。

パッケージのサービスでは、鍵を設定ディレクトリへ直接保存する代わりに、App キーの取り込み を使ってください。

秘密鍵はその App のどのインストールとしても認証できるため、厳重に保護してください。GitHub の秘密鍵管理ガイド と認証情報のローテーション も参照してください。

認証情報のローテーション

GitHub App の秘密鍵には有効期限がない ため、認証を継続するための定期的な手動交換は不要です。セキュリティポリシーで要求される場合や、漏えいの疑いがある場合に交換します。短命な installation token の再取得は SDK が自動で行い、秘密鍵の交換とは別の処理です。

PAT は引き続き期限前の再発行が必要です。SDK が Actions サービス用の認証情報を更新しても、PAT の有効期限が延びたり、失効した PAT が置き換わったりはしません。

パッケージのサービスで暗号化した認証情報を交換する場合は、systemd のローテーションとロールバック に従い、同じ名前に --no-default で新しい値を登録してから、通常停止・正常終了の確認・起動を行います。apply では systemd が復号した認証ファイルは更新されません。

Linux / macOS で通常の PAT ファイルや App キーファイルを計画的に交換する場合は、次の手順で更新します。

1. 同じ最小権限・リポジトリ範囲の 新しい PAT を作るか、既存 App に秘密鍵を追加生成します。必要な承認・SSO の設定も先に済ませます。計画的な切り替えの間は旧認証情報を有効なまま保持し、先に再生成・失効させないでください。
2. 旧ファイルをアクセス制限した状態でロールバック用に保持し、設定先のファイルを新しい値でアトミックに置き換えます。所有者のみアクセス可能な権限と、デーモンの実行ユーザーによる読み取りを維持します。App の鍵を更新しても credential.clientId と credential.installationId は変えません。
3. ghalet apply --config /absolute/path/to/config.yaml を実行します。全 target を drain し、パスが同じでも新しいクライアントがファイルを再読込します。drain の期限 を考慮し、無停止・無中断の更新が保証されるとは考えないでください。
4. Apply の結果、ghalet status --fail-on-error、デーモンのログ、信頼できるテストジョブで、その認証情報を共有する全 target を確認します。成功後に初めて GitHub 側で旧 PAT を失効させるか旧 App キーを削除し、不要になったロールバック用のコピーも削除します。

新しい認証情報で失敗した場合は、失効操作の前に保護した旧ファイルを戻し、再度 apply します。認証方式や App の識別情報も変更する場合は、対応する YAML も保持・復元してください。Apply の失敗で設定が自動ロールバックするわけではありません。

tokenEnv では、シェルの変数を書き換えても稼働中のデーモンには反映されません。起動環境を更新し、通常停止と正常終了の確認後に起動してください。

type: gh では、デーモンの環境にある GH_TOKEN、GITHUB_TOKEN がこの順に保存済みログインより優先されます 。これらの環境変数からトークンを取得している場合も、起動環境を更新し、同様に通常停止と正常終了の確認後に起動してください。保存済みログインの変更や apply だけでは、環境変数のトークンは置き換わりません。環境変数のトークンが保存済みログインに優先していない場合に限り、デーモンの実行ユーザーでログインを差し替え・再認可した後に apply し、新しいクライアントに現在のトークンを取得させます。設定反映 も参照してください。

認証情報が漏えいした場合は、通常の移行期間を設けず直ちに失効させ、安全な新しい認証情報でサービスを復旧してください。

設定の確認

同じ設定・実行ユーザーで ghalet config validate、ghalet run、ghalet status --fail-on-error の順に確認します。設定の検証はローカルで行うもので、GitHub の権限確認ではありません。デーモンが対象の Scale Set を登録し、その名前を runs-on に使う信頼できるテスト workflow を実行できることを確認してください。

認証や登録に失敗した場合は、トークンの期限切れ・失効、PAT 発行者のアクセス権、resource owner と承認、App の権限とインストール時の承認、対象リポジトリ、client ID・installation ID・鍵の組み合わせを確認します。Runner group でも workflow のリポジトリが許可されている必要があります。アクセスエラーを解消するために全権限を付けることは避けてください。