输出 Markdown 到 Overview 标签（PipelineRuns & TaskRuns）

本指南演示如何通过将 Markdown 写入名为 overview-markdown 的 Task Result，在 PipelineRuns 和 TaskRuns 的 Overview 标签中展示可读性强的报告。

前提条件

集群中已安装 Tekton Pipelines。
可选但推荐： 部署 Tekton Results，以便即使旧的 TaskRuns/PipelineRuns 被垃圾回收，摘要仍可查询。

为什么使用 Tekton Results？如果集群对运行记录进行严格修剪，集群内的 TaskRun/PipelineRun 对象（及其结果）可能会消失。Tekton Results 提供了一个集中存储，使历史 Overview 报告依然可访问。

工作原理

UI 会读取 Task 的 result，其名称必须精确为 overview-markdown。
你写入该结果文件的任何 Markdown 内容都会在运行的 Overview 标签中渲染。
在 Pipeline 中，每个 Task 都可以生成自己的 overview-markdown，Overview 标签会按 Task 分组显示它们。
你不需要写入 Pipeline 级别的结果给 Overview 标签，写入 Task 的 overview-markdown 即可。

限制： 单个 Task 的结果值默认限制为 4 KB。请保持摘要简洁；必要时链接到更大的工件。如果需要更复杂的布局，可以参考 Customize Task Overview with Templates。如果想配置结果大小限制，可以参考 Result Limit Exceeded When Writing Tekton Task Results。

步骤

1. 定义名为 `overview-markdown` 的 Task result

创建（或更新）你的 Task，声明一个名称完全相同的字符串类型 result。

在 Task 的某个步骤中，将 Markdown 写入 $(results.overview-markdown.path)。

示例 Task（根据需要替换 <image>）：

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

保持 Markdown 简短且聚焦。单个 Task 的结果值默认限制为 4 KB。对于较长的报告：

将完整工件（如 HTML、JSON、PDF）上传到你的存储或工件仓库。
在 Markdown 中放置链接（例如 [Full report](https://artifact.example.com/run/123/report.html)）。

如果想配置结果大小限制，可以参考 Result Limit Exceeded When Writing Tekton Task Results。

2. 运行 Task

创建一个引用该 Task 的 TaskRun，等待其完成。

示例 TaskRun：

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: demo-markdown-overview-run
spec:
  taskRef:
    name: demo-markdown-overview

3. 查看 Overview

TaskRun 完成后，打开 TaskRun 的 Overview 标签查看渲染的 Markdown。

如果没有显示内容，请检查步骤日志确认文件已写入 $(results.overview-markdown.path)，且结果名称正确。

4. （可选）在 Pipeline 中使用

在 Pipeline 中，每个 Task 都可以输出自己的 overview-markdown。Overview 标签会按 Task 显示独立部分（例如 lint、scan、build）。

你不需要 Pipeline 级别的结果来实现此功能。Overview 标签只渲染 Task 结果。

示例 Pipeline（根据需要替换 <lint-image> <scan-image>）：

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

示例 PipelineRun：

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipeline-with-summaries-run
spec:
  pipelineRef:
    name: pipeline-with-summaries

打开 PipelineRun 的 Overview 标签，你将看到两个 Markdown 区块：lint 和 scan。

小贴士

名称必须精确： 结果名称必须是 overview-markdown（区分大小写）。
写入正确位置： 始终写入 $(results.overview-markdown.path)，无需 Pipeline 级别结果。
大小限制： 单个 Task 结果值默认限制为 4 KB。如需配置结果大小限制，请参考 Result Limit Exceeded When Writing Tekton Task Results。

故障排查

Overview 标签无内容显示
- 检查结果名称：必须完全是 overview-markdown。
- 确认步骤写入了 $(results.overview-markdown.path)。
- 确认你的 UI 版本支持此功能。
Pod 日志显示终止消息溢出
- 请参考 Result Limit Exceeded When Writing Tekton Task Results。

#输出 Markdown 到 Overview 标签（PipelineRuns & TaskRuns）

#目录

#前提条件

#工作原理

#步骤

#1. 定义名为 overview-markdown 的 Task result

#2. 运行 Task

#3. 查看 Overview

#4. （可选）在 Pipeline 中使用

#小贴士

#故障排查