feat(validate-metadata): take in account image tag prefix in metadata validation logic.

The validation logic is enhanced to skip the tag check when the prefix is set to "next__", accommodating backstage-incompatible workspaces.

Assisted-by: Cursor
Signed-off-by: David Festal <dfestal@redhat.com>

Author: davidfestal

.github/workflows/export-dynamic.yaml

@@ -413,3 +413,4 @@ jobs:
           plugins-root: ${{ github.workspace }}/source-repo/${{inputs.plugins-root}}
           target-backstage-version: ${{ inputs.target-backstage-version }}
           image-repository-prefix: ${{ steps.set-image-tag-name.outputs.IMAGE_REPOSITORY_PREFIX }}
+          image-tag-prefix: ${{ inputs.image-tag-prefix }}

.github/workflows/test-validate-metadata.yaml

@@ -398,3 +398,41 @@ jobs:
             file: 'plugins-list.yaml',
             message: 'plugins-list.yaml must be a YAML dictionary with plugin paths as keys'
           });
+
+  test-validation-next-prefix-skips-tag:
+    name: Test Validation (next__ prefix skips OCI tag check)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Node.js 24.x
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24.x
+
+      - name: Run Validate Metadata with next__ prefix
+        id: validate
+        uses: ./validate-metadata
+        with:
+          overlay-root: ${{ env.TEST_DIR }}/cases/next-prefix-skip
+          plugins-root: ${{ env.TEST_DIR }}/source
+          target-backstage-version: ${{ env.TARGET_BACKSTAGE_VERSION }}
+          image-repository-prefix: ${{ env.IMAGE_REPOSITORY_PREFIX }}
+          image-tag-prefix: next__
+
+      - name: Verify validation passed despite stale OCI tag
+        env:
+          VALIDATION_PASSED: ${{ steps.validate.outputs.validation-passed }}
+          VALIDATION_ERROR_COUNT: ${{ steps.validate.outputs.validation-error-count }}
+          VALIDATION_ERRORS: ${{ steps.validate.outputs.validation-errors }}
+        shell: node {0}
+        run: |
+          import assert from 'node:assert/strict';
+          const { VALIDATION_PASSED, VALIDATION_ERROR_COUNT, VALIDATION_ERRORS } = process.env;
+
+          // Metadata has bs_1.40.0__1.0.0 which doesn't match target 1.42.5,
+          // but with next__ prefix the OCI tag check is skipped
+          assert.equal(VALIDATION_PASSED, 'true');
+          assert.equal(VALIDATION_ERROR_COUNT, '0');
+          assert.equal(VALIDATION_ERRORS, '[]');

validate-metadata/action.yaml

@@ -14,6 +14,10 @@ inputs:
     description: Repository prefix for validating OCI reference format in dynamicArtifact
     required: false
     default: ""
+  image-tag-prefix:
+    description: OCI image tag prefix used by the export (e.g., "bs_1.48.3__", "next__", "pr_42__"). When "next__", OCI tag validation is skipped since the workspace is backstage-incompatible.
+    required: false
+    default: ""
 
 outputs:
   validation-passed:
@@ -38,6 +42,7 @@ runs:
         INPUTS_PLUGINS_ROOT: ${{ inputs.plugins-root }}
         INPUTS_TARGET_BACKSTAGE_VERSION: ${{ inputs.target-backstage-version }}
         INPUTS_IMAGE_REPOSITORY_PREFIX: ${{ inputs.image-repository-prefix }}
+        INPUTS_IMAGE_TAG_PREFIX: ${{ inputs.image-tag-prefix }}
       run: |
         npm install
         node validate-metadata.ts

validate-metadata/test/cases/next-prefix-skip/metadata/test-plugin.yaml

@@ -0,0 +1,12 @@
+apiVersion: extensions.backstage.io/v1alpha1
+kind: Package
+metadata:
+  name: test-plugin
+  namespace: rhdh
+spec:
+  packageName: '@test-org/plugin-test'
+  dynamicArtifact: oci://ghcr.io/test-org/test-repo/test-org-plugin-test:bs_1.40.0__1.0.0!test-org-plugin-test
+  version: 1.0.0
+  backstage:
+    role: frontend-plugin
+    supportedVersions: 1.42.5

validate-metadata/test/cases/next-prefix-skip/plugins-list.yaml

@@ -0,0 +1,2 @@
+plugins/test-plugin:
+plugins/test-backend:

validate-metadata/validate-metadata.ts

@@ -78,6 +78,7 @@ const OVERLAY_ROOT = process.env.INPUTS_OVERLAY_ROOT;
 const PLUGINS_ROOT = process.env.INPUTS_PLUGINS_ROOT;
 const TARGET_BACKSTAGE_VERSION = process.env.INPUTS_TARGET_BACKSTAGE_VERSION;
 const IMAGE_REPOSITORY_PREFIX = process.env.INPUTS_IMAGE_REPOSITORY_PREFIX || '';
+const IMAGE_TAG_PREFIX = process.env.INPUTS_IMAGE_TAG_PREFIX || '';
 
 // Validate required environment variables
 if (!OVERLAY_ROOT) {
@@ -360,19 +361,27 @@ function validateOciReference(
   packageName: string
 ): void {
   const { reference, tag } = parseOciReference(dynamicArtifact);
-  const expectedTag = `bs_${TARGET_BACKSTAGE_VERSION}__${pluginVersion}`;
 
-  if (tag !== expectedTag) {
-    errors.push({
-      kind: 'mismatch',
-      file: metadataFilePath,
-      field: 'dynamicArtifact.tag',
-      expected: expectedTag,
-      actual: tag,
-      message: `OCI tag mismatch: expected "${expectedTag}" but got "${tag}"`
-    });
+  // When the export uses next__ (workspace is backstage-incompatible),
+  // skip the tag prefix check -- the metadata tag is a remnant from the
+  // last compatible state and will self-correct on the next compatible update.
+  if (IMAGE_TAG_PREFIX !== 'next__') {
+    const expectedTag = IMAGE_TAG_PREFIX
+      ? `${IMAGE_TAG_PREFIX}${pluginVersion}`
+      : `bs_${TARGET_BACKSTAGE_VERSION}__${pluginVersion}`;
+
+    if (tag !== expectedTag) {
+      errors.push({
+        kind: 'mismatch',
+        file: metadataFilePath,
+        field: 'dynamicArtifact.tag',
+        expected: expectedTag,
+        actual: tag,
+        message: `OCI tag mismatch: expected "${expectedTag}" but got "${tag}"`
+      });
+    }
   }
-  
+
   // Validate reference format: <image-repository-prefix>/<package name with @ and / replaced by ->
   if (!IMAGE_REPOSITORY_PREFIX) {
     return;