GitHub App for bot-attributed commits & PRs

By default, Takuto Core pushes branches and opens pull requests using your personal gh credentials (or a scoped personal access token). That works, but every commit and PR is attributed to you.

Configuring a GitHub App instead lets Takuto Core act as a dedicated bot identity: commits and pull requests are attributed to the App’s account, and authentication uses a short-lived installation token that Takuto Core mints and rotates automatically — rather than a long-lived personal token sitting in your environment.

How attribution is decided. It follows your token setup, the same way for commits and PRs: if a personal access token (GH_TOKEN) is present, the work is attributed to you; with the App alone (no PAT), it’s attributed to the bot. There’s no per-run toggle — so for bot attribution, configure the App and leave GH_TOKEN unset.

Attribution, not cryptographic signing. This makes the App’s bot account the author/committer of the work. It does not GPG/SSH-sign your commits, so they won’t show GitHub’s green Verified badge — that requires commit signing, which is a separate concern. If you need Verified commits, configure signing in your workflow separately.

Why use a bot identity?

Beyond cleaner attribution, routing the agent’s work through a bot account buys you two things that matter for safety:

• Traceability. Every branch, commit, and PR the agent produces is clearly attributed to the bot rather than mixed in with your own work — so the record of what the agent did is unambiguous.
• Real review gates, even when you work solo. Because the PR’s author is the bot and not you, you can enable a branch protection rule that requires at least one approving review and still review and approve the agent’s PRs yourself. GitHub normally blocks you from approving your own PR, so without a bot author a solo developer can’t enforce a review gate at all. With one, every change gets a mandatory second look before it can merge — a big security win.

Protect your branches — always. An autonomous agent can do anything its token permits, so your repository’s own protections are the real safety net. On main (and any branch the agent targets), turn on branch protection: require a pull request before merging, require approving reviews, and forbid direct pushes. Takuto Core only ever pushes feature branches and opens PRs — it should never be able to commit straight to a protected branch. Don’t rely on the agent behaving; rely on the branch rules.

How it works

When [github] App credentials are set, Takuto Core:

1. Builds a JWT signed with your App’s private key.
2. Exchanges it for an installation access token via the GitHub API.
3. Configures git and gh inside each worktree to use that token for the run.

The token is scoped to the App’s installation and refreshed in the background, so no personal PAT is needed for pushes or PR creation.

1. Create the App

Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App (under your org’s settings if it’s an org repo). Fill in a name and homepage URL; you can leave the webhook inactive (Takuto Core polls, it doesn’t receive webhooks). Create it, then note the App ID shown on the App’s page.

2. Grant repository permissions

Under the App’s Permissions → Repository permissions, set exactly what a run needs — the same surface as the scoped token:

Keep it scoped to the specific repositories the agent should touch — nothing more.

3. Generate a private key

On the App’s page, under Private keys, click Generate a private key. GitHub downloads a .pem file. Treat it like a credential: store it somewhere mounted into the container, or paste it into takuto.env — never commit it to your repo.

4. Install the App

Click Install App and install it on the account/org that owns your repository, choosing only the repositories Takuto Core should work on. After installing, open the installation’s settings page — the URL ends in /installations/<number>. That number is your installation ID.

5. Configure Takuto Core

Set all three pieces in the [github] section. The three fields must be provided together, and the two private-key fields are mutually exclusive — use a path or an inline key:

[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-----"

Prefer keeping the key out of config.toml: put app_private_key in takuto.env, or mount the .pem and use app_private_key_path. See the [github] configuration reference for the exact field semantics.

6. Restart and verify

Restart Takuto Core (takuto restart, or docker compose up for the engine path). Run a workflow that opens a PR, and confirm the commit and PR are attributed to your App’s bot account rather than your personal user. If authentication fails, Takuto Core logs an actionable GitHub API error (for example, an installation-not-found or a permissions mismatch) — re-check the App ID, installation ID, and the granted permissions above.