[TonsOfFun]

Closes #641

What

An engine endpoint, POST <mount>/api/github_app/webhooks (Api::GithubAppWebhooksController, an ActionController::API like the other signed/token endpoints: no session, no CSRF, none of the host's controller concerns).

• Signature: X-Hub-Signature-256 must equal sha256= + HMAC-SHA256 of the raw body under ActionAgent.github_app_webhook_secret (new accessor, falls back to GITHUB_APP_WEBHOOK_SECRET), compared with ActiveSupport::SecurityUtils.secure_compare. Bad, malformed or missing signature: 401. No secret configured: 404. The secret is not part of github_app_configured?, so an App without a webhook keeps working as before.

• Answer: 202 right away; the delivery is applied in ActionAgent::GithubWebhookJob. JSON bodies and GitHub's form-encoded payload= bodies are both read; the job gets a slice of the payload (action, installation id/permissions/selection/suspended_at, added/removed repo ids, sender id), not the whole delivery.

• Idempotency: a new table, github_webhook_deliveries (delivery id unique, event, action, installation id, created_at; no payload). The delivery is inserted before the job is enqueued; a duplicate insert (RecordNotUnique, inside a savepoint) answers 202 {"status":"duplicate"} and does nothing. If enqueueing fails the row is removed so a redelivery is processed. Rows older than 7 days are pruned on each insert. I went with a table over Rails.cache because the unique index makes check-and-record one atomic insert across every web process whatever cache store the host runs (Cloud Run runs several instances; a memory or null store would dedupe nothing). Handlers also set state from the payload rather than toggling it, so a job run twice gives the same result.

• Events:

  Event	Action	Effect
  installation	deleted	removed_at set (if unset)
  installation	suspend	suspended_at set from the payload (or now)
  installation	unsuspend	suspended_at cleared
  installation	new_permissions_accepted	permissions replaced from the payload
  installation_repositories	removed	removed repos dropped from the owner's selection; repository_selection refreshed
  installation_repositories	added	repository_selection refreshed; nothing else to store, since the repository picker lists what the installation reaches from GitHub each time it opens
  github_app_authorization	revoked	the sender's stored GithubConnections deleted, only when github_client_id == github_app_client_id (see below)
  anything else (ping, push, ...)		202 {"status":"ignored"}, nothing recorded

  Deliveries for an installation_id no owner linked are ignored (an installation created is never auto-linked; linking stays the Settings flow with its admin check).

Migration

Ships the way the engine ships others: numbered template 029_create_active_agent_github_webhook_deliveries.rb.erb (emitted by rails g action_agent:install), the same migration in test/dummy/db/migrate, and the dummy schema.rb (version 29). Index names are short (index_<prefix>webhook_deliveries_on_*) to stay under the 63/64-char limits with longer prefixes. Hosts: run the generator and db:migrate when upgrading.

Docs

docs/framework/dashboard.md gains a "GitHub App webhooks" section (setup + event table) and no longer says "no webhook"; the initializer template and CHANGELOG mention the new setting.

Deviation from the issue: revoked authorization

The App's own user tokens are never stored (the installation callback holds them in-method only), and GithubConnection is the separate OAuth App flow (github_client_id). A github_app_authorization: revoked delivery is about the App's grant, not that OAuth App's, so deleting an OAuth App connection on it would remove a token that still works. The job therefore deletes the sender's connection only when the OAuth connection flow is configured with the App's own client id (i.e. the connection's token is an App user token). On activeagents.ai today, where the OAuth App is separate, the event changes nothing. If you want it to delete regardless, that's a one-line change.

Tests

• New actionagent/test/github_app_webhooks_test.rb (19 tests) against payload fixtures in actionagent/test/fixtures/files/github_webhooks/ with signatures computed in the test; no network (a WebMock stub only for the picker listing check). Covers valid/invalid/missing signatures, no secret = 404, ENV fallback, CSRF exemption, redelivery no-op (suspend, unsuspend, then a redelivered suspend leaves it unsuspended), enqueue failure not recorded, pruning, each event, unlinked installations, ignored events, form-encoded bodies, and both revoke cases.
• install_generator_test.rb: the 029 migration builds the same table shape as the dummy schema, with a unique delivery index, and reverses.
• Full engine suite locally (bin/test actionagent/test/*_test.rb, Ruby 3.3.8, rails8 gemfile): 1840 runs, 13800 assertions, 0 failures, 0 errors, 7 skips. RuboCop clean on changed Ruby files.

Host follow-up (activeagents/activeagents), after this ships

• Production App: set Webhook URL https://activeagents.ai/dashboard/api/github_app/webhooks, check Active, subscribe to Installation and Installation repositories (GitHub App authorization is sent automatically). Same for the staging App with https://staging.activeagents.ai/dashboard/api/github_app/webhooks.
• Expose the existing webhook secret to the service as GITHUB_APP_WEBHOOK_SECRET (or config.github_app_webhook_secret), keeping the Terraform/env files in sync; staging needs its own secret.
• Run the generator / db:migrate for the new table on repin.
• Update docs/infrastructure/gcp-cicd-setup.md step 1 ("leave Active unchecked until a receiver exists").

Not done here

• The manifest flow (Create GitHub App for self-hosters) still creates an App with no webhook; adding hook_attributes and showing the returned webhook_secret on the created page is a possible follow-up.
• Acceptance items "Uninstalling on GitHub marks removed in Settings" / "Adding or removing repositories updates the dashboard's list" are covered by tests with recorded payloads, not verified end to end against GitHub (needs the host follow-up above).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PCEJHsJpjXpDa9Kuq9i4Yg