bot 名義のコミットと PR のための GitHub App
デフォルトでは、Takuto Core はあなたの個人 gh 認証情報（または
範囲を絞った personal access token）を使ってブランチを push し、
pull request を開きます。これでも動きますが、すべてのコミットと PR が あなた に紐づきます。
代わりに GitHub App を設定すると、Takuto Core を専用の bot アイデンティティとして 動かせます: コミットと pull request は App のアカウントに紐づき、認証には、環境に置きっぱなしの 長命な個人トークンではなく、Takuto Core が自動で発行・ローテーションする 短命のインストールトークン が使われます。
暗号的な署名ではなく、紐づけ（attribution）です。 これにより App の bot アカウントが 作業の作者・コミッターになります。コミットを GPG/SSH 署名するわけ ではない ので、 GitHub の緑色の Verified バッジは付きません — それにはコミット署名が必要で、これは別の 話です。Verified コミットが必要なら、workflow 側で署名を別途設定してください。
なぜ bot アイデンティティを使うのか?
紐づけがすっきりするだけでなく、エージェントの作業を bot アカウント経由にすると、安全性の うえで重要な 2 つのものが手に入ります:
- トレーサビリティ。 エージェントが生み出すすべてのブランチ、コミット、PR が、あなた自身の 作業に混ざるのではなく、bot に明確に紐づきます — エージェントが何をしたか の記録が 曖昧さなく残ります。
- ひとりで作業していても、本物のレビューゲートを。 PR の作者があなたではなく bot になる ため、少なくとも 1 件の承認レビューを必須にする branch protection ルールを有効にしつつ、 エージェントの PR を自分でレビューして承認できます。GitHub は通常、自分自身 の PR を 承認することをブロックするので、bot の作者がいなければ、ひとりの開発者はレビューゲートを まったく強制できません。bot がいれば、すべての変更はマージ前に必ずもう一度目を通される ことになります — 大きなセキュリティ上の利点です。
ブランチは必ず保護する。 自律エージェントは、そのトークンが許す範囲なら何でもできます。 だからこそ、リポジトリ自身の保護が本当のセーフティネットになります。
main（およびエージェント が対象とするあらゆるブランチ）では branch protection を有効にしてください: マージ前に pull request を必須にし、承認レビューを必須にし、直接の push を禁止します。Takuto Core は 常に feature ブランチを push して PR を開くだけです — 保護されたブランチに直接コミットできて しまうことは決してあってはなりません。エージェントが行儀よくふるまうことに頼らず、ブランチ ルールに頼ってください。
しくみ
[github] の App 認証情報が設定されていると、Takuto Core は次のことを行います:
- App の秘密鍵で署名した JWT を組み立てます。
- それを GitHub API 経由で インストールアクセストークン と交換します。
- 各 worktree 内の
gitとghを、その実行中はそのトークンを使うように設定します。
トークンは App のインストールに範囲が限定され、バックグラウンドで更新されるので、push や PR 作成のために個人 PAT は不要です。
1. App を作成する
GitHub → Settings → Developer settings → GitHub Apps → New GitHub App（org のリポジトリ なら org の設定の下）へ進みます。名前とホームページ URL を入力します。webhook は 無効 のままで構いません（Takuto Core はポーリングし、webhook は受け取りません）。作成したら、 App のページに表示される App ID を控えておきます。
2. リポジトリ権限を付与する
App の Permissions → Repository permissions で、実行に必要なものだけを設定します — 範囲を絞ったトークン と同じ範囲です:
| 権限 | アクセス | 用途 |
|---|---|---|
| Contents | Read & write | ブランチとコミットの push |
| Pull requests | Read & write | PR を開く、マージのポーリング |
| Metadata | Read | 必須の基本権限 |
| Issues | Read & write | ticketing_system = "github" の場合のみ |
エージェントが触れるべき特定のリポジトリに範囲を絞ったまま — それ以上は付与しないでください。
3. 秘密鍵を生成する
App のページの Private keys で、Generate a private key をクリックします。GitHub が
.pem ファイルをダウンロードします。これは認証情報として扱ってください: container に
マウントされる場所に保存するか、takuto.env に貼り付けます — 決してリポジトリにコミットしないでください。
4. App をインストールする
Install App をクリックし、リポジトリを所有するアカウント / org にインストールします。
このとき Takuto Core が作業すべき リポジトリだけ を選びます。インストール後、インストールの
設定ページを開きます — URL は /installations/<number> で終わります。この番号が
インストール ID です。
5. Takuto Core を設定する
[github] セクションに 3 つすべてを設定します。3 つのフィールドはまとめて指定する必要があり、
秘密鍵の 2 つのフィールドは排他です — パス または インラインの鍵のどちらかを使います:
[github]
app_id = 123456
app_installation_id = 7654321
# マウントした PEM ファイルを指すか…
app_private_key_path = "/run/secrets/takuto-app.pem"
# …または鍵をインラインで保持します（これには config.toml より takuto.env を推奨）:
# app_private_key = "-----BEGIN RSA PRIVATE KEY-----\n…\n-----END RSA PRIVATE KEY-----"鍵は config.toml の外に置くことを推奨します: app_private_key を takuto.env に入れるか、
.pem をマウントして app_private_key_path を使います。正確なフィールドの意味については
[github] 設定リファレンス を参照してください。
6. 再起動して確認する
Takuto Core を再起動します（takuto restart、エンジンを直接動かす場合は docker compose up）。
PR を開く workflow を実行し、コミットと PR が個人ユーザーではなく App の bot アカウントに
紐づいていることを確認します。認証に失敗した場合、Takuto Core は対処可能な GitHub API
エラー（例えばインストールが見つからない、権限の不一致など）をログに出します — 上記の App ID、
インストール ID、付与した権限を見直してください。