Workspace update workflow should warn when appending new plugins to existing workspaces

What happened

The daily update-plugins-repo-refs workflow created PR #3252 on 2026-08-12, updating the ai-integrations workspace to upstream commit 6a0c7f7. The upstream diff introduced 3 new plugins. The workflow's merge logic in rhdh-plugin-export-utils/update-overlay/create-pr-if-necessary.js detected these as new entries and appended them to plugins-list.yaml as bare path: lines without any CLI arguments.

When /publish ran (run 31603258340), all 3 new plugins failed with: "Following shared package(s) should not be part of the plugin private dependencies: @backstage/catalog-model, @backstage/errors, @backstage/types." These plugins required --embed-package flags that the workflow had no mechanism to generate or warn about.

The PR was ultimately closed and replaced by issue #3257 + PR #3260, where the code agent added proper --embed-package flags per detailed human instructions. Total time from auto-PR creation to working merge: ~7.5 hours.

The workflow currently differentiates new workspace additions (workspace-addition label) from updates (workspace-update label), but it does NOT distinguish between a simple ref bump on an existing workspace and a ref bump that also adds new plugins to plugins-list.yaml. Both get the generic workspace-update label.

What could go better

When the merge logic appends new plugin entries to an existing workspace's plugins-list.yaml, the PR should clearly surface this to reviewers. Currently, a ref-only update and a ref-update-with-new-plugins look identical from the label/title perspective. The PR body for new workspace additions already includes guidance text about completing export configuration, but this guidance is absent when new plugins are added to an existing workspace.

This is a high-confidence finding: the merge logic already tracks which lines are new vs existing (lines 135-163 of create-pr-if-necessary.js), so it has the data to generate a warning. The implementation effort is low — it requires emitting a list of newly-appended plugins into the PR body and optionally applying a distinct label.

I am less confident about whether the workflow should attempt to auto-detect --embed-package requirements, as that would require dependency tree analysis (cloning the upstream repo, running install, parsing the dep graph). A warning is simpler and sufficient — the human or code agent can then add the appropriate flags.

Proposed change

Modify the update-plugins-repo-refs workflow (specifically the merge logic in the reusable workflow from rhdh-plugin-export-utils) to:

1. Track newly-appended plugin entries during the plugins-list.yaml merge step. The logic already compares existing lines against discovered lines — capture the list of lines that are appended (new plugins not in the existing file).

2. Add a warning section to the PR body when new plugins are appended, listing the new plugin paths and noting: "These new plugins were added without CLI arguments. They may require --embed-package flags if they depend on Backstage shared packages transitively. Run /publish to validate, and add --embed-package <package> entries if the export fails with shared-package errors."

3. Apply a new-plugins-added label (or similar) in the label-mandatory-workspace-prs workflow when the PR diff shows new entries in plugins-list.yaml. This is distinct from workspace-addition (new workspace) and workspace-update (any change to existing workspace).

Since the core logic lives in redhat-developer/rhdh-plugin-export-utils, the implementation may require a coordinated change there. File this issue in the overlays repo as a feature request and coordinate with the export-utils maintainers.

Validation criteria

The next auto-update PR that adds new plugins to an existing workspace's plugins-list.yaml should: (1) include a warning section in the PR body listing the newly-added plugins and mentioning --embed-package, and (2) carry a label distinguishing it from a simple ref update. Verify against the next 3 workspace update PRs that introduce new plugins — all should have the warning. A PR that only bumps source.json without new plugin entries should NOT get the warning or label.

Generated by retro agent from https://github.com/redhat-developer/rhdh-plugin-export-overlays/pull/3252

Start with rhdh-plugin-export-utils/update-overlay/create-pr-if-necessary.js, especially the merge logic around lines 135-163, then inspect the label-mandatory-workspace-prs workflow. Trace how update PR bodies and labels are assembled, and verify that a workspace update adding plugins gets the warning and label while a source.json-only bump does not.