用 GitHub App 让提交与 PR 归属到机器人身份

默认情况下，Takuto Core 会用你个人的 gh 凭据（或一个受限的个人访问令牌）来推送分支、创建 pull request。这样能用，但每一次提交和每一个 PR 都会归到你名下。

改成配置一个 GitHub App，就能让 Takuto Core 以专属的机器人身份行事：提交和 pull request 归属到 App 的账户，而身份验证用的是一个短时效的 installation token——由 Takuto Core 自动签发并轮换，而不是把一个长期有效的个人 token 一直摆在你的环境里。

这是归属，不是密码学签名。 这只会把 App 的机器人账户设为这些工作的 author/committer，并不会用 GPG/SSH 给你的提交签名，因此它们不会显示 GitHub 的绿色 Verified 徽章——那需要提交签名，是另一回事。如果你需要 Verified 提交，请在你的 workflow 里单独配置签名。

为什么要用机器人身份？

除了让归属更清爽之外，把 agent 的工作经由一个机器人账户来路由，还能为安全带来两点切实的好处：

  • 可追溯性。 agent 产出的每一个分支、每一次提交、每一个 PR 都清楚地归到这个 bot 名下，而不是和你自己的工作混在一起——于是agent 究竟做了什么的记录一目了然、毫不含糊。
  • 即便你单干，也能有真正的评审关卡。 因为 PR 的 author 是这个 bot 而不是你，你就可以启用一条要求至少一个批准评审的 branch protection 规则，同时仍由你本人来评审并批准 agent 的 PR。GitHub 通常不允许你批准自己的 PR，所以若没有一个机器人 author，单人开发者根本无法落实评审关卡。而有了它，每一处改动在能够合并之前都会经过一次强制的二次把关——这是一项重大的安全收益。

保护好你的分支——永远如此。 一个自主运行的 agent 能做它的 token 所允许的任何事，所以你仓库自身的保护措施才是真正的安全网。请在 main（以及 agent 会作为目标的任何分支）上开启 branch protection：合并前必须经过 pull request、必须有批准评审，并禁止直接推送。Takuto Core 始终只推送 feature 分支并创建 PR——它绝不应该能够直接向受保护的分支提交。别指望 agent 会规矩行事；要靠分支规则来兜底。

工作原理

当 [github] 的 App 凭据设置好后，Takuto Core 会：

  1. 用你 App 的私钥构造并签名一个 JWT。
  2. 通过 GitHub API 把它换成一个 installation access token。
  3. 在每个 worktree 内部配置好 git 和 gh，让本次运行使用该 token。

这个 token 的作用域限定在该 App 的 installation 内，并在后台刷新，因此推送或创建 PR 都不再需要个人 PAT。

1. 创建 App

前往 GitHub → Settings → Developer settings → GitHub Apps → New GitHub App（如果是组织仓库，则在你组织的设置里）。填好名称和主页 URL；webhook 可以保持未启用（Takuto Core 是轮询的，不接收 webhook）。创建之后，记下 App 页面上显示的 App ID。

2. 授予仓库权限

在该 App 的 Permissions → Repository permissions 下，精确设置一次运行所需的权限——和受限令牌的范围一致：

权限访问级别用途
ContentsRead & write推送分支与提交
Pull requestsRead & write创建 PR 并轮询合并状态
MetadataRead必需的基础权限
IssuesRead & write仅当 ticketing_system = "github" 时需要

把范围限定在 agent 应当触碰的那几个特定仓库上——多一个都别给。

3. 生成私钥

在该 App 的页面上，于 Private keys 下点击 Generate a private key。GitHub 会下载一个 .pem 文件。把它当作凭据对待：要么放在某个会挂载进 container 的位置，要么粘贴进 takuto.env——千万别把它提交到你的仓库里。

4. 安装 App

点击 Install App，把它安装到拥有你仓库的那个账户/组织上，并只选择 Takuto Core 应当处理的那些仓库。安装完成后，打开该 installation 的设置页——URL 以 /installations/<number> 结尾。那个数字就是你的 installation ID。

5. 配置 Takuto Core

在 [github] 区段里设置全部三项。这三个字段必须一起提供，而两个私钥字段互斥——要么用路径，要么用内联密钥：

[github]
app_id = 123456
app_installation_id = 7654321
# Either point at a mounted PEM file…
app_private_key_path = "/run/secrets/takuto-app.pem"
# …or keep the key inline (prefer takuto.env over config.toml for this):
# 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 的机器人账户，而不是你的个人用户。如果身份验证失败，Takuto Core 会记录一条可操作的 GitHub API 错误（例如 installation-not-found 或权限不匹配）——届时请重新核对上面的 App ID、installation ID 以及所授予的权限。