docs: simplify plugin URL references, link to shared docs

[jonkoops]

Replaces the duplicated ref:// and {{inherit}} documentation with a link to the canonical reference in the rhdh repo. Removes the outdated behavioral difference note, as the init container now supports ref:// as well. Keeps the operator-specific ConfigMap merge behavior note.

Depends on redhat-developer/rhdh#5204.

RHIDP-15876

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rhdh-qodo-merge]

PR Summary by Qodo

Docs: link plugin URL references to canonical RHDH docs

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Replace duplicated ref:// / {{inherit}} docs with a canonical RHDH link.
• Drop outdated init-container behavior difference note; keep operator merge behavior note.

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep mirrored docs in this repo

• ➕ Docs stay self-contained and readable offline/without GitHub access
• ➕ No dependency on external anchors/URLs remaining stable
• ➖ High risk of drift from the canonical RHDH behavior and examples
• ➖ Requires ongoing maintenance across repos for the same content

2. Auto-sync canonical docs (subtree/CI sync job)

• ➕ Self-contained docs while staying consistent with canonical source
• ➕ Reduces manual duplication and drift
• ➖ Adds CI/release process complexity and potential merge conflicts
• ➖ Still needs governance for when/what gets synced

Recommendation: Linking to the canonical RHDH documentation is the best trade-off here: it removes duplication and eliminates doc drift with minimal process overhead. If offline/self-contained docs become a strong requirement later, consider an automated sync approach rather than reintroducing manual duplication.

Files changed (1) +2 / -31

Documentation (1) +2 / -31

dynamic-plugins.mdReplace local plugin reference docs with canonical link +2/-31

Replace local plugin reference docs with canonical link

• Replaces the in-repo explanation and YAML examples for 'ref://' and ':{{inherit}}' with a link to the canonical "Plugin References" section in the RHDH repository. Removes the now-outdated note about a behavioral difference with the init container, while retaining the operator-specific note about resolving references during ConfigMap merge and failing reconciliation on unresolved references.

docs/dynamic-plugins.md

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

✅ Compliance rules (platform): 18 rules

✅ Cross-repo context

  ⚠️ Failed to retrieve: redhat-developer/rhdh

  Not relevant to this PR: redhat-developer/rhdh-plugins

1. Unconditional reference-resolution claim 🐞 Bug ≡ Correctness

Description

docs/dynamic-plugins.md states the operator resolves all plugin URL references during ConfigMap
merge and fails reconciliation on unresolved references, but the implementation only performs that
resolution when OPERATOR_DP_PROCESSING is enabled (default false) and the shipped install manifest
does not set it. This can mislead users into expecting operator-side validation/resolution in
default installs where the operator will instead pass references through unmodified.

Code

docs/dynamic-plugins.md[102]

+**Operator-specific behavior:** The operator resolves all references during ConfigMap merge (before passing to the init container). If a reference cannot be resolved, the operator returns an error and the Backstage CR will not reconcile.

Relevance

● Weak

Similar doc-mismatch/gating clarification suggestion was definitely_rejected in PR #3215 for same
section.

PR-#3215

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The docs assert operator-side resolution during merge, but the code only resolves when
OPERATOR_DP_PROCESSING is true (default false). The default installation manifest’s manager env
section does not set OPERATOR_DP_PROCESSING, so in default installs the operator will not resolve
references during merge as the docs imply.

docs/dynamic-plugins.md[98-103]
pkg/model/dynamic-plugins.go[74-76]
pkg/model/dynamic-plugins.go[313-320]
dist/rhdh/install.yaml[4026-4045]
config/profile/rhdh/patches/deployment-patch.yaml[18-31]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The docs claim the operator resolves plugin URL references during ConfigMap merge unconditionally, but code only does this when `OPERATOR_DP_PROCESSING=true` (and the default install manifests do not set it). This should be documented to avoid misleading users about when operator-side resolution/validation happens.

### Issue Context
Reference resolution in `MergePluginsData()` is guarded by `IsOperatorDPProcessing()` with a default of `false`, and the generated `dist/rhdh/install.yaml` manager container env does not include `OPERATOR_DP_PROCESSING`.

### Fix Focus Areas
- docs/dynamic-plugins.md[98-103]
- pkg/model/dynamic-plugins.go[74-76]
- pkg/model/dynamic-plugins.go[313-320]
- dist/rhdh/install.yaml[4026-4045]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}