docs: update images stanza to new items format

content/en/architecture/ci-operator.md

@@ -195,26 +195,49 @@ artifacts in `pipeline:bin` and the output image base is replaced with the appro
 
 {{< highlight yaml >}}
 images:
-- dockerfile_path: "Dockerfile" # this is a relative path from the root of the repository to the multi-stage Dockerfile
-  from: "base" # a reference to the named base_image, used to replace the last FROM image in the Dockerfile
-  inputs:
-    bin: # declares that the "bin" tag is used as the builder image when overwriting that FROM instruction
-      as:
-      - "registry.ci.openshift.org/ocp/builder:golang-1.13"
-  to: "mycomponent" # names the output container image "mycomponent"
-- dockerfile_path: "tests/Dockerfile"
-  from: "test-bin" # base the build off of the built test binaries
-  inputs:
-    cli:
-      paths:
-      - destination_dir: "."
-        source_path: "/go/bin/oc" # inject the OpenShift clients into the build context directory
-  to: "mytests" # names the output container image "mytests"
-- dockerfile_literal: |- # Trivial dockerfiles can just be inlined
-    FROM base
-    RUN yum install -y python2
-  from: "test-bin"
-  to: test-bin-with-python2
+  items:
+  - dockerfile_path: "Dockerfile" # this is a relative path from the root of the repository to the multi-stage Dockerfile
+    from: "base" # a reference to the named base_image, used to replace the last FROM image in the Dockerfile
+    inputs:
+      bin: # declares that the "bin" tag is used as the builder image when overwriting that FROM instruction
+        as:
+        - "registry.ci.openshift.org/ocp/builder:golang-1.13"
+    to: "mycomponent" # names the output container image "mycomponent"
+  - dockerfile_path: "tests/Dockerfile"
+    from: "test-bin" # base the build off of the built test binaries
+    inputs:
+      cli:
+        paths:
+        - destination_dir: "."
+          source_path: "/go/bin/oc" # inject the OpenShift clients into the build context directory
+    to: "mytests" # names the output container image "mytests"
+  - dockerfile_literal: |- # Trivial dockerfiles can just be inlined
+      FROM base
+      RUN yum install -y python2
+    from: "test-bin"
+    to: test-bin-with-python2
+{{< / highlight >}}
+
+The `images` stanza supports optional fields to control when the auto-generated `-images` presubmit and postsubmit jobs
+should run. These fields work the same way as the equivalent fields in the `tests` stanza:
+
+* `run_if_changed` Set a regex to trigger the images job only when a pull request changes a matching path.
+* `skip_if_only_changed` Set a regex to skip the images job when all changes in the pull request match.
+* `pipeline_run_if_changed` Like `run_if_changed`, but operates on the pipeline graph instead of Prow.
+* `pipeline_skip_if_only_changed` Like `skip_if_only_changed`, but operates on the pipeline graph instead of Prow.
+* `build_if_affected` Set to `true` to only build images when the build graph is affected by the changes.
+
+**Note:** `run_if_changed`, `skip_if_only_changed`, `pipeline_run_if_changed`, and `pipeline_skip_if_only_changed` are mutually exclusive.
+
+For example, to skip building images when only documentation files change:
+
+{{< highlight yaml >}}
+images:
+  skip_if_only_changed: ^docs/|\.md$|^OWNERS$
+  items:
+  - dockerfile_path: "Dockerfile"
+    from: "base"
+    to: "mycomponent"
 {{< / highlight >}}
 
 By making use of the previously compiled artifacts in the intermediate `pipeline:bin` image, this repository is able to
@@ -231,27 +254,29 @@ Images substitution can happen in one of the following ways:
 - in a `--from=` argument:
 ```yaml
 images:
-- dockerfile_literal: |
-    # ...
-    COPY --from=nginx:latest /tmp/dummy /tmp/dummy
-  inputs:
-    bin:
-      as:
-      - nginx:latest
+  items:
+  - dockerfile_literal: |
+      # ...
+      COPY --from=nginx:latest /tmp/dummy /tmp/dummy
+    inputs:
+      bin:
+        as:
+        - nginx:latest
 ```
-`nginx:latest` is going to be replaced with `pipeline:bin`  
+`nginx:latest` is going to be replaced with `pipeline:bin`
 
 - in a `FROM` directive:
 ```yaml
 images:
-- dockerfile_literal: |
-    FROM nginx:latest AS builder 
-    # ...
-    COPY --from=builder /tmp/dummy /tmp/dummy
-  inputs:
-    bin:
-      as:
-      - nginx:latest
+  items:
+  - dockerfile_literal: |
+      FROM nginx:latest AS builder
+      # ...
+      COPY --from=builder /tmp/dummy /tmp/dummy
+    inputs:
+      bin:
+        as:
+        - nginx:latest
 ```
 `nginx:latest` is going to be replaced with `pipeline:bin`
 
@@ -270,19 +295,21 @@ base_images:
     tag: rhel-9-golang-1.24-openshift-4.21
 
 images:
-- dockerfile_path: Dockerfile
-  inputs:
-    ocp_builder_rhel-9-golang-1.24-openshift-4.21:
-      as:
-      - registry.ci.openshift.org/ocp/builder:rhel-9-golang-1.24-openshift-4.21
-  to: my-component
+  items:
+  - dockerfile_path: Dockerfile
+    inputs:
+      ocp_builder_rhel-9-golang-1.24-openshift-4.21:
+        as:
+        - registry.ci.openshift.org/ocp/builder:rhel-9-golang-1.24-openshift-4.21
+    to: my-component
 ```
 
 **After (auto-detected):**
 ```yaml
 images:
-- dockerfile_path: Dockerfile
-  to: my-component
+  items:
+  - dockerfile_path: Dockerfile
+    to: my-component
 ```
 
 The Dockerfile's `FROM registry.ci.openshift.org/ocp/builder:rhel-9-golang-1.24-openshift-4.21` is automatically detected and configured at build time.
@@ -294,14 +321,15 @@ The `build_args` option in `ci-operator` configuration specifies a list of [buil
 
 ```yaml
 images:
-- build_args:
-    - name: product
-      value: okd
-  dockerfile_literal: |-
-    FROM centos:8
-    ARG product=ocp
-  from: os
-  to: test-image
+  items:
+  - build_args:
+      - name: product
+        value: okd
+    dockerfile_literal: |-
+      FROM centos:8
+      ARG product=ocp
+    from: os
+    to: test-image
 ```
 
 ## How Builds Work In CI
@@ -310,7 +338,7 @@ Every container image built in CI is implemented by
 `ci-operator` uses the parameters in the `images` stanza from the configuration file to define `builds` options on CI clusters.
 
 
-| `images`              | `build`                                        |
+| `images.items[]`      | `build`                                        |
 |-----------------------|------------------------------------------------|
 | `.build_args`         | `.spec.strategy.dockerStrategy.buildArgs`      |
 | `.dockerfile_literal` | `.spec.source.dockerfile`                      |

content/en/architecture/images.md

@@ -21,13 +21,14 @@ base_images:
     namespace: ocp
     tag: rhel-8-golang-1.15-openshift-4.6
 images:
-- dockerfile_path: Dockerfile.rhel7
-  from: base
-  inputs:
-    ocp_builder_rhel-8-golang-1.15-openshift-4.6:
-      as:
-      - registry.ci.openshift.org/ocp/builder:rhel-8-golang-1.15-openshift-4.6
-  to: cluster-etcd-operator
+  items:
+  - dockerfile_path: Dockerfile.rhel7
+    from: base
+    inputs:
+      ocp_builder_rhel-8-golang-1.15-openshift-4.6:
+        as:
+        - registry.ci.openshift.org/ocp/builder:rhel-8-golang-1.15-openshift-4.6
+    to: cluster-etcd-operator
 ```
 
 This build uses a build manifest at `Dockerfile.rhel7` in the repository, which looks like:

content/en/getting-started/examples.md

@@ -67,9 +67,10 @@ promotion:
     namespace: ocp
     name: 4.4
 images:
-- from: ubi8
-  to: component # promotes "component" by default
-  context_dir: images/component
+  items:
+  - from: ubi8
+    to: component # promotes "component" by default
+    context_dir: images/component
 {{< / highlight >}}
 
 ## Consuming an Image

content/en/how-tos/multi-architecture.md

@@ -17,11 +17,12 @@ base_images:
     namespace: ocp
     tag: "9"
 images:
-- context_dir: .
-  from: os
-  to: my-image
-  additional_architectures:
-  - arm64
+  items:
+  - context_dir: .
+    from: os
+    to: my-image
+    additional_architectures:
+    - arm64
 ```
 
 In the above example, the `os` image defined in the `base_images` is used as a base to build the `my-image` image.

content/en/how-tos/nested-podman.md

@@ -85,24 +85,25 @@ build_root:
     name: ci-tools-build-root
     tag: "1.23"
 images:
-# Use the `nested-podman` as a base image for the e2e test.
-# Copy the source code and the oc binary into it.
-- from: nested-podman
-  dockerfile_literal: |
-      FROM nested-podman
-      COPY oc /usr/bin/oc
-      COPY src/ /opt/app-root/src/
-      WORKDIR /opt/app-root/src
-  inputs:
-    cli:
-      paths:
-      - destination_dir: .
-        source_path: /usr/bin/oc
-    src:
-      paths:
-      - destination_dir: src/
-        source_path: /go/src/github.com/openshift/ci-tools
-  to: e2e-image
+  items:
+  # Use the `nested-podman` as a base image for the e2e test.
+  # Copy the source code and the oc binary into it.
+  - from: nested-podman
+    dockerfile_literal: |
+        FROM nested-podman
+        COPY oc /usr/bin/oc
+        COPY src/ /opt/app-root/src/
+        WORKDIR /opt/app-root/src
+    inputs:
+      cli:
+        paths:
+        - destination_dir: .
+          source_path: /usr/bin/oc
+      src:
+        paths:
+        - destination_dir: src/
+          source_path: /go/src/github.com/openshift/ci-tools
+    to: e2e-image
 resources:
   '*':
     requests:

content/en/how-tos/testing-operator-sdk-operators.md

@@ -45,8 +45,9 @@ base_images:
     name: "redhat-operator-index"
     tag: "v4.7"
 images:
-- from: "ubi"
-  to: "tested-operator"
+  items:
+  - from: "ubi"
+    to: "tested-operator"
 operator:
   bundles: # entries create bundle images from Dockerfiles and an index containing all bundles
   - as: my-bundle

content/en/how-tos/use-registries-in-build-farm.md

@@ -198,9 +198,10 @@ for each image that is promoted:
 
 ```yaml
 images:
-- dockerfile_path: images/my-component
-  from: base
-  to: my-component
+  items:
+  - dockerfile_path: images/my-component
+    from: base
+    to: my-component
 promotion:
   to:
   - name: "4.7"
@@ -220,9 +221,10 @@ for each image that is promoted, with the named tag in each stream:
 
 ```yaml
 images:
-- dockerfile_path: images/my-component
-  from: base
-  to: my-component
+  items:
+  - dockerfile_path: images/my-component
+    from: base
+    to: my-component
 promotion:
   to:
   - namespace: my-organization

content/en/internals/steps.md

@@ -24,9 +24,10 @@ base_images:
 binary_build_commands: # …
 build_root: # …
 images:
-- from: os
-  to: ci-operator
-  # …
+  items:
+  - from: os
+    to: ci-operator
+    # …
 test_binary_build_commands: # …
 tests:
 - as: unit