feat: support image.docker.platform

Adds support for `image.docker.platform` per GitLab CI spec (introduced
in GitLab 18.0). The platform string is forwarded to both:

- `docker pull --platform <platform>` to fetch the requested manifest
- `docker run --platform <platform>` so the container runs against
  that platform even if a multi-arch image was already cached locally

Mirrors the existing `image.docker.user` plumbing.

Refs https://docs.gitlab.com/ci/yaml/#imagedockerplatform — supersedes
the abandoned attempt in #1595 (closed for missing tests + style).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: inistor

src/data-expander.ts

@@ -188,7 +188,7 @@ export function imageComplex (data: any) {
     return {
         name: typeof data === "string" ? data : data.name,
         entrypoint: data.entrypoint,
-        ...(data.docker?.user ? {docker: {user: data.docker?.user}} : {}),
+        ...(data.docker?.user || data.docker?.platform ? {docker: {user: data.docker.user, platform: data.docker.platform}} : {}),
     };
 }
 

src/job.ts

@@ -670,6 +670,7 @@ If you know what you're doing and would like to suppress this warning, use one o
         this._dotenvVariables = await this.initProducerReportsDotenvVariables(writeStreams, Utils.expandVariables(this._variables));
         const expanded = Utils.unscape$$Variables(Utils.expandVariables({...this._variables, ...this._dotenvVariables}));
         const imageName = this.imageName(expanded);
+        const imagePlatform = this.imagePlatform(expanded);
         const helperImageName = argv.helperImage;
         const safeJobName = this.safeJobName;
 
@@ -682,7 +683,7 @@ If you know what you're doing and would like to suppress this warning, use one o
         }
 
         if (imageName) {
-            await this.pullImage(writeStreams, imageName);
+            await this.pullImage(writeStreams, imageName, imagePlatform);
 
             const buildVolumeName = this.buildVolumeName;
             const tmpVolumeName = this.tmpVolumeName;
@@ -971,6 +972,11 @@ If you know what you're doing and would like to suppress this warning, use one o
                 dockerCmd += `--user ${imageUser} `;
             }
 
+            const imagePlatform = this.imagePlatform(expanded);
+            if (imagePlatform) {
+                dockerCmd += `--platform ${imagePlatform} `;
+            }
+
             if (this.argv.containerEmulate) {
                 const runnerName: string = this.argv.containerEmulate;
 
@@ -1207,6 +1213,13 @@ If you know what you're doing and would like to suppress this warning, use one o
         return Utils.expandText(image["docker"]["user"], vars);
     }
 
+    private imagePlatform (vars: {[key: string]: string} = {}): string | null {
+        const image = this.jobData["image"];
+        if (!image) return null;
+        if (!image["docker"]) return null;
+        return Utils.expandText(image["docker"]["platform"], vars);
+    }
+
     get imageEntrypoint (): string[] | null {
         const image = this.jobData["image"];
 
@@ -1235,14 +1248,16 @@ If you know what you're doing and would like to suppress this warning, use one o
         }
     }
 
-    private async pullImage (writeStreams: WriteStreams, imageToPull: string) {
+    private async pullImage (writeStreams: WriteStreams, imageToPull: string, imagePlatform: string | null = null) {
         const pullPolicy = this.argv.pullPolicy;
+        const platformArgs = imagePlatform ? ["--platform", imagePlatform] : [];
+        const platformSuffix = imagePlatform ? ` (${imagePlatform})` : "";
         const actualPull = async () => {
             await this.validateCiDependencyProxyServerAuthentication(imageToPull);
             const time = process.hrtime();
-            await Utils.spawn([this.argv.containerExecutable, "pull", imageToPull]);
+            await Utils.spawn([this.argv.containerExecutable, "pull", imageToPull, ...platformArgs]);
             const endTime = process.hrtime(time);
-            writeStreams.stdout(chalk`${this.formattedJobName} {magentaBright pulled} ${imageToPull} in {magenta ${prettyHrtime(endTime)}}\n`);
+            writeStreams.stdout(chalk`${this.formattedJobName} {magentaBright pulled} ${imageToPull}${platformSuffix} in {magenta ${prettyHrtime(endTime)}}\n`);
             this.refreshLongRunningSilentTimeout(writeStreams);
         };
 

tests/test-cases/image/.gitlab-ci.yml

@@ -64,6 +64,14 @@ image-user:
   script:
     - id -u
 
+image-platform:
+  image:
+    name: alpine
+    docker:
+      platform: linux/amd64
+  script:
+    - uname -m
+
 image-entrypoint-with-variables:
   variables:
     FOO: BAR

tests/test-cases/image/integration.test.ts

@@ -128,6 +128,27 @@ test.concurrent("image <image-user>", async () => {
     expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining(expected));
 });
 
+test.concurrent("image <image-platform>", async () => {
+    const writeStreams = new WriteStreamsMock();
+
+    await handler({
+        pullPolicy: "always",
+        cwd: "tests/test-cases/image",
+        job: ["image-platform"],
+        stateDir: ".gitlab-ci-local-image-platform",
+    }, writeStreams);
+
+    // The "pulled" log line includes the requested platform, proving --platform
+    // was forwarded to `docker pull` rather than silently dropped. Use `.*` to
+    // span the chalk ANSI escape codes between tokens.
+    expect(writeStreams.stdoutLines.join("\n")).toMatch(/pulled.*alpine.*linux\/amd64/);
+
+    // The job runs successfully on the host (linux/amd64 matches the CI runner arch).
+    expect(writeStreams.stdoutLines).toEqual(expect.arrayContaining([
+        chalk`{blueBright image-platform} {greenBright >} x86_64`,
+    ]));
+});
+
 test.concurrent("pull invalid image", async () => {
     const jobs: Job[] = [];
     const writeStreams = new WriteStreamsMock();