Tekton Pruner: Auto-Clean Old PipelineRuns and TaskRuns (2026)

Tekton’s garbage collection is a feature that automatically deletes old PipelineRun and TaskRun resources, along with their associated TaskRun and PipelineRun status sub-resources.

Let’s see it in action. Imagine you have a CI/CD pipeline defined using Tekton. After a few runs, you’ll notice a growing number of PipelineRun and TaskRun objects in your Kubernetes cluster.

# List all PipelineRuns
kubectl get pipelineruns -n tekton-pipelines

# List all TaskRuns
kubectl get taskruns -n tekton-pipelines

Without pruning, these objects will consume cluster resources and can make it harder to find recent runs. The Tekton Pruner is designed to clean these up automatically.

The core problem Tekton Pruner solves is the unbounded growth of PipelineRun and TaskRun resources. These resources, while essential for tracking execution history, can quickly fill up a Kubernetes cluster’s etcd if not managed. This leads to increased API server load, slower kubectl operations, and potential resource exhaustion. The Pruner addresses this by implementing a configurable retention policy, ensuring that only a defined number of recent runs are kept.

Internally, the Tekton Pruner operates as a controller within the Tekton operator or as a standalone component. It watches for PipelineRun and TaskRun resources. When a resource is created, the Pruner checks if its creation timestamp falls outside the configured retention window. If it does, the Pruner initiates the deletion of the resource. For PipelineRun resources, this deletion also cascades to their associated TaskRun resources and status sub-resources, effectively cleaning up the entire history of a pipeline execution.

The primary levers you control are the retention periods for PipelineRun and TaskRun resources. These are typically configured via environment variables or command-line flags when deploying the Tekton controller or the Pruner component.

• TEKTON_PIPELINERUN_RETENTION_DAYS: This variable (or its equivalent flag) determines how many days worth of PipelineRun resources to keep. For example, setting TEKTON_PIPELINERUN_RETENTION_DAYS=7 will ensure that PipelineRun resources older than 7 days are eligible for deletion.
• TEKTON_TASKRUN_RETENTION_DAYS: Similarly, this controls the retention period for TaskRun resources. A common setting is TEKTON_TASKRUN_RETENTION_DAYS=7.

These values are often set within the deployment manifest of the Tekton controller. For instance, in a Kubernetes deployment, you might find them in the env section of a container spec:

env:
  - name: TEKTON_PIPELINERUN_RETENTION_DAYS
    value: "7"
  - name: TEKTON_TASKRUN_RETENTION_DAYS
    value: "7"

The Pruner doesn’t just delete resources based on age; it also considers the number of resources to retain. In some configurations, you can specify a maximum number of PipelineRun or TaskRun objects to keep, regardless of age. This is particularly useful if you have a very high volume of runs and want to ensure a consistent, small footprint.

The retention logic is applied independently to PipelineRun and TaskRun resources. This means you can have different retention policies for each. For example, you might want to keep PipelineRun history for 30 days but only TaskRun history for 7 days, allowing for detailed task-level debugging for a shorter period while maintaining overall pipeline completion records for longer.

When deleting a PipelineRun, the Pruner also cleans up its associated TaskRun resources. This is a crucial aspect of its functionality, as it prevents orphaned TaskRun objects from accumulating. The deletion process is a standard Kubernetes garbage collection event, where the owner reference on the TaskRun points to the PipelineRun, ensuring that when the parent is deleted, the child is also removed.

The Pruner also handles the deletion of status sub-resources. These are often smaller, more frequent updates to the PipelineRun and TaskRun objects themselves, and their accumulation can also impact API performance. By cleaning these up, the Pruner ensures a more comprehensive resource cleanup.

A common misconception is that the Pruner deletes all history. In reality, it’s a configurable retention policy. You can set it to keep runs for a very long time, effectively disabling aggressive pruning if desired, though this defeats the purpose of resource management. The Pruner’s effectiveness is directly tied to how aggressively you configure its retention settings.

The next logical step after understanding pruning is how to visualize and query this historical data effectively, even with pruning in place.