Skip to content

✨ Owner-facing GitHub webhook setup: Settings card, generated secret, create-hook, owner guide #18017

Closed
5 of 5 issues completed

Description

@clubanderson

Problem

Turning GitHub webhooks on for hive's own spoke (hivecommons/hive → oke-11) cut kick latency and API spend. Other hive owners (e.g. @Danathar's self-hosted hive on projectbluefin repos) want the same, but today the setup is not discoverable: the receiver (POST /api/webhook/github), the secret (GITHUB_WEBHOOK_SECRET env only), the event list and the hub-relay path are documented across three operator pages, there is no dashboard surface that tells an owner what URL/secret/events to configure, and there is no way to mint a per-hive secret without a shell on the spoke. Hive's own webhook secret must never be shared; every owner needs their own.

What exists

  • Spoke receiver pkg/dashboard/api_github_webhook.go: verifies X-Hub-Signature-256 against GITHUB_WEBHOOK_SECRET, or the hub's relay signature against the per-hive relay key (🐛 [v5] hosted hives reject every relayed GitHub webhook: the hub never gives the spoke a way to verify them #17911). Events invalidate PR cache, wake an early eval cycle, kick on CI failure, dispatch reviews, refresh the tracker.
  • Hub relay pkg/hub/webhook.go: the hub verifies GitHub App deliveries and forwards them to every enrolled hive managing the repo whose dashboard URL is public, hub-signed with that hive's own relay key. Hosted spokes already get this with no owner action (verified on hive-oke: every hosted spoke with a managed repo receives relays).
  • Health in /api/status.webhooks (events_1h, last_event_at, verification, mode).

Proposal

  1. pkg/github: WebhookSecret() reads GITHUB_WEBHOOK_SECRET, else /data/github-webhook-secret.key (0600, same pattern as the relay key). Receiver and WebhookVerification() use it.
  2. Owner-only API: GET /api/config/github/webhooks (payload URL, events, content type, verification mode, secret source, health, App hook permissions), POST /api/config/github/webhooks/secret (generate, store 0600, return once), POST /api/config/github/webhooks/create (create the org/repo hook through the App when the installation has organization_hooks / repository_hooks: write).
  3. Settings → Forge App → GitHub webhooks card: exact payload URL, events to tick, content type, Generate secret (shown once, copy), Create webhook for me (only when the App permission is granted), live status / "no events yet" guidance, link to the guide.
  4. src/docs/webhooks.md: owner guide for hosted (automatic via relay — verify only) and self-hosted (own webhook + own secret) hives, with troubleshooting (401 signature mismatch, 404 wrong path, 503 no secret, relay vs direct) and what improves when webhooks are on.

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 12, 2026
  2. hivecommons-hive commented on Nov 12, 2026

    @hivecommons-hive
    Contributor

    Decomposed into five sequenced sub-issues (each too distinct in surface — secret storage, owner API, App write, UI, docs — to land as one reviewable PR):

    1. [scanner] github: WebhookSecret() reads GITHUB_WEBHOOK_SECRET else /data/github-webhook-secret.key (0600), receiver and status use it #18025 — pkg/github.WebhookSecret(): env else /data/github-webhook-secret.key (0600), receiver + status read it
    2. [scanner] dashboard: owner API GET /api/config/github/webhooks and POST .../webhooks/secret (generate, store 0600, return once) #18026 — owner API GET /api/config/github/webhooks + POST …/webhooks/secret (blocked by 1)
    3. [scanner] dashboard: POST /api/config/github/webhooks/create — create the org/repo hook through the App when hook permissions are granted #18028 — POST …/webhooks/create through the App when hook permissions are granted (blocked by 2)
    4. [scanner] dashboard: Settings → Forge App → GitHub webhooks card (payload URL, events, generate secret, create hook, live status) #18029 — Settings → Forge App → GitHub webhooks card (blocked by 2)
    5. [scanner] docs: owner guide for GitHub webhook setup (hosted via relay vs self-hosted own secret) with troubleshooting #18031 — owner guide in src/docs/webhooks.md + operator-reference (blocked by 4; closes this issue)

    The hive picks each child up as its blocker closes.


    🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

    — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  3. github-actions commented on Nov 12, 2026

    @github-actions
    Contributor

    @clubanderson this issue was closed by @hivecommons-hive[bot] as completed.

    If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

    If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions