TaskRuns

A TaskRun allows you to instantiate and execute a Task on-cluster. A Task specifies one or more Steps that execute container images and each container image performs a specific piece of build work.

Overview

A TaskRun executes the Steps in the Task in the order they are specified until all Steps have executed successfully or a failure occurs.

TaskRun Configuration

A TaskRun 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

Identifies this resource object as a TaskRun object.

metadata

object

required

Specifies the metadata that uniquely identifies the TaskRun, such as a name.

spec

object

required

Specifies the configuration for the TaskRun.

spec.taskRef

object

Specifies the Task that the TaskRun will execute (use either taskRef or taskSpec).

spec.taskSpec

object

Embeds the Task definition directly in the TaskRun (use either taskRef or taskSpec).

Optional Fields

spec.serviceAccountName

string

Specifies a ServiceAccount object that provides custom credentials for executing the TaskRun.

spec.params

array

Specifies the desired execution parameters for the Task.

spec.timeout

string

Specifies the timeout before the TaskRun fails.

spec.podTemplate

object

Specifies a Pod template to use as the starting point for configuring the Pods for the Task.

spec.workspaces

array

Specifies the physical volumes to use for the Workspaces declared by a Task.

spec.retries

integer

Specifies the number of times to retry the TaskRun execution when it fails.

spec.debug

object

Specifies any breakpoints and debugging configuration for the Task execution.

Specifying the Target Task

Using taskRef

To specify the Task you want to execute in your TaskRun, use the taskRef field:

spec:
  taskRef:
    name: read-task

Using taskSpec

You can also embed the desired Task definition directly in the TaskRun using the taskSpec field:

spec:
  taskSpec:
    workspaces:
    - name: source
    steps:
      - name: build-and-push
        image: gcr.io/kaniko-project/executor:v0.17.1
        workingDir: $(workspaces.source.path)
        env:
          - name: "DOCKER_CONFIG"
            value: "/tekton/home/.docker/"
        command:
          - /kaniko/executor
        args:
          - --destination=gcr.io/my-project/gohelloworld

Specifying Parameters

If a Task has parameters, you can use the params field to specify their values:

spec:
  params:
    - name: flags
      value: -someflag
    - name: url
      value: https://github.com/tektoncd/pipeline.git

If a parameter does not have an implicit default value, you must explicitly set its value.

Propagated Parameters

When using an inlined taskSpec, parameters from the parent TaskRun will be available to the Task without needing to be explicitly defined:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: hello-
spec:
  params:
    - name: message
      value: "hello world!"
  taskSpec:
    steps:
    - name: default
      image: ubuntu
      script: |
        echo $(params.message)

Specifying Workspaces

If a Task specifies one or more Workspaces, you must map those Workspaces to the corresponding physical volumes in your TaskRun definition:

workspaces:
  - name: myworkspace
    persistentVolumeClaim:
      claimName: mypvc
    subPath: my-subdir

Workspace Volume Sources

PersistentVolumeClaim
emptyDir
ConfigMap
Secret

workspaces:
  - name: myworkspace
    persistentVolumeClaim:
      claimName: mypvc

workspaces:
  - name: myworkspace
    emptyDir: {}

workspaces:
  - name: myworkspace
    configMap:
      name: my-configmap

workspaces:
  - name: myworkspace
    secret:
      secretName: my-secret

Configuring Failure Timeout

You can use the timeout field to set the TaskRun's desired timeout value. The timeout is a duration conforming to Go’s ParseDuration format. For example, valid values are 1h30m, 1h, 1m, and 60s.

spec:
  timeout: "5m"
  taskRef:
    name: build-push

If a TaskRun runs longer than its timeout value, the pod associated with the TaskRun will be deleted.

When a TaskRun times out, the logs of the TaskRun are not preserved as the pod is deleted.

Specifying Retries

You can use the retries field to set how many times you want to retry on a failed TaskRun. All TaskRun failures are retriable except for Cancellation.

spec:
  retries: 3
  taskRef:
    name: flaky-task

For a retriable TaskRun, when an error occurs:

The error status is archived in status.RetriesStatus
The Succeeded condition is updated with status Unknown and reason ToBeRetried
status.StartTime, status.PodName and status.Results are unset to trigger another retry attempt

Specifying ServiceAccount

You can execute the Task in your TaskRun with a specific set of credentials by specifying a ServiceAccount object name:

spec:
  serviceAccountName: build-bot
  taskRef:
    name: build-push

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 Task will execute:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: mytaskrun
spec:
  taskRef:
    name: mytask
  podTemplate:
    securityContext:
      runAsNonRoot: true
      runAsUser: 1001
    volumes:
      - name: my-cache
        persistentVolumeClaim:
          claimName: my-volume-claim

TaskRun Status

The status field defines the observed state of TaskRun.

Status Fields

status.conditions

array

Contains the latest observations of the TaskRun’s state.

status.podName

string

Name of the pod containing the containers responsible for executing this task’s steps.

status.startTime

string

The time at which the TaskRun began executing, in RFC3339 format.

status.completionTime

string

The time at which the TaskRun finished executing, in RFC3339 format.

status.results

array

List of results written out by the task’s containers.

status.steps

array

Contains the state of each step container.

Status Example

status:
  completionTime: "2019-08-12T18:22:57Z"
  conditions:
    - lastTransitionTime: "2019-08-12T18:22:57Z"
      message: All Steps have completed executing
      reason: Succeeded
      status: "True"
      type: Succeeded
  podName: status-taskrun-pod
  startTime: "2019-08-12T18:22:51Z"
  steps:
    - container: step-hello
      imageID: docker-pullable://busybox@sha256:895ab622e92e18d6b461d671081757af7dbaa3b00e3e28e12505af7817f73649
      name: hello
      terminated:
        containerID: docker://d5a54f5bbb8e7a6fd3bc7761b78410403244cf4c9c5822087fb0209bf59e3621
        exitCode: 0
        finishedAt: "2019-08-12T18:22:56Z"
        reason: Completed
        startedAt: "2019-08-12T18:22:54Z"

Overall Status

status	reason	message	completionTime	Description
Unknown	Started	n/a	No	TaskRun has just been picked up by the controller
Unknown	Running	n/a	No	TaskRun has been validated and started to perform its work
True	Succeeded	n/a	Yes	TaskRun completed successfully
False	Failed	n/a	Yes	TaskRun failed because one of the steps failed
False	TaskRunTimeout	n/a	Yes	TaskRun timed out

Cancelling a TaskRun

To cancel a TaskRun that’s currently executing, update its status to mark it as cancelled:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: go-example-git
spec:
  # ...
  status: "TaskRunCancelled"

When you cancel a TaskRun, the running pod associated with that TaskRun is deleted. This means that the logs of the TaskRun are not preserved.

Debugging a TaskRun

Breakpoint on Failure

TaskRuns can be halted on failure for troubleshooting:

spec:
  debug:
    breakpoints:
      onFailure: "enabled"

Debug Environment

After accessing the container environment, you can use the following scripts in the /tekton/debug/scripts directory:

debug-continue - Mark the step as a success and exit the breakpoint
debug-fail-continue - Mark the step as a failure and exit the breakpoint

Example TaskRun with Referenced Task

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: read-task
spec:
  workspaces:
  - name: input
  steps:
    - name: readme
      image: ubuntu
      script: cat $(workspaces.input.path)/README.md
---
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: read-repo-run
spec:
  taskRef:
    name: read-task
  workspaces:
  - name: input
    persistentVolumeClaim:
      claimName: mypvc
    subPath: my-subdir

Example TaskRun with Embedded Task

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  workspaces:
  - name: source
    persistentVolumeClaim:
      claimName: my-pvc
  taskSpec:
    workspaces:
    - name: source
    steps:
      - name: build-and-push
        image: gcr.io/kaniko-project/executor:v0.17.1
        workingDir: $(workspaces.source.path)
        env:
          - name: "DOCKER_CONFIG"
            value: "/tekton/home/.docker/"
        command:
          - /kaniko/executor
        args:
          - --destination=gcr.io/my-project/gohelloworld

Get Started

Core Concepts

Guides

Advanced Features

Resolvers

Operations

Migration

Overview

TaskRun Configuration

Required Fields

Optional Fields

Specifying the Target Task

Using taskRef

Using taskSpec

Specifying Parameters

Propagated Parameters

Specifying Workspaces

Workspace Volume Sources

Configuring Failure Timeout

Specifying Retries

Specifying ServiceAccount

Pod Template

TaskRun Status

Status Fields

Status Example

Overall Status

Cancelling a TaskRun

Debugging a TaskRun

Breakpoint on Failure

Debug Environment

Example TaskRun with Referenced Task

Example TaskRun with Embedded Task

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced Features

Resolvers

Operations

Migration

​Overview

​TaskRun Configuration

​Required Fields

​Optional Fields

​Specifying the Target Task

​Using taskRef

​Using taskSpec

​Specifying Parameters

​Propagated Parameters

​Specifying Workspaces

​Workspace Volume Sources

​Configuring Failure Timeout

​Specifying Retries

​Specifying ServiceAccount

​Pod Template

​TaskRun Status

​Status Fields

​Status Example

​Overall Status

​Cancelling a TaskRun

​Debugging a TaskRun

​Breakpoint on Failure

​Debug Environment

​Example TaskRun with Referenced Task

​Example TaskRun with Embedded Task

Build docs developers (and LLMs) love

Overview

TaskRun Configuration

Required Fields

Optional Fields

Specifying the Target Task

Using taskRef

Using taskSpec

Specifying Parameters

Propagated Parameters

Specifying Workspaces

Workspace Volume Sources

Configuring Failure Timeout

Specifying Retries

Specifying ServiceAccount

Pod Template

TaskRun Status

Status Fields

Status Example

Overall Status

Cancelling a TaskRun

Debugging a TaskRun

Breakpoint on Failure

Debug Environment

Example TaskRun with Referenced Task

Example TaskRun with Embedded Task