将 Markdown 输出到 Overview 选项卡(PipelineRuns 和 TaskRuns)
本指南介绍如何通过将 Markdown 写入名为 overview-markdown 的 Task Result,在 PipelineRuns 和 TaskRuns 的 Overview 选项卡中显示人类可读的报告。
目录
前提条件工作原理步骤1. 定义一个名为overview-markdown 的 Task result2. 运行 Task3. 查看 Overview4.(可选)在 Pipeline 中使用提示故障排查前提条件
- 集群中已安装 Tekton Pipelines。
- 可选但推荐:已部署 Tekton Results,以便即使旧的 TaskRuns/PipelineRuns 被垃圾回收后,你的摘要仍然可以查询。
为什么需要 Tekton Results?如果你的集群会激进地清理 run,那么集群中的 TaskRun/PipelineRun 对象(及其 results)可能会消失。Tekton Results 提供了一个集中式存储,因此历史 Overview 报告仍然可以访问。
工作原理
- UI 读取 Task 中名称完全为
overview-markdown的 result。 - 你写入该 result 文件的任何 Markdown 都会在 run 的 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>):
请保持 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 示例:
3. 查看 Overview
TaskRun 完成后,打开该 TaskRun 的 Overview 选项卡查看渲染后的 Markdown。
如果没有任何内容渲染,请检查 step 日志,确认文件已写入 $(results.overview-markdown.path),并且 result 名称正确。
4.(可选)在 Pipeline 中使用
在 Pipeline 中,每个 Task 都可以输出自己的 overview-markdown。Overview 选项卡会按 Task 分别显示多个部分(例如 lint、scan、build)。
你不需要为此功能使用 Pipeline 的 results。只有 Task results 会在 Overview 选项卡中渲染。
Pipeline 示例(按需替换 <lint-image> <scan-image>):
PipelineRun 示例:
打开该 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 版本支持此功能。
- 检查 result 名称:必须严格为
- Pod 日志显示 termination message overflow