feat(backport-legacy-split): announce a failed backport on the source PR

[vcauesantos]

Summary

A failed legacy backport said nothing. The summary comment is built after both halves run, so any exit before that skipped it, and the only trace was a red check on a PR that is normally already merged by then. A target that never got a backport was indistinguishable from one that never needed one.

This posts a comment on the source PR when a backport fails:

⚠️ Backport to v0.34 failed — action required

The automation did not complete for v0.34. See the failed run to decide whether to retry or backport manually.

Already opened for this target: loft-sh/vcluster#4146

How backporting works

The job still fails. This only makes it say so where the author will see it.

What this deliberately does not do

An earlier version of this branch dropped the paths that don't exist on the legacy branch and opened a partial backport as a draft. That is removed. The objection raised in review holds: a partial backport risks a regression on the release branch, because an incomplete PR reads as a complete one and a green partial can be merged as though nothing were missing.

The all-or-nothing apply is unchanged. This PR only adds reporting.

Design notes

• Generic on purpose. Identical wording whether a path is missing on the legacy branch, a patch conflicts, or a clone or push fails. The run log stays the single place detail lives, so the comment can't go stale against a failure mode nobody has hit yet.
• "Action required", not "manual PR needed". Only the run can tell a retryable clone or push failure from one needing a hand-written backport.
• It names any PR already opened. A mixed backport opens the OSS PR before the pro half runs, so a failure does not imply nothing was created. Claiming otherwise would send someone to duplicate it — and that half-done state is exactly what DEVOPS-1438 reports.
• Same sticky marker as the success body, so a re-run that succeeds replaces the failure notice in place rather than stacking a contradictory pair.
• !cancelled() on the comment steps instead of the default success(). Without it the step is skipped on exactly the runs that need it.
• Emitted via an EXIT trap so every failure path is covered, not just the one that prompted this.
• The docs link is a docs-url input, not a constant. This action is shared with the public OSS mirror, so an internal link must never be assumed; the line is omitted when a caller sets nothing.

Test plan

• make test-backport-legacy-split — 37/37 pass (31 before, 6 added).
  • A half that can't apply emits a failure body and still exits non-zero.
  • A PR opened before the failure is named, not denied.
  • Identical wording for an unappliable patch and for a clone failure.
  • Run URL used when the Actions env is present, plain-wording fallback when not.
  • A successful run posts its normal body and never the failure one.
  • Every failure test was confirmed to fail against main and pass with the change.
• shellcheck clean, make lint (actionlint + zizmor) no findings, make check-docs no drift.
• Run both with and without the Actions env set, since the suite runs inside Actions and run.sh reads those variables.

Required follow-up

The gate lives in the reusable workflow, so callers pinning it by SHA need that pin advanced before this takes effect. The action tag alone does not carry it:

• vcluster-pro (the only legacy-split: true caller, so the one that matters here)
• vcluster and loft-enterprise pin the same workflow and are already on different SHAs

The same caller PR should set the docs link:

docs-url: https://app.notion.com/p/loftsh/Managing-Patch-Releases-35710940806980a2b080de7f3adb0d27

Closes DEVOPS-1438

[vcauesantos]

/vcluster-review

[vcluster-pr-approver]

🔍 The agent swarm is reviewing PR #242. I'll post the results here when it's done.

Admins can watch the run live

[vcluster-pr-approver]

@vcauesantos ✅ Review finished for #242

View the session