feat(plugin-metadata): add OCI image URL generation for PR builds (#23)

subhashkhileri · claude · web-flow · commit ee7d9d5c0458 · 2026-01-28T11:19:46.000+05:30
When GIT_PR_NUMBER environment variable is set, local plugin paths
are replaced with OCI URLs pointing to the plugin export overlays
registry (ghcr.io/redhat-developer/rhdh-plugin-export-overlays).

Co-authored-by: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/docs/api/utils/plugin-metadata.md b/docs/api/utils/plugin-metadata.md
@@ -178,13 +178,29 @@ async function generateDynamicPluginsConfigFromMetadata(
 - Throws error if no valid metadata files found
 - All generated plugins have `disabled: false`
 
+**PR Build Behavior (when `GIT_PR_NUMBER` is set):**
+- Replaces local plugin paths with OCI URLs
+- Fetches plugin versions from source repo's `package.json`
+- Throws error if `source.json` or `plugins-list.yaml` not found
+- Throws error if version fetching fails
+
 **Example:**
 
 ```typescript
 const config = await generateDynamicPluginsConfigFromMetadata();
 console.log(`Generated config with ${config.plugins?.length} plugins`);
 ```
 
+**Example Output (PR Build):**
+
+```yaml
+plugins:
+  - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/my-plugin:pr_1234__1.0.0
+    disabled: false
+    pluginConfig:
+      # ... from metadata
+```
+
 ---
 
 ### loadAndInjectPluginMetadata()
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -2,38 +2,81 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.1.2] - Current
+## [1.1.5] - Current
 
 ### Added
-- Keycloak integration with modular auth configuration
+- **Plugin metadata auto-generation**: When `dynamic-plugins.yaml` doesn't exist, configuration is automatically generated from `metadata/*.yaml` files
+- **OCI URL generation for PR builds**: When `GIT_PR_NUMBER` is set, local plugin paths are replaced with OCI URLs (e.g., `oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/my-plugin:pr_1234__1.0.0`)
+- Plugin metadata injection into existing `dynamic-plugins.yaml` configurations
+- New utilities: `shouldInjectPluginMetadata()`, `generateDynamicPluginsConfigFromMetadata()`, `loadAndInjectPluginMetadata()`, `extractPluginName()`
+- **Early pod failure detection**: `waitForPodsWithFailureDetection()` in KubernetesClientHelper detects CrashLoopBackOff, ImagePullBackOff, init container failures, etc. within seconds instead of waiting for full timeout
+
+### Changed
+- Plugin versions for OCI URLs are fetched from source repo's `package.json` using `source.json` commit ref
+- Metadata handling disabled for periodic builds (when `JOB_NAME` contains `periodic-`)
+- Strict error handling for PR builds (fails if source files missing or fetch fails)
+- Improved boxen formatting for YAML output
+- RHDH and Keycloak deployments now use early failure detection for faster error reporting
+
+### Environment Variables
+- `GIT_PR_NUMBER`: Enables OCI URL generation for PR builds
+- `RHDH_SKIP_PLUGIN_METADATA_INJECTION`: Disables all metadata handling
+
+## [1.1.4]
+
+### Fixed
+- Keycloak: Use plain HTTP route to avoid certificate issues (#19)
+
+### Security
+- Bump `lodash` from 4.17.21 to 4.17.23
+- Bump `tar` from 7.5.2 to 7.5.6
+
+## [1.1.3]
+
+### Added
+- Comprehensive VitePress documentation site (#14)
+
+### Fixed
+- Corepack setup for Yarn 3 in CI workflow (#16)
+
+## [1.1.2]
+
+### Added
+- Keycloak integration with modular auth configuration (#8)
 - KeycloakHelper class for Keycloak deployment and management
 - Support for guest and Keycloak authentication providers
 - Automatic Keycloak deployment in global setup
 - Default realm, client, groups, and users configuration
+- Keycloak integration documentation (#9)
 
 ### Changed
 - Improved RHDHDeployment class with `configure()` method
 - Enhanced configuration merging for auth-specific configs
 - Better environment variable handling
 
+## [1.1.1]
+
+### Added
+- Playwright helpers: UIHelper, LoginHelper, APIHelper (#7)
+- Page objects: CatalogPage, HomePage, CatalogImportPage, ExtensionsPage, NotificationPage
+
 ## [1.1.0]
 
 ### Added
 - Initial release of `rhdh-e2e-test-utils`
 - RHDHDeployment class for RHDH deployment
 - Playwright test fixtures (rhdh, uiHelper, loginHelper, baseURL)
 - Base Playwright configuration with `defineConfig`
-- UIhelper class for Material-UI interactions
-- LoginHelper class for authentication
-- APIHelper class for GitHub and Backstage APIs
-- Page objects (CatalogPage, HomePage, CatalogImportPage, ExtensionsPage, NotificationPage)
 - KubernetesClientHelper for Kubernetes operations
 - YAML merging utilities
 - Environment variable substitution
 - ESLint configuration factory
 - TypeScript base configuration
 - Support for Helm and Operator deployment methods
 
+### Fixed
+- Config file resolution for published package (#6)
+
 ## [1.0.0]
 
 ### Added
diff --git a/docs/guide/configuration/config-files.md b/docs/guide/configuration/config-files.md
@@ -205,6 +205,26 @@ When injection is enabled, deployment will fail if:
 - No valid metadata files are found in the directory
 :::
 
+### OCI URL Replacement for PR Builds
+
+When `GIT_PR_NUMBER` is set (by OpenShift CI), local plugin paths are automatically replaced with OCI URLs pointing to the PR's built artifacts:
+
+```yaml
+# Local development
+- package: ./dynamic-plugins/dist/backstage-community-plugin-tech-radar
+
+# PR build (GIT_PR_NUMBER=1845)
+- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-tech-radar:pr_1845__1.13.0
+```
+
+This allows E2E tests to run against the actual OCI images built for the PR.
+
+::: warning
+For PR builds, OCI URL generation is required. Deployment will fail if `source.json` or `plugins-list.yaml` doesn't exist, or if version fetching fails.
+:::
+
+See [Plugin Metadata - OCI URL Generation](/guide/utilities/plugin-metadata#oci-url-generation-for-pr-builds) for complete details.
+
 ### Package Reference Matching
 
 The package automatically matches plugins across different reference formats:
diff --git a/docs/guide/configuration/environment-variables.md b/docs/guide/configuration/environment-variables.md
@@ -33,10 +33,23 @@ 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 |
 | `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | When set (any value), disables metadata injection | Opt-out |
 | `JOB_NAME` | CI job name (set by OpenShift CI/Prow) | If contains `periodic-`, injection is disabled |
 
-See [Plugin Metadata Injection](/guide/configuration/config-files#plugin-metadata-injection) for details.
+### OCI URL Generation
+
+When `GIT_PR_NUMBER` is set, the package replaces local plugin paths with OCI URLs:
+
+```yaml
+# Before
+- package: ./dynamic-plugins/dist/my-plugin
+
+# After (with GIT_PR_NUMBER=1234)
+- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/my-plugin:pr_1234__1.0.0
+```
+
+See [Plugin Metadata](/guide/utilities/plugin-metadata#oci-url-generation-for-pr-builds) for complete details.
 
 ## Keycloak Variables
 
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
@@ -76,7 +76,11 @@ stringData:
 ```
 
 ::: tip Skip dynamic-plugins.yaml
-If your workspace has a `metadata/` directory with Package CRD files, you can skip creating `dynamic-plugins.yaml`. The package will automatically generate configuration from metadata files. See [Plugin Metadata Injection](/guide/configuration/config-files#plugin-metadata-injection).
+If your workspace has a `metadata/` directory with Package CRD files, you can skip creating `dynamic-plugins.yaml`. The package will automatically generate configuration from metadata files.
+
+For PR builds in CI (when `GIT_PR_NUMBER` is set), the package also automatically replaces local plugin paths with OCI URLs pointing to the PR's built artifacts.
+
+See [Plugin Metadata Injection](/guide/configuration/config-files#plugin-metadata-injection) for details.
 :::
 
 ## Step 4: Create Environment File
diff --git a/docs/guide/utilities/kubernetes-client.md b/docs/guide/utilities/kubernetes-client.md
@@ -95,6 +95,32 @@ const domain = await k8sClient.getClusterIngressDomain();
 // Returns: "apps.cluster.example.com"
 ```
 
+## Pod Operations
+
+### `waitForPodsWithFailureDetection(namespace, labelSelector, timeout?, pollInterval?)`
+
+Wait for pods to be ready with early failure detection. Unlike `oc rollout status`, this method detects unrecoverable failure states (CrashLoopBackOff, ImagePullBackOff, etc.) within seconds and fails fast with container logs:
+
+```typescript
+await k8sClient.waitForPodsWithFailureDetection(
+  "my-namespace",
+  "app.kubernetes.io/instance=my-app",
+  300,  // timeout in seconds (default: 300)
+  5000  // poll interval in ms (default: 5000)
+);
+```
+
+**Detected failure states:**
+- `CrashLoopBackOff` - container keeps crashing
+- `ImagePullBackOff` / `ErrImagePull` - can't pull image
+- `CreateContainerConfigError` - config issues (missing secrets, etc.)
+- `Init:*` variants - init container failures
+
+When a failure is detected, the method:
+1. Logs the failure reason
+2. Fetches container logs via `oc logs`
+3. Throws an error with the failure details
+
 ## Deployment Operations
 
 ### `scaleDeployment(namespace, name, replicas)`
diff --git a/docs/guide/utilities/plugin-metadata.md b/docs/guide/utilities/plugin-metadata.md
@@ -127,10 +127,49 @@ The `RHDHDeployment` class automatically uses these utilities during `deploy()`:
 
 See [Configuration Files](/guide/configuration/config-files#plugin-metadata-injection) for detailed behavior.
 
+## OCI URL Generation for PR Builds
+
+When `GIT_PR_NUMBER` is set (by OpenShift CI), local plugin paths are automatically replaced with OCI URLs pointing to the PR's built artifacts.
+
+### How It Works
+
+1. Reads `source.json` from the workspace directory to get the source repo and commit ref
+2. Reads `plugins-list.yaml` to get the list of plugin paths
+3. Fetches each plugin's `package.json` from the source repo to get the current version
+4. Generates OCI URLs in the format:
+
+```
+oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/{plugin-name}:pr_{PR_NUMBER}__{version}
+```
+
+### Example
+
+```yaml
+# Local development
+- package: ./dynamic-plugins/dist/backstage-community-plugin-tech-radar
+
+# PR build (GIT_PR_NUMBER=1845)
+- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-tech-radar:pr_1845__1.13.0
+```
+
+### Required Files
+
+For OCI URL generation, your workspace must have these files (generated by CI):
+
+| File | Purpose |
+|------|---------|
+| `source.json` | Contains `repo` (GitHub URL) and `repo-ref` (commit SHA) |
+| `plugins-list.yaml` | Lists plugin paths (e.g., `plugins/tech-radar:`) |
+
+::: warning
+For PR builds, OCI URL generation is strict - deployment will fail if required files are missing or version fetching fails. This ensures PR builds don't silently fall back to local paths.
+:::
+
 ## Environment Variables
 
 | Variable | Effect |
 |----------|--------|
+| `GIT_PR_NUMBER` | Enables OCI URL generation for PR builds |
 | `RHDH_SKIP_PLUGIN_METADATA_INJECTION` | Disables all metadata handling |
 | `JOB_NAME` | If contains `periodic-`, disables metadata handling |
 
diff --git a/docs/tutorials/ci-cd-integration.md b/docs/tutorials/ci-cd-integration.md
@@ -170,6 +170,35 @@ on:
     - cron: "0 6 * * *"  # Daily at 6 AM
 ```
 
+## OpenShift CI / Prow Integration
+
+For OpenShift CI (Prow), the package supports automatic OCI URL generation for PR builds.
+
+### Environment Variables
+
+| Variable | Description | Set By |
+|----------|-------------|--------|
+| `GIT_PR_NUMBER` | PR number - enables OCI URL generation | OpenShift CI |
+| `JOB_NAME` | Job name (e.g., `pull-ci-...` or `periodic-...`) | OpenShift CI |
+
+### OCI URL Generation
+
+When `GIT_PR_NUMBER` is set, plugin paths are automatically replaced with OCI URLs:
+
+```yaml
+# Before
+- package: ./dynamic-plugins/dist/my-plugin
+
+# After (GIT_PR_NUMBER=1234)
+- package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/my-plugin:pr_1234__1.0.0
+```
+
+### Periodic/Nightly Builds
+
+For periodic builds (when `JOB_NAME` contains `periodic-`), metadata injection is disabled automatically. Tests use default RHDH configuration.
+
+See [Plugin Metadata](/guide/utilities/plugin-metadata#oci-url-generation-for-pr-builds) for complete details.
+
 ## Best Practices
 
 1. **Use fail-fast: false** - Run all projects even if one fails
diff --git a/docs/tutorials/plugin-testing.md b/docs/tutorials/plugin-testing.md
@@ -84,7 +84,14 @@ myPlugin:
 ```
 
 ::: tip Automatic Plugin Configuration
-If your workspace has a `metadata/` directory with Package CRD files, you can skip creating `dynamic-plugins.yaml`. The package will automatically generate configuration from metadata files during PR builds. See [Plugin Metadata Injection](/guide/configuration/config-files#plugin-metadata-injection) for details.
+If your workspace has a `metadata/` directory with Package CRD files, you can skip creating `dynamic-plugins.yaml`. The package will automatically:
+
+1. **Generate configuration** from all metadata files (all plugins enabled)
+2. **Replace paths with OCI URLs** for PR builds (when `GIT_PR_NUMBER` is set)
+
+Example OCI URL: `oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/my-plugin:pr_1234__1.0.0`
+
+See [Plugin Metadata Injection](/guide/configuration/config-files#plugin-metadata-injection) for details.
 :::
 
 ## Step 4: Write Tests
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "rhdh-e2e-test-utils",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Test utilities for RHDH E2E tests",
   "license": "Apache-2.0",
   "type": "module",
@@ -82,7 +82,6 @@
     "@eslint/js": "^9.39.1",
     "@keycloak/keycloak-admin-client": "^26.0.0",
     "@kubernetes/client-node": "^1.4.0",
-    "boxen": "^8.0.1",
     "eslint": "^9.39.1",
     "eslint-plugin-check-file": "^3.3.1",
     "eslint-plugin-playwright": "^2.4.0",
diff --git a/src/deployment/keycloak/deployment.ts b/src/deployment/keycloak/deployment.ts
@@ -355,9 +355,10 @@ export class KeycloakHelper {
    */
   async waitUntilReady(timeout: number = 300): Promise<void> {
     this._log(`Waiting for Keycloak to be ready...`);
-    await this.k8sClient.waitForStatefulSetReady(
+    const labelSelector = `app.kubernetes.io/instance=${this.deploymentConfig.releaseName}`;
+    await this.k8sClient.waitForPodsWithFailureDetection(
       this.deploymentConfig.namespace,
-      this.deploymentConfig.releaseName,
+      labelSelector,
       timeout,
     );
   }
diff --git a/src/deployment/rhdh/deployment.ts b/src/deployment/rhdh/deployment.ts
diff --git a/src/utils/kubernetes-client.ts b/src/utils/kubernetes-client.ts
diff --git a/src/utils/plugin-metadata.ts b/src/utils/plugin-metadata.ts
diff --git a/yarn.lock b/yarn.lock
