redhat-developer · subhashkhileri · May 5, 2026
diff --git a/docs/api/utils/plugin-metadata.md b/docs/api/utils/plugin-metadata.md
@@ -154,7 +154,8 @@ Unified entry point for both PR and nightly plugin resolution flows. Called auto
 ```typescript
 async function processPluginsForDeployment(
   config: DynamicPluginsConfig,
-  metadataPath?: string
+  metadataPath?: string,
+  dpdyPackages?: Set<string>
 ): Promise<DynamicPluginsConfig>
 ```
 
@@ -163,13 +164,14 @@ async function processPluginsForDeployment(
 |-----------|------|---------|-------------|
 | `config` | [`DynamicPluginsConfig`](#dynamicpluginsconfig) | - | The plugins config to process |
 | `metadataPath` | `string` | `"../metadata"` | Path to metadata directory |
+| `dpdyPackages` | `Set<string>` | - | Pre-loaded DPDY package set (for testing; fetched automatically if omitted in nightly) |
 
 **Returns:** Processed configuration with resolved OCI references.
 
 **Behavior:**
 - **PR mode** (`!isNightlyJob()`): Injects `appConfigExamples` from metadata as base config, then resolves packages to OCI URLs (PR-specific if `GIT_PR_NUMBER` set, metadata refs otherwise)
-- **Nightly mode** (`isNightlyJob()`): Resolves packages to OCI refs from metadata only (no config injection)
-- Respects `RHDH_SKIP_PLUGIN_METADATA_INJECTION` to skip config injection
+- **Nightly mode** (`isNightlyJob()`): DPDY plugins use `{{inherit}}` (no config injection); non-DPDY OCI plugins use full metadata refs with config injection
+- Respects `RHDH_SKIP_PLUGIN_METADATA_INJECTION` to skip config injection (local only, ignored in CI)
 
 ---
 

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -18,6 +18,12 @@ All notable changes to this project will be documented in this file.
 
 - **Plugin Metadata Resolution documentation**: New overlay reference page (`docs/overlay/reference/plugin-metadata-resolution.md`) with scenario tables showing how every plugin type resolves in PR check and nightly modes, config injection behavior with deep merge examples, and cross-workspace plugin handling.
 
+### Changed
+
+- **Nightly `{{inherit}}` resolution for DPDY plugins**: In nightly mode, plugins that exist in the RHDH catalog index (`default.packages.yaml`) now resolve to `{{inherit}}` tags instead of pinned OCI refs. This tests against the exact plugin versions shipped in the RC. Non-DPDY OCI plugins continue using full metadata refs with config injection. The DPDY list is fetched at runtime from the `rhdh` repo, using `RELEASE_BRANCH_NAME` to select the branch (required in CI, defaults to `main` locally). The `{{inherit}}` ref preserves the registry from metadata (`registry.access.redhat.com`, `quay.io`, etc.) so the runtime key matches the DPDY entry.
+- **`RHDH_SKIP_PLUGIN_METADATA_INJECTION` is local-only**: This env var is now ignored in CI (`CI=true`). It was intended for local development opt-out only — in CI, metadata injection should always run to ensure consistent test behavior.
+- **`RELEASE_BRANCH_NAME` required in CI for nightly**: When running nightly mode in CI, `RELEASE_BRANCH_NAME` must be set (exported by the OpenShift CI step registry). Locally it defaults to `main`.
+
 ## [1.1.35]
 
 ### Fixed

diff --git a/docs/guide/configuration/config-files.md b/docs/guide/configuration/config-files.md
@@ -215,9 +215,11 @@ Plugin metadata injection is **enabled by default** for:
 - Local development
 - PR builds in CI
 
-Injection is **disabled** when:
-- [`RHDH_SKIP_PLUGIN_METADATA_INJECTION`](/guide/configuration/environment-variables#plugin-metadata-variables) environment variable is set
-- `JOB_NAME` contains `periodic-` (nightly/periodic CI builds)
+Injection is **disabled locally** when:
+- [`RHDH_SKIP_PLUGIN_METADATA_INJECTION`](/guide/configuration/environment-variables#plugin-metadata-variables) is set to `true` (ignored in CI)
+
+In **nightly mode** (`E2E_NIGHTLY_MODE=true` or `JOB_NAME` contains `periodic-`):
+- Only non-DPDY OCI plugins get injection; DPDY plugins use `{{inherit}}` with RHDH defaults
 
 ::: warning
 When injection is enabled, deployment will fail if:

diff --git a/docs/guide/configuration/environment-variables.md b/docs/guide/configuration/environment-variables.md
@@ -34,7 +34,7 @@ These are set automatically during deployment:
 | `CI` | Enables auto-cleanup | - |
 | `CHART_URL` | Custom Helm chart URL | `oci://quay.io/rhdh/chart` |
 | `SKIP_KEYCLOAK_DEPLOYMENT` | Skip Keycloak auto-deploy | `false` |
-| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | Disable plugin metadata injection | - |
+| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | Disable plugin metadata injection (local only, ignored in CI) | - |
 
 ## Plugin Metadata Variables
 
@@ -43,9 +43,10 @@ These control automatic plugin configuration injection from metadata files:
 | Variable | Description | Effect |
 |----------|-------------|--------|
 | `GIT_PR_NUMBER` | PR number (set by OpenShift CI) | Enables OCI URL generation for PR builds |
-| `E2E_NIGHTLY_MODE` | When `"true"`, activates nightly mode | Uses released OCI refs, skips metadata injection |
-| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | When `"true"`, disables metadata injection | Opt-out |
-| `JOB_NAME` | CI job name (set by OpenShift CI/Prow) | If contains `periodic-`, injection is disabled |
+| `E2E_NIGHTLY_MODE` | When `"true"`, activates nightly mode | DPDY plugins use `{{inherit}}`, non-DPDY OCI plugins get full refs + config injection |
+| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | When `"true"`, disables metadata injection | Local-only opt-out (ignored when `CI=true`) |
+| `RELEASE_BRANCH_NAME` | Release branch (set by OpenShift CI step registry) | Used to fetch `default.packages.yaml` for DPDY resolution in nightly mode. Required in CI, defaults to `main` locally |
+| `JOB_NAME` | CI job name (set by OpenShift CI/Prow) | If contains `periodic-`, nightly mode is activated |
 | `JOB_MODE` | CI-only: `nightly` or `pr-check` (set by step registry) | Informational |
 
 ### OCI URL Generation

diff --git a/docs/guide/utilities/plugin-metadata.md b/docs/guide/utilities/plugin-metadata.md
@@ -27,10 +27,13 @@ Metadata handling is **enabled by default** for:
 - Local development
 - PR builds in CI
 
-Metadata handling is **disabled** when:
-- `RHDH_SKIP_PLUGIN_METADATA_INJECTION` is set to `true`
-- `E2E_NIGHTLY_MODE` is set to `true`
-- `JOB_NAME` contains `periodic-` (nightly builds)
+Metadata injection is **disabled** when:
+- `RHDH_SKIP_PLUGIN_METADATA_INJECTION` is set to `true` (local only — ignored in CI)
+
+In **nightly mode** (`E2E_NIGHTLY_MODE=true` or `JOB_NAME` contains `periodic-`):
+- DPDY plugins (in `default.packages.yaml`) use `{{inherit}}` tags — no config injection
+- Non-DPDY OCI plugins use full metadata refs — with config injection
+- Wrapper plugins keep their local paths — no config injection
 
 ::: info Priority
 The `isNightlyJob()` function checks in this order:
@@ -59,15 +62,17 @@ test.beforeAll(async ({ rhdh }) => {
    - If `dynamic-plugins.yaml` **exists**: merged with package defaults + auth config
    - If `dynamic-plugins.yaml` **doesn't exist**: auto-generated from all `metadata/*.yaml` files, then merged with defaults/auth (deduplicated by normalized plugin name — OCI wins over local `-dynamic` paths)
 
-2. **Metadata injection** (PR/local mode only, skipped in nightly):
-   - `appConfigExamples` from metadata merged as base config
-   - User-provided `pluginConfig` overrides metadata values
+2. **Metadata injection**:
+   - **PR/local**: `appConfigExamples` from metadata merged as base config; user `pluginConfig` overrides
+   - **Nightly**: only for non-DPDY OCI plugins (DPDY plugins get config via `{{inherit}}`)
 
-3. **Package resolution** (both modes) — per plugin, in priority order:
+3. **Package resolution** — per plugin, in priority order:
    | Condition | Result |
    |-----------|--------|
    | Plugin in workspace build + `GIT_PR_NUMBER` set | PR OCI URL: `pr_{number}__{version}` |
+   | Nightly + DPDY + OCI | `{{inherit}}` tag (RHDH resolves version from built-in DPDY) |
    | Plugin has metadata with OCI `dynamicArtifact` | Metadata's OCI ref (preserves original registry) |
+   | Plugin has metadata with wrapper path | Wrapper path from metadata |
    | No metadata match (cross-workspace plugins, npm packages) | Kept as-is |
 
 4. **Wrapper disabling** (PR builds only, when `GIT_PR_NUMBER` set):
@@ -174,36 +179,46 @@ The system operates in three modes based on environment variables:
 | | **PR Check** | **Nightly** | **Local Dev** |
 |---|---|---|---|
 | **Trigger** | `GIT_PR_NUMBER` set | `E2E_NIGHTLY_MODE=true` | No env vars |
-| **Config injection** | Yes — `appConfigExamples` merged | Skipped | Yes |
-| **OCI resolution** | PR tags (`pr_{n}__{v}`) for workspace plugins, metadata refs for others | Metadata refs for all | Metadata refs for all |
+| **Config injection** | Yes — all plugins | Selective — non-DPDY OCI only | Yes — all plugins |
+| **DPDY OCI resolution** | PR tags or metadata refs | `{{inherit}}` tag | Metadata refs |
+| **Non-DPDY OCI resolution** | PR tags or metadata refs | Metadata refs + config injection | Metadata refs |
+| **Wrapper plugins** | Metadata path | Metadata path | Metadata path |
 | **Wrapper disabling** | Yes (`disableWrappers`) | No | No |
 | **Cross-workspace plugins** | Kept as-is | Kept as-is | Kept as-is |
 
-### Why Metadata Refs (Not `{{inherit}}`)
+### DPDY vs Non-DPDY in Nightly
+
+DPDY (dynamic-plugins.default.yaml) plugins are those shipped in the RHDH catalog index image, listed in [`default.packages.yaml`](https://github.com/redhat-developer/rhdh/blob/main/default.packages.yaml) (both `enabled` and `disabled` sections). In nightly mode:
+
+- **DPDY + OCI**: Use `{{inherit}}` tag — RHDH resolves the version from its built-in DPDY. This tests the exact versions shipped in the RC. No config injection (RHDH provides defaults).
+- **Non-DPDY + OCI**: Use full metadata refs from `spec.dynamicArtifact`. Config injection enabled (these plugins aren't in the RHDH defaults).
+- **Wrapper plugins**: Always use the metadata wrapper path regardless of DPDY status. No config injection.
 
-Metadata files are the most accurate source for latest published plugin versions. The daily `update-plugins-repo-refs` workflow keeps them current. By contrast, many OCI plugins (~49) are not in the catalog index (DPDY), and some that are have older versions. Using metadata ensures nightly tests run against the latest published artifacts.
+The DPDY list is fetched at runtime from the `rhdh` repo using `RELEASE_BRANCH_NAME` (required in CI, defaults to `main` locally).
 
 ### processPluginsForDeployment
 
 This is the unified entry point for both PR and nightly plugin resolution flows. It is called automatically during `deploy()`.
 
 ```
-Step 1: Inject metadata configs (PR/local mode only)
-  → deepMerge(metadata.appConfigExamples, user.pluginConfig)
-  → Skipped when: isNightlyJob() OR RHDH_SKIP_PLUGIN_METADATA_INJECTION="true"
+Step 1: Inject metadata configs
+  → PR/local: deepMerge(metadata.appConfigExamples, user.pluginConfig) for all plugins
+  → Nightly: only non-DPDY OCI plugins get injection
+  → Skipped locally when RHDH_SKIP_PLUGIN_METADATA_INJECTION="true" (ignored in CI)
 
-Step 2: Resolve packages to OCI (both modes)
-  → Per plugin: PR OCI URL > metadata OCI ref > passthrough
+Step 2: Resolve packages (both modes)
+  → Per plugin: PR OCI URL > DPDY {{inherit}} > metadata OCI ref > wrapper path > passthrough
 ```
 
 ## Environment Variables
 
 | Variable | Effect |
 |----------|--------|
 | `GIT_PR_NUMBER` | Enables OCI URL generation for PR builds |
-| `E2E_NIGHTLY_MODE` | When `true`, activates nightly mode (uses released OCI refs) |
-| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | Disables all metadata handling |
-| `JOB_NAME` | If contains `periodic-`, disables metadata handling |
+| `E2E_NIGHTLY_MODE` | When `true`, activates nightly mode (DPDY → `{{inherit}}`, non-DPDY → full refs) |
+| `RELEASE_BRANCH_NAME` | Branch for fetching `default.packages.yaml` (required in CI, defaults to `main` locally) |
+| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | Disables metadata injection (local only, ignored in CI) |
+| `JOB_NAME` | If contains `periodic-`, activates nightly mode |
 | `JOB_MODE` | CI-only: `nightly` or `pr-check` (set by step registry) |
 
 See [Environment Variables](/guide/configuration/environment-variables#plugin-metadata-variables) for details.

diff --git a/docs/overlay/reference/environment-variables.md b/docs/overlay/reference/environment-variables.md
@@ -76,9 +76,10 @@ These control automatic plugin configuration generation from metadata files:
 | Variable | Description | Effect |
 |----------|-------------|--------|
 | `GIT_PR_NUMBER` | PR number | Enables OCI URL generation using that PR's built images |
-| `E2E_NIGHTLY_MODE` | When `true`, activates nightly mode | Uses released OCI refs from metadata, skips config injection |
-| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | When `true`, disables metadata injection | Opt-out for all metadata handling |
-| `JOB_NAME` | CI job name (set by OpenShift CI/Prow) | If contains `periodic-`, injection is disabled |
+| `E2E_NIGHTLY_MODE` | When `true`, activates nightly mode | DPDY plugins use `{{inherit}}`, non-DPDY OCI plugins get full refs + config injection |
+| `RELEASE_BRANCH_NAME` | Release branch (set by OpenShift CI) | Used to fetch `default.packages.yaml` for DPDY resolution. Required in CI, defaults to `main` locally |
+| `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | When `true`, disables metadata injection | Local-only opt-out (ignored when `CI=true`) |
+| `JOB_NAME` | CI job name (set by OpenShift CI/Prow) | If contains `periodic-`, nightly mode is activated |
 
 ### When to Use These Variables
 
@@ -87,18 +88,21 @@ These control automatic plugin configuration generation from metadata files:
 | PR builds in CI | `GIT_PR_NUMBER` is set automatically |
 | Test PR builds locally | Set `GIT_PR_NUMBER` manually to use PR's OCI images |
 | Nightly/periodic builds | `E2E_NIGHTLY_MODE=true` or `JOB_NAME` contains `periodic-` (auto-detected in CI) |
-| Manual opt-out | Set `RHDH_SKIP_PLUGIN_METADATA_INJECTION=true` |
+| Manual opt-out (local only) | Set `RHDH_SKIP_PLUGIN_METADATA_INJECTION=true` (ignored in CI) |
 
 ### Metadata Handling Behavior
 
 **Enabled by default** for:
 - Local development
 - PR builds in CI
 
-**Disabled automatically** when:
-- `RHDH_SKIP_PLUGIN_METADATA_INJECTION` is set to `true`
-- `E2E_NIGHTLY_MODE` is set to `true`
-- `JOB_NAME` contains `periodic-` (nightly builds)
+**Disabled locally** when:
+- `RHDH_SKIP_PLUGIN_METADATA_INJECTION` is set to `true` (ignored in CI)
+
+**Selective in nightly mode** (`E2E_NIGHTLY_MODE=true` or `JOB_NAME` contains `periodic-`):
+- DPDY OCI plugins: no injection (use `{{inherit}}` tag, RHDH provides config)
+- Non-DPDY OCI plugins: injection enabled (full metadata refs)
+- Wrapper plugins: no injection
 
 ::: info Priority
 When `GIT_PR_NUMBER` is set, PR mode always takes precedence over nightly mode. This prevents broken combinations of PR images with nightly configuration.