feat: Add check_run webhook support for CI failure auto-remediation

[knechtionscoding]

What type of PR is this?

/kind feature

What this PR does / why we need it:

Adds first-class support for CI/CD failure auto-remediation by teaching the
GitHub webhook path to understand check_run events. Previously check_run
events fell through to the generic default handler (only sender + action
extracted), and GitHubWebhookFilter had no way to filter by conclusion or
check name — so a CI auto-fix spawner would trigger on every completed check run
(pass or fail) and could not distinguish lint from test from build failures.

This PR makes the framework changes needed to build a spawner that watches for a
specific failing check and dispatches an agent to fix it, all additive and
backward-compatible:

• API (api/v1alpha2): two new optional fields on GitHubWebhookFilter:
  • conclusion — filters check_run events by conclusion (kubebuilder enum:
    success, failure, cancelled, timed_out, action_required,
    neutral, skipped, stale).
  • checkName — filters check_run events by check run name (exact match or
    glob, e.g. lint, build-*).
• Parsing (ParseGitHubWebhook): a *github.CheckRunEvent case that
  populates repository info, Title (check name), HeadSHA, URL, and the
  associated PR Branch/Number.
• Matching (matchesFilterWithoutFilePatterns): conclusion (exact) and
  checkName (glob) matching for check_run events.
• Templates (ExtractGitHubWorkItem): new CI-specific variables
  {{.CheckName}}, {{.Conclusion}}, {{.CheckRunURL}}, {{.HeadSHA}},
  {{.CheckApp}}.
• Reporting (webhookSourceKind): maps check_run to pull-request when
  the check is linked to a PR, so status reporting attaches to the PR.

go-github/v66 already provides github.CheckRunEvent, so no new dependency is
introduced.

Which issue(s) this PR is related to:

Fixes #946

Special notes for your reviewer:

• API version: the fields are added only to api/v1alpha2 (the current
  served/storage version). The issue text referenced api/v1alpha1, which
  predates the version bump; per project convention new API surface lands only
  in the latest version. Conversion is a JSON round-trip, so the new
  v1alpha2-only fields are dropped cleanly on down-conversion to v1alpha1
  (covered by TestTaskSpawnerConvert_CheckRunFilterFieldsDownConvert).
• Scope: limited to check_run. The godoc hints that workflow_run shares
  conclusion values, but that is intentionally left as a follow-up rather than
  adding speculative API.
• Shared type: GitHubWebhookFilter is used by both TaskSpawner and
  SessionSpawner, so the regenerated CRDs for both pick up the new fields.
• Overlap with New use case: CI-failure-driven agent remediation with check status filtering on githubPullRequests #809: New use case: CI-failure-driven agent remediation with check status filtering on githubPullRequests #809 proposes the same CI-remediation use case via a
  polling approach (checkConclusion/checkNames on the githubPullRequests
  source). This PR implements the webhook/push approach from New use case: CI/CD failure auto-remediation pipeline via check_run webhook events — with GitHubWebhookFilter extensions for conclusion-based filtering #946. If this is
  merged, New use case: CI-failure-driven agent remediation with check status filtering on githubPullRequests #809 should likely be closed as superseded.
• Tests: added check_run parsing, conclusion/checkName matching (including
  a positive happy-path case), event-type-not-allowed, template-variable
  extraction, and the conversion down-convert test. Docs
  (docs/reference.md) and a runnable example
  (examples/17-taskspawner-ci-remediation/) are included.
• Ran make verify and make test — both pass.

Does this PR introduce a user-facing change?

TaskSpawner/SessionSpawner `githubWebhook` filters now support `check_run` events: added `conclusion` and `checkName` filter fields and new template variables (`CheckName`, `Conclusion`, `CheckRunURL`, `HeadSHA`, `CheckApp`) for building CI-failure auto-remediation pipelines.

---

Summary by cubic

Adds first-class check_run webhook support to enable CI failure auto-remediation. Spawners can now target specific failing checks by conclusion and name with better context for templates and reporting.

• New Features
  • api/v1alpha2: add optional conclusion and checkName to GitHubWebhookFilter for check_run events (exact and glob match).
  • Parse check_run payloads to extract repo, check name (Title), HeadSHA, URL, and linked PR Branch/Number.
  • Match check_run events by conclusion (exact) and checkName (glob).
  • Expose template vars: CheckName, Conclusion, CheckRunURL, HeadSHA, CheckApp.
  • Map check_run to pull-request reporting when linked; regenerate CRDs; add docs/tests and an example (examples/17-taskspawner-ci-remediation) that names tasks by check run ID, removes excludeAuthors, and guards PR-less runs with index/if.

^{Written for commit d0f57bf. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 12 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[knechtionscoding]

@gjkim42 relatively small one, but ready for review

[gjkim42]

/kelos api-review

[kelos-bot]

🤖 Kelos Task Status

Task kelos-api-reviewer-issue-comment-2427726db04e has succeeded. ✅

[kelos-bot]

🤖 Kelos API Reviewer Agent @gjkim42

API Design Review

Verdict: REQUEST CHANGES
Scope: Adds v1alpha2 conclusion and checkName filters for GitHub check_run webhooks, plus check-run template and reporting context.

Findings

Compatibility

• [P0] internal/conversion/taskspawner_test.go:265 and internal/conversion/taskspawner.go:30 — The new test codifies dropping Conclusion and CheckName during down-conversion even though TaskSpawner v1alpha1 remains served. A client that reads and updates a v1alpha2 object through v1alpha1 will silently erase these filters, broadening a filter such as “failed lint check” to every completed check_run. Preserve the opaque v1alpha2-only filter data across the v1alpha1 round trip, following the existing nameTemplate preservation pattern, and test the complete v1alpha2 → v1alpha1 → v1alpha2 round trip.

Validation

• [P1] api/v1alpha2/taskspawner_types.go:482 — The conclusion enum omits startup_failure, which GitHub defines as a possible check suite or check run conclusion in CheckConclusionState. Because the CRD rejects values outside the enum, users cannot target these legitimate failures. Add startup_failure to the marker, godoc, reference/example documentation, generated CRDs, and matching tests.

Documentation

• [P2] api/v1alpha2/taskspawner_types.go:916 — The Branch, PromptTemplate, and NameTemplate godoc blocks explicitly enumerate GitHub webhook variables but omit CheckName, Conclusion, CheckRunURL, HeadSHA, and CheckApp, even though the example uses them in all three template surfaces. Update the three field comments (lines 916, 927, and 957) and regenerate the CRDs so the schema documentation matches the implemented contract.

Suggestions

• Define a named string type and documented constants for the conclusion enum instead of exposing it as an untyped string; this follows Kubernetes enum conventions and gives Go clients compile-time vocabulary for the supported values.

/kelos needs-input

[gjkim42]

Since it's alpha, we don't want to consider the droped fields by roundtrip.

[gjkim42]

/kelos review

[kelos-bot]

🤖 Kelos Task Status

Task kelos-reviewer-issue-comment-42e719ec1975 has succeeded. ✅

[kelos-bot]

🤖 Kelos Reviewer Agent @gjkim42

Review Summary

Verdict: REQUEST CHANGES
Overall correctness: patch is incorrect
Scope: Adds check_run webhook parsing, filtering, template variables, PR reporting context, generated CRDs, documentation, and a CI-remediation example.

Findings Overview

Priority	Count	File:Line	Summary
P0	0	—	none
P1	2	examples/17-taskspawner-ci-remediation/taskspawner.yaml:48	PR-only templates fail on valid check runs without linked PR metadata
P1	2	examples/17-taskspawner-ci-remediation/taskspawner.yaml:16	The example excludes the GitHub Actions sender modeled by this PR
P2	2	examples/17-taskspawner-ci-remediation/taskspawner.yaml:52	The Task name suppresses later check runs for the same PR and check
P2	2	internal/webhook/handler.go:886	The new reporting classification branch is untested
P3	0	—	none

Findings

Correctness

• [P1] examples/17-taskspawner-ci-remediation/taskspawner.yaml:48 — GitHub delivers check_run events for non-PR branch checks and documents that fork pushes can have an empty pull_requests array. In those valid cases ParseGitHubWebhook omits Branch and Number, but this manifest unconditionally renders both in branch, nameTemplate, and promptTemplate; missingkey=error makes Task construction fail and the handler return 500 for every matching delivery. Gate this workflow on PR association before rendering, or make the implementation and example safely handle check runs without linked PR metadata.
• [P1] examples/17-taskspawner-ci-remediation/taskspawner.yaml:16 — The PR's own checkRunPayload fixture models completed GitHub Actions checks with sender.login equal to github-actions[bot], while this manifest excludes that sender. Because spawner-level excludeAuthors runs before the conclusion and check-name filters, the advertised lint/test/build failures are rejected before a Task can be created. Remove this exclusion and use the explicit checkName filters to scope the intended checks.
• [P2] examples/17-taskspawner-ci-remediation/taskspawner.yaml:52 — ci-fix-{{.Number}}-{{.CheckName}} is identical for every run of the same check on a PR, so a later failure on another commit or rerun is silently deduplicated while the earlier Task exists, including its one-hour post-completion TTL. Include the check run's {{.ID}} in the name so redeliveries of one run collapse without suppressing distinct runs.

Tests

• [P2] internal/webhook/handler.go:886 — The new check_run reporting classification is not added to the existing TestWebhookSourceKind table, so the claimed PR-reporting behavior is unpinned. Add cases for a linked check run (Number > 0 → pull-request) and an unlinked check run (Number == 0 → issue).

Key takeaways

• Both independent review paths identified the example's sender exclusion as conflicting with its intended GitHub Actions workflow.