fix(github-app): stop warning about undeliverable webhook events

Merged
BN
2mo ago
+382-85

Problem

The startup subscription check warns on every boot even for a correctly configured App, because required_trigger_events() listed three events GET /app can never report.

  • pull_request_target is not a webhook event at all. It is a workflow trigger preloop synthesizes from the pull_request webhook (events/pull_request.rs), so GitHub has nothing to report and the entry could never be satisfied.
  • check_run / check_suite are auto-subscribed for Apps holding checks: write and are omitted from events, so their absence never meant they were undelivered. Verified against a live App: 17 check_suite deliveries while events was ["pull_request","push"].

It also told operators to "tick the missing events" for events whose checkbox GitHub does not render, because the App lacks the gating permission — a dead end that cost real debugging time.

Change

  • Drop pull_request_target; treat check_run/check_suite as satisfied by checks: write.
  • read_app_events_at becomes read_app_subscription_at, returning events and permissions (AppSubscription) from the response it already fetched.
  • The warning now splits its advice: events tickable today, versus events needing a permission grant (and installation acceptance) first.
  • The per-event permission mapping mirrors each event's "must have at least read-level access for the …" clause in GitHub's webhook events reference.
  • Docs updated (docs/github-app-webhook.md, docs/github-app-api-compat.md), which published the same wrong list.

Tests

The old test built its "complete subscription" from the table under test, so it passed no matter how many fictional event names the list contained. It now asserts every entry against a literal list of real GitHub webhook events, plus new coverage for the implicitly-delivered check events and for permission bucketing.

Against the real App shape (events: [pull_request, push], permissions: {checks: write, contents: read, metadata: read, pull_requests: read}) the warning drops from 12 entries to 9 real ones, split into 6 tickable now and 3 blocked on the Issues/Actions permissions.

just test-ci passes locally (fmt, clippy, tests, conformance).

Drive-by

store.rs carried a clippy::manual_is_multiple_of error that already failed just test-ci on main under Rust 1.97. Unrelated to this fix, but the gate cannot run without it.

Summary by cubic

Fixes the GitHub App startup subscription check so a correctly configured App no longer warns about undeliverable webhook events.

The check previously required pull_request_target (which GitHub never delivers — preloop synthesizes it from the pull_request webhook) and flagged check_run/check_suite as missing even though checks: write auto-subscribes them and GitHub omits them from events.

  • Reads events and permissions from the same GET /app response; the warning now separates events tickable now from events needing a permission grant (and installation acceptance) first.
  • Drops pull_request_target from the required list and treats check_run/check_suite as satisfied by checks: write.
  • Updates docs that published the wrong list; tests now assert required events are real GitHub webhook events instead of deriving from the table under test.
  • Drive-by: fixes a clippy::manual_is_multiple_of failure in store.rs that breaks just test-ci on main.

[!NOTE]

Stop warning about undeliverable webhook events by enriching GitHub App subscription model with permissions

  • Replaces read_app_events with read_app_subscription, which fetches both webhook events and permissions from GET /app and returns an AppSubscription struct
  • Introduces TriggerEvent and MissingTriggerEvent structs that model each required event's gating permission and whether write-level permission implicitly delivers it (check_run, check_suite are implicit with checks: write)
  • warn_missing_trigger_events now computes missing events using explicit subscriptions and implicit delivery, then logs a single consolidated warning with step-by-step guidance grouping events by the permission to grant
  • Removes pull_request_target from the required trigger set (synthesized from pull_request) and updates docs/github-app-api-compat.md and docs/github-app-webhook.md accordingly
  • Risk: read_app_subscription_at now parses a permissions object from GET /app; if GitHub omits or renames permission keys, has_permission/has_write_permission in github_app.rs may misclassify missing events and suppress or misattribute warnings

Macroscope summarized dbb3f38.

Summary by CodeRabbit

  • Bug Fixes

    • Improved GitHub App webhook subscription checks by accounting for required permissions.
    • Warnings now distinguish missing event subscriptions from events blocked by insufficient permissions.
    • Correctly treats check-related events as available when the appropriate write permission is granted.
    • Removed unnecessary warnings for pull_request_target, which is generated from another webhook event.

  • Documentation

    • Updated GitHub App webhook and compatibility guidance to reflect subscription and permission requirements.