Skip to main content
A Pipeline is a collection of Tasks that you define and arrange in a specific order of execution as part of your continuous integration flow.

​
Overview

Each Task in a Pipeline executes as a Pod on your Kubernetes cluster. You can configure various execution conditions to fit your business needs.

​
Pipeline Configuration

A Pipeline 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 Pipeline object.
​
metadata
object
required
Specifies metadata that uniquely identifies the Pipeline object. For example, a name.
​
spec
object
required
Specifies the configuration information for this Pipeline object.
​
spec.tasks
array
required
Specifies the Tasks that comprise the Pipeline and the details of their execution.

​
Optional Fields

​
spec.params
array
Specifies the Parameters that the Pipeline requires.
​
spec.workspaces
array
Specifies a set of Workspaces that the Pipeline requires.
​
spec.results
array
Specifies the location to which the Pipeline emits its execution results.
​
spec.description
string
Holds an informative description of the Pipeline object.
​
spec.finally
array
Specifies one or more Tasks to be executed in parallel after all other tasks have completed.

​
Specifying Workspaces

Workspaces allow you to specify one or more volumes that each Task in the Pipeline requires during execution: 
spec:
  workspaces:
    - name: pipeline-ws1
  tasks:
    - name: use-ws-from-pipeline
      taskRef:
        name: gen-code
      workspaces:
        - name: output
          workspace: pipeline-ws1
    - name: use-ws-again
      taskRef:
        name: commit
      workspaces:
        - name: src
          workspace: pipeline-ws1
      runAfter:
        - use-ws-from-pipeline
For more information, see the Workspaces documentation.

​
Specifying Parameters

You can specify global parameters that you want to supply to the Pipeline at execution time. Parameters are passed to the Pipeline from its corresponding PipelineRun.

​
Parameter Format

Parameter names:
  • Must only contain alphanumeric characters, hyphens (-), and underscores (_)
  • Must begin with a letter or an underscore (_)

​
Parameter Types

Each declared parameter has a type field, which can be set to array, string, or object.

​
Example Pipeline with Parameters

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: pipeline-with-parameters
spec:
  params:
    - name: context
      type: string
      description: Path to context
      default: /some/where/or/other
    - name: flags
      type: array
      description: List of flags
  tasks:
    - name: build-skaffold-web
      taskRef:
        name: build-push
      params:
        - name: pathToDockerFile
          value: Dockerfile
        - name: pathToContext
          value: "$(params.context)"
        - name: flags
          value: ["$(params.flags[*])"]

​
Adding Tasks to the Pipeline

Your Pipeline definition must reference at least one Task. Each Task within a Pipeline must have a valid name and a taskRef or a taskSpec.

​
Using taskRef

tasks:
  - name: build-the-image
    taskRef:
      name: build-push

​
Using taskSpec

tasks:
  - name: say-hello
    taskSpec:
      steps:
      - image: ubuntu
        script: echo 'hello there'

​
Specifying Parameters in Tasks

You can provide parameters to Tasks: 
spec:
  tasks:
    - name: build-skaffold-web
      taskRef:
        name: build-push
      params:
        - name: pathToDockerFile
          value: Dockerfile
        - name: pathToContext
          value: /workspace/examples/microservices/leeroy-web

​
Using the runAfter Field

If you need your Tasks to execute in a specific order within the Pipeline, use the runAfter field to indicate that a Task must execute after one or more other Tasks. 
workspaces:
- name: source
tasks:
- name: test-app
  taskRef:
    name: make-test
  workspaces:
  - name: source
    workspace: source
- name: build-app
  taskRef:
    name: kaniko-build
  runAfter:
    - test-app
  workspaces:
  - name: source
    workspace: source

​
Using the retries Field

For each Task in the Pipeline, you can specify the number of times Tekton should retry its execution when it fails: 
tasks:
  - name: build-the-image
    retries: 1
    taskRef:
      name: build-push

​
Guard Task Execution using when Expressions

To run a Task only when certain conditions are met, you can guard task execution using the when field.

​
Components of when Expressions

ComponentDescriptionSyntax
inputInput for the when expressionStatic values or variables (parameters or results)
operatorRepresents an input’s relationship to valuesin or notin
valuesAn array of string valuesArray of static values or variables

​
Examples

tasks:
  - name: first-create-file
    when:
      - input: "$(params.path)"
        operator: in
        values: ["README.md"]
    taskRef:
      name: first-create-file

tasks:
  - name: echo-file-exists
    when:
      - input: "$(tasks.check-file.results.exists)"
        operator: in
        values: ["yes"]
    taskRef:
      name: echo-file-exists

tasks:
  - name: run-lint
    when:
      - input: "$(workspaces.lint-config.bound)"
        operator: in
        values: ["true"]
    taskRef:
      name: lint-source

​
Using Results

Tasks can emit Results when they execute. A Pipeline can use these Results for two purposes:
  1. Pass the Result of a Task into the Parameters or when expressions of another
  2. Emit Results and include data from the Results of its Tasks

​
Passing Results Between Tasks

tasks:
  - name: generate-id
    taskRef:
      name: generate-build-id
  - name: build-image
    taskRef:
      name: build-push
    params:
      - name: build-id
        value: "$(tasks.generate-id.results.build-id)"

​
Emitting Results from a Pipeline

spec:
  results:
    - name: sum
      description: The sum of the two provided integers
      value: "$(tasks.calculate-sum.results.sum)"
  tasks:
    - name: calculate-sum
      taskRef:
        name: add-task

​
Configuring Task Timeout

You can use the timeout field in the Task spec within the Pipeline to set the timeout of the TaskRun: 
spec:
  tasks:
    - name: build-the-image
      taskRef:
        name: build-push
      timeout: "0h1m30s"

​
Adding Finally to the Pipeline

You can specify finally tasks that should execute after all the Tasks in your Pipeline have completed: 
spec:
  tasks:
    - name: build-app
      taskRef:
        name: build
    - name: test-app
      taskRef:
        name: test
  finally:
    - name: cleanup
      taskRef:
        name: cleanup-workspace
    - name: notify
      taskRef:
        name: send-notification

​
Finally Tasks Features

  • finally tasks are executed in parallel
  • finally tasks are guaranteed to execute after all pipeline tasks complete
  • finally tasks can access execution status of pipeline tasks
  • finally tasks support when expressions

​
Using Execution Status in Finally Tasks

finally:
  - name: notify-failure
    when:
      - input: "$(tasks.status)"
        operator: in
        values: ["Failed"]
    taskRef:
      name: send-alert
  - name: cleanup-success
    when:
      - input: "$(tasks.status)"
        operator: in
        values: ["Succeeded"]
    taskRef:
      name: cleanup

​
Complete Pipeline Example

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: build-test-deploy
spec:
  params:
    - name: repo-url
      type: string
    - name: image-name
      type: string
  workspaces:
    - name: source
    - name: docker-credentials
  tasks:
    - name: fetch-source
      taskRef:
        name: git-clone
      params:
        - name: url
          value: $(params.repo-url)
      workspaces:
        - name: output
          workspace: source
    - name: run-tests
      taskRef:
        name: run-unit-tests
      runAfter:
        - fetch-source
      workspaces:
        - name: source
          workspace: source
    - name: build-image
      taskRef:
        name: kaniko
      runAfter:
        - run-tests
      params:
        - name: IMAGE
          value: $(params.image-name)
      workspaces:
        - name: source
          workspace: source
        - name: dockerconfig
          workspace: docker-credentials
  finally:
    - name: cleanup-workspace
      taskRef:
        name: cleanup
      workspaces:
        - name: source
          workspace: source

Build docs developers (and LLMs) love

Get started for freeTalk to us