Feature or Permissions Toggle: Disable manual approval flows (UI) during drag/drop + freight selection

[etetar]

Checklist

• [x] I've searched the issue queue to verify this is not a duplicate feature request.
• [x] I've pasted the output of kargo version, if applicable.
• [x] I've pasted logs, if applicable.

Proposed Feature

Add the ability to hide/disable manual approval flows in the UI based on user permissions or configuration.

Specific Capabilities

1. Prevent drag-and-drop of ineligible (unverified/unpromoted upstream) freight to ineligible stages
2. Disable manual freight selection for ineligible freight (those displaying a warning icon)

Implementation Approach

Recommended approach: Tie these restrictions to the freights/status permission. Users without this permission would have no access to manual approval workflows in the UI.

Alternative approaches:

• Configuration toggles at the Stage level
• Configuration toggles at the Warehouse/Freight level
• Configuration toggles at the Project level

Note: Configuration-based approaches may be more complex to implement or less practical, as few admins would want to fully disable manual approvals (for all users).

Motivation

Current Behavior

As of version 1.8.0, two new UI features allow users to initiate promotions of ineligible freight:

1. Drag-and-drop: Users can drag ineligible freight to ineligible stages with no visual indication that the freight is ineligible during the drag operation
2. Manual freight selection: Users can click "Select" on freight objects marked with a warning icon

Both actions trigger a manual approval dialog:

Currently, the system properly enforces permissions—users without freights/status permissions receive an error when clicking "Approve" in the dialog, preventing unauthorized manual approvals.

The Problem

While the permission enforcement works correctly, the UI allows users to initiate workflows they can never complete, leading to:

1. User confusion: Users without approval permissions can drag freight and open the manual promotion dialog, only to be denied when they click "Approve"
2. UI clutter: During manual freight selection, ineligible freight objects (with warning icons) are visible and clickable even when the user will never be able to approve them
3. Poor user experience: There's no indication during drag-and-drop that freight is ineligible for the target stage

Use Case

In many production environments, the majority of users should never be allowed to bypass verifications or perform manual approvals. For these users, the current UI presents options they cannot use, creating unnecessary confusion and friction.

Desired Outcome

Users without manual approval permissions should have a cleaner, more intuitive experience:

• Cannot drag ineligible freight to ineligible stages
• Cannot click "Promote" on freight objects with warning indicators, or even see this option

[krancour]

I'm pinning this because a lot of people have brought this up and I don't want lots of duplicate issues. Also my response is a general one informed by multiple discussions about this and not only based on @etetar's proposal above.

First, for anyone who may not have known, manual approval isn't a new feature. Drag and drop is a new feature, and thus also is the manual approval dialog that appears when attempting to promote Freight to a Stage for which it is currently unavailable. It is possible that some people who were previously unaware of the manual approval feature have just learned about it for the first time because of this new dialog.

The design choice to implement this dialog was a workaround. In an ideal world, we'd have liked to "gray out" any Stage to which the Freight you're dragging is not currently available. We were not able to do so at this time. Determining the availability of a single piece of Freight to a single, specific Stage is already quite a complicated "query." (In actuality, it's nothing as straightforward as a database query, for instance. There's quite a bit of complex logic involved.) Ascertaining the availability of a piece of Freight to every Stage is, unfortunately, that same complexity x n, and in most cases cannot (yet) be accomplished quickly enough as to be adequately responsive when you start dragging a piece of Freight. It's easy to imagine what a poor(er) UX it would be if you started to drag a piece of Freight and seconds went by before the DAG was updated in any way that reflected whether that Freight is or is not available to each Stage. Our choices were:

1. Don't implement drag and drop (yet?).

2. Allow dropping Freight on any Stage and show an error if availability criteria are not met.

3. Allow dropping Freight on any Stage and pop up an approval dialog if availability criteria are not met.

Of the three choices, the third was the least objectionable.

With the background out of the way, here is where we currently stand with this:

1. The UX can, no doubt, be improved upon and we intend to so.

2. We'd like to figure out how to determine availability more quickly so we can gray out any Stage to which the Freight currently being dragged is not available, like we'd originally wanted. To be transparent, doing so will probably take us quite some time.

3. Even after solving no.2, I don't think this dialog is likely to go away. I think the more likely scenario is that you can still drop Freight onto grayed out Stages, but you'll be met with this dialog. It will, at least, be less of a surprise.

4. There are other places in the UI where you can somehow attempt promotion of Freight to a Stage where that Freight is unavailable. In those spots, an error is currently displayed. We're actually likely to add the dialog to those spots as well, because it's a better UX than the error.

Another aspect of this, separate from the UX aspects: Some who have raised this issue, like @etetar, have framed it as a permissions issue, so I want to elaborate a little bit on why the manual approval feature exists in the first place, its nature, and how to use it effectively.

It exists mainly for "hotfixes." In urgent scenarios, it is possible you cannot wait for Freight containing a new, critical fix to traverse the length of your pipeline. Manual approval was intended as a way to bypass a segment of the pipeline and "fast forward" to a given Stage. Another way to think of it is as "force promote," and it was intended to be used sparingly.

Who can approve Freight for a given Stage? It is currently gated by the same permission required to promote to that same Stage. I believe this was, at least initially, a sensible implementation choice. To the extent that manual approval is tantamount to "force promoting," I believe it's a capability most appropriately entrusted to those entrusted to promote.

I can see the perspective where "force promoting" might be seen as a special / more powerful capability, and I can appreciate why that might drive some to want it gated by its own distinct permission. I would also challenge that notion by inverting it and bringing specific Stages into the conversation. If I don't trust a user to "force promote" to Stage X, I don't trust them to promote to Stage X at all. But I do believe there's room for some more discussion around this aspect of things. Any change here would be breaking, however, so please understand the bar for justifying it is going to be high.

[etetar]

@krancour would it be relatively simple to start with a stage-based configuration option to disable manual approvals for specific stages?

I'm not sure if there is an existing way to set configs like that, but perhaps it could be a custom annotation on the stage? Something like: kargo.akuity.io/disable-manual-approval: true. When this is true, then any of the flows to manually approve freight on that stage would be disabled (drag 'n' drop, warning icon manual freight selection, or the pre-1.8 manual approval flow).

Perhaps this could be a short-term option while a more comprehensive solution (around new permission options or freight/stage status) is designed. By the way, I'm not suggesting the stage config would be a "temporary" fix, as it seems like it would be a useful hard disable to have going forward.

---

Re: the permissions around "force promoting".

We are currently preventing anyone but system admins from doing force promotes by excluding the freights/status patch rule from all pipeline user Roles. This is mainly because we currently have a separate pipeline for "hotfix" type flows, but even if we were to move that to the main pipeline, we would still only want to allow force promotions to the "staging" environment to prevent completely broken or unverified artifacts from going directly to prod.