Connect a GitHub webhook#

A signed GitHub event starts a Session only when it matches an owned Agent/environment binding. Rat Things keeps webhook verification, repository checkout and terminal Turn notification as separate stages.

Prerequisites#

Deploy the Agents API and execution backend, configure an admitted model, and authenticate the Rat Things CLI as the operator who will own the Sessions. The selected environment must support repository commands. Keep the GitHub webhook, clone and comment credentials separate.

Configure the webhook#

Store a high-entropy signing secret, a repository-read token and a comment-write token in Secrets Manager. Set these Terraform inputs to their ARNs:

• github_webhook_secret_arn
• github_clone_token_secret_arn
• github_notify_token_secret_arn

Set github_comment_trigger to a distinct non-empty trigger for this deployment. Keep repository hosts allowlisted. Apply the deployment configuration using the normal Terraform workflow; secret values must not enter Terraform variables or state.

In the repository's webhook settings, use the deployed webhook_urls.github output, application/json, and the matching signing secret. Select pull-request and issue-comment events. Keep separate hooks, secrets and destinations for development and production.

Bind the repository to an Agent#

Create an Agent with the model, instructions and tools appropriate for repository review. Create an environment template with the required packages and network access. Save a binding with those returned IDs as github-binding.json:

{
  "version": "1",
  "sourceKind": "github",
  "selector": { "repository": "OWNER/REPOSITORY" },
  "agentId": "agent_example",
  "environment": {
    "type": "openai_hosted",
    "environment_template_id": "envtpl_example"
  }
}

rat-things bind-source --file github-binding.json
rat-things source-bindings

openai_hosted is the standard wire name for a managed environment. On this endpoint, Rat Things provisions that environment in your AWS account. The authenticated operator owns the binding and resulting Sessions. Generic repository selectors are trusted operator configuration; they do not independently prove repository ownership.

A notification destination does not give the Agent GitHub write tools. Declare any desired agent-callable operations separately on the Agent, with their own credentials and grants.

Trigger the first response#

Opening, reopening or updating a pull request, or marking it ready for review, submits a review. A newly created pull-request comment containing the configured trigger submits a question. Other signed event types are acknowledged and ignored.

The accepted receipt contains a Session ID. Inspect that Session's Turns and Items with the standard API or CLI. The saved terminal root Turn supplies the result comment; worker exit alone does not trigger another reply. Repeated delivery IDs are deduplicated. Repository occurrences use separate Sessions so a later event cannot change an earlier checkout ref.

Credential handling#

The verifier reads only the signing secret. Trusted checkout uses the repository-read token; terminal Turn delivery uses the notification token. Tokens never belong in clone URLs, bindings, Agent instructions or webhook bodies. The current clone adapter consumes a configured token; it does not mint GitHub App installation tokens from the event's installation ID.

Troubleshooting#

• A signed ping returns 202 with ignored: true; it does not execute an Agent.
• source_not_bound means no verified source selector matched an Agent/environment binding.
• 401 means signature verification failed. Check the configured secret and exact raw body.
• A failed Turn needs inspection through Session Items and worker diagnostics. A completed Turn with no comment needs delivery-fence and notification-credential inspection.
• An ambiguous comment outcome needs provider reconciliation before another write is attempted.

See channel adapters for accepted event shapes and deployment controls.