[kfab-cloud]

Summary

When GitLab refuses Project Access Token creation for permission reasons, prepareReviewPayload throws the intended repo-named Maintainer-role guidance, with no raw numeric project id. The dispatcher keeps classifying it as gitlab_project_access_required, failing the review, disabling Code Reviewer, and emailing the owner just as quickly as today. Failures that already classify as action-required are no longer reported to Sentry at error level from prepareReviewPayload. They are still logged, and unclassified failures are still captured.

Why

Sentry KILOCODE-WEB-1RFS (1373 lifetime occurrences, still happening) reports "Failed to create Project Access Token for GitLab code review on <repo>. Error: Cannot create bot token for project 34. You need Maintainer role or higher." from POST /api/webhooks/gitlab → tryDispatchPendingReviews → dispatchReservedReview → prepareReviewPayload. The cause is on the customer side: the connected GitLab credential does not have the Maintainer role, so GitLab returns 403 when we try to create a Project Access Token. The product already handles this. The dispatcher classifies the message as gitlab_project_access_required, fails the review, disables Code Reviewer, and emails the owner. Two code defect…

Planned changes

• Add a cause-aware helper (e.g. isGitLabProjectAccessTokenPermissionError) in apps/web/src/lib/integrations/platforms/gitlab/credential-errors.ts. It recognizes a direct GitLabProjectAccessTokenPermissionError, a TRPCError FORBIDDEN whose c…
• Use the helper in the prepare-review-payload.ts GitLab PrAT catch in place of the bare instanceof. Keep the reconnect check first. Change the thrown message to name only review.repo_full_name: no numeric project id, and no wrapped inner me…
• In the prepareReviewPayload outer catch, skip captureException when classifyCodeReviewActionRequiredFailure(getErrorMessage(error)) returns a reason. Keep the existing error log (or downgrade it to a warning that includes the reason) so th…
• Update and add unit tests in prepare-review-payload.test.ts and credential-errors tests (or the nearest existing test file).

Some details are abbreviated; see the full plan.

Full plan: https://github.com/Kilo-Org/cloud/blob/kfab/plan/planning-6d908b13-59ef-4fd1-b5b7-f218ce226aee/.plans/kfab/planning-6d908b13-59ef-4fd1-b5b7-f218ce226aee/plan.md

Source issue: #9109

Closes #9109

---

Factory-managed planning specification. This draft PR contains no product source and is not approval or implementation.