📚 Sync docs from alaudadevops/tektoncd-operator on 6a52ba9076729c8028c8284f7f02be7e74521124

edge-katanomi-app2[bot] · edge-katanomi-app2[bot] · commit 0cc213532693 · 2025-10-16T01:36:24.000Z
Source: docs: [DEVOPS-42384] add how-to docs for output markdown to the overview tab (#654) Author: yzc Ref: refs/heads/main Commit: 6a52ba9076729c8028c8284f7f02be7e74521124 This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: https://github.com/alaudadevops/tektoncd-operator/commit/6a52ba9076729c8028c8284f7f02be7e74521124 🤖 Synced on 2025-10-16 01:36:24 UTC
diff --git a/.github/SYNC_INFO.md b/.github/SYNC_INFO.md
@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-10-15 09:57:30 UTC
+- **Last synced**: 2025-10-16 01:36:24 UTC
 - **Source repository**: alaudadevops/tektoncd-operator
-- **Source commit**: [d8fd3e3edacc2e77fb8df195aa6130e0620eab8a](https://github.com/alaudadevops/tektoncd-operator/commit/d8fd3e3edacc2e77fb8df195aa6130e0620eab8a)
+- **Source commit**: [6a52ba9076729c8028c8284f7f02be7e74521124](https://github.com/alaudadevops/tektoncd-operator/commit/6a52ba9076729c8028c8284f7f02be7e74521124)
 - **Triggered by**: edge-katanomi-app2[bot]
-- **Workflow run**: [#85](https://github.com/alaudadevops/tektoncd-operator/actions/runs/18525047159)
+- **Workflow run**: [#86](https://github.com/alaudadevops/tektoncd-operator/actions/runs/18547555465)
 
 ## Files synced:
 - docs/
diff --git a/docs/en/pipelines/how_to/output-markdown-to-the-overview-tab.mdx b/docs/en/pipelines/how_to/output-markdown-to-the-overview-tab.mdx
@@ -0,0 +1,185 @@
+---
+weight: 10
+i18n:
+  title:
+    en: Output Markdown to the Overview Tab (PipelineRuns & TaskRuns)
+    zh: 输出 Markdown 到 Overview 标签（PipelineRuns & TaskRuns）
+title: Output Markdown to the Overview Tab (PipelineRuns & TaskRuns)
+---
+
+# Output Markdown to the Overview Tab (PipelineRuns & TaskRuns)
+
+This guide shows you how to surface human‑readable reports in the **Overview** tab of both **PipelineRuns** and **TaskRuns** by writing Markdown into a Task **Result** named `overview-markdown`.
+
+## Prerequisites
+
+- **Tekton Pipelines** installed on your cluster.
+- **Optional but recommended:** **Tekton Results** deployed so your summaries remain queryable even after old TaskRuns/PipelineRuns are garbage‑collected.
+
+> Why Tekton Results? If your cluster prunes runs aggressively, the in‑cluster TaskRun/PipelineRun objects (and their results) may disappear. Tekton Results provides a central store so historical Overview reports remain accessible.
+
+## How it works
+
+- The UI reads a Task's **result** with the **exact name** `overview-markdown`.
+- Whatever Markdown you write into that result file will be rendered in the run's **Overview** tab.
+- In a Pipeline, **each Task** can produce its own `overview-markdown`, and the Overview tab shows them grouped by Task.
+- You **do not** need to write to a **Pipeline** result for the Overview tab; write to the **Task's** `overview-markdown` instead.
+
+> **Limits:** A single Task's result value is limited to **4 KB** by default. Keep summaries concise; link out to larger artifacts when needed. If you want to configure the result size limit, you can refer to [Result Limit Exceeded When Writing Tekton Task Results](../trouble_shooting/result-limit-exceeded.mdx).
+
+## Steps
+
+### 1. Define a Task result named `overview-markdown`
+
+Create (or update) your Task so it declares a string result with that exact name.
+
+In one of the Task's steps, write Markdown to `$(results.overview-markdown.path)`.
+
+Example Task (replace `<image>` as needed):
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: demo-markdown-overview
+spec:
+  results:
+    - name: overview-markdown
+      description: "Markdown content displayed in the Overview tab."
+      type: string
+  steps:
+    - name: write-markdown
+      image: <image>
+      script: |
+        #!/bin/bash
+        # Write Markdown to the result path.
+        cat >"$(results.overview-markdown.path)" <<'EOF'
+        # Demo Overview
+
+        **Status:** ✅ Success
+
+        **Artifacts**
+        - Image: `ghcr.io/example/app:v1.2.3`
+        - SBOM: `sbom.spdx.json`
+
+        **Notes**
+        - Lint passed.
+        - 0 critical vulnerabilities found.
+
+        _Generated by **demo-markdown-overview**._
+        EOF
+```
+
+Keep the Markdown short and focused. A single Task's result value is limited to **4 KB** by default. For long reports:
+
+- Upload the full artifact (e.g., HTML, JSON, PDF) to your storage or artifact repository.
+- Put a link in the Markdown (e.g., `[Full report](https://artifact.example.com/run/123/report.html)`).
+
+If you want to configure the result size limit, you can refer to [Result Limit Exceeded When Writing Tekton Task Results](../trouble_shooting/result-limit-exceeded.mdx).
+
+### 2. Run the Task
+
+Create a TaskRun referencing your Task, wait for it to complete.
+
+Example TaskRun:
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  name: demo-markdown-overview-run
+spec:
+  taskRef:
+    name: demo-markdown-overview
+```
+
+### 3. View the overview
+
+After TaskRun completes, open the TaskRun's **Overview** tab to see the rendered Markdown.
+
+If nothing renders, check the step logs to confirm the file was written to `$(results.overview-markdown.path)` and that the result name is correct.
+
+### 4. (Optional) Use it in Pipelines
+
+In a Pipeline, each Task can output its **own** `overview-markdown`. The Overview tab will display separate sections per Task (e.g., `lint`, `scan`, `build`).
+
+You **do not** need to the **Pipeline**'s results for this feature. Only **Task** results are rendered in the Overview tab.
+
+Example Pipeline (replace `<lint-image>` `<scan-image>` as needed):
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Pipeline
+metadata:
+  name: pipeline-with-summaries
+spec:
+  tasks:
+    - name: lint
+      taskSpec:
+        results:
+          - name: overview-markdown
+            description: "Lint overview"
+            type: string
+        steps:
+          - name: run-lint
+            image: <lint-image>
+            script: |
+              #!/bin/bash
+              cat >"$(results.overview-markdown.path)" <<'EOF'
+              ## Lint Overview
+
+              - Files checked: **128**
+              - Issues: **0**
+              - Tool: `golangci-lint 1.57.2`
+              EOF
+
+    - name: scan
+      runAfter: [lint]
+      taskSpec:
+        results:
+          - name: overview-markdown
+            description: "Security scan overview"
+            type: string
+        steps:
+          - name: run-scan
+            image: <scan-image>
+            script: |
+              #!/bin/bash
+              cat >"$(results.overview-markdown.path)" <<'EOF'
+              ## Security Scan
+
+              **Findings**
+              - Critical: **0**
+              - High: **1** (CVE-2025-XXXX)
+              - Medium: **3**
+              EOF
+```
+
+Example PipelineRun:
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  name: pipeline-with-summaries-run
+spec:
+  pipelineRef:
+    name: pipeline-with-summaries
+```
+
+Open the PipelineRun's **Overview** tab. You should see two Markdown sections: **lint** and **scan**.
+
+## Tips
+
+- **Exact name matters:** The result must be named `overview-markdown` (case‑sensitive).
+- **Write to the right place:** Always write to `$(results.overview-markdown.path)`. You don't need a Pipeline‑level result.
+- **Size limit:** A single Task result value is capped at **4 KB** by default. If you want to configure the result size limit, you can refer to [Result Limit Exceeded When Writing Tekton Task Results](../trouble_shooting/result-limit-exceeded.mdx).
+
+## Troubleshooting
+
+- **Nothing shows in the Overview tab**
+  - Check the result name: it must be exactly `overview-markdown`.  
+  - Verify the step wrote to `$(results.overview-markdown.path)`.  
+  - Confirm your UI version supports this feature.
+- **Pod logs show termination message overflow**
+  - Refer to [Result Limit Exceeded When Writing Tekton Task Results](../trouble_shooting/result-limit-exceeded.mdx).
diff --git a/docs/en/pipelines/trouble_shooting/result-limit-exceeded.mdx b/docs/en/pipelines/trouble_shooting/result-limit-exceeded.mdx
@@ -0,0 +1,69 @@
+---
+weight: 10
+i18n:
+  title:
+    en: Result Limit Exceeded When Writing Tekton Task Results
+    zh: Tekton 任务结果写入限制
+title: Result Limit Exceeded When Writing Tekton Task Results
+---
+
+# Result Limit Exceeded When Writing Tekton Task Results
+
+## Problem Description
+
+When a Task step writes relatively large content into a **Task result**, the output may fail due to size limits.
+
+### Error Manifestation
+
+- **Pod logs show termination message overflow** (result too large for default 4 KB cap):
+
+  ```text
+  2025/10/15 03:22:24 ERROR Error while substituting step artifacts: error="Termination message is above max allowed size 4096, caused by large task result."
+  2025/10/15 03:22:24 Termination message is above max allowed size 4096, caused by large task result.
+  ```
+
+## Root Cause Analysis
+
+By default, Tekton Pipelines captures Task results through the container **termination message**, which Kubernetes limits to **4 KB**.
+This effectively caps a single Task's usable result size to **4096 bytes**.
+
+To lift that ceiling, Tekton supports reading results from **sidecar logs**, where a configurable `max-result-size` is applied **per result**.
+
+## Troubleshooting
+
+Following are the steps to configure the result size limit:
+
+1. Edit the TektonConfig resource by setting `spec.pipeline.results-from` and `spec.pipeline.max-result-size` as shown below:
+
+   ```yaml
+   apiVersion: operator.tekton.dev/v1alpha1
+   kind: TektonConfig
+   metadata:
+     name: config
+   spec:
+     pipeline:
+       # Use sidecar logs instead of termination messages
+       results-from: sidecar-logs
+       # Result size in bytes (example: 64 KiB). Max is 1,572,863 bytes.
+       max-result-size: 65536
+   ```
+
+2. The `feature-flags` ConfigMap will be updated automatically.
+
+   ```yaml
+   apiVersion: v1
+   kind: ConfigMap
+   metadata:
+     name: feature-flags
+     namespace: tekton-pipelines
+   data:
+     results-from: sidecar-logs
+     max-result-size: "65536"
+   ```
+
+3. No manual component restarts are required, changes will take effect automatically.
+
+## Related Content
+
+- [TektonPipeline](https://tekton.dev/docs/operator/tektonpipeline/)
+- [TektonConfig](https://tekton.dev/docs/operator/tektonconfig/)
