feat: Split oversized reports into multiple comments

[vovinacci]

A report bigger than the comment limit (GitHub 64 KiB, GitLab 1 MB) was cut at the limit, which lost the end of the report and left us with no hint that anything is missing (and usually broke the markdown too).

At times that heavily confused us and we had Atlantis as a good example of how it works nicely. So, now it is posted as several comments.

Behaviour for a report that fits in one comment does not change: the output is byte-identical to main (there is a test pinning that), and the placeholder comment is edited in place. Only the overflow is posted as new comments, each headed Kubechecks <identifier> Report (Part N of M). Every run posts its own comments; comments from earlier runs, including all parts of a split report, are hidden or deleted by TidyOutdatedComments as before.

How it splits: whole app sections first, then groups of checks, and only then the details of a single check, between lines. Fences and <details> open at a cut are closed and reopened in the next part, so every comment renders on its own. The comment at the top of pkg/msg/split.go walks through it.

Also in here:

• KUBECHECKS_MAX_COMMENTS_PER_CHECK, 1 to 999, default 999 (part numbers are budgeted for three digits). We see 20-30 comments on large changes in production without rate-limit trouble, a low default would truncate those.
• vcs.Client.UpdateMessage takes the PR, the note ID and the chunks; MaxCommentLength() is new; BuildComment takes an options struct.
• GitHub: a failed create is retried on rate limits only, a repeated create would post the chunk twice.
• The commit status is now set even if posting the comment fails. It used to stay pending although all checks had run.

Notes:

• Overflow comments are new comments, so subscribers get a notification for each of them.
• If posting fails part-way, the comments already posted stay, the last of them still saying "Continued in next comment".
• GitLab: checkReturnForBackoff treats every error except 429 as permanent. That was one call per report and is now one per comment, so a transient 5xx is more likely to cut a long report short. Happy to follow up separately.

Easiest order to review: pkg/vcs/types.go and the two clients, then pkg/msg (split.go first), then github_client/retry.go, which stands on its own.

Resolves #504.

[andridzi]

already tested, works perfectly!

[vovinacci]

@djeebus @Greyeye Small heads-up to review once you have some spare time.
Works for me and @andridzi like a charm.

[vovinacci]

@Greyeye @djeebus - a gentle nudge on this one. It continues to run without issue for us, and for @andridzi as well.

There has been no feedback so far, so I would like to ask for a decision either way.

To be explicit: "no, we do not want this" is a perfectly acceptable answer. We run it from a fork and can carry on doing so. I would simply prefer a clear decision to leaving the PR open indefinitely.

If the approach is the concern rather than the feature itself, I am happy to rework it - please point me at what you would like changed.

Many thanks.

[Copilot]

🟡 Changes recommended

A compile-blocking missing import and unresolved report-splitting correctness issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds provider-aware splitting of oversized GitHub/GitLab reports into multiple comments while preserving single-comment output.

Changes:

• Adds markdown-safe report chunking and comment limits.
• Updates VCS clients with chunk posting and retries.
• Adds configuration, tests, mocks, documentation, and CLI wiring.

File summaries

File	Description
pkg/vcs/types.go	Extends the VCS client contract.
pkg/vcs/gitlab_client/message.go	Posts GitLab report chunks.
pkg/vcs/gitlab_client/message_test.go	Tests GitLab chunk posting.
pkg/vcs/github_client/retry.go	Adds GitHub retry handling.
pkg/vcs/github_client/retry_test.go	Tests retry behavior.
pkg/vcs/github_client/message.go	Posts GitHub report chunks.
pkg/vcs/github_client/message_test.go	Tests GitHub posting behavior.
pkg/vcs/github_client/client.go	Adds comment retry configuration.
pkg/vcs/github_client/archive.go	Clarifies retry documentation.
pkg/utils.go	Defines the comment-count limit.
pkg/msg/split.go	Implements report chunking and markdown repair.
pkg/msg/split_test.go	Tests splitting behavior.
pkg/msg/message.go	Builds bounded report chunks.
pkg/msg/message_test.go	Tests report-building behavior.
pkg/events/check.go	Wires chunking and status handling.
pkg/config/config.go	Adds configuration and validation.
pkg/config/config_test.go	Tests configuration handling.
mocks/vcs/mocks/mock_MockClient.go	Updates generated VCS mocks.
docs/usage.md	Documents the new environment variable.
cmd/root.go	Adds the CLI configuration flag.

Review details

Files not reviewed (1)

• mocks/vcs/mocks/mock_MockClient.go: Generated file

Suppressed comments (2)

pkg/msg/message.go:323

• The parser documentation says tags inside inline code and indented code are plain text, but this scan recognizes <details> anywhere in the line. A literal `<details>` in check output will therefore mutate s.details; after a cut, the generated close/reopen tags can hide or restructure the following content. Track code spans/indented blocks or restrict tag detection before updating the details stack.

		case strings.HasPrefix(rest, "<details>"), strings.HasPrefix(rest, "<details "):
			s.details = append(s.details, openDetails{})
		case strings.HasPrefix(rest, "</details>") && len(s.details) > 0:
			s.details = s.details[:len(s.details)-1]
		}

pkg/msg/message.go:421

• When a details line exceeds the remaining budget, this branch replaces it with a truncated prefix and then advances to the next input line, discarding the unconsumed suffix. Minified JSON or a long diff line therefore still loses report content—the failure mode this change is intended to eliminate. Carry the remainder into the next part (while preserving the markdown state) instead of dropping it.

		for room := maxLen - buf.Len() - after.closerLen(); len(line) > room; room = maxLen - buf.Len() - after.closerLen() {
			if room < len(lineTruncated) {
				line = lineTruncated
				after = state
				break

• Files reviewed: 19/20 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[vovinacci]

slices.Clone lives in message.go, which imports it. split.go does not use it.