使用模板自定义 Task 概览

本指南介绍如何使用 ConfigMap-backed 模板 在 TaskRuns 和 PipelineRuns 的概览选项卡中渲染富 HTML 报告。

与其将完整的 HTML 或 Markdown 报告写入单个 Task result，不如让 Tasks 生成 少量结构化指标，然后由 UI 使用来自 ConfigMap 的模板来渲染最终概览。

在以下场景中使用本指南：

你希望为 Task 提供一个 一致、精美的概览（例如代码扫描摘要）。
你的 Markdown 概览已经 接近或超过 Task result 的有效大小限制。
你希望在多个 Tasks 或集群之间复用相同的布局。

模板渲染是 overview-markdown result 的一种 替代方案。如果某个 Task 仍然输出名为 overview-markdown 的 result，UI 将 优先使用该 Markdown，并跳过模板渲染。

前提条件工作原理步骤 1. 在 Markdown 和模板之间进行选择 2. 创建模板 ConfigMap 3. 为你的 Task 添加一个 result 4. 使用注解将 Task 绑定到模板 5. 运行 Task 并检查概览选项卡提示与约定故障排查概览选项卡中没有任何内容模板已渲染，但数据为空或错误 result 大小或 termination message 限制选中了错误的模板

前提条件

集群中已安装 Tekton Pipelines。
具有在共享模板命名空间 kube-public 中创建 ConfigMaps 的权限。

工作原理

你的 Task 输出一个或多个包含指标或摘要数据的 results。
你的 Task 元数据包含 annotations，用于告知 UI：
- 应使用哪个 ConfigMap 作为模板（通过 label selector）。
- 应读取哪些 Task results 并传递给模板。
UI：
- 检查 TaskRun 是否具有名为 overview-markdown 的 result。如果有，则渲染该 Markdown 并停止。
- 否则，从 TaskRun 中读取模板 annotations。
- 查找匹配的 ConfigMap 并加载 template.ejs。
- 读取 TaskRun 中声明的 results，并将它们合并为单个 JSON payload。
- 使用该 payload 计算 EJS 模板，并在概览选项卡中渲染生成的 HTML。

步骤

1. 在 Markdown 和模板之间进行选择

在以下情况下使用 overview-markdown result：

内容较短，并且容易保持在 result 大小限制以内。
你只需要非常简单的格式化。

在以下情况下使用模板 ConfigMap：

你需要更复杂的布局（列、徽章、进度条等）。
你已经有结构化指标，并希望展示得更美观。
你希望多个 Tasks 共享同一种概览布局。

如果同时配置了两种方式，overview-markdown 会优先生效。你只需不要向 overview-markdown result 写入任何内容，即可查看模板输出。

2. 创建模板 ConfigMap

创建一个包含你的 EJS 模板以及用于标识其所属 Task 的 labels 的 ConfigMap。

EJS 是一种简单的模板语言，可让你使用纯 JavaScript 生成 HTML 标记。无需拘泥于如何组织内容。也不用重新发明迭代和控制流。它就是纯 JavaScript。有关更多详细信息，请参阅：

示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-task-0.1-overview-template
  # configmap should be in kube-public namespace
  namespace: kube-public
  labels:
    # Which Task this template is for
    style.tekton.dev/overview-template-task: my-task
    # Version of the Task/template pairing
    style.tekton.dev/overview-template-task-version: "0.1"
    # Which engine the UI should use
    style.tekton.dev/overview-template-engine: ejs
data:
  template.ejs: |
    <%
      const m = metrics || {};
      const asNumber = (value, fallback = 0) => {
        const parsed = Number(value);
        return Number.isFinite(parsed) ? parsed : fallback;
      };
    %>

    <div style="font:12px sans-serif;margin:8px 0">
      <div style="display:flex;align-items:center;margin-bottom:6px">
        <strong>My Task Summary</strong>
        <% if (m.report_url) { %>
          <a href="<%= m.report_url %>" target="_blank" rel="noreferrer" style="margin-left:8px">
            View report
          </a>
        <% } %>
        <span style="margin-left:auto;color:#5c1">
          Status: <%= m.status || "UNKNOWN" %>
        </span>
      </div>

      <div style="display:flex;flex-wrap:wrap;gap:6px;color:#666">
        <div style="flex:1;min-width:110px">
          <b><%= asNumber(m.total) %></b> Total
        </div>
        <div style="flex:1;min-width:110px">
          <b><%= asNumber(m.passed) %></b> Passed
        </div>
        <div style="flex:1;min-width:110px">
          <b><%= asNumber(m.failed) %></b> Failed
        </div>
      </div>
    </div>

要点：

模板文件名始终是 template.ejs。
UI 会将来自 results 的变量注入模板。
你可以使用常规的 EJS 语法（<% %>、<%= %>）来实现简单逻辑和格式化。

3. 为你的 Task 添加一个 result

在 Task 中定义一个 result，用于携带模板使用的指标。

Task 示例：

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-task
spec:
  results:
    - name: TASK_METRICS
      type: object
      description: Summary metrics for the overview template.
      properties:
        total: {}
        passed: {}
        failed: {}
        status: {}
        report_url: {}
  steps:
    - name: run-and-collect-metrics
      image: <your-image>
      script: |
        #!/usr/bin/env sh
        set -eu

        # TODO: replace these with real values
        total=10
        passed=9
        failed=1
        status="OK"
        report_url="https://example.com/report/123"

        printf '{"total": "%s", "passed": "%s", "failed": "%s", "status": "%s", "report_url": "%s"}' \
          "$total" \
          "$passed" \
          "$failed" \
          "$status" \
          "$report_url" \
          > "$(results.TASK_METRICS.path)"

指南：

保持 result 小而扁平。使用计数、百分比、状态和 URL 等简单字段。
不要嵌入大量文本块。
如果使用 object result，请确保 step 写入的是 有效 JSON（无尾随逗号、引号正确）。

4. 使用注解将 Task 绑定到模板

在 Task 上使用 annotations，告诉 UI 应使用哪个模板，以及应传入哪些 results。

单 result 示例：

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: my-task
  annotations:
    # 1) Where to find the template ConfigMap
    style.tekton.dev/overview-template-selector: >
      style.tekton.dev/overview-template-task=my-task,
      style.tekton.dev/overview-template-task-version=0.1

    # 2) Which Task result(s) to read from the TaskRun
    #    Here: expose TASK_METRICS as "metrics" in template.ejs
    #    If you do not specify an alias key, the result name is used (TASK_METRICS).
    style.tekton.dev/overview-template-result-key: TASK_METRICS:metrics

spec:
  results:
    - name: TASK_METRICS
      type: object
  steps:
    - name: run-and-collect-metrics
      image: <your-image>
      # ...

从概念上讲，UI 将构造如下 payload：

{
  "metrics": {
    "total": "10",
    "passed": "9",
    "failed": "1",
    "status": "OK",
    "report_url": "https://example.com/report/123"
  }
}

然后，它会使用该 payload 计算 template.ejs，这样你就可以使用 metrics.total、metrics.status 等字段。

你可以将多个 Task results 合并为一次模板渲染。这在以下场景中很有用：

一个 result 存放指标。
另一个 result 存放完整报告的 URL。

示例：

metadata:
  annotations:
    style.tekton.dev/overview-template-selector: >
      style.tekton.dev/overview-template-task=sonarqube-scanner,
      style.tekton.dev/overview-template-task-version=0.5

    # Multiple results, separated by commas
    # Aliases:
    # - CODE_SCAN_METRICS -> metrics
    # - SCAN_RESULT_URL   -> SCAN_RESULT_URL (no alias)
    # - SCAN_PROJECT      -> SCAN_PROJECT (no alias)
    style.tekton.dev/overview-template-result-key: |
      CODE_SCAN_METRICS:metrics,SCAN_RESULT_URL,SCAN_PROJECT

UI 将构建类似如下的 payload：

{
  "metrics": {
    "bugs": "2",
    "vulnerabilities": "1"
  },
  "SCAN_RESULT_URL": "https://devops-sonar.example.net/dashboard?id=project&branch=main",
  "SCAN_PROJECT": ["foo", "bar"]
}

5. 运行 Task 并检查概览选项卡

将 ConfigMap 和 Task 应用到集群中。

创建一个使用该 Task 的 TaskRun 或 PipelineRun，例如：

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: my-task-run
spec:
  taskRef:
    name: my-task

等待运行完成。
在 UI 中打开该运行，并选择概览选项卡。

如果一切配置正确，你应该能够看到模板生成的 HTML。

如果 Task 还输出了 overview-markdown，则会显示 Markdown，而不是模板。

提示与约定

优先使用较小的 metrics result。 将 results 视为紧凑摘要。
保持模板逻辑简单。 重点放在展示上，而不是业务逻辑上。避免在模板中进行大量计算。
防御性地处理缺失数据。 在模板中使用默认值，以免缺少字段导致渲染失败。

故障排查

概览选项卡中没有任何内容

Task 是否输出了空的 overview-markdown？
- 如果是，UI 会显示该空 Markdown，并忽略模板。你只需不要向 overview-markdown result 写入任何内容，即可查看模板输出。
TaskRun 是否包含 overview-template-result-key 中列出的 result(s)？
- 检查 TaskRun YAML，并查看 .status.results。
overview-template-selector 中的 selector 是否在 kube-public 命名空间中恰好匹配一个 ConfigMap？
- 使用 kubectl get configmap -l <your-selector> -n kube-public 进行测试。

模板已渲染，但数据为空或错误

如果你使用的是 object result，请确认该 result 是有效的，并且包含模板期望的字段。
检查 overview-template-result-key 的名称是否与 Task result 名称完全一致。

result 大小或 termination message 限制

从 results 中移除非必要字段。
将按文件的详细报告推送到日志或外部系统，只在 result 中包含摘要数字和 URL。
请记住，每个 Task 在所有 steps 和 results 之间仍然共享同一个 termination-message 配额。

选中了错误的模板

确保 overview-template-selector 足够具体（例如同时包含 Task 名称和版本）。
避免对无关模板重复使用相同的 labels。
如果有多个 ConfigMaps 匹配该 selector，请进一步收紧 labels，确保只选中一个 ConfigMap。

一旦你具备了 模板 ConfigMap、metric results 和正确的 Task annotations，就可以在不修改 UI 本身的情况下，构建可复用、可版本化的 Task 概览布局。

#使用模板自定义 Task 概览

#目录

#前提条件

#工作原理

#步骤

#1. 在 Markdown 和模板之间进行选择

#2. 创建模板 ConfigMap

#3. 为你的 Task 添加一个 result

#4. 使用注解将 Task 绑定到模板

#5. 运行 Task 并检查概览选项卡

#提示与约定

#故障排查

#概览选项卡中没有任何内容

#模板已渲染，但数据为空或错误

#result 大小或 termination message 限制

#选中了错误的模板