Add support for PipelineRun display name

[valAndre07]

Feature request

A PipelineRun in the UI is currently represented by the technical name, that is meant to be machine readable, not human readable.

It will be helpful to add new field to PipelineRun for display name, like it was done in this TEP for pipeline and task.

Param substitution would be great 🙏

After that, I could open a request on the dashboard repo to add this.

Before

After

[vdemeester]

Thanks for the request! After thinking through the design, here's a scoped-down proposal that I think delivers the value while keeping the change minimal.

apiVersion: tekton.dev/v1
kind: PipelineRun
spec:
  displayName: "Build for PR #123"
  pipelineRef:
    name: build

• Pure literal string — no variable/param substitution, no status field, no reconciler changes. The dashboard would read spec.displayName directly.
• Optional length-cap validation in the webhook.

On param substitution (the 🙏), I'd suggest not doing it in-core, because the dynamic data you want (PR number, branch, SHA…) is already resolved at PipelineRun creation time by Pipelines-as-Code and Tekton TriggerTemplates — they can bake the resolved value straight into spec.displayName. Pulling params into the reconciler for this field would add complexity (garbage-in risk, divergence with the existing Pipeline.spec.displayName which is context.*-only) for something the surrounding tooling already covers.
The only inconsistency of this appreach is that every other displayName in Tekton (Pipeline, Task, PipelineTask) supports $(context.*) substitution; this field intentionally would not, to keep it zero-logic. We can revisit a resolved status.displayName later if there's real demand.

Question for you @valAndre07: Does relying on PaC/Triggers for the dynamic part work for your use case, or is there a scenario where the substitution has to happen in-core?

[valAndre07]

Thanks a lot for your answer, very clear :)

We are using JenkinsX/Lighthouse for triggering pipelines dynamically. That's why we need param substitution (correct me if I'm wrong), if we want to display something like Build for PR #123

[vdemeester]

Thanks a lot for your answer, very clear :)

We are using JenkinsX/Lighthouse for triggering pipelines dynamically. That's why we need param substitution (correct me if I'm wrong), if we want to display something like Build for PR #123

Ah interesting, they do not provide their own "substitution" on top of tektoncd/pipeline one right ? (like pac does)

[valAndre07]

I don't think so. If I'm not wrong we just have theses params that are injected as PipelineRun params

[vdemeester]

@valAndre07 yeah you are right, after digging into Lighthouse's code I have to walk back part of my earlier proposal 😅

Lighthouse copies your PipelineRun spec verbatim and only ever injects dynamic data into spec.params , that means a literal-only displayName can't get your PR number.

So the literal-only idea doesn't actually serve your case. The consistent design (and the one that does) is the same spec→status flow every other displayName already uses:

• spec.displayName — raw input, supports $(params.*) / $(context.*)
• status.displayName — resolved value the reconciler writes, which the dashboard reads

That mirrors PipelineTask.displayName exactly (see pipelinerunstate.go#L336). With that, you'd set spec.displayName: "Build for PR $(params.PULL_NUMBER)" and let Lighthouse fill the param. So spec.displayName would be literal (the params in there, ..) but in the status.spec.displayName, it would be the resolved value..

I think it is acceptable, @tektoncd/core-maintainers wdyt ?

[AlanGreene]

A TEP was previously started for this feature request although it didn't progress much: tektoncd/community#1174

Would it be a good idea to resurrect it and move this discussion there to ensure all use cases are considered and the plan is properly fleshed out before implementation, including impact on various clients including Dashboard and CLI?

[rajnish-jais]

Picking up @AlanGreene's suggestion to resurrect TEP-0157 before any implementation. @say5 has been quiet since the rebase ask, so unless they object I'd like to take over the TEP — happy to add them as co-author on the revision.

I've drafted an updated version that incorporates the discussion above:

• Two-field design (spec.displayName + status.displayName) matching PipelineTask.displayName so authors don't learn a second model.
• Substitution limited in v1 to $(params.*) and $(context.pipelineRun.*) — covers the JenkinsX/Lighthouse case @valAndre07 raised, since Lighthouse injects through spec.params. $(tasks.*) / $(results.*) are technically supported by the same substitution machinery (already used in PipelineTask.DisplayName at apply.go:530), but I've scoped them out for now because the label needs to be useful from the moment a PipelineRun enters a Dashboard list view — long before tasks complete. Easy to revisit in a follow-up if anyone has a use case for "post-completion summary" labels.
• Unresolved references are left verbatim with a warning event (cosmetic field shouldn't fail a PipelineRun).
• Validation: 200-char default cap (configurable via a new feature flag), $(tasks.*) / $(results.*) rejected at admission.
• Client impact spelled out for Dashboard and CLI (tektoncd/cli) per @AlanGreene's ask — Dashboard prefers status.displayName when non-empty, CLI surfaces it as a header line / column; metadata.name remains the primary identifier (tkn pr logs <name> etc. unchanged).
• Alternatives section captures the literal-only proposal and why it doesn't solve Lighthouse, the annotation-based approach, and the do-nothing option.

I'll send a PR against tektoncd/community shortly (either as a revision to #1174 if @say5 is open to it, or as a fresh PR superseding it). Wanted to surface intent here first in case @vdemeester / @tektoncd/core-maintainers want to push back on scope or on the variable-context boundary before I push the draft.

One open question for the maintainers: should status.displayName be considered immutable after first write, or recomputed on every reconcile that touches spec? I've drafted it as write-once for consistency with completed-run status immutability, but happy to flip if the convention is the other way.

[vdemeester]

Thanks @rajnish-jais ! On the open question, I think immutable after the first is good for consistency. I don't see a valid usecase to have it mutable.