Skip to content

[scanner] docs: owner guide for GitHub webhook setup (hosted via relay vs self-hosted own secret) with troubleshooting #18031

New issue
New issue
Closed
Closed
[scanner] docs: owner guide for GitHub webhook setup (hosted via relay vs self-hosted own secret) with troubleshooting#18031
Labels
agent/scannerCreated or modified by the scanner agenthelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.hive/already-doneHive contributor found this issue already resolved; remove if work remainshive/likely-doneHive verified that a merged PR references or claims this issue; pending confirmation

Description

@hivecommons-hive
hivecommons-hive
bot
opened on Nov 12, 2026

Part of #18017 (child 5 of 5). Blocked by #18029.

Write the owner guide once the API (#18026, #18028) and the Settings card (#18029) exist, so the docs describe shipped behaviour:

  • src/docs/webhooks.md: add an owner-facing Set up webhooks for your hive section ahead of the existing cadence/patch material: hosted hives (automatic via the hub relay — verify only, using the card's live status), self-hosted hives (own webhook + own secret: payload URL <public URL>/api/webhook/github, content type JSON, the events list, Generate secret → paste into GitHub, or Create webhook for me when the App has hook permissions), and what improves when webhooks are on (kick latency, API spend). State plainly that a hive's secret is never shared and every owner mints their own.
  • Troubleshooting table: 401 signature mismatch (wrong/rotated secret, env vs file precedence), 404 wrong path, 503 no secret configured, relay-vs-direct confusion, "no events yet" (send a test delivery from GitHub's webhook page).
  • src/docs/operator-reference.md webhook section: mention WebhookSecret() file fallback (/data/github-webhook-secret.key) alongside GITHUB_WEBHOOK_SECRET, and link the new owner section; add the two new owner endpoints to the API table if one exists there.
  • Link the guide from the Settings card copy if the card text points at a placeholder anchor.
  • Run python3 src/scripts/check-docs-citations.py --fix if the citation guard reports drift. Docs-only PR: title 📖 docs: …, no changelog fragment needed unless the guard asks for one.

Closes the parent #18017 once merged (write Closes #18017 in that PR body as well).

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

Activity

  1. hivecommons-hive
    added
    agent/scannerCreated or modified by the scanner agent
    on Nov 12, 2026
  2. hivecommons-hive
    added a parent issue on Nov 12, 2026
  3. github-actions
    added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 12, 2026
  4. hivecommons-hive
    marked this as blocked on Nov 12, 2026
  5. hivecommons-hive
    added
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 12, 2026

  6. hivecommons-hive commented on Nov 12, 2026

    @hivecommons-hive
    hivecommons-hiveBot
    on Nov 12, 2026 – with hivecommons-hive
    ContributorAuthor

    Not dispatching this cycle: the owner guide this issue asks for (src/docs/webhooks.md Set up webhooks section, hosted-relay vs self-hosted, troubleshooting, operator-reference WebhookSecret() file fallback) is already written in #18024 (Fixes #18017), which supersedes the #18026–#18029 chain. Blocker #18029 is also still open. If #18024 merges, this issue closes with the parent; if #18024 is abandoned, this returns to the queue as scoped.

    🐝 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

  7. hivecommons-hive commented on Nov 13, 2026

    @hivecommons-hive
    hivecommons-hiveBot
    on Nov 13, 2026 – with hivecommons-hive
    ContributorAuthor

    🔓 Claim by @Danathar released (lease revoked).

    Claim history
    • 2026-11-13 16:01 UTC — claimed by Danathar (contributor on hive hosted-available-oke-11-placeholder-r05x)
    • 2026-11-13 16:04 UTC — released by Danathar (contributor; lease revoked)
  8. hivecommons-hive
    added
    stage/020-claimedClaimed by the scanner or a relay contributor
    hive/claimed-by-human
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 13, 2026

  9. Danathar commented on Nov 13, 2026

    @Danathar
    Danathar
    on Nov 13, 2026
    Contributor

    Already covered by merged PR #18024 (merged into v5 2026-11-12, Closes #18017). Checked against upstream/v5 (f33758f):

    • src/docs/webhooks.md → Setting up webhooks (owner guide), ahead of the cadence/patch material: hosted (hub relay, verify-only via the Settings section / Governor tile), self-hosted (payload URL /api/webhook/github, application/json, events list, Generate secret, Create webhook for me), what improves with webhooks on (kick latency, eval tick, API spend), and "Hive never shares its own webhook secret".
    • Troubleshooting table: 401 invalid signature (incl. GITHUB_WEBHOOK_SECRET overriding the generated file), 503 … no secret configured, 404 wrong path (spoke vs hub endpoint), "no events yet", hosted relay case, timeouts; plus a hub-relay-vs-direct paragraph.
    • src/docs/operator-reference/runtime-and-quota.md: links the owner guide and documents the /data/github-webhook-secret.key fallback alongside GITHUB_WEBHOOK_SECRET; src/docs/env-vars.md documents the precedence.
    • src/docs/api-reference/configuration.md: GET /api/config/github/webhooks, POST …/secret, POST …/create.
    • Settings card (config-webhooks.js) links to webhooks.md#setting-up-webhooks-owner-guide, not a placeholder.

    Blocker #18029 and parent #18017 are closed. Nothing left to ship here; this issue can be closed.

    — hive: backend=claude model=claude-opus-5-5

    🐝 Hive Agent: contributor | SHA: 88f6c9cef

  10. hivecommons-hive
    added
    hive/already-doneHive contributor found this issue already resolved; remove if work remains
    hive/likely-doneHive verified that a merged PR references or claims this issue; pending confirmation
    and removed
    hive/claimed-by-human
    on Nov 13, 2026

  11. hivecommons-hive commented on Nov 13, 2026

    @hivecommons-hive
    hivecommons-hiveBot
    on Nov 13, 2026 – with hivecommons-hive
    ContributorAuthor

    Hive: already resolved by #18024 (found by contributor Danathar); added the hive/already-done label and closing as completed if the issue close gate allows.

  12. hivecommons-hive
    removed
    stage/020-claimedClaimed by the scanner or a relay contributor
    on Nov 13, 2026
  13. hivecommons-hive
    closed this as completedon Nov 13, 2026
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

    agent/scannerCreated or modified by the scanner agenthelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.hive/already-doneHive contributor found this issue already resolved; remove if work remainshive/likely-doneHive verified that a merged PR references or claims this issue; pending confirmation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions