Gate container image validation behind feature flag

Add containerImageValidation experimental feature flag that gates the
new container image validation behind an opt-in toggle. When the flag
is off (default), the legacy converter logic is used. When enabled,
the improved validation with expression handling runs.

The legacy code is duplicated to keep code paths fully isolated and
make the eventual cleanup diff minimal — just delete the legacy
functions and the flag guards.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

expressions/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/expressions",
-  "version": "0.3.43",
+  "version": "0.3.44",
   "license": "MIT",
   "type": "module",
   "source": "./src/index.ts",

expressions/src/completion.ts

@@ -35,6 +35,7 @@ export function complete(
   context: Dictionary,
   extensionFunctions: FunctionInfo[],
   functions?: Map<string, FunctionDefinition>,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   featureFlags?: FeatureFlags
 ): CompletionItem[] {
   // Lex
@@ -66,7 +67,7 @@ export function complete(
     const result = contextKeys(context);
 
     // Merge with functions
-    result.push(...functionItems(extensionFunctions, featureFlags));
+    result.push(...functionItems(extensionFunctions));
 
     return result;
   }
@@ -91,15 +92,10 @@ export function complete(
   return contextKeys(result);
 }
 
-function functionItems(extensionFunctions: FunctionInfo[], featureFlags?: FeatureFlags): CompletionItem[] {
+function functionItems(extensionFunctions: FunctionInfo[]): CompletionItem[] {
   const result: CompletionItem[] = [];
-  const flags = featureFlags ?? new FeatureFlags();
 
   for (const fdef of [...Object.values(wellKnownFunctions), ...extensionFunctions]) {
-    // Filter out case function if feature is disabled
-    if (fdef.name === "case" && !flags.isEnabled("allowCaseFunction")) {
-      continue;
-    }
     result.push({
       label: fdef.name,
       description: fdef.description,

expressions/src/features.test.ts

@@ -51,11 +51,7 @@ describe("FeatureFlags", () => {
 
     it("returns all features when all is enabled", () => {
       const flags = new FeatureFlags({all: true});
-      expect(flags.getEnabledFeatures()).toEqual([
-        "missingInputsQuickfix",
-        "blockScalarChompingWarning",
-        "allowCaseFunction"
-      ]);
+      expect(flags.getEnabledFeatures()).toEqual(["missingInputsQuickfix", "blockScalarChompingWarning"]);
     });
   });
 });

expressions/src/features.ts

@@ -30,10 +30,11 @@ export interface ExperimentalFeatures {
   blockScalarChompingWarning?: boolean;
 
   /**
-   * Enable the case() function in expressions.
+   * Enable improved container image validation that handles
+   * expressions gracefully and validates empty/docker:// images.
    * @default false
    */
-  allowCaseFunction?: boolean;
+  containerImageValidation?: boolean;
 }
 
 /**
@@ -48,7 +49,7 @@ export type ExperimentalFeatureKey = Exclude<keyof ExperimentalFeatures, "all">;
 const allFeatureKeys: ExperimentalFeatureKey[] = [
   "missingInputsQuickfix",
   "blockScalarChompingWarning",
-  "allowCaseFunction"
+  "containerImageValidation"
 ];
 
 export class FeatureFlags {

languageserver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/languageserver",
-  "version": "0.3.43",
+  "version": "0.3.44",
   "description": "Language server for GitHub Actions",
   "license": "MIT",
   "type": "module",
@@ -48,8 +48,8 @@
     "actions-languageserver": "./bin/actions-languageserver"
   },
   "dependencies": {
-    "@actions/languageservice": "^0.3.43",
-    "@actions/workflow-parser": "^0.3.43",
+    "@actions/languageservice": "^0.3.44",
+    "@actions/workflow-parser": "^0.3.44",
     "@octokit/rest": "^21.1.1",
     "@octokit/types": "^9.0.0",
     "vscode-languageserver": "^8.0.2",

languageservice/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/languageservice",
-  "version": "0.3.43",
+  "version": "0.3.44",
   "description": "Language service for GitHub Actions",
   "license": "MIT",
   "type": "module",
@@ -47,8 +47,8 @@
     "watch": "tsc --build tsconfig.build.json --watch"
   },
   "dependencies": {
-    "@actions/expressions": "^0.3.43",
-    "@actions/workflow-parser": "^0.3.43",
+    "@actions/expressions": "^0.3.44",
+    "@actions/workflow-parser": "^0.3.44",
     "vscode-languageserver-textdocument": "^1.0.7",
     "vscode-languageserver-types": "^3.17.2",
     "vscode-uri": "^3.0.8",

languageservice/src/complete.expressions.test.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
-import {data, DescriptionDictionary, FeatureFlags} from "@actions/expressions";
+import {data, DescriptionDictionary} from "@actions/expressions";
 import {CompletionItem, CompletionItemKind, MarkupContent} from "vscode-languageserver-types";
 import {complete, getExpressionInput} from "./complete.js";
 import {ContextProviderConfig} from "./context-providers/config.js";
@@ -69,8 +69,7 @@ describe("expressions", () => {
     it("single region", async () => {
       const input = "run-name: ${{ | }}";
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
 
       expect(result.map(x => x.label)).toEqual([
@@ -113,8 +112,7 @@ describe("expressions", () => {
     it("single region with existing input", async () => {
       const input = "run-name: ${{ g| }}";
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
 
       expect(result.map(x => x.label)).toEqual([
@@ -135,8 +133,7 @@ describe("expressions", () => {
     it("single region with existing condition", async () => {
       const input = "run-name: ${{ g| == 'test' }}";
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
 
       expect(result.map(x => x.label)).toEqual([
@@ -157,8 +154,7 @@ describe("expressions", () => {
     it("multiple regions with partial function", async () => {
       const input = "run-name: Run a ${{ inputs.test }} one-line script ${{ from|('test') == inputs.name }}";
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
 
       expect(result.map(x => x.label)).toEqual([
@@ -179,8 +175,7 @@ describe("expressions", () => {
     it("multiple regions - first region", async () => {
       const input = "run-name: test-${{ git| == 1 }}-${{ github.event }}";
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
 
       expect(result.map(x => x.label)).toEqual([
@@ -201,8 +196,7 @@ describe("expressions", () => {
     it("multiple regions", async () => {
       const input = "run-name: test-${{ github }}-${{ | }}";
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
 
       expect(result.map(x => x.label)).toEqual([
@@ -1181,8 +1175,7 @@ jobs:
 `;
 
       const result = await complete(...getPositionFromCursor(input), {
-        contextProviderConfig,
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
+        contextProviderConfig
       });
       expect(result.map(x => x.label)).toEqual([
         "env",

languageservice/src/complete.test.ts

@@ -6,7 +6,6 @@ import {getPositionFromCursor} from "./test-utils/cursor-position.js";
 import {TestLogger} from "./test-utils/logger.js";
 import {clearCache} from "./utils/workflow-cache.js";
 import {ValueProviderConfig, ValueProviderKind} from "./value-providers/config.js";
-import {FeatureFlags} from "@actions/expressions/features";
 
 registerLogger(new TestLogger());
 
@@ -898,11 +897,9 @@ jobs:
   });
 
   describe("expression completions", () => {
-    it("include case function when enabled", async () => {
+    it("includes case function", async () => {
       const input = "on: push\njobs:\n  build:\n    runs-on: ${{ c|";
-      const result = await complete(...getPositionFromCursor(input), {
-        featureFlags: new FeatureFlags({allowCaseFunction: true})
-      });
+      const result = await complete(...getPositionFromCursor(input));
 
       expect(result).not.toBeUndefined();
       // Expression completions starting with 'c': case, contains
@@ -910,18 +907,5 @@ jobs:
       expect(labels).toContain("case");
       expect(labels).toContain("contains");
     });
-
-    it("exclude case function when disabled", async () => {
-      const input = "on: push\njobs:\n  build:\n    runs-on: ${{ c|";
-      const result = await complete(...getPositionFromCursor(input), {
-        featureFlags: new FeatureFlags({allowCaseFunction: false})
-      });
-
-      expect(result).not.toBeUndefined();
-      // Expression completions starting with 'c': contains
-      const labels = result.map(x => x.label);
-      expect(labels).not.toContain("case");
-      expect(labels).toContain("contains");
-    });
   });
 });

languageservice/src/hover.test.ts

@@ -195,7 +195,7 @@ jobs:
     const result = await hover(...getPositionFromCursor(input), testHoverConfig("uses", "step-uses", undefined));
     expect(result).not.toBeUndefined();
     expect(result?.contents).toEqual(
-      "Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image."
+      "Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, a [private repository with access enabled](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository), or in a published Docker container image."
     );
   });
 });

lerna.json

@@ -6,5 +6,5 @@
     "languageservice",
     "languageserver"
   ],
-  "version": "0.3.43"
+  "version": "0.3.44"
 }

package-lock.json

@@ -136,7 +136,7 @@
     },
     "expressions": {
       "name": "@actions/expressions",
-      "version": "0.3.43",
+      "version": "0.3.44",
       "license": "MIT",
       "devDependencies": {
         "@types/jest": "^29.0.3",
@@ -396,11 +396,11 @@
     },
     "languageserver": {
       "name": "@actions/languageserver",
-      "version": "0.3.43",
+      "version": "0.3.44",
       "license": "MIT",
       "dependencies": {
-        "@actions/languageservice": "^0.3.43",
-        "@actions/workflow-parser": "^0.3.43",
+        "@actions/languageservice": "^0.3.44",
+        "@actions/workflow-parser": "^0.3.44",
         "@octokit/rest": "^21.1.1",
         "@octokit/types": "^9.0.0",
         "vscode-languageserver": "^8.0.2",
@@ -940,11 +940,11 @@
     },
     "languageservice": {
       "name": "@actions/languageservice",
-      "version": "0.3.43",
+      "version": "0.3.44",
       "license": "MIT",
       "dependencies": {
-        "@actions/expressions": "^0.3.43",
-        "@actions/workflow-parser": "^0.3.43",
+        "@actions/expressions": "^0.3.44",
+        "@actions/workflow-parser": "^0.3.44",
         "vscode-languageserver-textdocument": "^1.0.7",
         "vscode-languageserver-types": "^3.17.2",
         "vscode-uri": "^3.0.8",
@@ -13345,10 +13345,10 @@
     },
     "workflow-parser": {
       "name": "@actions/workflow-parser",
-      "version": "0.3.43",
+      "version": "0.3.44",
       "license": "MIT",
       "dependencies": {
-        "@actions/expressions": "^0.3.43",
+        "@actions/expressions": "^0.3.44",
         "cronstrue": "^2.21.0",
         "yaml": "^2.0.0-8"
       },

workflow-parser/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actions/workflow-parser",
-  "version": "0.3.43",
+  "version": "0.3.44",
   "license": "MIT",
   "type": "module",
   "source": "./src/index.ts",
@@ -48,7 +48,7 @@
     "watch": "tsc --build tsconfig.build.json --watch"
   },
   "dependencies": {
-    "@actions/expressions": "^0.3.43",
+    "@actions/expressions": "^0.3.44",
     "cronstrue": "^2.21.0",
     "yaml": "^2.0.0-8"
   },

workflow-parser/src/model/convert.ts

@@ -1,3 +1,4 @@
+import {FeatureFlags} from "@actions/expressions";
 import {TemplateContext} from "../templates/template-context.js";
 import {TemplateToken, TemplateTokenError} from "../templates/tokens/template-token.js";
 import {FileProvider} from "../workflows/file-provider.js";
@@ -37,9 +38,15 @@ export type WorkflowTemplateConverterOptions = {
    * By default, conversion will be skipped if there are errors in the {@link TemplateContext}.
    */
   errorPolicy?: ErrorPolicy;
+
+  /**
+   * Feature flags for experimental features.
+   * When not provided, all experimental features are disabled.
+   */
+  featureFlags?: FeatureFlags;
 };
 
-const defaultOptions: Required<WorkflowTemplateConverterOptions> = {
+const defaultOptions: Omit<Required<WorkflowTemplateConverterOptions>, "featureFlags"> = {
   maxReusableWorkflowDepth: 4,
   fetchReusableWorkflowDepth: 0,
   errorPolicy: ErrorPolicy.ReturnErrorsOnly
@@ -54,6 +61,11 @@ export async function convertWorkflowTemplate(
   const result = {} as WorkflowTemplate;
   const opts = getOptionsWithDefaults(options);
 
+  // Store feature flags in context for converter functions
+  if (options.featureFlags) {
+    context.state["featureFlags"] = options.featureFlags;
+  }
+
   if (context.errors.getErrors().length > 0 && opts.errorPolicy === ErrorPolicy.ReturnErrorsOnly) {
     result.errors = context.errors.getErrors().map(x => ({
       Message: x.message
@@ -132,7 +144,9 @@ export async function convertWorkflowTemplate(
   return result;
 }
 
-function getOptionsWithDefaults(options: WorkflowTemplateConverterOptions): Required<WorkflowTemplateConverterOptions> {
+function getOptionsWithDefaults(
+  options: WorkflowTemplateConverterOptions
+): Omit<Required<WorkflowTemplateConverterOptions>, "featureFlags"> {
   return {
     maxReusableWorkflowDepth:
       options.maxReusableWorkflowDepth !== undefined

workflow-parser/src/model/converter/container.test.ts

@@ -0,0 +1,318 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+import {nullTrace} from "../../test-utils/null-trace.js";
+import {parseWorkflow} from "../../workflows/workflow-parser.js";
+import {convertWorkflowTemplate, ErrorPolicy} from "../convert.js";
+
+// Minimal FeatureFlags-compatible object for tests
+const featureFlags = {isEnabled: (f: string) => f === "containerImageValidation"};
+
+async function getErrors(content: string): Promise<string[]> {
+  const result = parseWorkflow({name: "wf.yaml", content}, nullTrace);
+  result.context.state["featureFlags"] = featureFlags;
+  const template = await convertWorkflowTemplate(result.context, result.value!, undefined, {
+    errorPolicy: ErrorPolicy.TryConversion
+  });
+  return (template.errors ?? []).map((e: {Message: string}) => e.Message);
+}
+
+function expectNoContainerErrors(errors: string[]): void {
+  const containerErrors = errors.filter(e => e.includes("Container image"));
+  expect(containerErrors).toHaveLength(0);
+}
+
+function expectContainerError(errors: string[], count = 1): void {
+  const containerErrors = errors.filter(e => e.includes("Container image cannot be empty"));
+  expect(containerErrors).toHaveLength(count);
+}
+
+describe("container image validation", () => {
+  describe("shorthand form", () => {
+    it("container: '' is silent for job container", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container: ''
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("container: docker:// errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container: docker://
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("container: valid-image passes", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container: ubuntu:16.04
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+  });
+
+  describe("mapping form", () => {
+    it("container image: '' errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      image: ''
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("container image: docker:// errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      image: docker://
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("container: {} (empty object, missing image) errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container: {}
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("container image: null errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      image:
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("empty image with expression in other field still errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      image: ''
+      options: \${{ matrix.opts }}
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+  });
+
+  describe("services shorthand", () => {
+    it("services svc: '' errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      svc: ''
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("services svc: docker:// errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      svc: docker://
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+  });
+
+  describe("services mapping", () => {
+    it("services svc image: '' errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      svc:
+        image: ''
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("services svc image: docker:// errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      svc:
+        image: docker://
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("services svc: {} (empty object) errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      svc: {}
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+
+    it("empty image with expression sibling service still errors", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      svc1:
+        image: ''
+      svc2: \${{ matrix.svc }}
+    steps:
+      - run: echo hi`);
+      expectContainerError(errors);
+    });
+  });
+
+  describe("expression safety", () => {
+    it("container: expression skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container: \${{ matrix.container }}
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("container image: expression skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      image: \${{ matrix.image }}
+      options: --privileged
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("container with expression key skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      \${{ vars.KEY }}: ubuntu
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("services: expression skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services: \${{ fromJSON(inputs.services) }}
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("services with expression alias key skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      \${{ matrix.alias }}: postgres
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("services container with expression key skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      db:
+        \${{ vars.KEY }}: postgres
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("container with all expression fields skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    container:
+      image: \${{ matrix.image }}
+      options: \${{ matrix.options }}
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("services svc: expression skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      db: \${{ matrix.db }}
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+
+    it("services image: expression skips validation", async () => {
+      const errors = await getErrors(`on: push
+jobs:
+  build:
+    runs-on: linux
+    services:
+      db:
+        image: \${{ matrix.db_image }}
+        options: --health-cmd pg_isready
+    steps:
+      - run: echo hi`);
+      expectNoContainerErrors(errors);
+    });
+  });
+});

workflow-parser/src/model/converter/container.ts

@@ -1,17 +1,199 @@
+import {FeatureFlags} from "@actions/expressions";
 import {TemplateContext} from "../../templates/template-context.js";
 import {MappingToken, SequenceToken, StringToken, TemplateToken} from "../../templates/tokens/index.js";
 import {isString} from "../../templates/tokens/type-guards.js";
 import {Container, Credential} from "../workflow-template.js";
 
-export function convertToJobContainer(context: TemplateContext, container: TemplateToken): Container | undefined {
+function getFeatureFlags(context: TemplateContext): FeatureFlags | undefined {
+  return context.state["featureFlags"] as FeatureFlags | undefined;
+}
+
+const DOCKER_URI_PREFIX = "docker://";
+
+function isEmptyImage(value: string): boolean {
+  const trimmed = value.startsWith(DOCKER_URI_PREFIX) ? value.substring(DOCKER_URI_PREFIX.length) : value;
+  return trimmed.length === 0;
+}
+
+export function convertToJobContainer(
+  context: TemplateContext,
+  container: TemplateToken,
+  isServiceContainer = false
+): Container | undefined {
+  // Feature flag guard — use legacy implementation when flag is off
+  if (!getFeatureFlags(context)?.isEnabled("containerImageValidation")) {
+    return convertToJobContainerLegacy(context, container);
+  }
+
+  if (container.isExpression) {
+    return;
+  }
+
+  // Shorthand form
+  if (isString(container)) {
+    const image = container.assertString("container item");
+    if (!image || image.value.length === 0) {
+      if (isServiceContainer) {
+        context.error(container, "Container image cannot be empty");
+      }
+      return;
+    }
+
+    if (isEmptyImage(image.value)) {
+      context.error(container, "Container image cannot be empty");
+      return;
+    }
+
+    return {image};
+  }
+
+  // Mapping form
+  const mapping = container.assertMapping("container item");
+  if (!mapping) {
+    return;
+  }
+
+  let image: StringToken | undefined;
+  let env: MappingToken | undefined;
+  let ports: SequenceToken | undefined;
+  let volumes: SequenceToken | undefined;
+  let options: StringToken | undefined;
+  let credentials: Credential | undefined;
+  let hasExpressionKey = false;
+  let hasExpression = false;
+
+  for (const item of mapping) {
+    if (item.key.isExpression) {
+      hasExpressionKey = true;
+      continue;
+    }
+
+    const key = item.key.assertString("container item key");
+
+    switch (key.value) {
+      case "image":
+        if (item.value.isExpression) {
+          hasExpression = true;
+          break;
+        }
+        image = item.value.assertString("container image");
+        break;
+      case "credentials":
+        if (!item.value.isExpression) {
+          credentials = convertCredentials(context, item.value);
+        }
+        break;
+      case "env":
+        if (!item.value.isExpression) {
+          env = item.value.assertMapping("container env");
+        }
+        break;
+      case "ports":
+        if (!item.value.isExpression) {
+          ports = item.value.assertSequence("container ports");
+        }
+        break;
+      case "volumes":
+        if (!item.value.isExpression) {
+          volumes = item.value.assertSequence("container volumes");
+        }
+        break;
+      case "options":
+        if (!item.value.isExpression) {
+          options = item.value.assertString("container options");
+        }
+        break;
+      default:
+        context.error(key, `Unexpected container item key: ${key.value}`);
+    }
+  }
+
+  // Validate image
+  if (image) {
+    if (isEmptyImage(image.value)) {
+      context.error(image, "Container image cannot be empty");
+      return;
+    }
+    return {image, credentials, env, ports, volumes, options};
+  }
+
+  // No image key — skip error if expression keys could provide one
+  if (!hasExpressionKey && !hasExpression) {
+    context.error(container, "Container image cannot be empty");
+  }
+}
+
+export function convertToJobServices(context: TemplateContext, services: TemplateToken): Container[] | undefined {
+  // Feature flag guard — use legacy implementation when flag is off
+  if (!getFeatureFlags(context)?.isEnabled("containerImageValidation")) {
+    return convertToJobServicesLegacy(context, services);
+  }
+
+  if (services.isExpression) {
+    return;
+  }
+
+  const serviceList: Container[] = [];
+  const mapping = services.assertMapping("services");
+
+  for (const service of mapping) {
+    if (service.key.isExpression) {
+      continue;
+    }
+
+    service.key.assertString("service key");
+    const container = convertToJobContainer(context, service.value, true);
+    if (container) {
+      serviceList.push(container);
+    }
+  }
+
+  return serviceList;
+}
+
+function convertCredentials(context: TemplateContext, value: TemplateToken): Credential | undefined {
+  const mapping = value.assertMapping("credentials");
+  if (!mapping) {
+    return;
+  }
+
+  let username: StringToken | undefined;
+  let password: StringToken | undefined;
+
+  for (const item of mapping) {
+    if (item.key.isExpression) {
+      continue;
+    }
+
+    const key = item.key.assertString("credentials item");
+    if (item.value.isExpression) {
+      continue;
+    }
+
+    switch (key.value) {
+      case "username":
+        username = item.value.assertString("credentials username");
+        break;
+      case "password":
+        password = item.value.assertString("credentials password");
+        break;
+      default:
+        context.error(key, `credentials key ${key.value}`);
+    }
+  }
+
+  return {username, password};
+}
+
+// ===== Legacy implementations (remove when containerImageValidation graduates) =====
+
+function convertToJobContainerLegacy(context: TemplateContext, container: TemplateToken): Container | undefined {
   let image: StringToken | undefined;
   let env: MappingToken | undefined;
   let ports: SequenceToken | undefined;
   let volumes: SequenceToken | undefined;
   let options: StringToken | undefined;
 
-  // Skip validation for expressions for now to match
-  // behavior of the other parsers
   for (const [, token] of TemplateToken.traverse(container)) {
     if (token.isExpression) {
       return;
@@ -19,7 +201,6 @@ export function convertToJobContainer(context: TemplateContext, container: Templ
   }
 
   if (isString(container)) {
-    // Workflow uses shorthand syntax `container: image-name`
     image = container.assertString("container item");
     return {image: image};
   }
@@ -35,7 +216,7 @@ export function convertToJobContainer(context: TemplateContext, container: Templ
           image = value.assertString("container image");
           break;
         case "credentials":
-          convertToJobCredentials(context, value);
+          convertToJobCredentialsLegacy(context, value);
           break;
         case "env":
           env = value.assertMapping("container env");
@@ -70,13 +251,13 @@ export function convertToJobContainer(context: TemplateContext, container: Templ
   }
 }
 
-export function convertToJobServices(context: TemplateContext, services: TemplateToken): Container[] | undefined {
+function convertToJobServicesLegacy(context: TemplateContext, services: TemplateToken): Container[] | undefined {
   const serviceList: Container[] = [];
 
   const mapping = services.assertMapping("services");
   for (const service of mapping) {
     service.key.assertString("service key");
-    const container = convertToJobContainer(context, service.value);
+    const container = convertToJobContainerLegacy(context, service.value);
     if (container) {
       serviceList.push(container);
     }
@@ -84,7 +265,7 @@ export function convertToJobServices(context: TemplateContext, services: Templat
   return serviceList;
 }
 
-function convertToJobCredentials(context: TemplateContext, value: TemplateToken): Credential | undefined {
+function convertToJobCredentialsLegacy(context: TemplateContext, value: TemplateToken): Credential | undefined {
   const mapping = value.assertMapping("credentials");
 
   let username: StringToken | undefined;

workflow-parser/src/model/converter/job.ts

@@ -50,7 +50,7 @@ export function convertJob(context: TemplateContext, jobKey: StringToken, token:
         break;
 
       case "container":
-        convertToJobContainer(context, item.value);
+        handleTemplateTokenErrors(item.value, context, undefined, () => convertToJobContainer(context, item.value));
         container = item.value;
         break;
 
@@ -103,7 +103,7 @@ export function convertJob(context: TemplateContext, jobKey: StringToken, token:
         break;
 
       case "services":
-        convertToJobServices(context, item.value);
+        handleTemplateTokenErrors(item.value, context, undefined, () => convertToJobServices(context, item.value));
         services = item.value;
         break;
 

workflow-parser/src/workflow-v1.0.json

@@ -2172,7 +2172,7 @@
       }
     },
     "step-uses": {
-      "description": "Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.",
+      "description": "Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, a [private repository with access enabled](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository), or in a published Docker container image.",
       "string": {
         "require-non-empty": true
       }
@@ -2345,7 +2345,7 @@
       "mapping": {
         "properties": {
           "image": {
-            "type": "non-empty-string",
+            "type": "string",
             "description": "Use `jobs.<job_id>.container.image` to define the Docker image to use as the container to run the action. The value can be the Docker Hub image or a registry name."
           },
           "options": {
@@ -2390,7 +2390,7 @@
         "matrix"
       ],
       "one-of": [
-        "non-empty-string",
+        "string",
         "container-mapping"
       ]
     },

workflow-parser/testdata/skipped-tests.txt

@@ -91,3 +91,4 @@ yaml-schema-sequence.yml
 yaml-schema-str-flow-styles.yml
 yaml-schema-string.yml
 yaml-schema-timestamp.yml
+job-container-invalid.yml