将 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 分组显示。
你不需要为 Overview 选项卡写入 Pipeline result；应改为写入 Task 的 overview-markdown。

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

步骤

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

创建（或更新）你的 Task，使其声明一个名称完全相同的 string result。

在该 Task 的某个 step 中，将 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 的 result 值默认限制为 4 KB。对于较长的报告：

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

如果你想配置 result 大小限制，可以参考 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. 查看概览

TaskRun 完成后，打开 TaskRun 的 Overview 选项卡，查看渲染后的 Markdown。

如果没有任何内容渲染，请检查 step 日志，确认文件已写入 $(results.overview-markdown.path)，并且 result 名称正确。

4. （可选）在 Pipelines 中使用

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

对于此功能，你不需要使用 Pipeline 的 results。只有 Task results 会在 Overview 选项卡中渲染。

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。

提示

名称必须完全一致： result 必须命名为 overview-markdown（区分大小写）。
写入正确的位置： 始终写入 $(results.overview-markdown.path)。你不需要 Pipeline 级别的 result。
大小限制： 单个 Task result 值默认上限为 4 KB。如果你想配置 result 大小限制，可以参考 Result Limit Exceeded When Writing Tekton Task Results。

故障排查

Overview 选项卡中没有任何内容
- 检查 result 名称：必须严格是 overview-markdown。
- 验证 step 是否写入了 $(results.overview-markdown.path)。
- 确认你的 UI 版本支持此功能。
Pod 日志显示 termination message overflow
- 参考 Result Limit Exceeded When Writing Tekton Task Results。

#将 Markdown 输出到 Overview 选项卡（PipelineRuns 和 TaskRuns）

#目录

#前提条件

#工作原理

#步骤

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

#2. 运行 Task

#3. 查看概览

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

#提示

#故障排查