📚 Sync docs from alaudadevops/tektoncd-operator on 09aba9d56f81394581a0ce5c32155dc88870c2f8

Source: feat: [DEVOPS-42788] support multi-version images for catalog Tasks (#875)
Author: yzc
Ref: refs/heads/main
Commit: 09aba9d56f81394581a0ce5c32155dc88870c2f8

This commit automatically syncs documentation changes from the source-docs repository.

🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/09aba9d56f81394581a0ce5c32155dc88870c2f8
🤖 Synced on 2025-12-04 09:03:38 UTC

Author: edge-katanomi-app2[bot]

.github/SYNC_INFO.md

@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-12-02 14:33:58 UTC
+- **Last synced**: 2025-12-04 09:03:38 UTC
 - **Source repository**: alaudadevops/tektoncd-operator
-- **Source commit**: [a90e048c6ebe4f7738049c98aba9c8c05e17a4b4](https://github.com/alaudadevops/tektoncd-operator/commit/a90e048c6ebe4f7738049c98aba9c8c05e17a4b4)
+- **Source commit**: [09aba9d56f81394581a0ce5c32155dc88870c2f8](https://github.com/alaudadevops/tektoncd-operator/commit/09aba9d56f81394581a0ce5c32155dc88870c2f8)
 - **Triggered by**: edge-katanomi-app2[bot]
-- **Workflow run**: [#106](https://github.com/alaudadevops/tektoncd-operator/actions/runs/19862247353)
+- **Workflow run**: [#107](https://github.com/alaudadevops/tektoncd-operator/actions/runs/19923390282)
 
 ## Files synced:
 - docs/

docs/en/development/catalog/convention.md

@@ -108,12 +108,60 @@ spec:
       memory: "4Gi"
 ```
 
-### 4. Building Custom Images with Dependencies
+### 4. Image Management for Catalog Tasks
 
-If Tasks in the catalog depend on custom images, we need to provide `Dockerfile` and build pipelines in the catalog.
+Catalog Tasks that expose configurable runtime images must publish metadata and defaults consistently so the UI and controllers can discover them.
 
-- Build environments are stored in the `images/{image-name}` directory
-- Image build pipeline orchestration files are stored in `.tekton/images/build-{image-name}.yaml`
+#### Configurable Image Metadata
+
+Represent each image option with a single `ConfigMap` scoped to one Task and one Task version. Include the human-readable name and full image reference, and add labels so the UI/controller can filter by Task/version.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: tekton-task-go-1-25
+  namespace: kube-public
+  labels:
+    catalog.tekton.dev/source: system
+    catalog.tekton.dev/tool-image-golang: 1.25
+    catalog.tekton.dev/tool-image-run-script: go-1.25
+data:
+  name: "Go 1.25"
+  image: "registry.example.com/tekton/golang:1.25"
+```
+
+Key fields and labels:
+- `data.name`: dropdown label.
+- `data.image`: full image reference.
+- `catalog.tekton.dev/source`: identifies the source.
+- `catalog.tekton.dev/tool-image-<tool>`: identifies the tool image for the Task.
+- `catalog.tekton.dev/tool-image-run-script`: identifies the tool image for `run-script` Task.
+
+#### Catalog Defaults and Tagging
+
+- Keep existing `image` parameter defaults in Tasks; do not clear them.
+- Use minor-only tags for catalog images (for example, `v7.0`) and publish a `latest` alias for the newest minor release.
+- Publish one `ConfigMap` per runtime version with `name` and `image` data plus Task/version labels; keep defaults on the current minor until a new Task minor is added.
+- When introducing a new runtime minor (for example, Python 3.14), keep the older Task minor default on the previous image (3.13), add a new Task minor with no default image to force explicit selection, and add the corresponding per-version `ConfigMap` entries.
+
+  ```yaml
+  global:
+    images:
+      python-3_13:
+        repository: devops/tektoncd/hub/python
+        tag: v3.13
+      python-latest:
+        repository: devops/tektoncd/hub/python
+        tag: latest
+  ```
+
+#### Custom Image Builds
+
+If Tasks in the catalog depend on custom images, provide the `Dockerfile` and build pipelines in the catalog so they can be reproduced.
+
+- Build environments are stored in the `images/{image-name}` directory.
+- Image build pipeline orchestration files are stored in `.tekton/images/build-{image-name}.yaml`.
 
 #### Image Security
 
@@ -136,11 +184,7 @@ If Tasks in the catalog depend on custom images, we need to provide `Dockerfile`
 
 #### Image Tags
 
-If the image is custom, you can directly use the version number generated by `git-version` in the pipeline as the Tag.
-
-If the image is customized based on a specific community version, it is recommended to add the community version number as a prefix in the Tag. For example, `v0.56.0-{version}`
-
-In the pipeline, you can specify the image prefix by configuring the `tag-prefix` parameter.
+Follow the catalog tagging strategy above for custom builds (minor-only tags plus a `latest` alias). If the image is derived from a specific community version, include that upstream version in the tag prefix when needed for traceability (for example, `v0.56.0-v7.0`).
 
 #### Image Path
 

docs/en/teps/catalog/0005-configurable-task-images.md

@@ -226,13 +226,11 @@ Required labels (example keys shown above):
   ```yaml
   global:
     images:
-      python-3.13:
+      python-3_13:
         repository: devops/tektoncd/hub/python
-        digest: sha256:c603e490c552823f9361cbd7fde2f2b374ec66f2b1175b3871ec9dc474c36bff
         tag: v3.13
       python-latest:
         repository: devops/tektoncd/hub/python
-        digest: sha256:c603e490c552823f9361cbd7fde2f2b374ec66f2b1175b3871ec9dc474c36bff
         tag: latest
   ```