Skip to main content
A PipelineRun allows you to instantiate and execute a Pipeline on-cluster.

​
Overview

A Pipeline specifies one or more Tasks in the desired order of execution. A PipelineRun executes the Tasks in the Pipeline in the order they are specified until all Tasks have executed successfully or a failure occurs.
A PipelineRun automatically creates corresponding TaskRuns for every Task in your Pipeline.
The Status field tracks the current state of a PipelineRun, and can be used to monitor progress. This field contains the status of every TaskRun, as well as the full PipelineSpec used to instantiate this PipelineRun, for full auditability.

​
PipelineRun Configuration

A PipelineRun definition supports the following fields:

​
Required Fields

​
apiVersion
string
required
Specifies the API version, for example tekton.dev/v1 or tekton.dev/v1beta1.
​
kind
string
required
Indicates that this resource object is a PipelineRun object.
​
metadata
object
required
Specifies the metadata that uniquely identifies the PipelineRun object. For example, a name.
​
spec
object
required
Specifies the configuration information for this PipelineRun object.
​
spec.pipelineRef
object
Specifies the target Pipeline (use either pipelineRef or pipelineSpec).
​
spec.pipelineSpec
object
Embeds the Pipeline definition directly in the PipelineRun (use either pipelineRef or pipelineSpec).

​
Optional Fields

​
spec.params
array
Specifies the desired execution parameters for the Pipeline.
​
spec.serviceAccountName
string
Specifies a ServiceAccount object that supplies specific execution credentials for the Pipeline.
​
spec.status
string
Specifies options for cancelling a PipelineRun.
​
spec.taskRunSpecs
array
Specifies a list of PipelineTaskRunSpec which allows for setting ServiceAccountName, Pod template, and Metadata for each task.
​
spec.timeouts
object
Specifies the timeout before the PipelineRun fails.
​
spec.podTemplate
object
Specifies a Pod template to use as the basis for the configuration of the Pod that executes each Task.
​
spec.workspaces
array
Specifies a set of workspace bindings which must match the names of workspaces declared in the pipeline being used.

​
Specifying the Target Pipeline

​
Using pipelineRef

You must specify the target Pipeline that you want the PipelineRun to execute, either by referencing an existing Pipeline definition: 
spec:
  pipelineRef:
    name: mypipeline

​
Using pipelineSpec

Or by embedding a Pipeline definition directly in the PipelineRun: 
spec:
  pipelineSpec:
    tasks:
      - name: task1
        taskRef:
          name: mytask

​
Specifying Parameters

You can specify Parameters that you want to pass to the Pipeline during execution: 
spec:
  params:
    - name: pl-param-x
      value: "100"
    - name: pl-param-y
      value: "500"
You must specify all the Parameters that the Pipeline expects. Parameters that have default values specified in Pipeline are not required to be provided by PipelineRun.

​
Propagated Parameters

When using an inlined spec, parameters from the parent PipelineRun will be propagated to any inlined specs without needing to be explicitly defined: 
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: pr-echo-
spec:
  params:
    - name: HELLO
      value: "Hello World!"
    - name: BYE
      value: "Bye World!"
  pipelineSpec:
    tasks:
      - name: echo-hello
        taskSpec:
          steps:
            - name: echo
              image: ubuntu
              script: |
                #!/usr/bin/env bash
                echo "$(params.HELLO)"
      - name: echo-bye
        taskSpec:
          steps:
            - name: echo
              image: ubuntu
              script: |
                #!/usr/bin/env bash
                echo "$(params.BYE)"

​
Specifying Workspaces

If your Pipeline specifies one or more Workspaces, you must map those Workspaces to the corresponding physical volumes in your PipelineRun definition: 
workspaces:
  - name: myworkspace
    persistentVolumeClaim:
      claimName: mypvc
    subPath: my-subdir

​
Using volumeClaimTemplate

You can also create a PersistentVolumeClaim from a template: 
workspaces:
  - name: myworkspace
    volumeClaimTemplate:
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 1Gi

​
Specifying ServiceAccount

You can execute the Pipeline in your PipelineRun with a specific set of credentials by specifying a ServiceAccount object name: 
spec:
  serviceAccountName: build-bot
  pipelineRef:
    name: mypipeline

​
Mapping ServiceAccount to Tasks

If you require more granularity in specifying execution credentials, use the taskRunSpecs[].serviceAccountName field: 
spec:
  taskRunTemplate:
    serviceAccountName: sa-1
  taskRunSpecs:
    - pipelineTaskName: build-task
      serviceAccountName: sa-for-build

​
Specifying Pod Template

You can specify a Pod template configuration that will serve as the configuration starting point for the Pod in which the container images specified in your Tasks will execute: 
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mypipelinerun
spec:
  pipelineRef:
    name: mypipeline
  taskRunTemplate:
    podTemplate:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
      volumes:
        - name: my-cache
          persistentVolumeClaim:
            claimName: my-volume-claim

​
Configuring Failure Timeout

You can use the timeouts field to set the PipelineRun's desired timeout value. There are three sub-fields:
​
timeouts.pipeline
string
Specifies the timeout for the entire PipelineRun. Defaults to the global configurable default timeout of 60 minutes.
​
timeouts.tasks
string
Specifies the timeout for the cumulative time taken by non-finally Tasks.
​
timeouts.finally
string
The timeout for the cumulative time taken by finally Tasks.

​
Timeout Example

timeouts:
  pipeline: "0h0m60s"
  tasks: "0h0m40s"
  finally: "0h0m20s"

​
Constraint

All three sub-fields are optional, and will be automatically processed according to the following constraint: 
timeouts.pipeline >= timeouts.tasks + timeouts.finally
Each timeout field is a duration conforming to Go’s ParseDuration format. For example, valid values are 1h30m, 1h, 1m, and 60s.

​
PipelineRun Status

​
Status Fields

​
status.conditions
array
Contains the latest observations of the PipelineRun’s state.
​
status.startTime
string
The time at which the PipelineRun began executing, in RFC3339 format.
​
status.completionTime
string
The time at which the PipelineRun finished executing, in RFC3339 format.
​
status.pipelineSpec
object
The exact PipelineSpec used when starting the PipelineRun.
​
status.pipelineResults
array
Results emitted by this PipelineRun.
​
status.childReferences
array
A list of references to each TaskRun or Run in this PipelineRun.

​
Status Example

status:
  completionTime: "2020-05-04T02:19:14Z"
  conditions:
    - lastTransitionTime: "2020-05-04T02:19:14Z"
      message: "Tasks Completed: 4, Skipped: 0"
      reason: Succeeded
      status: "True"
      type: Succeeded
  startTime: "2020-05-04T02:00:11Z"
  childReferences:
  - name: triggers-release-nightly-frwmw-build
    pipelineTaskName: build
    kind: TaskRun

​
Overall Status

statusreasoncompletionTimeDescription
UnknownStartedNoPipelineRun has just been picked up by the controller
UnknownRunningNoPipelineRun has been validated and started to perform its work
UnknownStoppingNoPipelineRun is being stopped
TrueSucceededYesAll Tasks in the Pipeline have succeeded
TrueCompletedYesAll Tasks in the Pipeline completed successfully, including one or more skipped Tasks
FalseFailedYesPipelineRun failed because one of the Tasks failed
FalsePipelineRunTimeoutYesPipelineRun timed out
FalsePipelineRunCancelledYesPipelineRun was cancelled successfully

​
Cancelling a PipelineRun

To cancel a PipelineRun that’s currently executing, update its status: 
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # ...
  status: "Cancelled"

​
Gracefully Cancelling a PipelineRun

To gracefully cancel a PipelineRun, set the spec.status field to CancelledRunFinally: 
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # ...
  status: "CancelledRunFinally"
This allows the finally tasks to execute before the PipelineRun is cancelled.

​
Complete PipelineRun Example

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: pipelinerun-with-params
spec:
  params:
    - name: pl-param-x
      value: "100"
    - name: pl-param-y
      value: "500"
  pipelineRef:
    name: pipeline-with-parameters
  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi
  taskRunTemplate:
    serviceAccountName: default
    podTemplate:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
  timeouts:
    pipeline: "1h"
    tasks: "45m"
    finally: "15m"

Build docs developers (and LLMs) love

Get started for freeTalk to us