[release-1.9-post-cqa] [RHDHBUGS-2802]: Remove !<plugin-name> suffixes from OCI artifact paths (#1994)

openshift-cherrypick-robot · themr0c · claude · web-flow · commit d3a37e8b4d9a · 2026-04-01T19:23:31.000+02:00
Co-authored-by: Fabrice Flore-Thébault &lt;ffloreth@redhat.com&gt;
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/assemblies/extend_installing-and-viewing-plugins-in-rhdh/assembly-install-plugins-from-oci-registries-by-using-custom-certificates.adoc b/assemblies/extend_installing-and-viewing-plugins-in-rhdh/assembly-install-plugins-from-oci-registries-by-using-custom-certificates.adoc
@@ -16,7 +16,7 @@ includes:
 
 plugins:
 - disabled: false
-  package: oci://reg.example.com:5000/myplugin:v0.0.1!backstage-plugin-myplugin
+  package: oci://reg.example.com:5000/myplugin:v0.0.1
 ----
 
 == Prerequisites
diff --git a/modules/configure_configuring-rhdh/proc-configure-the-dynamic-plugins-cache.adoc b/modules/configure_configuring-rhdh/proc-configure-the-dynamic-plugins-cache.adoc
@@ -24,7 +24,7 @@ Example `dynamic-plugins.yaml` file configuration to download the remote artifac
 plugins:
   - disabled: false
     pullPolicy: Always
-    package: 'oci://quay.io/example-org/example-plugin:v1.0.0!internal-backstage-plugin-example'
+    package: 'oci://quay.io/example-org/example-plugin:v1.0.0'
 ----
 
 `forceDownload: false` (default)::
diff --git a/modules/extend_dynamic-plugins-reference/rhdh-supported-plugins.sh b/modules/extend_dynamic-plugins-reference/rhdh-supported-plugins.sh
@@ -641,9 +641,9 @@ generate_migration_table() {
             old_path="./dynamic-plugins/dist/${plugin_name}"
 
             # Extract new path - get the base URL without the version/integrity part
-            # Format: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-jenkins:bs_1.45.3__0.26.0!backstage-community-plugin-jenkins
+            # Format: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-jenkins:bs_1.45.3__0.26.0
             # We want: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-jenkins:<tag>
-            # First remove everything after the ! (integrity hash), then remove the tag to get base
+            # Remove the tag to get the base path
             artifact_without_hash="${dynamic_artifact%%!*}"
             new_path_base="${artifact_without_hash%:*}"
             new_path="${new_path_base}:<tag>"
diff --git a/modules/integrate_accelerating-ai-development-with-openshift-ai-connector-for-rhdh/proc-set-up-with.adoc b/modules/integrate_accelerating-ai-development-with-openshift-ai-connector-for-rhdh/proc-set-up-with.adoc
@@ -168,9 +168,9 @@ The {product-very-short} Pod requires two dynamic plugins.
 ----
 plugins:
   - disabled: false
-    package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog:bs_1.42.5__0.7.0!red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog
+    package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog:bs_1.42.5__0.7.0
   - disabled: false
-    package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend:bs_1.42.5__0.3.0!red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend
+    package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend:bs_1.42.5__0.3.0
 ----
 
 . Add the `Connector` sidecar containers to the {product-very-short} Pod.
diff --git a/modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc b/modules/integrate_interacting-with-model-context-protocol-tools-for-rhdh/proc-verify-successful-installation-of-mcp-plugins.adoc
@@ -28,16 +28,16 @@ $ oc logs -c install-dynamic-plugins deployment/<my-product-deployment>
 [source]
 ----
 ..... prior logs ....
-======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend
+======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2
 	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:next__0.2.0 to local filesystem
-	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2!backstage-plugin-mcp-actions-backend
+	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-plugin-mcp-actions-backend:bs_1.42.5__0.1.2
 ----
 . You must see entries for any of the MCP tool plugins you installed as shown in the following code:
 +
 [source]
 ----
 ..... prior logs ....
-======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
-	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool to local filesystem
-	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3!red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool
+======= Installing dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3
+	==> Copying image oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3 to local filesystem
+	==> Successfully installed dynamic plugin oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-software-catalog-mcp-tool:bs_1.42.5__0.2.3
 ----
diff --git a/modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc b/modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc
@@ -20,7 +20,7 @@ You can add the aggregated Scorecard widget to a customizable {product-very-shor
 [source,yaml]
 ----
 plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5
     disabled: false
     pluginConfig:
       dynamicPlugins:
diff --git a/modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc b/modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc
@@ -21,7 +21,7 @@ You can add the aggregated Scorecard widget to a read-only {product-very-short}
 [source,yaml]
 ----
 plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5
     disabled: false
     pluginConfig:
       dynamicPlugins:
diff --git a/modules/observability_evaluate-project-health-using-scorecards/proc-enable-scorecards.adoc b/modules/observability_evaluate-project-health-using-scorecards/proc-enable-scorecards.adoc
@@ -17,7 +17,7 @@ To monitor component health and quality in {product-very-short}, you must enable
 [source,yaml]
 ----
 plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard:bs_1.45.3__2.3.5
     disabled: false
     pluginConfig:
       dynamicPlugins:
@@ -36,6 +36,6 @@ plugins:
                   if:
                     allOf:
                       - isKind: component
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend:bs_1.45.3__2.3.5
     disabled: false
 ----
diff --git a/modules/observability_evaluate-project-health-using-scorecards/proc-integrate-github-health-metrics-using-scorecards.adoc b/modules/observability_evaluate-project-health-using-scorecards/proc-integrate-github-health-metrics-using-scorecards.adoc
@@ -88,7 +88,7 @@ integrations:
 [source,yaml]
 ----
 plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-github:bs_1.45.3__2.3.5
     disabled: false
 ----
 
diff --git a/modules/observability_evaluate-project-health-using-scorecards/proc-integrate-jira-health-metrics-using-scorecards.adoc b/modules/observability_evaluate-project-health-using-scorecards/proc-integrate-jira-health-metrics-using-scorecards.adoc
@@ -43,7 +43,7 @@ You must use the proxy setup to ensure configuration compatibility if you also u
 [source,yaml]
 ----
 plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5
     disabled: false
 ----
 ... In your {product-very-short} `{my-app-config-file}` file, add the following direct setup settings:
@@ -67,7 +67,7 @@ where:
 [source,yaml]
 ----
 plugins:
-  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5!red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-scorecard-backend-module-jira:bs_1.45.3__2.3.5
     disabled: false
 ----
 
diff --git a/modules/shared/con-dynamic-plugins.adoc b/modules/shared/con-dynamic-plugins.adoc
@@ -12,7 +12,7 @@ With dynamic plugins, instead of modifying the {backstage} application itself, y
 [source,yaml]
 ----
 plugins:
-  - package: oci://quay.io/account-name/image-name:tag!plugin-name
+  - package: oci://quay.io/account-name/image-name:tag
     disabled: false
     pluginConfig: {}
 ----
diff --git a/modules/shared/proc-add-a-custom-dynamic-plugin-to-rhdh.adoc b/modules/shared/proc-add-a-custom-dynamic-plugin-to-rhdh.adoc
@@ -12,9 +12,9 @@ Use this procedure to add custom dynamic plugins to {product} by updating the dy
 [source,yaml]
 ----
 plugins:
-  - package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0!backstage-community-plugin-entity-feedback
+  - package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0
     disabled: false
-  - package: oci://quay.io/_<user_name>_/entity-feedback-plugin-backend:0.6.0!backstage-community-plugin-entity-feedback-backend
+  - package: oci://quay.io/_<user_name>_/entity-feedback-plugin-backend:0.6.0
     disabled: false
 ----
 +
diff --git a/modules/shared/proc-add-a-dynamic-plugin-to-rhdh.adoc b/modules/shared/proc-add-a-dynamic-plugin-to-rhdh.adoc
@@ -9,7 +9,7 @@ To add a custom dynamic plugin to {product}, update the `dynamic-plugins.yaml` f
 [source,yaml,subs="+attributes,+quotes"]
 ----
 plugins:
-  - package: oci://quay.io/_<account-name>_/_<image-name>_:_<tag>_!_<plugin-name>_
+  - package: oci://quay.io/_<account-name>_/_<image-name>_:_<tag>_
     disabled: false
     pluginConfig: {}
 ----
@@ -29,7 +29,7 @@ The following example integrates a plugin named `simple-example` with {product-v
 ----
 plugins:
   # Option 1: Load from an OCI image
-  - package: oci://quay.io/<namespace>/simple-example:v0.1.0!backstage-plugin-simple-example
+  - package: oci://quay.io/<namespace>/simple-example:v0.1.0
     disabled: false
     pluginConfig:
       dynamicPlugins:
diff --git a/modules/shared/proc-configure-front-end-plugin-wiring.adoc b/modules/shared/proc-configure-front-end-plugin-wiring.adoc
@@ -23,7 +23,7 @@ This configuration determines how the plugin is integrated with the {product-ver
 ----
 plugins:
   # Option 1: Load from an OCI image
-  - package: oci://quay.io/<namespace>/simple-example:v0.1.0!backstage-plugin-simple-example
+  - package: oci://quay.io/<namespace>/simple-example:v0.1.0
     disabled: false
     pluginConfig:
       dynamicPlugins:
diff --git a/modules/shared/proc-display-the-front-end-plugin.adoc b/modules/shared/proc-display-the-front-end-plugin.adoc
@@ -12,7 +12,7 @@ Use this procedure to configure and display a front-end plugin in the {product}
 .`dynamic-plugins.yaml` file fragment
 [source,yaml]
 ----
-- package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0!backstage-community-plugin-entity-feedback
+- package: oci://quay.io/_<user_name>_/entity-feedback-plugin:0.5.0
   disabled: false
   pluginConfig:
     dynamicPlugins:
diff --git a/modules/shared/proc-install-and-configure-a-third-party-techdocs-add-on.adoc b/modules/shared/proc-install-and-configure-a-third-party-techdocs-add-on.adoc
@@ -61,7 +61,7 @@ $ docker push quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
 [source,yaml,subs="+quotes,+attributes"]
 ----
 plugins:
-      - package: oci://quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest!_<techdocs_add-on_package>_
+      - package: oci://quay.io/_<user_name>_/_<techdocs_add-on_image>_:latest
         disabled: false
         pluginConfig:
           dynamicPlugins:
diff --git a/modules/shared/proc-load-a-plugin-packaged-as-an-oci-image.adoc b/modules/shared/proc-load-a-plugin-packaged-as-an-oci-image.adoc
@@ -37,29 +37,7 @@ oc create secret generic _<secret_name>_ --from-file=auth.json=${XDG_RUNTIME_DIR
 
 . Define the plugin with the `oci://` prefix by using one of the following formats in your `dynamic-plugins.yaml` file:
 
-Standard explicit definition:: Use the format `oci://<image_name>:<tag>!<plugin_path>`, as shown in the following example:
-+
-Example configuration in `dynamic-plugins.yaml` file:
-+
-[source,yaml]
-----
-plugins:
-  - disabled: false
-    package: oci://quay.io/example/image:v0.0.1!backstage-plugin-myplugin
-----
-
-Using image digests:: To perform an integrity check, use the image digest in place of the tag in the `dynamic-plugins.yaml` file as shown in the following example:
-+
-Example configuration in `dynamic-plugins.yaml` file:
-+
-[source,yaml]
-----
-plugins:
-  - disabled: false
-    package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc!backstage-plugin-myplugin
-----
-
-Using path auto-detection:: If the OCI image has only a single plugin, you can omit the path after the exclamation point. The installation program automatically extracts the path from the image metadata, as shown in the following example:
+Standard definition:: Use the format `oci://<image_name>:<tag>`, as shown in the following example. The installation program automatically extracts the plugin path from the image metadata.
 +
 Example configuration in `dynamic-plugins.yaml` file:
 +
@@ -73,39 +51,22 @@ plugins:
 [NOTE]
 ====
 You must package images with the `@red-hat-developer-hub/cli` to ensure the system applies the `io.backstage.dynamic-packages` annotation.
+
+You must define exactly one plugin from that OCI image in the configuration files. The system returns an error if the configuration files contain many plugins or no matching plugins.
 ====
 
-Using version inheritance:: To inherit a version from a base configuration file, for example, `dynamic-plugins.default.yaml`, use the `{{inherit}}` placeholder to inherit the `v0.0.2` tag, as shown in the following example:
-+
-Example configuration in `dynamic-plugins.default.yaml` file:
-+
-[default-source,yaml]
-----
-plugins:
-  - disabled: false
-    package: oci://quay.io/example/image:v0.0.2!backstage-plugin-myplugin
-----
+Using image digests:: To perform an integrity check, use the image digest in place of the tag in the `dynamic-plugins.yaml` file as shown in the following example:
 +
 Example configuration in `dynamic-plugins.yaml` file:
 +
 [source,yaml]
 ----
-includes:
-  - dynamic-plugins.default.yaml
 plugins:
   - disabled: false
-    package: oci://quay.io/example/image:{{inherit}}!backstage-plugin-myplugin
+    package: oci://quay.io/example/image@sha256:28036abec4dffc714394e4ee433f16a59493db8017795049c831be41c02eb5dc
 ----
-+
-[NOTE]
-====
-An error occurs if you use `{{inherit}}` in the includes file itself or if no matching plugin key exists in the base configuration.
-====
 
-Combining version inheritance with path omission::
-When using `{{inherit}}` for version inheritance, you can also use the plugin path auto-detection feature by omitting the plugin path entirely. Use this approach when the base configuration in included files already has an explicit path or uses auto-detection itself.
-+
-For example, if the plugin in the included file uses auto-detection that resolves to `oci://quay.io/example/image:v0.0.2!example-path`, and you use `{{inherit}}` without a path, it will inherit both the version `v0.0.2` and the plugin path `example-path`.
+Using version inheritance:: To inherit a version from a base configuration file, for example, `dynamic-plugins.default.yaml`, use the `{{inherit}}` placeholder to inherit the `v0.0.2` tag, as shown in the following example:
 +
 Example configuration in `dynamic-plugins.default.yaml` file:
 +
@@ -129,7 +90,7 @@ plugins:
 +
 [NOTE]
 ====
-You must define exactly one plugin from that OCI image in the configuration files. The system returns an error if the configuration files contain many plugins or no matching plugins.
+An error occurs if you use `{{inherit}}` in the includes file itself or if no matching plugin key exists in the base configuration.
 ====
 
 . To apply the changes, restart the {product-very-short} application.
diff --git a/modules/shared/proc-mirror-plugins-from-a-file.adoc b/modules/shared/proc-mirror-plugins-from-a-file.adoc
@@ -13,9 +13,9 @@ Example `plugins.txt` file:
 +
 [source,text]
 ----
-oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1!backstage-community-plugin-quay
-oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1!backstage-community-plugin-github-actions
-oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-azure-devops:1.8.0--0.8.2!backstage-community-plugin-azure-devops
+oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1
+oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1
+oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-azure-devops:1.8.0--0.8.2
 ----
 . Download the mirroring script:
 +
diff --git a/modules/shared/proc-mirror-specific-plugins-by-direct-reference.adoc b/modules/shared/proc-mirror-specific-plugins-by-direct-reference.adoc
@@ -20,14 +20,9 @@ For example:
 [source,terminal,subs="+quotes,+attributes"]
 ----
 bash mirror-plugins.sh \
-    --plugins 'oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1!backstage-community-plugin-quay' \
-              'oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1!backstage-community-plugin-github-actions' \
+    --plugins oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-quay:1.8.0--1.22.1 \
+              oci://quay.io/rhdh-plugin-catalog/backstage-community-plugin-github-actions:1.8.0--0.11.1 \
     --to-registry _<my.registry.example.com>_
 ----
 where:
-`--to-registry _<my.registry.example.com>_`:: Enter the URL for the target mirror registry where you want to mirror the catalog index.
-+
-[NOTE]
-====
-You must quote plugin URLs that contain an OCI subpath (`!`) to prevent shell interpretation.
-====
+`--to-registry _<my.registry.example.com>_`:: Enter the URL for the target mirror registry where you want to mirror the catalog index.
