Route alerts to safe, repository-local GitHub issues #4683

🤖 Generated by the Agentic Engineer

User Story

As a portfolio maintainer,
I want alert signals to create or update an actionable incident issue in the affected product's repository,
So that I am notified and the engineer can investigate and fix it where the work belongs without exposing sensitive evidence.

Summary and motivation

Deliver the alert-transport migration for devantler-tech/monorepo#4053. This is not a detector-removal project or a central alert inbox. Preserve the existing controlled proof in #2755 rather than creating a competing test framework.

Proposed Solution

Adapt the current Coroot, Flux, Alertmanager and direct-check transports through maintained integrations where suitable, or a small authenticated adapter where they cannot meet the requirements. Reuse the existing organization GitHub App for issue/comment publishing; native integrations requiring another App are exceptions to justify, not the default. Route using reviewed product ownership configuration, never a destination chosen by alert text. Preserve meaningful grouping, grace periods, detection, runtime-alert ingestion/dashboard behavior and the independent off-cluster heartbeat.

One incident maps to one owning-repository issue, reusing an existing issue covering it where appropriate. Bounded significant updates stay in that issue. Trustworthy recovery updates the incident; unresolved remediation stays open. Mention the maintainer on actionable initial messages, not every repeated scrape. Assignment remains real ownership.

Acceptance Criteria

• Inventory and map every currently active Slack alert route at implementation time. Track private and runtime-local routing dependencies privately; declared configuration does not prove live destination or delivery.
• Select and document maintained native integrations/adapter reuse before adding a bespoke service. Flux's GitHub commit-status provider is not mistaken for generic GitHub issue creation.
• Use the verified existing organization App publishing path with notification-scoped installation tokens, reviewed repository routing and authentication; reject unknown ownership/visibility rather than guessing.
• Compare integrations against the epic's smallest-justified-App-set target. If a heartbeat or alert integration requires another App, document why the existing App and a supported webhook/adapter cannot deliver the same outcome safely before adopting it. Preserve any justified third-party App requirement rather than forcing insecure consolidation.
• Public issue titles/bodies/comments contain only safe actionable fields. Never forward raw logs, labels, annotations, URLs, credentials, internal topology or private-source evidence.
• Wrong-owner, unknown-field, injected-destination and sensitive-data-canary tests fail closed. Private issues/configuration are not copied onto the public project.
• Concurrent/repeated firing, meaningful transitions, recovery, recurrence, rate limits, token expiry and ambiguous writes do not cause incident spam or false delivery receipts; retries have bounded durable handling.
• Preserve Alertmanager functions that are still needed, plus current detectors, grace/grouping behavior and coverage. Retirement must not silence useful signals.
• Keep the lost-heartbeat path outside the cluster and record any non-Slack urgent fallback decision. GitHub delivery is not claimed to be guaranteed emergency paging.
• Land default-off, test both delivery states, then activate route-by-route with rollback available and the controlled notification proof from Prove controlled detector-to-GitHub alert delivery #2755.
• Confirm correct-repository bot issue/comment creation, actual inbox/phone notification and same-thread follow-up. API success alone is not phone-delivery proof.
• Merge and verify all route cutovers before retiring obsolete Slack integrations/credential copies; follow staged destructive-change and shared-credential handoff rules.

Dependencies and flow

Depends on the verified notification publisher/App path from the maintainer-conversation delivery issue. #2755 owns the controlled final detector-to-GitHub proof.

Priority: High. Effort: Large. This delivery is underway following the maintainer's direct request. #5291 and #5294 prepare the disabled publisher; route cutovers and the observed inbox/phone proof in #2755 remain required before transport retirement.

Evidence and reuse candidates

Current public alerting runbook, Flux Provider behavior, and Healthchecks GitHub Issues integration. The latter is a candidate for the off-cluster heartbeat, not proof that mentions, privacy or recovery behavior meet the migration requirements.

GitHub App convergence — maintainer direction 2026-10-09

Reuse the existing organization GitHub App first. Minimize the number of Apps supporting the development process; additional Apps require an evidenced limitation, not a separate App per workflow. Consolidate only after consumer-by-consumer verification, preserving least privilege and existing trust boundaries. This tracking update does not install, uninstall or change any App or credential.

GitHub installation-token scoping allows narrower repository and permission access than the App installation itself. Token isolation is preferred where it meets the requirement; it is not a claim that the current installation has been audited.