Skip to main content

GitHub

A GitHub App puts your agent in issues, pull requests and their comment threads.

Setup​

  1. Create a GitHub App under your org or account settings. Give it read and write access to Issues and Pull requests, and subscribe it to the events listed below. Generate a private key and pick a webhook secret.

  2. Store the credentials:

    broods env set GITHUB_APP_ID
    broods env set GITHUB_PRIVATE_KEY
    broods env set GITHUB_WEBHOOK_SECRET
  3. Define the connection and the repositories it answers in:

    broods/index.ts
    import {
    defineAgent,
    defineGitHubChannel,
    defineGitHubConnection,
    env,
    } from "broods";

    export const github = defineGitHubConnection({
    webhookSecret: env("GITHUB_WEBHOOK_SECRET"),
    appId: env("GITHUB_APP_ID"),
    privateKey: env("GITHUB_PRIVATE_KEY"),
    botUserName: "my-bot[bot]",
    });

    export const platform = defineGitHubChannel({
    name: "platform",
    connection: github,
    repo: "owner/repo",
    });

    export const myAgent = defineAgent({
    name: "my-agent",
    connections: [github],
    });
  4. Run broods dev or broods deploy and set the printed URL as the App's webhook URL.

  5. Install the App on the repositories it should see.

The App's install list already limits which repositories reach the agent, so allowedChannelIds: ["*"] on the connection is a common choice here.

Configuration​

FieldRequiredDescription
webhookSecretyesGitHub App webhook secret
appIdyesGitHub App ID
privateKeyyesGitHub App private key
botUserNamenobot login for mention detection, such as my-bot or my-bot[bot]
botUserIdnobot's numeric user id. Broods ignores every comment by a Bot account, its own included, with or without it
triggerOnIssueOpennofalse stops auto-runs on issues opened or reopened. Default true
triggerOnPROpennofalse stops auto-runs on pull requests opened or reopened. Default true
apiUrlnoAPI base URL, for GitHub Enterprise. Must be public https
allowedChannelIdsnoextra repositories as owner/repo, or ["*"] for every installed repository
allowedUserIdsnoGitHub logins allowed to trigger the agent. Everyone when omitted
traceno"enabled" adds the dashboard trace link to replies
partitionnoworkspace folder split. See Workspaces

Events​

EventActions
issuesopened, reopened, assigned
pull_requestopened, reopened, assigned
issue_commentcreated, including pull request comments
pull_request_review_commentcreated

With botUserName set, a comment runs the agent only when it mentions @botUserName. Without it, every human comment runs the agent. Editing an issue, a pull request or a comment never runs it, so a typo fix does not bring a second answer.

triggerOnIssueOpen and triggerOnPROpen only cover opened and reopened, and never fire when a Bot account (Dependabot, the agent's own App) did it. Assigning the issue or pull request to the user account named in botUserName triggers it whatever these two flags say, so with botUserName set you can turn both off and still call the bot in by assigning it. An assignee of type Bot (a GitHub App) never triggers.

Context and replies​

When a comment triggers the agent, Broods fetches the issue or pull request title, body and earlier comments and adds them as context for that turn. An agent tagged halfway through a thread sees what came before. The triggering comment is still the user message.

The answer is posted as one Markdown comment once the model finishes. GitHub has no live message editing, so there is no streaming. Slash text is passed to the agent as input, and the agent cannot send files or pictures except as links.

Each issue or pull request is its own conversation. With a partition of { by: "conversation" }, closing the issue or pull request deletes its workspace folder. See Workspaces.

See Channels for channel tools and shared behavior.