Proposal: schema-governed correlation-id label for PaC-created PipelineRuns

[ci-operator]

Hi PaC folks 👋

I’d like to propose a small, PaC-scoped feature: a deterministic, schema-governed correlation ID label that PaC applies to all PipelineRuns created for a given webhook event.

The goal is to give users a stable, configurable per-event correlation ID, derived from a configurable set of fields available at webhook delivery, that other controllers and observability tooling can key on.

---

Problem statement

When PaC handles a webhook (push / PR / MR, etc.), it may create multiple PipelineRuns for that single event. Downstream, people often want to answer “which runs came from this event?” and group logs, metrics, and CloudEvents on that basis.

Some constraints:

• There’s currently no built-in way in PaC to turn a canonical set of webhook fields (provider, repo, SHA, PR/MR number, delivery ID, etc.) into a stable, reproducible ID.
• Any identifiers coming from other layers (e.g., Tekton Triggers’ triggers-eventid, where used) are typically random, not derived from a user-defined schema, and not reproducible in a policy-driven way.
• Different teams define “same event” differently:
  • per webhook delivery,
  • per PR + commit,
  • per branch + commit,
  • etc.

Right now there is no standard, PaC-native mechanism to compute a deterministic correlation-id from these fields and apply it to all PipelineRuns that PaC creates for that event.”

---

Proposal

Introduce a schema-governed correlation ID that PaC computes per webhook event and applies as a label to all PipelineRuns it creates for that event.

1. Correlation policy reference on Repository

Add an optional field to the PaC Repository CR (shape subject to bikeshedding):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
spec:
  # ...
  correlationPolicy:
    secretRef:
      name: konflux-correlation-policy  # or any user-chosen Secret

• If spec.correlationPolicy.secretRef.name is set, PaC looks up that Secret in the Repository’s namespace.
• If it is not set, PaC does nothing (no correlation-id) or uses a default/global policy – open to discussion.

2. Correlation policy Secret (schema)

The referenced Secret would contain a policy describing how to compute a correlation ID:

• A UUIDv5 namespace (string).
• A field list selecting normalized webhook fields PaC already knows about (e.g., provider, org, repo_url, commit_sha, pr_number, event_id).
• A canonical JSON template describing how to lay those fields out before hashing.

For each webhook event, PaC would:

1. Normalize the webhook payload into an internal map (provider, org, repo_url, commit_sha, pr_number, event_id, etc.).
2. Select the fields listed in the policy.
3. Render them into canonical JSON using the policy template.
4. Compute UUIDv5(policy.namespaceUUID, canonical_json).
5. Treat that value as the Event Correlation ID (ECID).

This is explicitly about determinism, not security (UUIDv5 uses SHA-1; this is not an attestation mechanism).

3. Label on all PaC-created PipelineRuns for that event

For every PipelineRun PaC creates in response to that webhook event, PaC would set:

metadata.labels["pipelinesascode.tekton.dev/correlation-id"] = <computed UUIDv5>

This covers:

• repository-defined pipelines,
• any PaC-managed build/test workflows,
• other PaC-generated runs tied to the same webhook.

Downstream controllers/tools can then group “all runs from this event” by this label, without PaC needing to coordinate with them.

4. Caching & performance

Implementation detail, but worth calling out:

• PaC should watch/cache the correlation policy Secret per namespace (shared informer-style), not hard-read it on every event.
• Changing the policy (especially the namespace UUID or field set) changes correlation semantics; we should document that policy rotation is strongly discouraged and leave any enforcement to cluster policy/admission.

---

Non-goals (PaC side)

• No changes to Tekton CRDs.
• No opinion on how downstream controllers use the correlation-id; PaC just provides a deterministic label.
• No attempt at cryptographic provenance or SLSA-like guarantees (that remains in Chains/attestation purview).
• No additional persistent storage; everything lives in labels and existing Kubernetes/CRD objects.

---

Why in PaC?

PaC is in the right place to do this because it:

• sees the full webhook payload, including provider-specific fields,
• already normalizes provider data,
• already has per-repository configuration (Repository CR),
• is the layer that may fan a single webhook into multiple PipelineRuns.

Having PaC mint a deterministic, policy-governed correlation-id and stamp all its PipelineRuns with it gives users a consistent hook that other controllers and observability systems can rely on.

---

Questions for maintainers

• Does spec.correlationPolicy.secretRef on Repository feel like the right place to configure this, or would you prefer a global config or different shape?
• Are you okay with a reserved label key like pipelinesascode.tekton.dev/correlation-id on all PaC-created PipelineRuns, or should the label key itself be configurable?
• Any concerns with UUIDv5 + canonical JSON as the hashing mechanism for the same event under this policy becoming the correlation ID”?

Happy to adjust naming/shape to fit PaC’s design; the core ask is: can PaC standardize a deterministic, schema-driven correlation-id per webhook event and label all PaC-created PipelineRuns with it?