Tekton – Tasks and Pipelines

Vault: Install Tekton Pipelines

Mon, 01 Jan 0001 00:00:00 +0000

This page includes content about running Tekton with specific platforms and cloud providers. The accuracy and freshness of this vendor documentation varies by vendor.

If you want to contribute with platform-specific documentation, follow the vendor contributions guidelines.

This guide explains how to install Tekton Pipelines.

Prerequisites

A Kubernetes cluster running version 1.28 or later.
Kubectl.
Grant cluster-admin privileges to the current user. See the Kubernetes role-based access control (RBAC) docs for more information.
(Optional) Install a Metrics Server if you need support for high availability use cases.

See the local installation guide if you want to test Tekton on your computer.

Installation

To install Tekton Pipelines on a Kubernetes cluster:

Run one of the following commands depending on which version of Tekton Pipelines you want to install:
- Latest official release:
```
kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml
```
  Note: These instructions are ideal as a quick start installation guide with Tekton Pipelines and not meant for the production use. Please refer to the operator to install, upgrade and manage Tekton projects.
- Nightly release:
```
kubectl apply --filename https://storage.googleapis.com/tekton-releases-nightly/pipeline/latest/release.yaml
```
- Specific release:
```
 kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/previous/<version_number>/release.yaml
```
  Replace <version_number> with the numbered version you want to install. For example, v0.26.0.
- Untagged release:
  
  If your container runtime does not support image-reference:tag@digest:
```
kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.notags.yaml
```

Multi-tenant installation is only partially supported today, read the guide for reference.

Monitor the installation:
```
kubectl get pods --namespace tekton-pipelines --watch
```
When all components show 1/1 under the READY column, the installation is complete. Hit Ctrl + C to stop monitoring.

Congratulations! You have successfully installed Tekton Pipelines on your Kubernetes cluster.

Before you proceed, create or select a project on Google Cloud and install the gcloud CLI on your computer.

To install Tekton Pipelines:

Enable the Google Kubernetes Engine (GKE) API:

gcloud services enable container.googleapis.com

Create a cluster with Workload Identity enabled. For example:
```
gcloud container clusters create tekton-cluster \
  --num-nodes=<nodes> \
  --region=<location> \
  --workload-pool=<project-id>.svc.id.goog
```
Where:
- <location> is the cluster location. For example, us-central1. See the documentation about regional and zonal clusters for more information.
- <project-id> is the project ID.
- <nodes> is the number of nodes.
Workload Identity allows your GKE cluster to access Google Cloud services using an Identity Access Management (IAM) service account. For example, the Tekton build and push guide explains how to authenticate to Artifact Registry on a cluster with Workload Identity enabled.

You can also enable Workload Idenitity on an existing cluster.
Follow the regular Kubernetes installation steps.

Private clusters

If you are running a private cluster and experience problems with GKE DNS resolution, allow the port 8443 in your firewall rules.

gcloud compute firewall-rules update <firewall_rule_name> --allow tcp:8443

See the documentation about firewall rules for private clusters for more information.

Autopilot

If you are using Autopilot mode on your GKE cluster and experience some problems, try the following:

Allow port 8443 in your firewall rules.

gcloud compute firewall-rules update <firewall_rule_name> --allow tcp:8443

Disable the affinity assistant.

kubectl patch cm feature-flags -n tekton-pipelines \
  -p '{"data":{"disable-affinity-assistant":"true"}}'

Increase the ephemeral storage.

To install Tekton Pipelines on OpenShift, you must first apply the anyuid security context constraint to the tekton-pipelines-controller service account. This is required to run the webhook Pod. See Security Context Constraints for more information.

Log on as a user with cluster-admin privileges. The following example uses the default system:admin user:
```
oc login -u system:admin
```

Set up the namespace (project) and configure the service account:

oc new-project tekton-pipelines
oc adm policy add-scc-to-user anyuid -z tekton-pipelines-controller
oc adm policy add-scc-to-user anyuid -z tekton-pipelines-webhook

Install Tekton Pipelines:

Because OpenShift uses random user id (and user id range per namespace) for pods, we need to remove the securityContext.runAsUser and securityContext.runAsGroup from any container from the release.yaml. You will need to have yq installed for this to work. Another way would be to download the yaml, search and replace (here replace with nothing) in your favourite editor.
```
curl https://storage.googleapis.com/tekton-releases/pipeline/latest/release.notags.yaml | yq 'del(.spec.template.spec.containers[].securityContext.runAsUser, .spec.template.spec.containers[].securityContext.runAsGroup)' | oc apply -f -
```
See the OpenShift CLI documentation for more information on the oc command.
Monitor the installation using the following command until all components show a Running status:
```
oc get pods --namespace tekton-pipelines --watch
```
Note: Hit CTRL + C to stop monitoring.

Congratulations! You have successfully installed Tekton Pipelines on your OpenShift environment.

To run OpenShift 4.x on your laptop (or desktop), take a look at Red Hat CodeReady Containers.

Additional configuration options

You can enable additional alpha and beta features, customize execution parameters, configure availability, and many more options. See the additional configuration options for more information.

Next steps

To get started with Tekton check the Introductory tutorials, the how-to guides, and the examples folder.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Resolver Reference

Writing a resolver is made easier with the github.com/tektoncd/pipeline/pkg/resolution/resolver/framework package. This package exposes a number of interfaces that let your code control what kind of behaviour it should have when running.

To get started really quickly see the resolver template, or for a howto guide see how to write a resolver.

The `Resolver` Interface

Implementing this interface is required. It provides just enough configuration for the framework to get a resolver running.

Method to Implement	Description
Initialize	Use this method to perform any setup required before the resolver starts receiving requests.
GetName	Use this method to return a name to refer to your Resolver by. e.g. `"Git"`
GetSelector	Use this method to specify the labels that a resolution request must have to be routed to your resolver.
Validate	Use this method to validate the resolution Spec given to your resolver.
Resolve	Use this method to perform get the resource based on the ResolutionRequestSpec as input and return it, along with any metadata about it in annotations. Errors returned by this method mark the ResolutionRequest as Failed, unless the error type is considered transient (e.g. a Kubernetes request timeout or etcd leader changes).

Method to Implement	Description
Initialize	Use this method to perform any setup required before the resolver starts receiving requests.
GetName	Use this method to return a name to refer to your Resolver by. e.g. `"Git"`
GetSelector	Use this method to specify the labels that a resolution request must have to be routed to your resolver.
ValidateParams	Use this method to validate the params given to your resolver.
Resolve	Use this method to perform get the resource based on params as input and return it, along with any metadata about it in annotations

The `ConfigWatcher` Interface

Implement this optional interface if your Resolver requires some amount of admin configuration. For example, if you want to allow admin users to configure things like timeouts, namespaces, lists of allowed registries, api endpoints or base urls, service account names to use, etc…

Method to Implement Description

GetConfigName Use this method to return the name of the configmap admins will use to configure this resolver. Once this interface is implemented your Validate and Resolve methods will be able to access your latest resolver configuration by calling framework.GetResolverConfigFromContext(ctx). Note that this configmap must exist when your resolver starts - put a default one in your resolver’s config/ directory.

Method to Implement	Description
GetConfigName	Use this method to return the name of the configmap admins will use to configure this resolver. Once this interface is implemented your `Validate` and `Resolve` methods will be able to access your latest resolver configuration by calling `framework.GetResolverConfigFromContext(ctx)`. Note that this configmap must exist when your resolver starts - put a default one in your resolver’s `config/` directory.

The `TimedResolution` Interface

Implement this optional interface if your Resolver needs to custimze the timeout a resolution request can take. This may be based on knowledge of the underlying storage (e.g. some git repositories are slower to clone than others) or might be something an admin configures with a configmap.

The default timeout of a request is 1 minute if this interface is not implemented. Note: There is currently a global maximum timeout of 1 minute for all resolution requests to prevent zombie requests remaining in an incomplete state forever.

Method to Implement	Description
GetResolutionTimeout	Return a custom timeout duration from this method to control how long a resolution request to this resolver may take.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Migrating From Tekton `v1alpha1` to Tekton `v1beta1`

This document describes the differences between v1alpha1 Tekton entities and their v1beta1 counterparts. It also describes how to replace the supported types of PipelineResources with Tasks from the Tekton Catalog of equivalent functionality.

Changes to fields

In Tekton v1beta1, the following fields have been changed:

Old field	New field
`spec.inputs.params`	`spec.params`
`spec.inputs`	Removed from `Tasks`
`spec.outputs`	Removed from `Tasks`
`spec.inputs.resources`	`spec.resources.inputs`
`spec.outputs.resources`	`spec.resources.outputs`

Changes to input parameters

In Tekton v1beta1, input parameters have been moved from spec.inputs.params to spec.params.

For example, consider the following v1alpha1 parameters:

# Task.yaml (v1alpha1)
spec:
  inputs:
    params:
      - name: ADDR
        description: Address to curl.
        type: string

# TaskRun.yaml (v1alpha1)
spec:
  inputs:
    params:
      - name: ADDR
        value: https://example.com/foo.json

The above parameters are now represented as follows in v1beta1:

# Task.yaml (v1beta1)
spec:
  params:
    - name: ADDR
      description: Address to curl.
      type: string

# TaskRun.yaml (v1beta1)
spec:
  params:
    - name: ADDR
      value: https://example.com/foo.json

Replacing `PipelineResources` with `Tasks`

See “Replacing PipelineResources with Tasks” for information and examples on how to replace PipelineResources when migrating from v1alpha1 to v1beta1.

Changes to PipelineResources

In Tekton v1beta1, PipelineResources have been moved from spec.input.resources and spec.output.resources to spec.resources.inputs and spec.resources.outputs, respectively.

For example, consider the following v1alpha1 definition:

# Task.yaml (v1alpha1)
spec:
  inputs:
    resources:
      - name: skaffold
        type: git
  outputs:
    resources:
      - name: baked-image
        type: image

# TaskRun.yaml (v1alpha1)
spec:
  inputs:
    resources:
      - name: skaffold
        resourceSpec:
          type: git
          params:
            - name: revision
              value: v0.32.0
            - name: url
              value: https://github.com/GoogleContainerTools/skaffold
  outputs:
    resources:
      - name: baked-image
        resourceSpec:
          - type: image
            params:
              - name: url
                value: gcr.io/foo/bar

The above definition becomes the following in v1beta1:

# Task.yaml (v1beta1)
spec:
  resources:
    inputs:
      - name: src-repo
        type: git
    outputs:
      - name: baked-image
        type: image

# TaskRun.yaml (v1beta1)
spec:
  resources:
    inputs:
      - name: src-repo
        resourceSpec:
          type: git
          params:
            - name: revision
              value: main
            - name: url
              value: https://github.com/tektoncd/pipeline
    outputs:
      - name: baked-image
        resourceSpec:
          - type: image
            params:
              - name: url
                value: gcr.io/foo/bar

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with Resolvers

Introduction

This guide will take you from an empty Kubernetes cluster to a functioning Tekton Pipelines installation and a PipelineRun executing with a Pipeline stored in a git repo.

Prerequisites

A computer with kubectl.
A Kubernetes cluster running at least Kubernetes 1.28. A kind cluster should work fine for following the guide on your local machine.
An image registry that you can push images to. If you’re using kind make sure your KO_DOCKER_REPO environment variable is set to kind.local.
A publicly available git repository where you can put a pipeline yaml file.

Step 1: Install Tekton Pipelines and the Resolvers

See the installation instructions for Tekton Pipeline, and the installation instructions for the built-in resolvers.

Step 2: Ensure Pipelines is configured to enable resolvers

Starting with v0.41.0, remote resolvers for Tekton Pipelines are enabled by default, but can be disabled via feature flags in the resolvers-feature-flags configmap in the tekton-pipelines-resolvers namespace. Check that configmap to verify that the resolvers you wish to have enabled are set to "true".

The feature flags for the built-in resolvers are:

The bundles resolver: enable-bundles-resolver
The git resolver: enable-git-resolver
The hub resolver: enable-hub-resolver
The cluster resolver: enable-cluster-resolver

Step 3: Try it out!

In order to test out your install you’ll need a Pipeline stored in a public git repository. First cd into a clone of your repo and then create a new branch:

# checkout a new branch in the public repo you're using
git checkout -b add-a-simple-pipeline

Then create a basic pipeline:

cat <<"EOF" > pipeline.yaml
kind: Pipeline
apiVersion: tekton.dev/v1beta1
metadata:
  name: a-simple-pipeline
spec:
  params:
  - name: username
  tasks:
  - name: task-1
    params:
    - name: username
      value: $(params.username)
    taskSpec:
      params:
      - name: username
      steps:
      - image: alpine:3.15
        script: |
          echo "hello $(params.username)"
EOF

Commit the pipeline and push it to your git repo:

git add ./pipeline.yaml
git commit -m "Add a basic pipeline to test Tekton Pipeline remote resolution"

# push to your publicly accessible repository, replacing origin with
# your git remote's name
git push origin add-a-simple-pipeline

And finally create a PipelineRun that uses your pipeline:

# first assign your public repo's url to an environment variable
REPO_URL=# insert your repo's url here

# create a pipelinerun yaml file
cat <<EOF > pipelinerun.yaml
kind: PipelineRun
apiVersion: tekton.dev/v1beta1
metadata:
  name: run-basic-pipeline-from-git
spec:
  pipelineRef:
    resolver: git
    params:
    - name: url
      value: ${REPO_URL}
    - name: revision
      value: add-a-simple-pipeline
    - name: pathInRepo
      value: pipeline.yaml
  params:
  - name: username
    value: liza
EOF

# execute the pipelinerun
kubectl apply -f ./pipelinerun.yaml

Step 4: Monitor the PipelineRun

First let’s watch the PipelineRun to see if it succeeds:

kubectl get pipelineruns -w

Shortly the PipelineRun should move into a Succeeded state.

Now we can check the logs of the PipelineRun’s only task:

kubectl logs run-basic-pipeline-from-git-task-1-pod
# This should print "hello liza"

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

How to write a Resolver

This how-to will outline the steps a developer needs to take when creating a new (very basic) Resolver. Rather than focus on support for a particular version control system or cloud platform this Resolver will simply respond with some hard-coded YAML.

If you aren’t yet familiar with the meaning of “resolution” when it comes to Tekton, a short summary follows. You might also want to read a little bit into Tekton Pipelines, particularly the docs on specifying a target Pipeline to run and, if you’re feeling particularly brave or bored, the really long design doc describing Tekton Resolution.

What’s a Resolver?

A Resolver is a program that runs in a Kubernetes cluster alongside Tekton Pipelines and “resolves” requests for Tasks and Pipelines from remote locations. More concretely: if a user submitted a PipelineRun that needed a Pipeline YAML stored in a git repo, then it would be a Resolver that’s responsible for fetching the YAML file from git and returning it to Tekton Pipelines.

This pattern extends beyond just git, allowing a developer to integrate support for other version control systems, cloud buckets, or storage systems without having to modify Tekton Pipelines itself.

Just want to see the working example?

If you’d prefer to look at the end result of this howto you can take a visit the ./resolver-template in the Tekton Resolution repo. That template is built on the code from this howto to get you up and running quickly.

Pre-requisites

Before getting started with this howto you’ll need to be comfortable developing in Go and have a general understanding of how Tekton Resolution works.

You’ll also need the following:

A computer with kubectl and ko installed.
A Kubernetes cluster running at least Kubernetes 1.28. A kind cluster should work fine for following the guide on your local machine.
An image registry that you can push images to. If you’re using kind make sure your KO_DOCKER_REPO environment variable is set to kind.local.
Tekton Pipelines and remote resolvers installed in your Kubernetes cluster. See the installation guide for instructions on installing it.

First Steps

The first thing to do is create an initial directory structure for your project. For this example we’ll create a directory and initialize a new go module with a few subdirectories for our code:

$ mkdir demoresolver

$ cd demoresolver

$ go mod init example.com/demoresolver

$ mkdir -p cmd/demoresolver

$ mkdir config

The cmd/demoresolver directory will contain code for the resolver and the config directory will eventually contain a yaml file for deploying the resolver to Kubernetes.

Initializing the resolver’s binary

A Resolver is ultimately just a program running in your cluster, so the first step is to fill out the initial code for starting that program. Our resolver here is going to be extremely simple and doesn’t need any flags or special environment variables, so we’ll just initialize it with a little bit of boilerplate.

Create cmd/demoresolver/main.go with the following setup code:

package main

import (
  "context"
  "github.com/tektoncd/pipeline/pkg/remoteresolution/resolver/framework"
  "knative.dev/pkg/injection/sharedmain"
)

func main() {
  sharedmain.Main("controller",
    framework.NewController(context.Background(), &resolver{}),
  )
}

type resolver struct {}

package main

import (
  "context"
  "github.com/tektoncd/pipeline/pkg/resolution/resolver/framework"
  "knative.dev/pkg/injection/sharedmain"
)

func main() {
  sharedmain.Main("controller",
    framework.NewController(context.Background(), &resolver{}),
  )
}

type resolver struct {}

This won’t compile yet but you can download the dependencies by running:

# Depending on your go version you might not need the -compat flag
$ go mod tidy -compat=1.17

Writing the Resolver

If you try to build the binary right now you’ll receive the following error:

$ go build -o /dev/null ./cmd/demoresolver

cmd/demoresolver/main.go:11:78: cannot use &resolver{} (type *resolver) as
type framework.Resolver in argument to framework.NewController:
        *resolver does not implement framework.Resolver (missing GetName method)

We’ve already defined our own resolver type but in order to get the resolver running you’ll need to add the methods defined in the framework.Resolver interface to your main.go file. Going through each method in turn:

The `Initialize` method

This method is used to start any libraries or otherwise setup any prerequisites your resolver needs. For this example we won’t need anything so this method can just return nil.

// Initialize sets up any dependencies needed by the resolver. None atm.
func (r *resolver) Initialize(context.Context) error {
  return nil
}

The `GetName` method

This method returns a string name that will be used to refer to this resolver. You’d see this name show up in places like logs. For this simple example we’ll return "Demo":

// GetName returns a string name to refer to this resolver by.
func (r *resolver) GetName(context.Context) string {
  return "Demo"
}

The `GetSelector` method

This method should return a map of string labels and their values that will be used to direct requests to this resolver. For this example the only label we’re interested in matching on is defined by tektoncd/resolution:

// GetSelector returns a map of labels to match requests to this resolver.
func (r *resolver) GetSelector(context.Context) map[string]string {
  return map[string]string{
    common.LabelKeyResolverType: "demo",
  }
}

What this does is tell the resolver framework that any ResolutionRequest object with a label of "resolution.tekton.dev/type": "demo" should be routed to our example resolver.

We’ll also need to add another import for this package at the top:

import (
  "context"
  
  // Add this one; it defines LabelKeyResolverType we use in GetSelector
  "github.com/tektoncd/pipeline/pkg/resolution/common"
  "github.com/tektoncd/pipeline/pkg/remoteresolution/resolver/framework"
  "knative.dev/pkg/injection/sharedmain"
  pipelinev1 "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1"
)

import (
  "context"
  
  // Add this one; it defines LabelKeyResolverType we use in GetSelector
  "github.com/tektoncd/pipeline/pkg/resolution/common"
  "github.com/tektoncd/pipeline/pkg/resolution/resolver/framework"
  "knative.dev/pkg/injection/sharedmain"
  pipelinev1 "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1"
)

The `Validate` method

The Validate method checks that the resolution-spec submitted as part of a resolution request are valid. Our example resolver doesn’t expect any params in the spec so we’ll simply ensure that the there are no params. Our example resolver also expects format for the url to be demoscheme://<path> so we’ll validate this format. In the previous version, this was instead called ValidateParams method. See below for the differences.

// Validate ensures that the resolution spec from a request is as expected.
func (r *resolver) Validate(ctx context.Context, req *v1beta1.ResolutionRequestSpec) error {
  if len(req.Params) > 0 {
    return errors.New("no params allowed")
  }
  url := req.URL
  u, err := neturl.ParseRequestURI(url)
  if err != nil {
    return err
  }
  if u.Scheme != "demoscheme" {
    return fmt.Errorf("Invalid Scheme. Want %s, Got %s", "demoscheme", u.Scheme)
  }
  if u.Path == "" {
    return errors.New("Empty path.")
  }
  return nil
}

You’ll also need to add the net/url as neturl and "errors" package to your list of imports at the top of the file.

// ValidateParams ensures that the params from a request are as expected.
func (r *resolver) ValidateParams(ctx context.Context, params []pipelinev1.Param) error {
  if len(req.Params) > 0 {
    return errors.New("no params allowed")
  }
  return nil
}

You’ll also need to add the "errors" package to your list of imports at the top of the file.

The `Resolve` method

We implement the Resolve method to do the heavy lifting of fetching the contents of a file and returning them. It takes in the resolution request spec as input. For this example we’re just going to return a hard-coded string of YAML. Since Tekton Pipelines currently only supports fetching Pipeline resources via remote resolution that’s what we’ll return.

The method signature we’re implementing here has a framework.ResolvedResource interface as one of its return values. This is another type we have to implement but it has a small footprint:

// Resolve uses the given resolution spec to resolve the requested file or resource.
func (r *resolver) Resolve(ctx context.Context, req *v1beta1.ResolutionRequestSpec) (framework.ResolvedResource, error) {
  return &myResolvedResource{}, nil
}

// our hard-coded resolved file to return
const pipeline = `
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: my-pipeline
spec:
  tasks:
  - name: hello-world
    taskSpec:
      steps:
      - image: alpine:3.15.1
        script: |
          echo "hello world"
`

// myResolvedResource wraps the data we want to return to Pipelines
type myResolvedResource struct {}

// Data returns the bytes of our hard-coded Pipeline
func (*myResolvedResource) Data() []byte {
  return []byte(pipeline)
}

// Annotations returns any metadata needed alongside the data. None atm.
func (*myResolvedResource) Annotations() map[string]string {
  return nil
}

// RefSource is the source reference of the remote data that records where the remote 
// file came from including the url, digest and the entrypoint. None atm.
func (*myResolvedResource) RefSource() *pipelinev1.RefSource {
	return nil
}

// Resolve uses the given resolution spec to resolve the requested file or resource.
func (r *resolver) Resolve(ctx context.Context, params []pipelinev1.Param) (framework.ResolvedResource, error) {
  return &myResolvedResource{}, nil
}

// our hard-coded resolved file to return
const pipeline = `
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: my-pipeline
spec:
  tasks:
  - name: hello-world
    taskSpec:
      steps:
      - image: alpine:3.15.1
        script: |
          echo "hello world"
`

// myResolvedResource wraps the data we want to return to Pipelines
type myResolvedResource struct {}

// Data returns the bytes of our hard-coded Pipeline
func (*myResolvedResource) Data() []byte {
  return []byte(pipeline)
}

// Annotations returns any metadata needed alongside the data. None atm.
func (*myResolvedResource) Annotations() map[string]string {
  return nil
}

// RefSource is the source reference of the remote data that records where the remote 
// file came from including the url, digest and the entrypoint. None atm.
func (*myResolvedResource) RefSource() *pipelinev1.RefSource {
	return nil
}

// Resolve uses the given resolution spec to resolve the requested file or resource.
func (r *resolver) Resolve(ctx context.Context, req *v1beta1.ResolutionRequestSpec) (framework.ResolvedResource, error) {
  return &myResolvedResource{}, nil
}

// our hard-coded resolved file to return
const pipeline = `
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: my-pipeline
spec:
  tasks:
  - name: hello-world
    taskSpec:
      steps:
      - image: alpine:3.15.1
        script: |
          echo "hello world"
`

// myResolvedResource wraps the data we want to return to Pipelines
type myResolvedResource struct {}

// Data returns the bytes of our hard-coded Pipeline
func (*myResolvedResource) Data() []byte {
  return []byte(pipeline)
}

// Annotations returns any metadata needed alongside the data. None atm.
func (*myResolvedResource) Annotations() map[string]string {
  return nil
}

// RefSource is the source reference of the remote data that records where the remote 
// file came from including the url, digest and the entrypoint. None atm.
func (*myResolvedResource) RefSource() *pipelinev1.RefSource {
	return nil
}

Best practice: In order to enable Tekton Chains to record the source information of the remote data in the SLSA provenance, the resolver should implement the RefSource() method to return a correct RefSource value. See the following example.

// RefSource is the source reference of the remote data that records where the remote 
// file came from including the url, digest and the entrypoint.
func (*myResolvedResource) RefSource() *pipelinev1.RefSource {
	return &v1.RefSource{
		URI: "https://github.com/user/example",
		Digest: map[string]string{
			"sha1": "example",
		},
		EntryPoint: "foo/bar/task.yaml",
	}
}

The deployment configuration

Finally, our resolver needs some deployment configuration so that it can run in Kubernetes.

A full description of the config is beyond the scope of a short howto but in summary we’ll tell Kubernetes to run our resolver application along with some environment variables and other configuration that the underlying knative framework expects. The deployed application is put in the tekton-pipelines namespace and uses ko to build its container image. Finally the ServiceAccount our deployment uses is tekton-pipelines-resolvers, which is the default ServiceAccount shared by all resolvers in the tekton-pipelines-resolvers namespace.

The full configuration follows:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demoresolver
  namespace: tekton-pipelines-resolvers
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demoresolver
  template:
    metadata:
      labels:
        app: demoresolver
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - podAffinityTerm:
              labelSelector:
                matchLabels:
                  app: demoresolver
              topologyKey: kubernetes.io/hostname
            weight: 100
      serviceAccountName: tekton-pipelines-resolvers
      containers:
      - name: controller
        image: ko://example.com/demoresolver/cmd/demoresolver
        resources:
          requests:
            cpu: 100m
            memory: 100Mi
          limits:
            cpu: 1000m
            memory: 1000Mi
        ports:
        - name: metrics
          containerPort: 9090
        env:
        - name: SYSTEM_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: CONFIG_LOGGING_NAME
          value: config-logging
        - name: CONFIG_OBSERVABILITY_NAME
          value: config-observability
        - name: METRICS_DOMAIN
          value: tekton.dev/resolution
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsNonRoot: true
          capabilities:
            drop:
            - all

Phew, ok, put all that in a file at config/demo-resolver-deployment.yaml and you’ll be ready to deploy your application to Kubernetes and see it work!

Trying it out

Now that all the code is written your new resolver should be ready to deploy to a Kubernetes cluster. We’ll use ko to build and deploy the application:

$ ko apply -f ./config/demo-resolver-deployment.yaml

Assuming the resolver deployed successfully you should be able to see it in the output from the following command:

$ kubectl get deployments -n tekton-pipelines

# And here's approximately what you should see when you run this command:
NAME          READY   UP-TO-DATE   AVAILABLE   AGE
controller    1/1     1            1           2d21h
demoresolver  1/1     1            1           91s
webhook       1/1     1            1           2d21

To exercise your new resolver, let’s submit a request for its hard-coded pipeline. Create a file called test-request.yaml with the following content:

apiVersion: resolution.tekton.dev/v1beta1
kind: ResolutionRequest
metadata:
  name: test-request
  labels:
    resolution.tekton.dev/type: demo

And submit this request with the following command:

$ kubectl apply -f ./test-request.yaml && kubectl get --watch resolutionrequests

You should soon see your ResolutionRequest printed to screen with a True value in its SUCCEEDED column:

resolutionrequest.resolution.tekton.dev/test-request created
NAME           SUCCEEDED   REASON
test-request   True

Press Ctrl-C to get back to the command line.

If you now take a look at the ResolutionRequest’s YAML you’ll see the hard-coded pipeline yaml in its status.data field. It won’t be totally recognizable, though, because it’s encoded as base64. Have a look with the following command:

$ kubectl get resolutionrequest test-request -o yaml

You can convert that base64 data back into yaml with the following command:

$ kubectl get resolutionrequest test-request -o jsonpath="{$.status.data}" | base64 -d

Great work, you’ve successfully written a Resolver from scratch!

Next Steps

At this point you could start to expand the Resolve() method in your Resolver to fetch data from your storage backend of choice.

Or if you prefer to take a look at a more fully-realized example of a Resolver, see the code for the gitresolver hosted in the Tekton Pipeline repo.

Finally, another direction you could take this would be to try writing a PipelineRun for Tekton Pipelines that speaks to your Resolver. Can you get a PipelineRun to execute successfully that uses the hard-coded Pipeline your Resolver returns?

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Controller Performance Configuration

Configure ThreadsPerController, QPS and Burst

Overview

This document will show us how to configure tekton-pipeline-controller’s performance. In general, there are mainly have three parameters will impact the performance of tekton controller, they are ThreadsPerController, QPS and Burst.

ThreadsPerController: Threads (goroutines) to create per controller. It’s the number of threads to use when processing the controller’s work queue.

QPS: Queries per Second. Maximum QPS to the master from this client.
Burst: Maximum burst for throttle.

Performance Configuration

Configure Thread, QPS and Burst

Default, the value of ThreadsPerController, QPS and Burst is 2, 5.0 and 10 accordingly.

Sometimes, above default values can’t meet performance requirements, then you need to overwrite these values. You can modify them in the tekton controller deployment. You can specify these customized values in the tekton-pipelines-controller container via threads-per-controller, kube-api-qps and kube-api-burst flags accordingly. For example:

spec:
  serviceAccountName: tekton-pipelines-controller
  containers:
    - name: tekton-pipelines-controller
      image: ko://github.com/tektoncd/pipeline/cmd/controller
      args: [
          "-kube-api-qps", "50",
          "-kube-api-burst", "50",
          "-threads-per-controller", "32",
          # other flags defined here...
        ]

Now, the ThreadsPerController, QPS and Burst have been changed to be 32, 50 and 50.

You can also set THREADS_PER_CONTROLLER, KUBE_API_QPS and KUBE_API_BURST environment variables to overwrite default values. If flags and environment variables are set, command line args will take precedence.

Note:

Although in above example, you set QPS and Burst to be 50 and 50. However, the actual values of them are multiplied by 2, so the actual QPS and Burst is 100 and 100.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Controllers flags

The different controllers tektoncd/pipeline ships comes with a set of flags that can be changed (in the yaml payloads) for advanced use cases. This page is documenting them.

Common set of flags

The following flags are available on all “controllers”, aka controller, webhook, events and resolvers.

  -add_dir_header
        If true, adds the file directory to the header of the log messages
  -alsologtostderr
        log to standard error as well as files (no effect when -logtostderr=true)
  -cluster string
        Defaults to the current cluster in kubeconfig.
  -disable-ha
        Whether to disable high-availability functionality for this component.  This flag will be deprecated and removed when we have promoted this feature to stable, so do not pass it without filing an issue upstream!
  -kube-api-burst int
        Maximum burst for throttle.
  -kube-api-qps float
        Maximum QPS to the server from the client.
  -kubeconfig string
        Path to a kubeconfig. Only required if out-of-cluster.
  -log_backtrace_at value
        when logging hits line file:N, emit a stack trace
  -log_dir string
        If non-empty, write log files in this directory (no effect when -logtostderr=true)
  -log_file string
        If non-empty, use this log file (no effect when -logtostderr=true)
  -log_file_max_size uint
        Defines the maximum size a log file can grow to (no effect when -logtostderr=true). Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)
  -logtostderr
        log to standard error instead of files (default true)
  -one_output
        If true, only write logs to their native severity level (vs also writing to each lower severity level; no effect when -logtostderr=true)
  -server string
        The address of the Kubernetes API server. Overrides any value in kubeconfig. Only required if out-of-cluster.
  -skip_headers
        If true, avoid header prefixes in the log messages
  -skip_log_headers
        If true, avoid headers when opening log files (no effect when -logtostderr=true)
  -stderrthreshold value
        logs at or above this threshold go to stderr when writing to files and stderr (no effect when -logtostderr=true or -alsologtostderr=false) (default 2)
  -v value
        number for the log level verbosity
  -vmodule value
        comma-separated list of pattern=N settings for file-filtered logging

`controller`

The main controller binary has additional flags to configure its behavior.

  -entrypoint-image string
        The container image containing our entrypoint binary.
  -namespace string
        Namespace to restrict informer to. Optional, defaults to all namespaces.
  -nop-image string
        The container image used to stop sidecars
  -resync-period duration
        The period between two resync run (going through all objects) (default 10h0m0s)
  -shell-image string
        The container image containing a shell
  -shell-image-win string
        The container image containing a windows shell
  -sidecarlogresults-image string
        The container image containing the binary for accessing results.
  -threads-per-controller int
        Threads (goroutines) to create per controller (default 2)
  -workingdirinit-image string
        The container image containing our working dir init binary.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

HA Support for Tekton Pipeline Controllers

Overview

This document is aimed at helping Cluster Admins when configuring High Availability (HA) support for the Tekton Pipeline Controller and Webhook components. HA support allows components to remain operational when a disruption occurs, such as nodes being drained for upgrades.

Controller HA

For the Controller, HA is achieved by following an active/active model, where all replicas of the Controller can receive and process work items. In this HA approach the workqueue is distributed across buckets, where each replica owns a subset of those buckets and can process the load if the given replica is the leader of that bucket.

By default, only one Controller replica is configured, to reduce resource usage. This effectively disables HA for the Controller by default.

Configuring Controller Replicas

In order to achieve HA for the Controller, the number of replicas for the Controller should be greater than one. This allows other instances to take over in case of any disruption on the current active controller.

You can modify the replicas number in the Controller deployment under spec.replicas, or apply an update to a running deployment:

kubectl -n tekton-pipelines scale deployment tekton-pipelines-controller --replicas=3

Configuring Leader Election

Leader election can be configured in config-leader-election.yaml. The ConfigMap defines the following parameters:

Parameter	Default
`data.buckets`	1
`data.leaseDuration`	15s
`data.renewDeadline`	10s
`data.retryPeriod`	2s

Note: The maximum value of data.buckets at this time is 10.

Disabling Controller HA

If HA is not required, you can disable it by scaling the deployment back to one replica. You can also modify the controller deployment, by specifying in the tekton-pipelines-controller container the disable-ha flag. For example:

spec:
  serviceAccountName: tekton-pipelines-controller
  containers:
    - name: tekton-pipelines-controller
      # ...
      args: [
          # Other flags defined here...
          "-disable-ha=true",
        ]

Note: If you set -disable-ha=false and run multiple replicas of the Controller, each replica will process work items separately, which will lead to unwanted behavior when creating resources (e.g., TaskRuns, etc.).

In general, setting -disable-ha=false is not recommended. Instead, to disable HA, simply run one replica of the Controller deployment.

Webhook HA

The Webhook deployment is stateless, which means it can more easily be configured for HA, and even autoscale replicas in response to load.

By default, only one Webhook replica is configured, to reduce resource usage. This effectively disables HA for the Webhook by default.

Configuring Webhook Replicas

In order to achieve HA for the Webhook deployment, you can modify the replicas number in the Webhook deployment under spec.replicas, or apply an update to a running deployment:

kubectl -n tekton-pipelines scale deployment tekton-pipelines-webhook --replicas=3

You can also modify the HorizontalPodAutoscaler to set a minimum number of replicas:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: tekton-pipelines-webhook
# ...
spec:
  minReplicas: 1

By default, the Webhook deployment is not configured to block a Cluster Autoscaler from scaling down the node that’s running the only replica of the deployment using the cluster-autoscaler.kubernetes.io/safe-to-evict annotation. This means that during node drains, the Webhook might be unavailable temporarily, during which time Tekton resources can’t be created, updated or deleted. To avoid this, you can add the safe-to-evict annotation set to false to block node drains during autoscaling, or, better yet, configure multiple replicas of the Webhook deployment.

Avoiding Disruptions

To avoid the Webhook Service becoming unavailable during node unavailability (e.g., during node upgrades), you can ensure that a minimum number of Webhook replicas are available at time by defining a PodDisruptionBudget which sets a minAvailable greater than zero:

apiVersion: policy/v1beta1
kind: PodDisruptionBudget
metadata:
  name: tekton-pipelines-webhook
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/name: webhook
    app.kubernetes.io/component: webhook
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
    # ...
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: webhook
      app.kubernetes.io/component: webhook
      app.kubernetes.io/instance: default
      app.kubernetes.io/part-of: tekton-pipelines

Webhook replicas are configured to avoid being scheduled onto the same node by default, so that a single node disruption doesn’t make all Webhook replicas unavailable.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Deprecations

Introduction

This doc provides a list of features in Tekton Pipelines that are deprecated or recently removed.

Deprecation Table

The following features are deprecated but have not yet been removed.

Deprecated Features	Deprecation Announcement	API Compatibility Policy	Earliest Date or Release of Removal
Several fields of Task.Step are deprecated	v0.36.0	Beta	Feb 25, 2023
ClusterTask is deprecated	v0.41.0	Beta	July 13, 2023
The `config-trusted-resources` configMap is deprecated	v0.45.0	Alpha	v0.46.0
The `default-cloud-events-sink` setting in the `config-defaults` configMap is deprecated in favour of the new `config-events` configMap.	v0.50.0	N/A	v0.59.0
v1beta1 Tasks, TaskRuns, Pipelines, and PipelineRuns are deprecated in favor of v1	v0.50.0	Beta	v0.62.0
The `resolver framework` is deprecated in favor of an upgraded framework	v0.60.0	N/A	v0.72.

v1beta1 deprecation

The v1beta1 versions of Task, TaskRun, Pipeline, and PipelineRun are deprecated in favor of the v1 versions of these APIs, as of release v0.50.0. Following the beta CRD compatibility policy, the earliest release the v1beta1 versions of these CRDs may be removed is 1 year later, or v0.62.0 (LTS). The v1beta1 client libraries will be retained until v0.62.0 has reached its end of life, 1 year later. Therefore, the earliest release the client libraries may be removed is v0.74.0, 12 months after v0.62.0.

Removed features

The features listed below have been removed but may still be supported in releases that have not reached their EOL.

Removed Feature	Removal Pull Request	Removal Date	Latest LTS Release with Support	EOL of Supported Release
The `PipelineRun.Status.TaskRuns` and `PipelineRun.Status.Runs` fields and the `embedded-status` feature flag along with their functionalities have been tombstoned since v0.45.	[TEP100] Remove Taskruns and Runs Fields for PipelineRunStatus	Jan 25, 2023	v0.44.0	Jan 24, 2024
PipelineResources are removed, along with the components of the API that rely on them as proposed in TEP-0074. See Removed `PipelineResources` related features for more info.	[TEP074] Remove Generic PipelineResources with Rest of Resources Types	Mar 8, 2023	v0.44.0	Jan 24, 2024
v1alpha1 Runs are removed, as proposed in TEP-0114, along with the feature flags `enable-custom-task` and `custom-task-version`.	TEP-0114: Remove support for v1alpha1.Run	April 7, 2023	v0.44.0	Jan 24, 2024
The `disable-affinity-assistant` feature flag is deprecated in favor of the `coschedule` feature flag	cleanup: [TEP-0135] remove deprecated disable-affinity-assistant feature flag	Mar 1, 2025	v0.68.0	Jan 30, 2026

The following features are removed as part of the deprecation of PipelineResources. See TEP-0074 for more information.

the fieldstask.spec.resources, taskRun.spec.resources, pipeline.spec.resources, pipelineRun.spec.resources, and taskRun.status.cloudEvents
images built upon PipelineResources
- the kubeconfigwriter image used with Cluster PipelineResource
- the imagedigestexporter image of Image PipelineResource
- the pullrequest-init image used with Pullrequest PipelineResource
- the gsutil image used with Storage PipelineResource
The tekton_pipelines_controller_cloudevent_count metric
The artifacts bucket/pvc setup by the pkg/artifacts package related with Storage PipelineResources
The generic pipelineResources functions including inputs and outputs resources and the from type
TaskRun.Status.ResourcesResult is deprecated and tombstoned #6301

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Debug

Overview

Debug spec is used for troubleshooting and breakpointing runtime resources. This doc helps understand the inner workings of debug in Tekton. Currently only the TaskRun resource is supported.

This is an alpha feature. The enable-api-fields feature flag must be set to "alpha" to specify debug in a taskRun.

Debugging TaskRuns

The following provides explanation on how Debugging TaskRuns is possible through Tekton. To understand how to use the debug spec for TaskRuns follow the TaskRun Debugging Documentation.

Breakpoint on Failure

Halting a TaskRun execution on Failure of a step.

Failure of a Step

The entrypoint binary is used to manage the lifecycle of a step. Steps are aligned beforehand by the TaskRun controller allowing each step to run in a particular order. This is done using -wait_file and the -post_file flags. The former let’s the entrypoint binary know that it has to wait on creation of a particular file before starting execution of the step. And the latter provides information on the step number and signal the next step on completion of the step.

On success of a step, the -post-file is written as is, signalling the next step which would have the same argument given for -wait_file to resume the entrypoint process and move ahead with the step.

On failure of a step, the -post_file is written with appending .err to it denoting that the previous step has failed with and error. The subsequent steps are skipped in this case as well, marking the TaskRun as a failure.

Halting a Step on failure

The failed step writes <step-no>.err to /tekton/run and stops running completely. To be able to debug a step we would need it to continue running (not exit), not skip the next steps and signal health of the step. By disabling step skipping, stopping write of the <step-no>.err file and waiting on a signal by the user to disable the halt, we would be simulating a “breakpoint”.

In this breakpoint, which is essentially a limbo state the TaskRun finds itself in, the user can interact with the step environment using a CLI or an IDE.

Exiting onfailure breakpoint

To exit a step which has been paused upon failure, the step would wait on a file similar to <step-no>.breakpointexit which would unpause and exit the step container. eg: Step 0 fails and is paused. Writing 0.breakpointexit in /tekton/run would unpause and exit the step container.

Breakpoint before step

TaskRun will be stuck waiting for user debugging before the step execution. When beforeStep-Breakpoint takes effect, the user can see the following information from the corresponding step container log:

debug before step breakpoint has taken effect, waiting for user's decision:
1) continue, use cmd: /tekton/debug/scripts/debug-beforestep-continue
2) fail-continue, use cmd: /tekton/debug/scripts/debug-beforestep-fail-continue

Executing /tekton/debug/scripts/debug-beforestep-continue will continue to execute the step program
Executing /tekton/debug/scripts/debug-beforestep-fail-continue will not continue to execute the task, and will mark the step as failed

Debug Environment

Additional environment augmentations made available to the TaskRun Pod to aid in troubleshooting and managing step lifecycle.

Mounts

/tekton/debug/scripts : Contains scripts which the user can run to mark the step as a success, failure or exit the breakpoint. Shared between all the containers.

/tekton/debug/info/<n> : Contains information about the step. Single EmptyDir shared between all step containers, but renamed to reflect step number. eg: Step 0 will have /tekton/debug/info/0, Step 1 will have /tekton/debug/info/1 etc.

Debug Scripts

/tekton/debug/scripts/debug-continue : Mark the step as completed with success by writing to /tekton/run. eg: User wants to exit onfailure breakpoint for failed step 0. Running this script would create /tekton/run/0 and /tekton/run/0/out.breakpointexit.

/tekton/debug/scripts/debug-fail-continue : Mark the step as completed with failure by writing to /tekton/run. eg: User wants to exit onfailure breakpoint for failed step 0. Running this script would create /tekton/run/0 and /tekton/run/0/out.breakpointexit.err.

/tekton/debug/scripts/debug-beforestep-continue : Mark the step continue to execute by writing to /tekton/run. eg: User wants to exit before step breakpoint for before step 0. Running this script would create /tekton/run/0 and /tekton/run/0/out.beforestepexit.

/tekton/debug/scripts/debug-beforestep-fail-continue : Mark the step not continue to execute by writing to /tekton/run. eg: User wants to exit before step breakpoint for before step 0. Running this script would create /tekton/run/0 and /tekton/run/0/out.beforestepexit.err.

Vault: Additional Configuration Options

Mon, 01 Jan 0001 00:00:00 +0000

This document describes additional options to configure your Tekton Pipelines installation.

Configuring built-in remote Task and Pipeline resolution

Four remote resolvers are currently provided as part of the Tekton Pipelines installation. By default, these remote resolvers are enabled. Each resolver can be disabled by setting the appropriate feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace:

The bundles resolver, disabled by setting the enable-bundles-resolver feature flag to false.
The git resolver, disabled by setting the enable-git-resolver feature flag to false.
The hub resolver, disabled by setting the enable-hub-resolver feature flag to false.
The cluster resolver, disabled by setting the enable-cluster-resolver feature flag to false.

Configuring CloudEvents notifications

When configured so, Tekton can generate CloudEvents for TaskRun, PipelineRun and CustomRunlifecycle events. The main configuration parameter is the URL of the sink. When not set, no notification is generated.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-events
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  formats: tektonv1
  sink: https://my-sink-url

The sink used to be configured in the config-defaults config map. This option is still available, but deprecated, and will be removed.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  default-cloud-events-sink: https://my-sink-url

Additionally, CloudEvents for CustomRuns require an extra configuration to be enabled. This setting exists to avoid collisions with CloudEvents that might be sent by custom task controllers:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  send-cloudevents-for-runs: true

Configuring self-signed cert for private registry

The SSL_CERT_DIR is set to /etc/ssl/certs as the default cert directory. If you are using a self-signed cert for private registry and the cert file is not under the default cert directory, configure your registry cert in the config-registry-cert ConfigMap with the key cert.

Configuring environment variables

Environment variables can be configured in the following ways, mentioned in order of precedence from lowest to highest.

Implicit environment variables
Step/StepTemplate environment variables
Environment variables specified via a default PodTemplate.
Environment variables specified via a PodTemplate.

The environment variables specified by a PodTemplate supercedes all other ways of specifying environment variables. However, there exists a configuration i.e. default-forbidden-env, the environment variable specified in this list cannot be updated via a PodTemplate.

For example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-timeout-minutes: "50"
  default-service-account: "tekton"
  default-forbidden-env: "TEST_TEKTON"
---
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: mytask
  namespace: default
spec:
  steps:
    - name: echo-env
      image: ubuntu
      command: ["bash", "-c"]
      args: ["echo $TEST_TEKTON "]
      env:
          - name: "TEST_TEKTON"
            value: "true"
---
apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: mytaskrun
  namespace: default
spec:
  taskRef:
    name: mytask
  podTemplate:
    env:
        - name: "TEST_TEKTON"
          value: "false"

In the above example the environment variable TEST_TEKTON will not be overriden by value specified in podTemplate, because the config-default option default-forbidden-env is configured with value TEST_TEKTON.

Configuring default resources requirements

Resource requirements of containers created by the controller can be assigned default values. This allows to fully control the resources requirement of TaskRun.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-container-resource-requirements: |
    place-scripts: # updates resource requirements of a 'place-scripts' container
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"    
  
    prepare: # updates resource requirements of a 'prepare' container
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "256Mi"
        cpu: "500m"
  
    working-dir-initializer: # updates resource requirements of a 'working-dir-initializer' container
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"
  
    prefix-scripts: # updates resource requirements of containers which starts with 'scripts-'
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
  
    prefix-sidecar-scripts: # updates resource requirements of containers which starts with 'sidecar-scripts-'
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
  
    default: # updates resource requirements of init-containers and containers which has empty resource resource requirements
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "256Mi"
        cpu: "500m"

Any resource requirements set at the Task and TaskRun levels will overidde the default one specified in the config-defaults configmap.

Customizing basic execution parameters

You can specify your own values that replace the default service account (ServiceAccount), timeout (Timeout), resolver (Resolver), and Pod template (PodTemplate) values used by Tekton Pipelines in TaskRun and PipelineRun definitions. To do so, modify the ConfigMap config-defaults with your desired values.

The example below customizes the following:

the default service account from default to tekton.
the default timeout from 60 minutes to 20 minutes.
the default app.kubernetes.io/managed-by label is applied to all Pods created to execute TaskRuns.
the default Pod template to include a node selector to select the node where the Pod will be scheduled by default. A list of supported fields is available here. For more information, see PodTemplate in TaskRuns or PodTemplate in PipelineRuns.
the default Workspace configuration can be set for any Workspaces that a Task declares but that a TaskRun does not explicitly provide.
the default maximum combinations of Parameters in a Matrix that can be used to fan out a PipelineTask. For more information, see Matrix.
the default resolver type to git.
the default polling interval for the sidecar log results container via default-sidecar-log-polling-interval.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
data:
  default-service-account: "tekton"
  default-timeout-minutes: "20"
  default-pod-template: |
    nodeSelector:
      kops.k8s.io/instancegroup: build-instance-group    
  default-managed-by-label-value: "my-tekton-installation"
  default-task-run-workspace-binding: |
        emptyDir: {}
  default-max-matrix-combinations-count: "1024"
  default-resolver-type: "git"
  default-sidecar-log-polling-interval: "100ms"

`default-sidecar-log-polling-interval`

The default-sidecar-log-polling-interval key in the config-defaults ConfigMap specifies how frequently the Tekton sidecar log results container polls for step completion files written by steps in a TaskRun. Lower values (e.g., 10ms) make the sidecar more responsive but may increase CPU usage; higher values (e.g., 1s) reduce resource usage but may delay result collection. This value is used by the sidecar-tekton-log-results container and can be tuned for performance or test scenarios.

Example values:

100ms (default)
500ms
1s
10ms (for fast polling in tests)

Note: The default-sidecar-log-polling-interval setting is only applicable when results are created using the sidecar approach.

Note: The _example key in the provided config-defaults.yaml file lists the keys you can customize along with their default values.

Customizing the Pipelines Controller behavior

To customize the behavior of the Pipelines Controller, modify the ConfigMap feature-flags via kubectl edit configmap feature-flags -n tekton-pipelines.

Note: Changing feature flags may result in undefined behavior for TaskRuns and PipelineRuns that are running while the change occurs.

The flags in this ConfigMap are as follows:

coschedule: set this flag determines how PipelineRun Pods are scheduled with Affinity Assistant. Acceptable values are “workspaces” (default), “pipelineruns”, “isolate-pipelinerun”, or “disabled”. Setting it to “workspaces” will schedule all the taskruns sharing the same PVC-based workspace in a pipelinerun to the same node. Setting it to “pipelineruns” will schedule all the taskruns in a pipelinerun to the same node. Setting it to “isolate-pipelinerun” will schedule all the taskruns in a pipelinerun to the same node, and only allows one pipelinerun to run on a node at a time. Setting it to “disabled” will not apply any coschedule policy.
await-sidecar-readiness: set this flag to "false" to allow the Tekton controller to start a TasksRun’s first step immediately without waiting for sidecar containers to be running first. Using this option should decrease the time it takes for a TaskRun to start running, and will allow TaskRun pods to be scheduled in environments that don’t support Downward API volumes (e.g. some virtual kubelet implementations). However, this may lead to unexpected behaviour with Tasks that use sidecars, or in clusters that use injected sidecars (e.g. Istio). Setting this flag to "false" will mean the running-in-environment-with-injected-sidecars flag has no effect.
running-in-environment-with-injected-sidecars: set this flag to "false" to allow the Tekton controller to start a TasksRun’s first step immediately if it has no Sidecars specified. Using this option should decrease the time it takes for a TaskRun to start running. However, for clusters that use injected sidecars (e.g. Istio) this can lead to unexpected behavior.
require-git-ssh-secret-known-hosts: set this flag to "true" to require that Git SSH Secrets include a known_hosts field. This ensures that a git remote server’s key is validated before data is accepted from it when authenticating over SSH. Secrets that don’t include a known_hosts will result in the TaskRun failing validation and not running.
enable-tekton-oci-bundles: set this flag to "true" to enable the tekton OCI bundle usage (see the tekton bundle contract). Enabling this option allows the use of bundle field in taskRef and pipelineRef for Pipeline, PipelineRun and TaskRun. By default, this option is disabled ("false"), which means it is disallowed to use the bundle field.
disable-creds-init - set this flag to "true" to disable Tekton’s built-in credential initialization and use Workspaces to mount credentials from Secrets instead. The default is false. For more information, see the associated issue.
enable-api-fields: When using v1beta1 APIs, setting this field to “stable” or “beta” enables beta features. When using v1 APIs, setting this field to “stable” allows only stable features, and setting it to “beta” allows only beta features. Set this field to “alpha” to allow alpha features to be used.
enable-kubernetes-sidecar: Set this flag to "true" to enable native kubernetes sidecar support. This will allow Tekton sidecars to run as Kubernetes sidecars. Must be using Kubernetes v1.29 or greater.

For example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
data:
  enable-api-fields: "alpha" # Allow alpha fields to be used in Tasks and Pipelines.

trusted-resources-verification-no-match-policy: Setting this flag to fail will fail the taskrun/pipelinerun if no matching policies found. Setting to warn will skip verification and log a warning if no matching policies are found, but not fail the taskrun/pipelinerun. Setting to ignore will skip verification if no matching policies found. Defaults to “ignore”.
results-from: set this flag to “termination-message” to use the container’s termination message to fetch results from. This is the default method of extracting results. Set it to “sidecar-logs” to enable use of a results sidecar logs to extract results instead of termination message.
enable-provenance-in-status: Set this flag to "true" to enable populating the provenance field in TaskRun and PipelineRun status. The provenance field contains metadata about resources used in the TaskRun/PipelineRun such as the source from where a remote Task/Pipeline definition was fetched. By default, this is set to true. To disable populating this field, set this flag to "false".
set-security-context: Set this flag to true to set a security context for containers injected by Tekton that will allow TaskRun pods to run in namespaces with restricted pod security admission. By default, this is set to false.
set-security-context-read-only-root-filesystem: Set this flag to true to enable readOnlyRootFilesystem in the security context for containers injected by Tekton. This makes the root filesystem of the container read-only, enhancing security. Note that this requires set-security-context to be enabled. By default, this flag is set to false. Note: This feature does not work in windows as it is not supported there, Comparison with linux.

Alpha Features

Alpha features in the following table are still in development and their syntax is subject to change.

To enable the features without an individual flag: set the enable-api-fields feature flag to "alpha" in the feature-flags ConfigMap alongside your Tekton Pipelines deployment via kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"enable-api-fields":"alpha"}}'.
To enable the features with an individual flag: set the individual flag accordingly in the feature-flag ConfigMap alongside your Tekton Pipelines deployment. Example: kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"<FLAG-NAME>":"<FLAG-VALUE>"}}'.

Features currently in “alpha” are:

Feature	Proposal	Release	Individual Flag
Bundles	TEP-0005	v0.18.0	`enable-tekton-oci-bundles`
Hermetic Execution Mode	TEP-0025	v0.25.0
Windows Scripts	TEP-0057	v0.28.0
Debug	TEP-0042	v0.26.0
StdoutConfig and StderrConfig	TEP-0011	v0.38.0
Trusted Resources	TEP-0091	v0.49.0	`trusted-resources-verification-no-match-policy`
Configure Default Resolver	TEP-0133	v0.46.0
Coschedule	TEP-0135	v0.51.0	`coschedule`
keep pod on cancel	N/A	v0.52.0	`keep-pod-on-cancel`
CEL in WhenExpression	TEP-0145	v0.53.0	`enable-cel-in-whenexpression`
Param Enum	TEP-0144	v0.54.0	`enable-param-enum`

Beta Features

Beta features are fields of stable CRDs that follow our “beta” compatibility policy. To enable these features, set the enable-api-fields feature flag to "beta" in the feature-flags ConfigMap alongside your Tekton Pipelines deployment via kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"enable-api-fields":"beta"}}'.

Features currently in “beta” are:

Feature	Proposal	Alpha Release	Beta Release	Individual Flag
Remote Tasks and Remote Pipelines	TEP-0060		v0.41.0
`Provenance` field in Status	issue#5550	v0.41.0	v0.48.0	`enable-provenance-in-status`
Isolated `Step` & `Sidecar` `Workspaces`	TEP-0029	v0.24.0	v0.50.0
Matrix	TEP-0090	v0.38.0	v0.53.0
Task-level Resource Requirements	TEP-0104	v0.39.0	v0.53.0
Larger Results via Sidecar Logs	TEP-0127	v0.43.0	v0.61.0	`results-from`
Step and Sidecar Overrides	TEP-0094	v0.34.0		v0.61.0
Ignore Task Failure	TEP-0050	v0.55.0	v0.62.0	N/A

Enabling larger results using sidecar logs

Note: The maximum size of a Task’s results is limited by the container termination message feature of Kubernetes, as results are passed back to the controller via this mechanism. At present, the limit is per task is “4096 bytes”. All results produced by the task share this upper limit.

To exceed this limit of 4096 bytes, you can enable larger results using sidecar logs. By enabling this feature, you will have a configurable limit (with a default of 4096 bytes) per result with no restriction on the number of results. The results are still stored in the taskRun CRD, so they should not exceed the 1.5MB CRD size limit.

Note: to enable this feature, you need to grant get access to all pods/log to the tekton-pipelines-controller. This means that the tekton pipeline controller has the ability to access the pod logs.

Create a cluster role and rolebinding by applying the following spec to provide log access to tekton-pipelines-controller.

kubectl apply -f optional_config/enable-log-access-to-controller/

Set the results-from feature flag to use sidecar logs by setting results-from: sidecar-logs in the configMap.

kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"results-from":"sidecar-logs"}}'

If you want the size per result to be something other than 4096 bytes, you can set the max-result-size feature flag in bytes by setting max-result-size: 8192(whatever you need here). Note: The value you can set here cannot exceed the size of the CRD limit of 1.5 MB.

kubectl patch cm feature-flags -n tekton-pipelines -p '{"data":{"max-result-size":"<VALUE-IN-BYTES>"}}'

Configuring High Availability

If you want to run Tekton Pipelines in a way so that webhooks are resiliant against failures and support high concurrency scenarios, you need to run a Metrics Server in your Kubernetes cluster. This is required by the Horizontal Pod Autoscalers to compute replica count.

See HA Support for Tekton Pipeline Controllers for instructions on configuring High Availability in the Tekton Pipelines Controller.

The default configuration is defined in webhook-hpa.yaml which can be customized to better fit specific usecases.

Configuring tekton pipeline controller performance

Out-of-the-box, Tekton Pipelines Controller is configured for relatively small-scale deployments but there have several options for configuring Pipelines’ performance are available. See the Performance Configuration document which describes how to change the default ThreadsPerController, QPS and Burst settings to meet your requirements.

Running TaskRuns and PipelineRuns with restricted pod security standards

To allow TaskRuns and PipelineRuns to run in namespaces with restricted pod security standards, set the “set-security-context” feature flag to “true” in the feature-flags configMap. This configuration option applies a SecurityContext to any containers injected into TaskRuns by the Pipelines controller. If the Affinity Assistants feature is enabled, the SecurityContext is also applied to those containers. This SecurityContext may not be supported in all Kubernetes implementations (for example, OpenShift).

Note: running TaskRuns and PipelineRuns in the “tekton-pipelines” namespace is discouraged.

Platform Support

The Tekton project provides support for running on x86 Linux Kubernetes nodes.

The project produces images capable of running on other architectures and operating systems, but may not be able to help debug issues specific to those platforms as readily as those that affect Linux on x86.

The controller and webhook components are currently built for:

linux/amd64
linux/arm64
linux/ppc64le (PowerPC)
linux/s390x (IBM Z)

The entrypoint component is also built for Windows, which enables TaskRun workloads to execute on Windows nodes. See Windows documentation for more information.

Creating a custom release of Tekton Pipelines

You can create a custom release of Tekton Pipelines by following and customizing the steps in Creating an official release. For example, you might want to customize the container images built and used by Tekton Pipelines.

Verify Tekton Pipelines Release

We will refine this process over time to be more streamlined. For now, please follow the steps listed in this section to verify Tekton pipeline release.

Tekton Pipeline’s images are being signed by Tekton Chains since 0.27.1. You can verify the images with cosign using the Tekton’s public key.

Verify signatures using `cosign`

With Go 1.16+, you can install cosign by running:

go install github.com/sigstore/cosign/cmd/cosign@latest

You can verify Tekton Pipelines official images using the Tekton public key:

cosign verify -key https://raw.githubusercontent.com/tektoncd/chains/main/tekton.pub gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller:v0.28.1

which results in:

Verification for gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller:v0.28.1 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key
  - Any certificates were verified against the Fulcio roots.
{
  "Critical": {
    "Identity": {
      "docker-reference": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller"
    },
    "Image": {
      "Docker-manifest-digest": "sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8"
    },
    "Type": "Tekton container signature"
  },
  "Optional": {}
}

The verification shows a list of checks performed and returns the digest in Critical.Image.Docker-manifest-digest which can be used to retrieve the provenance from the transparency logs for that image using rekor-cli.

Verify the transparency logs using `rekor-cli`

Install the rekor-cli by running:

go install -v github.com/sigstore/rekor/cmd/rekor-cli@latest

Now, use the digest collected from the previous section in Critical.Image.Docker-manifest-digest, for example, sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8.

Search the transparency log with the digest just collected:

rekor-cli search --sha sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8

which results in:

Found matching entries (listed by UUID):
68a53d0e75463d805dc9437dda5815171502475dd704459a5ce3078edba96226

Tekton Chains generates provenance based on the custom format in which the subject holds the list of artifacts which were built as part of the release. For the Pipeline release, subject includes a list of images including pipeline controller, pipeline webhook, etc. Use the UUID to get the provenance:

rekor-cli get --uuid 68a53d0e75463d805dc9437dda5815171502475dd704459a5ce3078edba96226 --format json | jq -r .Attestation | base64 --decode | jq

which results in:

{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://tekton.dev/chains/provenance",
  "subject": [
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller",
      "digest": {
        "sha256": "0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/entrypoint",
      "digest": {
        "sha256": "2fa7f7c3408f52ff21b2d8c4271374dac4f5b113b1c4dbc7d5189131e71ce721"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init",
      "digest": {
        "sha256": "83d5ec6addece4aac79898c9631ee669f5fee5a710a2ed1f98a6d40c19fb88f7"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/imagedigestexporter",
      "digest": {
        "sha256": "e4d77b5b8902270f37812f85feb70d57d6d0e1fed2f3b46f86baf534f19cd9c0"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/nop",
      "digest": {
        "sha256": "59b5304bcfdd9834150a2701720cf66e3ebe6d6e4d361ae1612d9430089591f8"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/pullrequest-init",
      "digest": {
        "sha256": "4992491b2714a73c0a84553030e6056e6495b3d9d5cc6b20cf7bc8c51be779bb"
      }
    },
    {
      "name": "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/webhook",
      "digest": {
        "sha256": "bf0ef565b301a1981cb2e0d11eb6961c694f6d2401928dccebe7d1e9d8c914de"
      }
    }
  ],
  ...

Now, verify the digest in the release.yaml by matching it with the provenance, for example, the digest for the release v0.28.1:

curl -s https://storage.googleapis.com/tekton-releases/pipeline/previous/v0.28.1/release.yaml | grep github.com/tektoncd/pipeline/cmd/controller:v0.28.1 | awk -F"github.com/tektoncd/pipeline/cmd/controller:v0.28.1@" '{print $2}'

which results in:

sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8

Now, you can verify the deployment specifications in the release.yaml to match each of these images and their digest. The tekton-pipelines-controller deployment specification has a container named tekton-pipeline-controller and a list of image references with their digest as part of the args:

      containers:
        - name: tekton-pipelines-controller
          image: gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/controller:v0.28.1@sha256:0c320bc09e91e22ce7f01e47c9f3cb3449749a5f72d5eaecb96e710d999c28e8
          args: [
            # These images are built on-demand by `ko resolve` and are replaced
            # by image references by digest.
              "-git-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:v0.28.1@sha256:83d5ec6addece4aac79898c9631ee669f5fee5a710a2ed1f98a6d40c19fb88f7",
              "-entrypoint-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/entrypoint:v0.28.1@sha256:2fa7f7c3408f52ff21b2d8c4271374dac4f5b113b1c4dbc7d5189131e71ce721",
              "-nop-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/nop:v0.28.1@sha256:59b5304bcfdd9834150a2701720cf66e3ebe6d6e4d361ae1612d9430089591f8",
              "-imagedigest-exporter-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/imagedigestexporter:v0.28.1@sha256:e4d77b5b8902270f37812f85feb70d57d6d0e1fed2f3b46f86baf534f19cd9c0",
              "-pr-image",
              "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/pullrequest-init:v0.28.1@sha256:4992491b2714a73c0a84553030e6056e6495b3d9d5cc6b20cf7bc8c51be779bb",

Similarly, you can verify the rest of the images which were published as part of the Tekton Pipelines release:

gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/entrypoint
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/nop
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/imagedigestexporter
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/pullrequest-init
gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/webhook

Verify Tekton Resources

Trusted Resources is a feature to verify Tekton Tasks and Pipelines. The current version of feature supports v1beta1 Task and Pipeline. For more details please take a look at Trusted Resources.

Pipelineruns with Affinity Assistant

The cluster operators can review the guidelines to cordon a node in the cluster with the tekton controller and the affinity assistant is enabled.

TaskRuns with `imagePullBackOff` Timeout

Tekton pipelines has adopted a fail fast strategy with a taskRun failing with TaskRunImagePullFailed in case of an imagePullBackOff. This can be limited in some cases, and it generally depends on the infrastructure. To allow the cluster operators to decide whether to wait in case of an imagePullBackOff, a setting is available to configure the wait time such that the controller will wait for the specified duration before declaring a failure. For example, with the following config-defaults, the controller does not mark the taskRun as failure for 5 minutes since the pod is scheduled in case the image pull fails with imagePullBackOff. The default-imagepullbackoff-timeout is of type time.Duration and can be set to a duration such as “1m”, “5m”, “10s”, “1h”, etc. See issue https://github.com/tektoncd/pipeline/issues/5987 for more details.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-imagepullbackoff-timeout: "5m"

Disabling Inline Spec in Pipeline, TaskRun and PipelineRun

Tekton users may embed the specification of a Task (via taskSpec) or a Pipeline (via pipelineSpec) as an alternative to referring to an external resource via taskRef and pipelineRef respectively. This behaviour can be selectively disabled for three Tekton resources: TaskRun, PipelineRun and Pipeline.

In certain clusters and scenarios, an admin might want to disable the customisation of Tasks and Pipelines and only allow users to run pre-defined resources. To achieve that the admin should disable embedded specification via the disable-inline-spec flag, and remote resolvers too.

To disable inline specification, set the disable-inline-spec flag to "pipeline,pipelinerun,taskrun" in the feature-flags configmap.

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  disable-inline-spec: "pipeline,pipelinerun,taskrun"

Inline specifications can be disabled for specific resources only. To achieve that, set the disable-inline-spec flag to a comma-separated list of the desired resources. Valid values are pipeline, pipelinerun and taskrun.

The default value of disable-inline-spec is “”, which means inline specification is enabled in all cases.

Exponential Backoff for TaskRun and CustomRun Creation

By default, when Tekton Pipelines attempts to create a TaskRun or CustomRun resource and encounters an error, the controller will requeue the PipelineRun for another reconciliation attempt after a short delay. However, this may not be sufficient in a heavily loaded or busy cluster, where transient errors such as webhook timeouts or network issues are more likely to occur.

To improve robustness in environments where webhook timeouts or network errors are possible, you can enable an exponential backoff retry strategy for TaskRun and CustomRun creation by setting the enable-wait-exponential-backoff feature flag to "true" in the feature-flags ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-wait-exponential-backoff: "true"

When this flag is enabled, the controller will retry TaskRun and CustomRun creation using an exponential backoff strategy if it encounters admission webhook timeouts (e.g., "timeout").

This helps mitigate failures due to temporary unavailability of webhooks or network disruptions.

Backoff Configuration

You can further customize the backoff parameters (such as initial duration, factor, steps, and cap) using the wait-exponential-backoff ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: wait-exponential-backoff
  namespace: tekton-pipelines
data:
  duration: "1s"
  factor: "2.0"
  jitter: "0.0"
  steps: "10"
  cap: "30s"

duration: Initial wait time before the first retry.
factor: Multiplier for each subsequent retry interval.
steps: Maximum number of retry attempts.
cap: Maximum wait time between retries.

Default Behavior

If enable-wait-exponential-backoff is not set or is set to "false", the controller will rely on its standard reconcilation loop to retry TaskRun or CustomRun creation after a short delay when failures occur due to webhook or network errors.

Note: This feature is especially useful in clusters where webhook services (such as Kyverno, OPA, or custom admission controllers) may be temporarily unavailable or slow to respond.

Limiting Step reference concurrency resolution

You can control the maximum number of concurrent goroutines that the Tekton controller uses to resolve steps referencing a StepAction via the step.ref field.

When a TaskRun is processed, any step that uses a ref to a remote StepAction (e.g., one stored in a git repository or an OCI registry) triggers a fetch request. If a Task contains many such steps, the controller will attempt to resolve them all in parallel. This can lead to a “thundering herd” problem, potentially overwhelming remote servers, hitting API rate limits, saturating network resources, or placing excessive load on the Kubernetes API server and the Tekton controller itself.

To mitigate this, Tekton Pipelines includes a configurable concurrency limit. By default, a sensible limit is already in place to ensure stability.

Default Behavior

If the default-step-ref-concurrency-limit key is not set in the config-defaults ConfigMap, Tekton Pipelines defaults to a concurrency limit of 5. This provides a safe, built-in throttle without requiring any initial configuration.

Overriding the Default

You can override this default to better suit your environment’s capacity (e.g., a high-capacity, self-hosted git server might allow for a higher limit). To change the limit, set the default-step-ref-concurrency-limit key in your config-defaults ConfigMap.

Example: To increase the concurrency limit to 20:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-step-ref-concurrency-limit: "20"

Next steps

To get started with Tekton check the Introductory tutorials, the how-to guides, and the examples folder.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Artifacts

Overview

🌱 Artifacts is an alpha feature. The enable-artifacts feature flag must be set to "true" to read or write artifacts in a step.

Artifacts provide a way to track the origin of data produced and consumed within your Tekton Tasks.

Artifact Provenance Data

Artifacts fall into two categories:

Inputs: Artifacts downloaded and used by the Step/Task.
Outputs: Artifacts created and uploaded by the Step/Task.

Example Structure:

{
  "inputs":[
    {
      "name": "<input-category-name>", 
      "values": [
        {
          "uri": "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c", 
          "digest": { "sha256": "b35caccc..." }
        }
      ]
    }
  ],
  "outputs": [
    {
      "name": "<output-category-name>",
      "values": [
        {
          "uri": "pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
          "digest": {
            "sha256": "df85b9e3...",
            "sha1": "95588b8f..."
          }
        }
      ]
    }
  ]
}

The content is written by the Step to a file $(step.artifacts.path):

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: step-artifacts-
spec:
  taskSpec:
    description: |
            A simple task that populates artifacts to TaskRun stepState
    steps:
      - name: artifacts-producer
        image: bash:latest
        script: |
          cat > $(step.artifacts.path) << EOF
          {
            "inputs":[
              {
                "name":"source",
                "values":[
                  {
                    "uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
                    "digest":{
                      "sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
                    }
                  }
                ]
              }
            ],
            "outputs":[
              {
                "name":"image",
                "values":[
                  {
                    "uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
                    "digest":{
                      "sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
                      "sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
                    }
                  }
                ]
              }
            ]
          }
          EOF

It is recommended to use purl format for artifacts uri as shown in the example.

Output Artifacts in SLSA Provenance

Artifacts are classified as either:

Build Outputs - packages, images, etc. that are being published by the build.
Build Byproducts - logs, caches, etc. that are incidental artifacts that are produced by the build.

By default, Tekton Chains will consider all output artifacts as byProducts when generating in the SLSA provenance. In order to treat an artifact as a subject of the build, you must set a boolean field "buildOutput": true for the output artifact.

e.g.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: step-artifacts-
spec:
  taskSpec:
    description: |
            A simple task that populates artifacts to TaskRun stepState
    steps:
      - name: artifacts-producer
        image: bash:latest
        script: |
          cat > $(artifacts.path) << EOF
          {
            "outputs":[
              {
                "name":"image",
                "buildOutput": true,
                "values":[
                  {
                    "uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
                    "digest":{
                      "sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
                      "sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
                    }
                  }
                ]
              }
            ]
          }
          EOF

This informs Tekton Chains your desire to handle the artifact.

[!TIP] When authoring a StepAction or a Task, you can parametrize this field to allow users to indicate their desire depending on what they are uploading - this can be useful for actions that may produce either a build output or a byproduct depending on the context!

Passing Artifacts between Steps

You can pass artifacts from one step to the next using:

Specific Artifact: $(steps.<step-name>.inputs.<artifact-category-name>) or $(steps.<step-name>.outputs.<artifact-category-name>)

The example below shows how to access the previous’ step artifacts from another step in the same task

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: step-artifacts-
spec:
  taskSpec:
    description: |
            A simple task that populates artifacts to TaskRun stepState
    steps:
      - name: artifacts-producer
        image: bash:latest
        script: |
          # the script is for creating the output artifacts
          cat > $(step.artifacts.path) << EOF
          {
            "inputs":[
              {
                "name":"source",
                "values":[
                  {
                    "uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
                    "digest":{
                      "sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
                    }
                  }
                ]
              }
            ],
            "outputs":[
              {
                "name":"image",
                "values":[
                  {
                    "uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
                    "digest":{
                      "sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
                      "sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
                    }
                  }
                ]
              }
            ]
          }
          EOF          
      - name: artifacts-consumer
        image: bash:latest
        script: |
                    echo $(steps.artifacts-producer.outputs.image)

The resolved value of $(steps.<step-name>.outputs.<artifact-category-name>) is the values of an artifact. For this example, $(steps.artifacts-producer.outputs.image) is resolved to

[
                  {
                    "uri":"pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library",
                    "digest":{
                      "sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
                      "sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
                    }
                  }
]

Upon resolution and execution of the TaskRun, the Status will look something like:

{
  "artifacts": {
    "inputs": [
      {
        "name": "source",
        "values": [
          {
            "digest": {
              "sha256": "b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
            },
            "uri": "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c"
          }
        ]
      }
    ],
    "outputs": [
      {
        "name": "image",
        "values": [
          {
            "digest": {
              "sha1": "95588b8f34c31eb7d62c92aaa4e6506639b06ef2",
              "sha256": "df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48"
            },
            "uri": "pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library"
          }
        ]
      }
    ]
  },
  "steps": [
    {
      "container": "step-artifacts-producer",
      "imageID": "docker.io/library/bash@sha256:5353512b79d2963e92a2b97d9cb52df72d32f94661aa825fcfa0aede73304743",
      "inputs": [
        {
          "name": "source",
          "values": [
            {
              "digest": {
                "sha256": "b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
              },
              "uri": "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c"
            }
          ]
        }
      ],
      "name": "artifacts-producer",
      "outputs": [
        {
          "name": "image",
          "values": [
            {
              "digest": {
                "sha1": "95588b8f34c31eb7d62c92aaa4e6506639b06ef2",
                "sha256": "df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48"
              },
              "uri": "pkg:oci/nginx:stable-alpine3.17-slim?repository_url=docker.io/library"
            }
          ]
        }
      ],
      "terminated": {
        "containerID": "containerd://010f02d103d1db48531327a1fe09797c87c1d50b6a216892319b3af93e0f56e7",
        "exitCode": 0,
        "finishedAt": "2024-03-18T17:05:06Z",
        "message": "...",
        "reason": "Completed",
        "startedAt": "2024-03-18T17:05:06Z"
      },
      "terminationReason": "Completed"
    },
    {
      "container": "step-artifacts-consumer",
      "imageID": "docker.io/library/bash@sha256:5353512b79d2963e92a2b97d9cb52df72d32f94661aa825fcfa0aede73304743",
      "name": "artifacts-consumer",
      "terminated": {
        "containerID": "containerd://42428aa7e5a507eba924239f213d185dd4bc0882b6f217a79e6792f7fec3586e",
        "exitCode": 0,
        "finishedAt": "2024-03-18T17:05:06Z",
        "reason": "Completed",
        "startedAt": "2024-03-18T17:05:06Z"
      },
      "terminationReason": "Completed"
    }
  ]
}

Passing Artifacts between Tasks

You can pass artifacts from one task to the another using:

Specific Artifact: $(tasks.<task-name>.inputs.<artifact-category-name>) or $(tasks.<task-name>.outputs.<artifact-category-name>)

The example below shows how to access the previous’ task artifacts from another task in a pipeline

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: pipelinerun-consume-tasks-artifacts
spec:
  pipelineSpec:
    tasks:
      - name: produce-artifacts-task
        taskSpec:
          description: |
                        A simple task that produces artifacts
          steps:
            - name: produce-artifacts
              image: bash:latest
              script: |
                #!/usr/bin/env bash
                cat > $(artifacts.path) << EOF
                {
                  "inputs":[
                    {
                      "name":"input-artifacts",
                      "values":[
                        {
                          "uri":"pkg:example.github.com/inputs",
                          "digest":{
                            "sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
                          }
                        }
                      ]
                    }
                  ],
                  "outputs":[
                    {
                      "name":"image",
                      "values":[
                        {
                          "uri":"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c",
                          "digest":{
                            "sha256":"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48",
                            "sha1":"95588b8f34c31eb7d62c92aaa4e6506639b06ef2"
                          }
                        }
                      ]
                    }
                  ]
                }
                EOF                
      - name: consume-artifacts
        runAfter:
          - produce-artifacts-task
        taskSpec:
          steps:
            - name: artifacts-consumer-python
              image: python:latest
              script: |
                #!/usr/bin/env python3
                import json
                data = json.loads('$(tasks.produce-artifacts-task.outputs.image)')
                if data[0]['uri'] != "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c":
                  exit(1)

Similar to Step Artifacts. The resolved value of $(tasks.<task-name>.outputs.<artifact-category-name>) is the values of an artifact. For this example, $(tasks.produce-artifacts-task.outputs.image) is resolved to

[
  {
    "uri":"pkg:example.github.com/inputs",
    "digest":{
      "sha256":"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
    }
 }
]

Upon resolution and execution of the TaskRun, the Status will look something like:

{
 "artifacts": {
      "inputs": [
        {
          "name": "input-artifacts",
          "values": [
            {
              "digest": {
                "sha256": "b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0"
              },
              "uri": "pkg:example.github.com/inputs"
            }
          ]
        }
      ],
      "outputs": [
        {
          "name": "image",
          "values": [
            {
              "digest": {
                "sha1": "95588b8f34c31eb7d62c92aaa4e6506639b06ef2",
                "sha256": "df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48"
              },
              "uri": "pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c"
            }
          ]
        }
      ]
    },
    "completionTime": "2024-05-28T14:10:58Z",
    "conditions": [
      {
        "lastTransitionTime": "2024-05-28T14:10:58Z",
        "message": "All Steps have completed executing",
        "reason": "Succeeded",
        "status": "True",
        "type": "Succeeded"
      }
    ],
    "podName": "pipelinerun-consume-tasks-a41ee44e4f964e95adfd3aea417d52f90-pod",
    "provenance": {
      "featureFlags": {
        "awaitSidecarReadiness": true,
        "coschedule": "workspaces",
        "disableCredsInit": false,
        "disableInlineSpec": "",
        "enableAPIFields": "beta",
        "enableArtifacts": true,
        "enableCELInWhenExpression": false,
        "enableConciseResolverSyntax": false,
        "enableKeepPodOnCancel": false,
        "enableParamEnum": false,
        "enableProvenanceInStatus": true,
        "enableStepActions": true,
        "enableTektonOCIBundles": false,
        "enforceNonfalsifiability": "none",
        "maxResultSize": 4096,
        "requireGitSSHSecretKnownHosts": false,
        "resultExtractionMethod": "termination-message",
        "runningInEnvWithInjectedSidecars": true,
        "scopeWhenExpressionsToTask": false,
        "sendCloudEventsForRuns": false,
        "setSecurityContext": false,
        "verificationNoMatchPolicy": "ignore"
      }
    },
    "startTime": "2024-05-28T14:10:48Z",
    "steps": [
      {
        "container": "step-produce-artifacts",
        "imageID": "docker.io/library/bash@sha256:23f90212fd89e4c292d7b41386ef1a6ac2b8a02bbc6947680bfe184cbc1a2899",
        "name": "produce-artifacts",
        "terminated": {
          "containerID": "containerd://1291ce07b175a7897beee6ba62eaa1528427bacb1f76b31435eeba68828c445a",
          "exitCode": 0,
          "finishedAt": "2024-05-28T14:10:57Z",
          "message": "...",
          "reason": "Completed",
          "startedAt": "2024-05-28T14:10:57Z"
        },
        "terminationReason": "Completed"
      }
    ],
    "taskSpec": {
      "description": "A simple task that produces artifacts\n",
      "steps": [
        {
          "computeResources": {},
          "image": "bash:latest",
          "name": "produce-artifacts",
          "script": "#!/usr/bin/env bash\ncat > /tekton/artifacts/provenance.json << EOF\n{\n  \"inputs\":[\n    {\n      \"name\":\"input-artifacts\",\n      \"values\":[\n        {\n          \"uri\":\"pkg:example.github.com/inputs\",\n          \"digest\":{\n            \"sha256\":\"b35cacccfdb1e24dc497d15d553891345fd155713ffe647c281c583269eaaae0\"\n          }\n        }\n      ]\n    }\n  ],\n  \"outputs\":[\n    {\n      \"name\":\"image\",\n      \"values\":[\n        {\n          \"uri\":\"pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c\",\n          \"digest\":{\n            \"sha256\":\"df85b9e3983fe2ce20ef76ad675ecf435cc99fc9350adc54fa230bae8c32ce48\",\n            \"sha1\":\"95588b8f34c31eb7d62c92aaa4e6506639b06ef2\"\n          }\n        }\n      ]\n    }\n  ]\n}\nEOF\n"
        }
      ]
    }
}

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

StepActions

Overview

StepActions is a stable feature.

A StepAction is the reusable and scriptable unit of work that is performed by a Step.

A Step is not reusable, the work it performs is reusable and referenceable. Steps are in-lined in the Task definition and either perform work directly or perform a StepAction. A StepAction cannot be run stand-alone (unlike a TaskRun or a PipelineRun). It has to be referenced by a Step. Another way to think about this is that a Step is not composed of StepActions (unlike a Task being composed of Steps and Sidecars). Instead, a Step is an actionable component, meaning that it has the ability to refer to a StepAction. The author of the StepAction must be able to compose a Step using a StepAction and provide all the necessary context (or orchestration) to it.

Configuring a `StepAction`

A StepAction definition supports the following fields:

Required
- apiVersion - Specifies the API version. For example, tekton.dev/v1alpha1.
- kind - Identifies this resource object as a StepAction object.
- metadata - Specifies metadata that uniquely identifies the StepAction resource object. For example, a name.
- spec - Specifies the configuration information for this StepAction resource object.
- image - Specifies the image to use for the Step.
  - The container image must abide by the container contract.
Optional
- command
  - cannot be used at the same time as using script.
- args
- script
  - cannot be used at the same time as using command.
- env
- params
- results
- workingDir
- securityContext
- volumeMounts
- description

The example below demonstrates the use of most of the above-mentioned fields:

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: example-stepaction-name
spec:
  env:
    - name: HOME
      value: /home
  image: ubuntu
  command: ["ls"]
  args: ["-lh"]

Declaring Parameters

Like with Tasks, a StepAction must declare all the parameters that it uses. The same rules for Parameter name, type (including object, array and string) apply as when declaring them in Tasks. A StepAction can also provide default value to a Parameter.

Parameters are passed to the StepAction from its corresponding Step referencing it.

apiVersion: tekton.dev/v1beta1
kind: StepAction
metadata:
  name: stepaction-using-params
spec:
  params:
    - name: gitrepo
      type: object
      properties:
        url:
          type: string
        commit:
          type: string
    - name: flags
      type: array
    - name: outputPath
      type: string
      default: "/workspace"
  image: some-git-image
  args: [
    "-url=$(params.gitrepo.url)",
    "-revision=$(params.gitrepo.commit)",
    "-output=$(params.outputPath)",
    "$(params.flags[*])",
  ]

🌱 params cannot be directly used in a script in StepActions. Directly substituting params in scripts makes the workload prone to shell attacks. Therefore, we do not allow direct usage of params in scripts in StepActions. Instead, rely on passing params to env variables and reference them in scripts. We cannot do the same for inlined-steps because it breaks v1 API compatibility for existing users.

Passing Params to StepAction

A StepAction may require params. In this case, a Task needs to ensure that the StepAction has access to all the required params. When referencing a StepAction, a Step can also provide it with params, just like how a TaskRun provides params to the underlying Task.

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: step-action
spec:
  params:
    - name: param-for-step-action
      description: "this is a param that the step action needs."
  steps:
    - name: action-runner
      ref:
        name: step-action
      params:
        - name: step-action-param
          value: $(params.param-for-step-action)

Note: If a Step declares params for an inlined Step, it will also lead to a validation error. This is because an inlined Step gets its params from the TaskRun.

Parameter Substitution Precedence

When applying parameters to a StepAction, the substitutions are applied in the following order:

TaskRun parameter values in step parameters
Step-provided parameter values
Default values that reference other parameters
Simple default values
Step result references

This order ensures that:

TaskRun parameters are available for step parameter substitution
Step-provided values take precedence over defaults
Parameter references in defaults are resolved before simple defaults
Step result references are resolved last to allow referencing results from previous steps

Emitting Results

A StepAction also declares the results that it will emit.

apiVersion: tekton.dev/v1alpha1
kind: StepAction
metadata:
  name: stepaction-declaring-results
spec:
  results:
    - name: current-date-unix-timestamp
      description: The current date in unix timestamp format
    - name: current-date-human-readable
      description: The current date in human readable format
  image: bash:latest
  script: |
    #!/usr/bin/env bash
    date +%s | tee $(results.current-date-unix-timestamp.path)
    date | tee $(results.current-date-human-readable.path)

It is possible that a StepAction with Results is used multiple times in the same Task or multiple StepActions in the same Task produce Results with the same name. Resolving the Result names becomes critical otherwise there could be unexpected outcomes. The Task needs to be able to resolve these Result names clashes by mapping it to a different Result name. For this reason, we introduce the capability to store results on a Step level.

StepActions can also emit Results to $(step.results.<resultName>.path).

apiVersion: tekton.dev/v1alpha1
kind: StepAction
metadata:
  name: stepaction-declaring-results
spec:
  results:
    - name: current-date-unix-timestamp
      description: The current date in unix timestamp format
    - name: current-date-human-readable
      description: The current date in human readable format
  image: bash:latest
  script: |
    #!/usr/bin/env bash
    date +%s | tee $(step.results.current-date-unix-timestamp.path)
    date | tee $(step.results.current-date-human-readable.path)

Results from the above StepAction can be fetched by the Task or in another Step/StepAction via $(steps.<stepName>.results.<resultName>).

Fetching Emitted Results from StepActions

A Task can fetch Results produced by the StepActions (i.e. only Results emitted to $(step.results.<resultName>.path), NOT $(results.<resultName>.path)) using variable replacement syntax. We introduce a field to Task Results called Value whose value can be set to the variable $(steps.<stepName>.results.<resultName>).

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: task-fetching-results
spec:
  results:
    - name: git-url
      description: "url of git repo"
      value: $(steps.git-clone.results.url)
    - name: registry-url
      description: "url of docker registry"
      value: $(steps.kaniko.results.url)
  steps:
    - name: git-clone
      ref:
        name: clone-step-action
    - name: kaniko
      ref:
        name: kaniko-step-action

Results emitted to $(step.results.<resultName>.path) are not automatically available as TaskRun Results. The Task must explicitly fetch it from the underlying Step referencing StepActions.

For example, lets assume that in the previous example, the “kaniko” StepAction also produced a Result named “digest”. In that case, the Task should also fetch the “digest” from “kaniko” Step.

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: task-fetching-results
spec:
  results:
    - name: git-url
      description: "url of git repo"
      value: $(steps.git-clone.results.url)
    - name: registry-url
      description: "url of docker registry"
      value: $(steps.kaniko.results.url)
    - name: digest
      description: "digest of the image"
      value: $(steps.kaniko.results.digest)
  steps:
    - name: git-clone
      ref:
        name: clone-step-action
    - name: kaniko
      ref:
        name: kaniko-step-action

Passing Results between Steps

StepResults (i.e. results written to $(step.results.<result-name>.path), NOT $(results.<result-name>.path)) can be shared with following steps via replacement variable $(steps.<step-name>.results.<result-name>).

Pipeline supports two new types of results and parameters: array []string and object map[string]string.

Result Type	Parameter Type	Specification	`enable-api-fields`
string	string	`$(steps.<step-name>.results.<result-name>)`	stable
array	array	`$(steps.<step-name>.results.<result-name>[*])`	alpha or beta
array	string	`$(steps.<step-name>.results.<result-name>[i])`	alpha or beta
object	string	`$(tasks.<task-name>.results.<result-name>.key)`	alpha or beta

Note: Whole Array Results (using star notation) cannot be referred in script and env.

The example below shows how you could pass step results from a step into following steps, in this case, into a StepAction.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: step-action-run
spec:
  TaskSpec:
    steps:
      - name: inline-step
        results:
          - name: result1
            type: array
          - name: result2
            type: string
          - name: result3
            type: object
            properties:
              IMAGE_URL:
                type: string
              IMAGE_DIGEST:
                type: string
        image: alpine
        script: |
          echo -n "[\"image1\", \"image2\", \"image3\"]" | tee $(step.results.result1.path)
          echo -n "foo" | tee $(step.results.result2.path)
          echo -n "{\"IMAGE_URL\":\"ar.com\", \"IMAGE_DIGEST\":\"sha234\"}" | tee $(step.results.result3.path)          
      - name: action-runner
        ref:
          name: step-action
        params:
          - name: param1
            value: $(steps.inline-step.results.result1[*])
          - name: param2
            value: $(steps.inline-step.results.result2)
          - name: param3
            value: $(steps.inline-step.results.result3[*])

Note: Step Results can only be referenced in a Step's/StepAction's env, command and args. Referencing in any other field will throw an error.

Declaring WorkingDir

You can declare workingDir in a StepAction:

apiVersion: tekton.dev/v1alpha1
kind: StepAction
metadata:
  name: example-stepaction-name
spec:
  image:  gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:latest
  workingDir: /workspace
  script: |
    # clone the repo
    ...

The Task using the StepAction has more context about how the Steps have been orchestrated. As such, the Task should be able to update the workingDir of the StepAction so that the StepAction is executed from the correct location. The StepAction can parametrize the workingDir and work relative to it. This way, the Task does not really need control over the workingDir, it just needs to pass the path as a parameter.

apiVersion: tekton.dev/v1alpha1
kind: StepAction
metadata:
  name: example-stepaction-name
spec:
  image: ubuntu
  params:
    - name: source
      description: "The path to the source code."
  workingDir: $(params.source)

Declaring SecurityContext

You can declare securityContext in a StepAction:

apiVersion: tekton.dev/v1alpha1
kind: StepAction
metadata:
  name: example-stepaction-name
spec:
  image:  gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:latest
  securityContext:
      runAsUser: 0
  script: |
    # clone the repo
    ...

Note that the securityContext from StepAction will overwrite the securityContext from TaskRun.

Declaring VolumeMounts

You can define VolumeMounts in StepActions. The name of the VolumeMount MUST be a single reference to a string Parameter. For example, $(params.registryConfig) is valid while $(params.registryConfig)-foo and "unparametrized-name" are invalid. This is to ensure reusability of StepActions such that Task authors have control of which Volumes they bind to the VolumeMounts.

apiVersion: tekton.dev/v1alpha1
kind: StepAction
metadata:
  name: myStep
spec:
  params:
    - name: registryConfig
    - name: otherConfig
  volumeMounts:
    - name: $(params.registryConfig)
      mountPath: /registry-config
    - name: $(params.otherConfig)
      mountPath: /other-config
  image: ...
  script: ...

Declaring description

The description field is an optional field that allows you to add a user-facing name to the step that may be used to populate a UI.

apiVersion: tekton.dev/v1
kind: StepAction
metadata:
  name: myStep
spec:
  description: my step
  params: ...
  volumeMounts: ...
  image: ...
  script: ...

Referencing a StepAction

StepActions can be referenced from the Step using the ref field, as follows:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: step-action-run
spec:
  taskSpec:
    steps:
      - name: action-runner
        ref:
          name: step-action

Upon resolution and execution of the TaskRun, the Status will look something like:

status:
  completionTime: "2023-10-24T20:28:42Z"
  conditions:
  - lastTransitionTime: "2023-10-24T20:28:42Z"
    message: All Steps have completed executing
    reason: Succeeded
    status: "True"
    type: Succeeded
  podName: step-action-run-pod
  provenance:
    featureFlags:
      ...
  startTime: "2023-10-24T20:28:32Z"
  steps:
  - container: step-action-runner
    imageID: docker.io/library/alpine@sha256:eece025e432126ce23f223450a0326fbebde39cdf496a85d8c016293fc851978
    name: action-runner
    terminationReason: Completed
    terminated:
      containerID: containerd://46a836588967202c05b594696077b147a0eb0621976534765478925bb7ce57f6
      exitCode: 0
      finishedAt: "2023-10-24T20:28:42Z"
      reason: Completed
      startedAt: "2023-10-24T20:28:42Z"
  taskSpec:
    steps:
    - computeResources: {}
      image: alpine
      name: action-runner

If a Step is referencing a StepAction, it cannot contain the fields supported by StepActions. This includes:

image
command
args
script
env
volumeMounts

Using any of the above fields and referencing a StepAction in the same Step is not allowed and will cause a validation error.

# This is not allowed and will result in a validation error
# because the image is expected to be provided by the StepAction
# and not inlined.
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: step-action-run
spec:
  taskSpec:
    steps:
      - name: action-runner
        ref:
          name: step-action
        image: ubuntu

Executing the above TaskRun will result in an error that looks like:

Error from server (BadRequest): error when creating "STDIN": admission webhook "validation.webhook.pipeline.tekton.dev" denied the request: validation failed: image cannot be used with Ref: spec.taskSpec.steps[0].image

When a Step is referencing a StepAction, it can contain the following fields:

computeResources
workspaces (Isolated workspaces)
volumeDevices
imagePullPolicy
onError
stdoutConfig
stderrConfig
securityContext
envFrom
timeout
ref
params

Using any of the above fields and referencing a StepAction is allowed and will not cause an error. For example, the TaskRun below will execute without any errors:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: step-action-run
spec:
  taskSpec:
    steps:
      - name: action-runner
        ref:
          name: step-action
        params:
          - name: step-action-param
            value: hello
        computeResources:
          requests:
            memory: 1Gi
            cpu: 500m
        timeout: 1h
        onError: continue

Specifying Remote StepActions

A ref field may specify a StepAction in a remote location such as git. Support for specific types of remote will depend on the Resolvers your cluster’s operator has installed. For more information including a tutorial, please check resolution docs. The below example demonstrates referencing a StepAction in git:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: step-action-run-
spec:
  taskSpec:
    steps:
      - name: action-runner
        ref:
          resolver: git
          params:
            - name: url
              value: https://github.com/repo/repo.git
            - name: revision
              value: main
            - name: pathInRepo
              value: remote_step.yaml

The default resolver type can be configured by the default-resolver-type field in the config-defaults ConfigMap (alpha feature). See additional-configs.md for details.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tasks

Overview

A Task is a collection of Steps that you define and arrange in a specific order of execution as part of your continuous integration flow. A Task executes as a Pod on your Kubernetes cluster. A Task is available within a specific namespace, while a cluster resolver can be used to access Tasks across the entire cluster.

Note: The cluster resolver is the recommended way to access Tasks across the cluster. ClusterTasks are deprecated.

A Task declaration includes the following elements:

Configuring a Task

A Task definition supports the following fields:

Required:
- apiVersion - Specifies the API version. For example, tekton.dev/v1beta1.
- kind - Identifies this resource object as a Task object.
- metadata - Specifies metadata that uniquely identifies the Task resource object. For example, a name.
- spec - Specifies the configuration information for this Task resource object.
- steps - Specifies one or more container images to run in the Task.
Optional:
- description - An informative description of the Task.
- params - Specifies execution parameters for the Task.
- workspaces - Specifies paths to volumes required by the Task.
- results - Specifies the names under which Tasks write execution results.
- volumes - Specifies one or more volumes that will be available to the Steps in the Task.
- stepTemplate - Specifies a Container step definition to use as the basis for all Steps in the Task.
- sidecars - Specifies Sidecar containers to run alongside the Steps in the Task.

The non-functional example below demonstrates the use of most of the above-mentioned fields:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: example-task-name
spec:
  params:
    - name: pathToDockerFile
      type: string
      description: The path to the dockerfile to build
      default: /workspace/workspace/Dockerfile
    - name: builtImageUrl
      type: string
      description: location to push the built image to
  steps:
    - name: ubuntu-example
      image: ubuntu
      args: ["ubuntu-build-example", "SECRETS-example.md"]
    - image: gcr.io/example-builders/build-example
      command: ["echo"]
      args: ["$(params.pathToDockerFile)"]
    - name: dockerfile-pushexample
      image: gcr.io/example-builders/push-example
      args: ["push", "$(params.builtImageUrl)"]
      volumeMounts:
        - name: docker-socket-example
          mountPath: /var/run/docker.sock
  volumes:
    - name: example-volume
      emptyDir: {}

Defining `Steps`

A Step is a reference to a container image that executes a specific tool on a specific input and produces a specific output. To add Steps to a Task you define a steps field (required) containing a list of desired Steps. The order in which the Steps appear in this list is the order in which they will execute.

The following requirements apply to each container image referenced in a steps field:

The container image must abide by the container contract.
Each container image runs to completion or until the first failure occurs.
The CPU, memory, and ephemeral storage resource requests set on Steps will be adjusted to comply with any LimitRanges present in the Namespace. In addition, Kubernetes determines a pod’s effective resource requests and limits by summing the requests and limits for all its containers, even though Tekton runs Steps sequentially. For more detail, see Compute Resources in Tekton.

Note: If the image referenced in the step field is from a private registry, TaskRuns or PipelineRuns that consume the task must provide the imagePullSecrets in a podTemplate.

Below is an example of setting the resource requests and limits for a step:

v1
v1beta1

spec:
  steps:
    - name: step-with-limts
      computeResources:
        requests:
          memory: 1Gi
          cpu: 500m
        limits:
          memory: 2Gi
          cpu: 800m

spec:
  steps:
    - name: step-with-limts
      resources:
        requests:
          memory: 1Gi
          cpu: 500m
        limits:
          memory: 2Gi
          cpu: 800m

Reserved directories

There are several directories that all Tasks run by Tekton will treat as special

/workspace - This directory is where resources and workspaces are mounted. Paths to these are available to Task authors via variable substitution
/tekton - This directory is used for Tekton specific functionality:
- /tekton/results is where results are written to. The path is available to Task authors via $(results.name.path)
- There are other subfolders which are implementation details of Tekton and users should not rely on their specific behavior as it may change in the future

Running scripts within `Steps`

A step can specify a script field, which contains the body of a script. That script is invoked as if it were stored inside the container image, and any args are passed directly to it.

Note: If the script field is present, the step cannot also contain a command field.

Scripts that do not start with a shebang line will have the following default preamble prepended:

#!/bin/sh
set -e

You can override this default preamble by prepending a shebang that specifies the desired parser. This parser must be present within that Step's container image.

The example below executes a Bash script:

steps:
  - image: ubuntu # contains bash
    script: |
      #!/usr/bin/env bash
      echo "Hello from Bash!"

The example below executes a Python script:

steps:
  - image: python # contains python
    script: |
      #!/usr/bin/env python3
      print("Hello from Python!")

The example below executes a Node script:

steps:
  - image: node # contains node
    script: |
      #!/usr/bin/env node
      console.log("Hello from Node!")

You can execute scripts directly in the workspace:

steps:
  - image: ubuntu
    script: |
      #!/usr/bin/env bash
      /workspace/my-script.sh  # provided by an input resource

You can also execute scripts within the container image:

steps:
  - image: my-image # contains /bin/my-binary
    script: |
      #!/usr/bin/env bash
      /bin/my-binary

Windows scripts

Scripts in tasks that will eventually run on windows nodes need a custom shebang line, so that Tekton knows how to run the script. The format of the shebang line is:

#!win <interpreter command> <args>

Unlike linux, we need to specify how to interpret the script file which is generated by Tekton. The example below shows how to execute a powershell script:

steps:
  - image: mcr.microsoft.com/windows/servercore:1809
    script: |
      #!win powershell.exe -File
      echo 'Hello from PowerShell'

Microsoft provide powershell images, which contain Powershell Core (which is slightly different from powershell found in standard windows images). The example below shows how to use these images:

steps:
  - image: mcr.microsoft.com/powershell:nanoserver
    script: |
      #!win pwsh.exe -File
      echo 'Hello from PowerShell Core'

As can be seen the command is different. The windows shebang can be used for any interpreter, as long as it exists in the image and can interpret commands from a file. The example below executes a Python script:

  steps:
  - image: python
    script: |
      #!win python
      print("Hello from Python!")

Note that other than the #!win shebang the example is identical to the earlier linux example.

Finally, if no interpreter is specified on the #!win line then the script will be treated as a windows .cmd file which will be excecuted. The example below shows this:

  steps:
  - image: mcr.microsoft.com/powershell:lts-nanoserver-1809
    script: |
      #!win
      echo Hello from the default cmd file

Specifying a timeout

A Step can specify a timeout field. If the Step execution time exceeds the specified timeout, the Step kills its running process and any subsequent Steps in the TaskRun will not be executed. The TaskRun is placed into a Failed condition. An accompanying log describing which Step timed out is written as the Failed condition’s message.

The timeout specification follows the duration format as specified in the Go time package (e.g. 1s or 1ms).

The example Step below is supposed to sleep for 60 seconds but will be canceled by the specified 5 second timeout.

steps:
  - name: sleep-then-timeout
    image: ubuntu
    script: |
      #!/usr/bin/env bash
      echo "I am supposed to sleep for 60 seconds!"
      sleep 60      
    timeout: 5s

Specifying `onError` for a `step`

When a step in a task results in a failure, the rest of the steps in the task are skipped and the taskRun is declared a failure. If you would like to ignore such step errors and continue executing the rest of the steps in the task, you can specify onError for such a step.

onError can be set to either continue or stopAndFail as part of the step definition. If onError is set to continue, the entrypoint sets the original failed exit code of the script in the container terminated state. A step with onError set to continue does not fail the taskRun and continues executing the rest of the steps in a task.

To ignore a step error, set onError to continue:

steps:
  - image: docker.io/library/golang:latest
    name: ignore-unit-test-failure
    onError: continue
    script: |
            go test .

The original failed exit code of the script is available in the terminated state of the container.

kubectl get tr taskrun-unit-test-t6qcl -o json | jq .status
{
  "conditions": [
    {
      "message": "All Steps have completed executing",
      "reason": "Succeeded",
      "status": "True",
      "type": "Succeeded"
    }
  ],
  "steps": [
    {
      "container": "step-ignore-unit-test-failure",
      "imageID": "...",
      "name": "ignore-unit-test-failure",
      "terminated": {
        "containerID": "...",
        "exitCode": 1,
        "reason": "Completed",
      }
    },
  ],

For an end-to-end example, see the taskRun ignoring a step error and the pipelineRun ignoring a step error.

Accessing Step’s `exitCode` in subsequent `Steps`

A step can access the exit code of any previous step by reading the file pointed to by the exitCode path variable:

cat $(steps.step-<step-name>.exitCode.path)

The exitCode of a step without any name can be referenced using:

cat $(steps.step-unnamed-<step-index>.exitCode.path)

Produce a task result with `onError`

When a step is set to ignore the step error and if that step is able to initialize a result file before failing, that result is made available to its consumer task.

steps:
  - name: ignore-failure-and-produce-a-result
    onError: continue
    image: busybox
    script: |
      echo -n 123 | tee $(results.result1.path)
      exit 1

The task consuming the result using the result reference $(tasks.task1.results.result1) in a pipeline will be able to access the result and run with the resolved value.

Now, a step can fail before initializing a result and the pipeline can ignore such step failure. But, the pipeline will fail with InvalidTaskResultReference if it has a task consuming that task result. For example, any task consuming $(tasks.task1.results.result2) will cause the pipeline to fail.

steps:
  - name: ignore-failure-and-produce-a-result
    onError: continue
    image: busybox
    script: |
      echo -n 123 | tee $(results.result1.path)
      exit 1
      echo -n 456 | tee $(results.result2.path)

Breakpoint on failure with `onError`

Debugging a taskRun is supported to debug a container and comes with a set of tools to declare the step as a failure or a success. Specifying breakpoint at the taskRun level overrides ignoring a step error using onError.

Redirecting step output streams with `stdoutConfig` and `stderrConfig`

This is an alpha feature. The enable-api-fields feature flag must be set to "alpha" for Redirecting Step Output Streams to function.

This feature defines optional Step fields stdoutConfig and stderrConfig which can be used to redirection the output streams stdout and stderr respectively:

- name: ...
  ...
  stdoutConfig:
    path: ...
  stderrConfig:
    path: ...

Once stdoutConfig.path or stderrConfig.path is specified, the corresponding output stream will be duplicated to both the given file and the standard output stream of the container, so users can still view the output through the Pod log API. If both stdoutConfig.path and stderrConfig.path are set to the same value, outputs from both streams will be interleaved in the same file, but there will be no ordering guarantee on the data. If multiple Step’s stdoutConfig.path fields are set to the same value, the file content will be overwritten by the last outputting step.

Variable substitution will be applied to the new fields, so one could specify $(results.<name>.path) to the stdoutConfig.path or stderrConfig.path field to extract the stdout of a step into a Task result.

Example Usage

Redirecting stdout of boskosctl to jq and publish the resulting project-id as a Task result:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: boskos-acquire
spec:
  results:
  - name: project-id
  steps:
  - name: boskosctl
    image: gcr.io/k8s-staging-boskos/boskosctl
    args:
    - acquire
    - --server-url=http://boskos.test-pods.svc.cluster.local
    - --owner-name=christie-test-boskos
    - --type=gke-project
    - --state=free
    - --target-state=busy
    stdoutConfig:
      path: /data/boskosctl-stdout
    volumeMounts:
    - name: data
      mountPath: /data
  - name: parse-project-id
    image: imega/jq
    args:
    - -r
    - .name
    - /data/boskosctl-stdout
    stdoutConfig:
      path: $(results.project-id.path)
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data

NOTE:

If the intent is to share output between Steps via a file, the user must ensure that the paths provided are shared between the Steps (e.g via volumes).

There is currently a limit on the overall size of the Task results. If the stdout/stderr of a step is set to the path of a Task result and the step prints too many data, the result manifest would become too large. Currently the entrypoint binary will fail if that happens.

If the stdout/stderr of a Step is set to the path of a Task result, e.g. $(results.empty.path), but that result is not defined for the Task, the Step will run but the output will be captured in a file named $(results.empty.path) in the current working directory. Similarly, any stubstition that is not valid, e.g. $(some.invalid.path)/out.txt, will be left as-is and will result in a file path $(some.invalid.path)/out.txt relative to the current working directory.

Guarding `Step` execution using `when` expressions

You can define when in a step to control its execution.

The components of when expressions are input, operator, values, cel:

Component	Description	Syntax
`input`	Input for the `when` expression, defaults to an empty string if not provided.	* Static values e.g. `"ubuntu"` * Variables (parameters or results) e.g. `"$(params.image)"` or `"$(tasks.task1.results.image)"` or `"$(tasks.task1.results.array-results[1])"`
`operator`	`operator` represents an `input`’s relationship to a set of `values`, a valid `operator` must be provided.	`in` or `notin`
`values`	An array of string values, the `values` array must be provided and has to be non-empty.	* An array param e.g. `["$(params.images[])"]` An array result of a task `["$(tasks.task1.results.array-results[])"]` An array result of a step`["(steps.step1.results.array-results[])"]` `values` can contain static values e.g. `"ubuntu"` * `values` can contain variables (parameters or results) or a Workspaces’s `bound` state e.g. `["$(params.image)"]` or `["$(steps.step1.results.image)"]` or `["$(tasks.task1.results.array-results[1])"]` or `["$(steps.step1.results.array-results[1])"]`
`cel`	The Common Expression Language (CEL) implements common semantics for expression evaluation, enabling different applications to more easily interoperate. This is an `alpha` feature, `enable-cel-in-whenexpression` needs to be set to true to use this feature.	cel-syntax

The below example shows how to use when expressions to control step executions:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc-2
spec:
  resources:
    requests:
      storage: 5Gi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
---
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: step-when-example
spec:
  workspaces:
    - name: custom
      persistentVolumeClaim:
        claimName: my-pvc-2
  taskSpec:
    description: |
            A simple task that shows how to use when determine if a step should be executed
    steps:
      - name: should-execute
        image: bash:latest
        script: |
          #!/usr/bin/env bash
          echo "executed..."          
        when:
          - input: "$(workspaces.custom.bound)"
            operator: in
            values: [ "true" ]
      - name: should-skip
        image: bash:latest
        script: |
          #!/usr/bin/env bash
          echo skipskipskip          
        when:
          - input: "$(workspaces.custom2.bound)"
            operator: in
            values: [ "true" ]
      - name: should-continue
        image: bash:latest
        script: |
          #!/usr/bin/env bash
          echo blabalbaba          
      - name: produce-step
        image: alpine
        results:
          - name: result2
            type: string
        script: |
                    echo -n "foo" | tee $(step.results.result2.path)
      - name: run-based-on-step-results
        image: alpine
        script: |
                    echo "wooooooo"
        when:
          - input: "$(steps.produce-step.results.result2)"
            operator: in
            values: [ "bar" ]
    workspaces:
      - name: custom

The StepState for a skipped step looks like something similar to the below:

      {
        "container": "step-run-based-on-step-results",
        "imageID": "docker.io/library/alpine@sha256:c5b1261d6d3e43071626931fc004f70149baeba2c8ec672bd4f27761f8e1ad6b",
        "name": "run-based-on-step-results",
        "terminated": {
          "containerID": "containerd://bf81162e79cf66a2bbc03e3654942d3464db06ff368c0be263a8a70f363a899b",
          "exitCode": 0,
          "finishedAt": "2024-03-26T03:57:47Z",
          "reason": "Completed",
          "startedAt": "2024-03-26T03:57:47Z"
        },
        "terminationReason": "Skipped"
      }

Where terminated.exitCode is 0 and terminationReason is Skipped to indicate the Step exited successfully and was skipped.

Specifying `DisplayName`

The displayName field is an optional field that allows you to add a user-facing name to the step that may be used to populate a UI.

steps:
  - name: ignore-failure-and-produce-a-result
    displayName: "Ignore failure and produce a result"
    onError: continue
    image: busybox
    script: |
      echo -n 123 | tee $(results.result1.path)
      exit 1
      echo -n 456 | tee $(results.result2.path)

Specifying `Parameters`

You can specify parameters, such as compilation flags or artifact names, that you want to supply to the Task at execution time. Parameters are passed to the Task from its corresponding TaskRun.

Parameter name

Parameter name format:

Must only contain alphanumeric characters, hyphens (-), underscores (_), and dots (.). However, object parameter name and its key names can’t contain dots (.). See the reasons in the third item added in this PR.
Must begin with a letter or an underscore (_).

For example, foo.Is-Bar_ is a valid parameter name for string or array type, but is invalid for object parameter because it contains dots. On the other hand, barIsBa$ or 0banana are invalid for all types.

NOTE:

Parameter names are case insensitive. For example, APPLE and apple will be treated as equal. If they appear in the same TaskSpec’s params, it will be rejected as invalid.

If a parameter name contains dots (.), it must be referenced by using the bracket notation with either single or double quotes i.e. $(params['foo.bar']), $(params["foo.bar"]). See the following example for more information.

Parameter type

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

`object` type

object type is useful in cases where users want to group related parameters. For example, an object parameter called gitrepo can contain both the url and the commmit to group related information:

spec:
  params:
    - name: gitrepo
      type: object
      properties:
        url:
          type: string
        commit:
          type: string

Refer to the TaskRun example and the PipelineRun example in which object parameters are demonstrated.

NOTE:

object param must specify the properties section to define the schema i.e. what keys are available for this object param. See how to define properties section in the following example and the TEP-0075.

When providing value for an object param, one may provide values for just a subset of keys in spec’s default, and provide values for the rest of keys at runtime (example).

When using object in variable replacement, users can only access its individual key (“child” member) of the object by its name i.e. $(params.gitrepo.url). Using an entire object as a value is only allowed when the value is also an object like this example. See more details about using object param from the TEP-0075.

`array` type

array type is useful in cases where the number of compilation flags being supplied to a task varies throughout the Task's execution. array param can be defined by setting type to array. Also, array params only supports string array i.e. each array element has to be of type string.

spec:
  params:
    - name: flags
      type: array

`string` type

If not specified, the type field defaults to string. When the actual parameter value is supplied, its parsed type is validated against the type field.

The following example illustrates the use of Parameters in a Task. The Task declares 3 input parameters named gitrepo (of type object), flags (of type array) and someURL (of type string). These parameters are used in the steps.args list

For object parameter, you can only use individual members (aka keys).
You can expand parameters of type array inside an existing array using the star operator. In this example, flags contains the star operator: $(params.flags[*]).

Note: Input parameter values can be used as variables throughout the Task by using variable substitution.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: task-with-parameters
spec:
  params:
    - name: gitrepo
      type: object
      properties:
        url:
          type: string
        commit:
          type: string
    - name: flags
      type: array
    - name: someURL
      type: string
    - name: foo.bar
      description: "the name contains dot character"
      default: "test"
  steps:
    - name: do-the-clone
      image: some-git-image
      args: [
        "-url=$(params.gitrepo.url)",
        "-revision=$(params.gitrepo.commit)"
      ]
    - name: build
      image: my-builder
      args: [
        "build",
        "$(params.flags[*])",
        # It would be equivalent to use $(params["someURL"]) here,
        # which is necessary when the parameter name contains '.'
        # characters (e.g. `$(params["some.other.URL"])`). See the example in step "echo-param"
        'url=$(params.someURL)',
      ]
    - name: echo-param
      image: bash
      args: [
        "echo",
        "$(params['foo.bar'])",
      ]

The following TaskRun supplies the value for the parameter gitrepo, flags and someURL:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: run-with-parameters
spec:
  taskRef:
    name: task-with-parameters
  params:
    - name: gitrepo
      value:
        url: "abc.com"
        commit: "c12b72"
    - name: flags
      value:
        - "--set"
        - "arg1=foo"
        - "--randomflag"
        - "--someotherflag"
    - name: someURL
      value: "http://google.com"

Specifying Workspaces

Workspaces allow you to specify one or more volumes that your Task requires during execution. It is recommended that Tasks uses at most one writeable Workspace. For example:

spec:
  steps:
    - name: write-message
      image: ubuntu
      script: |
        #!/usr/bin/env bash
        set -xe
        echo hello! > $(workspaces.messages.path)/message        
  workspaces:
    - name: messages
      description: The folder where we write the message to
      mountPath: /custom/path/relative/to/root

For more information, see Using Workspaces in Tasks and the Workspaces in a TaskRun example YAML file.

Propagated `Workspaces`

Workspaces can be propagated to embedded task specs, not referenced Tasks. For more information, see Propagated Workspaces.

Emitting Results

A Task is able to emit string results that can be viewed by users and passed to other Tasks in a Pipeline. These results have a wide variety of potential uses. To highlight just a few examples from the Tekton Catalog: the git-clone Task emits a cloned commit SHA as a result, the generate-build-id Task emits a randomized ID as a result, and the kaniko Task emits a container image digest as a result. In each case these results convey information for users to see when looking at their TaskRuns and can also be used in a Pipeline to pass data along from one Task to the next. Task results are best suited for holding small amounts of data, such as commit SHAs, branch names, ephemeral namespaces, and so on.

To define a Task's results, use the results field. In the example below, the Task specifies two files in the results field: current-date-unix-timestamp and current-date-human-readable.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: print-date
  annotations:
    description: |
            A simple task that prints the date
spec:
  results:
    - name: current-date-unix-timestamp
      description: The current date in unix timestamp format
    - name: current-date-human-readable
      description: The current date in human readable format
  steps:
    - name: print-date-unix-timestamp
      image: bash:latest
      script: |
        #!/usr/bin/env bash
        date +%s | tee $(results.current-date-unix-timestamp.path)        
    - name: print-date-human-readable
      image: bash:latest
      script: |
        #!/usr/bin/env bash
        date | tee $(results.current-date-human-readable.path)

In this example, $(results.name.path) is replaced with the path where Tekton will store the Task’s results.

When this Task is executed in a TaskRun, the results will appear in the TaskRun’s status:

v1
v1beta1

apiVersion: tekton.dev/v1
kind: TaskRun
# ...
status:
  # ...
  results:
    - name: current-date-human-readable
      value: |
                Wed Jan 22 19:47:26 UTC 2020
    - name: current-date-unix-timestamp
      value: |
                1579722445

apiVersion: tekton.dev/v1beta1
kind: TaskRun
# ...
status:
  # ...
  taskResults:
    - name: current-date-human-readable
      value: |
                Wed Jan 22 19:47:26 UTC 2020
    - name: current-date-unix-timestamp
      value: |
                1579722445

Tekton does not perform any processing on the contents of results; they are emitted verbatim from your Task including any leading or trailing whitespace characters. Make sure to write only the precise string you want returned from your Task into the result files that your Task creates.

The stored results can be used at the Task level or at the Pipeline level.

Note Tekton does not enforce Task results unless there is a consumer: when a Task declares a result, it may complete successfully even if no result was actually produced. When a Task that declares results is used in a Pipeline, and a component of the Pipeline attempts to consume the Task’s result, if the result was not produced the pipeline will fail. TEP-0048 propopses introducing default values for results to help Pipeline authors manage this case.

Emitting Object `Results`

Emitting a task result of type object is implemented based on the TEP-0075. You can initialize object results from a task using JSON escaped string. For example, to assign the following data to an object result:

{"url":"abc.dev/sampler","digest":"19f02276bf8dbdd62f069b922f10c65262cc34b710eea26ff928129a736be791"}

You will need to use escaped JSON to write to pod termination message:

{\"url\":\"abc.dev/sampler\",\"digest\":\"19f02276bf8dbdd62f069b922f10c65262cc34b710eea26ff928129a736be791\"}

An example of a task definition producing an object result:

kind: Task
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
metadata:
  name: write-object
  annotations:
    description: |
            A simple task that writes object
spec:
  results:
    - name: object-results
      type: object
      description: The object results
      properties:
        url:
          type: string
        digest:
          type: string
  steps:
    - name: write-object
      image: bash:latest
      script: |
        #!/usr/bin/env bash
        echo -n "{\"url\":\"abc.dev/sampler\",\"digest\":\"19f02276bf8dbdd62f069b922f10c65262cc34b710eea26ff928129a736be791\"}" | tee $(results.object-results.path)

Note:

that the opening and closing braces are mandatory along with an escaped JSON.

object result must specify the properties section to define the schema i.e. what keys are available for this object result. Failing to emit keys from the defined object results will result in validation error at runtime.

Emitting Array `Results`

Tekton Task also supports defining a result of type array and object in addition to string. Emitting a task result of type array is a beta feature implemented based on the TEP-0076. You can initialize array results from a task using JSON escaped string, for example, to assign the following list of animals to an array result:

["cat", "dog", "squirrel"]

You will have to initialize the pod termination message as escaped JSON:

[\"cat\", \"dog\", \"squirrel\"]

An example of a task definition producing an array result with such greetings ["hello", "world"]:

kind: Task
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
metadata:
  name: write-array
  annotations:
    description: |
            A simple task that writes array
spec:
  results:
    - name: array-results
      type: array
      description: The array results
  steps:
    - name: write-array
      image: bash:latest
      script: |
        #!/usr/bin/env bash
        echo -n "[\"hello\",\"world\"]" | tee $(results.array-results.path)

Note that the opening and closing square brackets are mandatory along with an escaped JSON.

Now, similar to the Go zero-valued slices, an array result is considered as uninitialized (i.e. nil) if it’s set to an empty array i.e. []. For example, echo -n "[]" | tee $(results.result.path); is equivalent to result := []string{}. The result initialized in this way will have zero length. And trying to access this array with a star notation i.e. $(tasks.write-array-results.results.result[*]) or an element of such array i.e. $(tasks.write-array-results.results.result[0]) results in InvalidTaskResultReference with index out of range.

Depending on your use case, you might have to initialize a result array to the desired length just like using make() function in Go. make() function is used to allocate an array and returns a slice of the specified length i.e. result := make([]string, 5) results in ["", "", "", "", ""], similarly set the array result to following JSON escaped expression to allocate an array of size 2:

echo -n "[\"\", \"\"]" | tee $(results.array-results.path) # an array of size 2 with empty string
echo -n "[\"first-array-element\", \"\"]" | tee $(results.array-results.path) # an array of size 2 with only first element initialized
echo -n "[\"\", \"second-array-element\"]" | tee $(results.array-results.path) # an array of size 2 with only second element initialized
echo -n "[\"first-array-element\", \"second-array-element\"]" | tee $(results.array-results.path) # an array of size 2 with both elements initialized

This is also important to maintain the order of the elements in an array. The order in which the task result was initialized is the order in which the result is consumed by the dependent tasks. For example, a task is producing two array results images and configmaps. The pipeline author can implement deployment by indexing into each array result:

    - name: deploy-stage-1
      taskRef:
        name: deploy
      params:
        - name: image
          value: $(tasks.setup.results.images[0])
        - name: configmap
          value: $(tasks.setup.results.configmap[0])
      ...
    - name: deploy-stage-2
      taskRef:
        name: deploy
      params:
        - name: image
          value: $(tasks.setup.results.images[1])
        - name: configmap
          value: $(tasks.setup.results.configmap[1])

As a task author, make sure the task array results are initialized accordingly or set to a zero value in case of no image or configmap to maintain the order.

Note: Tekton uses termination messages. As written in tektoncd/pipeline#4808, the maximum size of a Task's results is limited by the container termination message feature of Kubernetes. At present, the limit is “4096 bytes”. This also means that the number of Steps in a Task affects the maximum size of a Result, as each Step is implemented as a container in the TaskRun’s pod. The more containers we have in our pod, the smaller the allowed size of each container’s message, meaning that the more steps you have in a Task, the smaller the result for each step can be. For example, if you have 10 steps, the size of each step’s Result will have a maximum of less than 1KB.

If your Task writes a large number of small results, you can work around this limitation by writing each result from a separate Step so that each Step has its own termination message. If a termination message is detected as being too large the TaskRun will be placed into a failed state with the following message: Termination message is above max allowed size 4096, caused by large task result. Since Tekton also uses the termination message for some internal information, so the real available size will less than 4096 bytes.

As a general rule-of-thumb, if a result needs to be larger than a kilobyte, you should likely use a Workspace to store and pass it between Tasks within a Pipeline.

Larger `Results` using sidecar logs

This is a beta feature which is guarded behind its own feature flag. The results-from feature flag must be set to "sidecar-logs" to enable larger results using sidecar logs.

Instead of using termination messages to store results, the taskrun controller injects a sidecar container which monitors the results of all the steps. The sidecar mounts the volume where results of all the steps are stored. As soon as it finds a new result, it logs it to std out. The controller has access to the logs of the sidecar container. CAUTION: we need you to enable access to kubernetes pod/logs.

This feature allows users to store up to 4 KB per result by default. Because we are not limited by the size of the termination messages, users can have as many results as they require (or until the CRD reaches its limit). If the size of a result exceeds this limit, then the TaskRun will be placed into a failed state with the following message: Result exceeded the maximum allowed limit.

Note: If you require even larger results, you can specify a different upper limit per result by setting max-result-size feature flag to your desired size in bytes (see instructions). CAUTION: the larger you make the size, more likely will the CRD reach its max limit enforced by the etcd server leading to bad user experience.

Refer to the detailed instructions listed in additional config to learn how to enable this feature.

Specifying Volumes

Specifies one or more Volumes that the Steps in your Task require to execute in addition to volumes that are implicitly created for input and output resources.

For example, you can use Volumes to do the following:

Mount a Kubernetes Secret.
Create an emptyDir persistent Volume that caches data across multiple Steps.
Mount a Kubernetes ConfigMap as Volume source.
Mount a host’s Docker socket to use a Dockerfile for building container images. Note: Building a container image on-cluster using docker build is very unsafe and is mentioned only for the sake of the example. Use kaniko instead.

Specifying Step Template

The stepTemplate field specifies a Container configuration that will be used as the starting point for all of the Steps in your Task. Individual configurations specified within Steps supersede the template wherever overlap occurs.

In the example below, the Task specifies a stepTemplate field with the environment variable FOO set to bar. The first Step in the Task uses that value for FOO, but the second Step overrides the value set in the template with baz. Additional, the Task specifies a stepTemplate field with the environment variable TOKEN set to public. The last one Step in the Task uses private in the referenced secret to override the value set in the template.

stepTemplate:
  env:
    - name: "FOO"
      value: "bar"
    - name: "TOKEN"
      value: "public"
steps:
  - image: ubuntu
    command: [echo]
    args: ["FOO is ${FOO}"]
  - image: ubuntu
    command: [echo]
    args: ["FOO is ${FOO}"]
    env:
      - name: "FOO"
        value: "baz"
  - image: ubuntu
    command: [echo]
    args: ["TOKEN is ${TOKEN}"]
    env:
      - name: "TOKEN"
        valueFrom:
          secretKeyRef:
            key: "token"
            name: "test"
---
# The secret 'test' part data is as follows.
data:
  # The decoded value of 'cHJpdmF0ZQo=' is 'private'.
  token: "cHJpdmF0ZQo="

Specifying Sidecars

The sidecars field specifies a list of Containers to run alongside the Steps in your Task. You can use Sidecars to provide auxiliary functionality, such as Docker in Docker or running a mock API server that your app can hit during testing. Sidecars spin up before your Task executes and are deleted after the Task execution completes. For further information, see Sidecars in TaskRuns.

Note: Starting in v0.62 you can enable native Kubernetes sidecar support using the enable-kubernetes-sidecar feature flag (see instructions). If kubernetes does not wait for your sidecar application to be ready, use a startupProbe to help kubernetes identify when it is ready.

Refer to the detailed instructions listed in additional config to learn how to enable this feature.

In the example below, a Step uses a Docker-in-Docker Sidecar to build a Docker image:

steps:
  - image: docker
    name: client
    script: |
      #!/usr/bin/env bash
      cat > Dockerfile << EOF
      FROM ubuntu
      RUN apt-get update
      ENTRYPOINT ["echo", "hello"]
      EOF
      docker build -t hello . && docker run hello
      docker images      
    volumeMounts:
      - mountPath: /var/run/
        name: dind-socket
sidecars:
  - image: docker:18.05-dind
    name: server
    securityContext:
      privileged: true
    volumeMounts:
      - mountPath: /var/lib/docker
        name: dind-storage
      - mountPath: /var/run/
        name: dind-socket
volumes:
  - name: dind-storage
    emptyDir: {}
  - name: dind-socket
    emptyDir: {}

Sidecars, just like Steps, can also run scripts:

sidecars:
  - image: busybox
    name: hello-sidecar
    script: |
            echo 'Hello from sidecar!'

Note: Tekton’s current Sidecar implementation contains a bug. Tekton uses a container image named nop to terminate Sidecars. That image is configured by passing a flag to the Tekton controller. If the configured nop image contains the exact command the Sidecar was executing before receiving a “stop” signal, the Sidecar keeps running, eventually causing the TaskRun to time out with an error. For more information, see issue 1347.

Adding Description

The description field is an optional field that allows you to add an informative description to the Task.

Using Variable Substitution

Tekton provides variables to inject values into the contents of certain fields. The values you can inject come from a range of sources including other fields in the Task, context-sensitive information that Tekton provides, and runtime information received from a TaskRun.

The mechanism of variable substitution is quite simple - string replacement is performed by the Tekton Controller when a TaskRun is executed.

Tasks allow you to substitute variable names for the following entities:

See the complete list of variable substitutions for Tasks and the list of fields that accept substitutions.

Using Variable Substitution

params and resources attributes can replace variable values as follows:

To reference a parameter in a Task, use the following syntax, where <name> is the name of the parameter:

# dot notation
# Here, the name cannot contain dots (eg. foo.bar is not allowed). If the name contains `dots`, it can only be accessed via the bracket notation.
$(params.<name> )
# or bracket notation (wrapping <name> with either single or double quotes):
# Here, the name can contain dots (eg. foo.bar is allowed).
$(params['<name>'])
$(params["<name>"])

To access parameter values from resources, see variable substitution

Code examples

Study the following code examples to better understand how to configure your Tasks:

_Tip: See the collection of Tasks in the Tekton community catalog for more examples.

Building and pushing a Docker image

The following example Task builds and pushes a Dockerfile-built image.

Note: Building a container image using docker build on-cluster is very unsafe and is shown here only as a demonstration. Use kaniko instead.

spec:
  params:
    # This may be overridden, but is a sensible default.
    - name: dockerfileName
      type: string
      description: The name of the Dockerfile
      default: Dockerfile
    - name: image
      type: string
      description: The image to build and push
  workspaces:
  - name: source
  steps:
    - name: dockerfile-build
      image: gcr.io/cloud-builders/docker
      workingDir: "$(workspaces.source.path)"
      args:
        [
          "build",
          "--no-cache",
          "--tag",
          "$(params.image)",
          "--file",
          "$(params.dockerfileName)",
          ".",
        ]
      volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock

    - name: dockerfile-push
      image: gcr.io/cloud-builders/docker
      args: ["push", "$(params.image)"]
      volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock

  # As an implementation detail, this Task mounts the host's daemon socket.
  volumes:
    - name: docker-socket
      hostPath:
        path: /var/run/docker.sock
        type: Socket

Mounting multiple `Volumes`

The example below illustrates mounting multiple Volumes:

spec:
  steps:
    - image: ubuntu
      script: |
        #!/usr/bin/env bash
        curl https://foo.com > /var/my-volume        
      volumeMounts:
        - name: my-volume
          mountPath: /var/my-volume

    - image: ubuntu
      script: |
        #!/usr/bin/env bash
        cat /etc/my-volume        
      volumeMounts:
        - name: my-volume
          mountPath: /etc/my-volume

  volumes:
    - name: my-volume
      emptyDir: {}

Mounting a `ConfigMap` as a `Volume` source

The example below illustrates how to mount a ConfigMap to act as a Volume source:

spec:
  params:
    - name: CFGNAME
      type: string
      description: Name of config map
    - name: volumeName
      type: string
      description: Name of volume
  steps:
    - image: ubuntu
      script: |
        #!/usr/bin/env bash
        cat /var/configmap/test        
      volumeMounts:
        - name: "$(params.volumeName)"
          mountPath: /var/configmap

  volumes:
    - name: "$(params.volumeName)"
      configMap:
        name: "$(params.CFGNAME)"

Using a `Secret` as an environment source

The example below illustrates how to use a Secret as an environment source:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: goreleaser
spec:
  params:
    - name: package
      type: string
      description: base package to build in
    - name: github-token-secret
      type: string
      description: name of the secret holding the github-token
      default: github-token
  workspaces:
  - name: source
  steps:
    - name: release
      image: goreleaser/goreleaser
      workingDir: $(workspaces.source.path)/$(params.package)
      command:
        - goreleaser
      args:
        - release
      env:
        - name: GOPATH
          value: /workspace
        - name: GITHUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: $(params.github-token-secret)
              key: bot-token

Using a `Sidecar` in a `Task`

The example below illustrates how to use a Sidecar in your Task:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: with-sidecar-task
spec:
  params:
    - name: sidecar-image
      type: string
      description: Image name of the sidecar container
    - name: sidecar-env
      type: string
      description: Environment variable value
  sidecars:
    - name: sidecar
      image: $(params.sidecar-image)
      env:
        - name: SIDECAR_ENV
          value: $(params.sidecar-env)
  steps:
    - name: test
      image: hello-world

Debugging

This section describes techniques for debugging the most common issues in Tasks.

Inspecting the file structure

A common issue when configuring Tasks stems from not knowing the location of your data. For the most part, files ingested and output by your Task live in the /workspace directory, but the specifics can vary. To inspect the file structure of your Task, add a step that outputs the name of every file stored in the /workspace directory to the build log. For example:

- name: build-and-push-1
  image: ubuntu
  command:
    - /bin/bash
  args:
    - -c
    - |
      set -ex
      find /workspace

You can also choose to examine the contents of every file used by your Task:

- name: build-and-push-1
  image: ubuntu
  command:
    - /bin/bash
  args:
    - -c
    - |
      set -ex
      find /workspace | xargs cat

Inspecting the `Pod`

To inspect the contents of the Pod used by your Task at a specific stage in the Task's execution, log into the Pod and add a Step that pauses the Task at the desired stage. For example:

- name: pause
  image: docker
  args: ["sleep", "6000"]

Running Step Containers as a Non Root User

All steps that do not require to be run as a root user should make use of TaskRun features to designate the container for a step runs as a user without root permissions. As a best practice, running containers as non root should be built into the container image to avoid any possibility of the container being run as root. However, as a further measure of enforcing this practice, steps can make use of a securityContext to specify how the container should run.

An example of running Task steps as a non root user is shown below:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: show-non-root-steps
spec:
  steps:
    # no securityContext specified so will use
    # securityContext from TaskRun podTemplate
    - name: show-user-1001
      image: ubuntu
      command:
        - ps
      args:
        - "aux"
    # securityContext specified so will run as
    # user 2000 instead of 1001
    - name: show-user-2000
      image: ubuntu
      command:
        - ps
      args:
        - "aux"
      securityContext:
        runAsUser: 2000
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: show-non-root-steps-run-
spec:
  taskRef:
    name: show-non-root-steps
  podTemplate:
    securityContext:
      runAsNonRoot: true
      runAsUser: 1001

In the example above, the step show-user-2000 specifies via a securityContext that the container for the step should run as user 2000. A securityContext must still be specified via a TaskRun podTemplate for this TaskRun to run in a Kubernetes environment that enforces running containers as non root as a requirement.

The runAsNonRoot property specified via the podTemplate above validates that steps part of this TaskRun are running as non root users and will fail to start any step container that attempts to run as root. Only specifying runAsNonRoot: true will not actually run containers as non root as the property simply validates that steps are not running as root. It is the runAsUser property that is actually used to set the non root user ID for the container.

If a step defines its own securityContext, it will be applied for the step container over the securityContext specified at the pod level via the TaskRun podTemplate.

More information about Pod and Container Security Contexts can be found via the Kubernetes website.

The example Task/TaskRun above can be found as a TaskRun example.

`Task` Authoring Recommendations

Recommendations for authoring Tasks are available in the Tekton Catalog.

Except as otherwise noted, the contents of this page are licensed under the Creative Commons Attribution 4.0 License. Code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

TaskRuns

Overview

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. A TaskRun executes the Steps in the Task in the order they are specified until all Steps have executed successfully or a failure occurs.

Configuring a `TaskRun`

A TaskRun definition supports the following fields:

Required:
- apiVersion - Specifies the API version, for example tekton.dev/v1beta1.
- kind - Identifies this resource object as a TaskRun object.
- metadata - Specifies the metadata that uniquely identifies the TaskRun, such as a name.
- spec - Specifies the configuration for the TaskRun.
  - taskRef or taskSpec - Specifies the Tasks that the TaskRun will execute.
Optional:
- serviceAccountName - Specifies a ServiceAccount object that provides custom credentials for executing the TaskRun.
- params - Specifies the desired execution parameters for the Task.
- timeout - Specifies the timeout before the TaskRun fails.
- podTemplate - Specifies a Pod template to use as the starting point for configuring the Pods for the Task.
- workspaces - Specifies the physical volumes to use for the Workspaces declared by a Task.
- debug- Specifies any breakpoints and debugging configuration for the Task execution.
- stepSpecs - Specifies configuration to use to override the Task’s Steps.
- sidecarSpecs - Specifies configuration to use to override the Task’s Sidecars.
- managedBy - Specifies the controller responsible for managing this TaskRun’s lifecycle.

Specifying the target `Task`

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

spec:
  taskRef:
    name: read-task

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
        # specifying DOCKER_CONFIG is required to allow kaniko to detect docker credential
        workingDir: $(workspaces.source.path)
        env:
          - name: "DOCKER_CONFIG"
            value: "/tekton/home/.docker/"
        command:
          - /kaniko/executor
        args:
          - --destination=gcr.io/my-project/gohelloworld

Tekton Bundles

A Tekton Bundle is an OCI artifact that contains Tekton resources like Tasks which can be referenced within a taskRef.

You can reference a Tekton bundle in a TaskRef in both v1 and v1beta1 using remote resolution. The example syntax shown below for v1 uses remote resolution and requires enabling beta features.

spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/myrepo/mycatalog
    - name: name
      value: echo-task
    - name: kind
      value: Task

You may also specify a tag as you would with a Docker image which will give you a repeatable reference to a Task.

spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/myrepo/mycatalog:v1.0.1
    - name: name
      value: echo-task
    - name: kind
      value: Task

You may also specify a fixed digest instead of a tag which ensures the referenced task is constant.

spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/myrepo/mycatalog@sha256:abc123
    - name: name
      value: echo-task
    - name: kind
      value: Task

A working example can be found here.

Any of the above options will fetch the image using the ImagePullSecrets attached to the ServiceAccount specified in the TaskRun. See the Service Account section for details on how to configure a ServiceAccount on a TaskRun. The TaskRun will then run that Task without registering it in the cluster allowing multiple versions of the same named Task to be run at once.

Tekton Bundles may be constructed with any toolsets that produces valid OCI image artifacts so long as the artifact adheres to the contract. Additionally, you may also use the tkn cli (coming soon).

Remote Tasks

(beta feature)

A taskRef field may specify a Task in a remote location such as git. Support for specific types of remote will depend on the Resolvers your cluster’s operator has installed. For more information including a tutorial, please check resolution docs. The below example demonstrates referencing a Task in git:

spec:
  taskRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      value: abc123
    - name: pathInRepo
      value: /task/golang-build/0.3/golang-build.yaml

Specifying `Parameters`

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

spec:
  params:
    - name: flags
      value: -someflag

Note: 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 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: hello-
spec:
  params:
    - name: message
      value: "hello world!"
  taskSpec:
    # There are no explicit params defined here.
    # They are derived from the TaskRun params above.
    steps:
    - name: default
      image: ubuntu
      script: |
                echo $(params.message)

On executing the task run, the parameters will be interpolated during resolution. The specifications are not mutated before storage and so it remains the same. The status is updated.

kind: TaskRun
metadata:
  name: hello-dlqm9
  ...
spec:
  params:
  - name: message
    value: hello world!
  serviceAccountName: default
  taskSpec:
    steps:
    - image: ubuntu
      name: default
      script: |
                echo $(params.message)
status:
  conditions:
  - lastTransitionTime: "2022-05-20T15:24:41Z"
    message: All Steps have completed executing
    reason: Succeeded
    status: "True"
    type: Succeeded
  ...
  steps:
  - container: step-default
    ...
  taskSpec:
    steps:
    - image: ubuntu
      name: default
      script: |
                echo "hello world!"

Propagated Object Parameters

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

Note: If an object parameter is being defined explicitly then you must define the spec of the object in Properties.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: object-param-result-
spec:
  params:
  - name: gitrepo
    value:
      commit: sha123
      url: xyz.com
  taskSpec:
    steps:
    - name: echo-object-params
      image: bash
      args:
      - echo
      - --url=$(params.gitrepo.url)
      - --commit=$(params.gitrepo.commit)

On executing the task run, the object parameters will be interpolated during resolution. The specifications are not mutated before storage and so it remains the same. The status is updated.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: object-param-result-vlnmb
  ...
spec:
  params:
  - name: gitrepo
    value:
      commit: sha123
      url: xyz.com
  serviceAccountName: default
  taskSpec:
    steps:
    - args:
      - echo
      - --url=$(params.gitrepo.url)
      - --commit=$(params.gitrepo.commit)
      image: bash
      name: echo-object-params
status:
  completionTime: "2022-09-08T17:09:37Z"
  conditions:
  - lastTransitionTime: "2022-09-08T17:09:37Z"
    message: All Steps have completed executing
    reason: Succeeded
    status: "True"
    type: Succeeded
    ...
  steps:
  - container: step-echo-object-params
    ...
  taskSpec:
    steps:
    - args:
      - echo
      - --url=xyz.com
      - --commit=sha123
      image: bash
      name: echo-object-params

Extra Parameters

(alpha only)

You can pass in extra Parameters if needed depending on your use cases. An example use case is when your CI system autogenerates TaskRuns and it has Parameters it wants to provide to all TaskRuns. Because you can pass in extra Parameters, you don’t have to go through the complexity of checking each Task and providing only the required params.

Parameter Enums

🌱 enum is an alpha feature. The enable-param-enum feature flag must be set to "true" to enable this feature.

If a Parameter is guarded by Enum in the Task, you can only provide Parameter values in the TaskRun that are predefined in the Param.Enum in the Task. The TaskRun will fail with reason InvalidParamValue otherwise.

You can also specify Enum for TaskRun with an embedded Task. The same param validation will be executed in this scenario.

See more details in Param.Enum.

Specifying `Resource` limits

Each Step in a Task can specify its resource requirements. See Defining Steps. Resource requirements defined in Steps and Sidecars may be overridden by a TaskRun’s StepSpecs and SidecarSpecs.

Specifying Task-level `ComputeResources`

(beta only)

Task-level compute resources can be configured in TaskRun.ComputeResources, or PipelineRun.TaskRunSpecs.ComputeResources.

e.g.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: task
spec:
  steps:
    - name: foo
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: taskrun
spec:
  taskRef:
    name: task
  computeResources:
    requests:
      cpu: 1
    limits:
      cpu: 2

Further details and examples could be found in Compute Resources in Tekton.

Specifying a `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. This allows you to customize the Pod configuration specifically for that TaskRun.

In the following example, the Task specifies a volumeMount (my-cache) object, also provided by the TaskRun, using a PersistentVolumeClaim volume. A specific scheduler is also configured in the SchedulerName field. The Pod executes with regular (non-root) user permissions.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: mytask
  namespace: default
spec:
  steps:
    - name: writesomething
      image: ubuntu
      command: ["bash", "-c"]
      args: ["echo 'foo' > /my-cache/bar"]
      volumeMounts:
        - name: my-cache
          mountPath: /my-cache
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: mytaskrun
  namespace: default
spec:
  taskRef:
    name: mytask
  podTemplate:
    schedulerName: volcano
    securityContext:
      runAsNonRoot: true
      runAsUser: 1001
    volumes:
      - name: my-cache
        persistentVolumeClaim:
          claimName: my-volume-claim

Specifying `Workspaces`

If a Task specifies one or more Workspaces, you must map those Workspaces to the corresponding physical volumes in your TaskRun definition. For example, you can map a PersistentVolumeClaim volume to a Workspace as follows:

workspaces:
  - name: myworkspace # must match workspace name in the Task
    persistentVolumeClaim:
      claimName: mypvc # this PVC must already exist
    subPath: my-subdir

For more information, see the following topics:

For information on mapping Workspaces to Volumes, see Using Workspace variables in TaskRuns.
For a list of supported Volume types, see Specifying VolumeSources in Workspaces.
For an end-to-end example, see Workspaces in a TaskRun.

Propagated Workspaces

When using an embedded spec, workspaces from the parent TaskRun will be propagated to any inlined specs without needing to be explicitly defined. This allows authors to simplify specs by automatically propagating top-level workspaces down to other inlined resources. Workspace substutions will only be made for commands, args and script fields of steps, stepTemplates, and sidecars.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: propagating-workspaces-
spec:
  taskSpec:
    steps:
      - name: simple-step
        image: ubuntu
        command:
          - echo
        args:
          - $(workspaces.tr-workspace.path)
  workspaces:
  - emptyDir: {}
    name: tr-workspace

Upon execution, the workspaces will be interpolated during resolution through to the taskSpec.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: propagating-workspaces-ndxnc
  ...
spec:
  ...
status:
  ...
  taskSpec:
    steps:
      ...
    workspaces:
    - name: tr-workspace

Propagating Workspaces to Referenced Tasks

Workspaces can only be propagated to embedded task specs, not referenced Tasks.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: workspace-propagation
spec:
  steps:
    - name: simple-step
      image: ubuntu
      command:
        - echo
      args:
        - $(workspaces.tr-workspace.path)
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: propagating-workspaces-
spec:
  taskRef:
    name: workspace-propagation
  workspaces:
  - emptyDir: {}
    name: tr-workspace

Upon execution, the above TaskRun will fail because the Task is referenced and workspace is not propagated. It must be explicitly defined in the spec of the defined Task.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  ...
spec:
  taskRef:
    kind: Task
    name: workspace-propagation
  workspaces:
  - emptyDir: {}
    name: tr-workspace
status:
  conditions:
  - lastTransitionTime: "2022-09-13T15:12:35Z"
    message: workspace binding "tr-workspace" does not match any declared workspace
    reason: TaskRunValidationFailed
    status: "False"
    type: Succeeded
  ...

Specifying `Sidecars`

A Sidecar is a container that runs alongside the containers specified in the Steps of a task to provide auxiliary support to the execution of those Steps. For example, a Sidecar can run a logging daemon, a service that updates files on a shared volume, or a network proxy.

Tekton supports the injection of Sidecars into a Pod belonging to a TaskRun with the condition that each Sidecar running inside the Pod are terminated as soon as all Steps in the Task complete execution. This might result in the Pod including each affected Sidecar with a retry count of 1 and a different container image than expected.

We are aware of the following issues affecting Tekton’s implementation of Sidecars:

The configured nop image must not provide the command that the Sidecar is expected to run, otherwise it will not exit, resulting in the Sidecar running forever and the Task eventually timing out. For more information, see the associated issue.
The kubectl get pods command returns the status of the Pod as “Completed” if a Sidecar exits successfully and as “Error” if a Sidecar exits with an error, disregarding the exit codes of the container images that actually executed the Steps inside the Pod. Only the above command is affected. The Pod's description correctly denotes a “Failed” status and the container statuses correctly denote their exit codes and reasons.

Configuring Task Steps and Sidecars in a TaskRun

(beta only)

A TaskRun can specify StepSpecs or SidecarSpecs to configure Step or Sidecar specified in a Task. Only named Steps and Sidecars may be configured.

For example, given the following Task definition:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: image-build-task
spec:
  steps:
    - name: build
      image: gcr.io/kaniko-project/executor:latest
  sidecars:
    - name: logging
      image: my-logging-image

An example TaskRun definition could look like:

v1
v1beta1

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: image-build-taskrun
spec:
  taskRef:
    name: image-build-task
  stepSpecs:
    - name: build
      computeResources:
        requests:
          memory: 1Gi
  sidecarSpecs:
    - name: logging
      computeResources:
        requests:
          cpu: 100m
        limits:
          cpu: 500m

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: image-build-taskrun
spec:
  taskRef:
    name: image-build-task
  stepOverrides:
    - name: build
      resources:
        requests:
          memory: 1Gi
  sidecarOverrides:
    - name: logging
      resources:
        requests:
          cpu: 100m
        limits:
          cpu: 500m

StepSpecs and SidecarSpecs must include the name field and may include resources. No other fields can be overridden. If the overridden Task uses a StepTemplate, configuration on Step will take precedence over configuration in StepTemplate, and configuration in StepSpec will take precedence over both.

When merging resource requirements, different resource types are considered independently. For example, if a Step configures both CPU and memory, and a StepSpec configures only memory, the CPU values from the Step will be preserved. Requests and limits are also considered independently. For example, if a Step configures a memory request and limit, and a StepSpec configures only a memory request, the memory limit from the Step will be preserved.

Specifying `LimitRange` values

In order to only consume the bare minimum amount of resources needed to execute one Step at a time from the invoked Task, Tekton will request the compute values for CPU, memory, and ephemeral storage for each Step based on the LimitRange object(s), if present. Any Request or Limit specified by the user (on Task for example) will be left unchanged.

For more information, see the LimitRange support in Pipeline.

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.

For a retriable TaskRun, when an error occurs:

The error status is archived in status.RetriesStatus
The Succeeded condition in status is updated:

Type: Succeeded
Status: Unknown
Reason: ToBeRetried

status.StartTime, status.PodName and status.Results are unset to trigger another retry attempt.

Configuring the failure timeout

You can use the timeout field to set the TaskRun's desired timeout value for each retry attempt. If you do not specify this value, the global default timeout value applies (the same, to each retry attempt). If you set the timeout to 0, the TaskRun will have no timeout and will run until it completes successfully or fails from an error.

The timeout value is a duration conforming to Go’s ParseDuration format. For example, valid values are 1h30m, 1h, 1m, 60s, and 0.

If a TaskRun runs longer than its timeout value, the pod associated with the TaskRun will be deleted. This means that the logs of the TaskRun are not preserved. The deletion of the TaskRun pod is necessary in order to stop TaskRun step containers from running.

The global default timeout is set to 60 minutes when you first install Tekton. You can set a different global default timeout value using the default-timeout-minutes field in config/config-defaults.yaml. If you set the global timeout to 0, all TaskRuns that do not have a timeout set will have no timeout and will run until it completes successfully or fails from an error.

:note: An internal detail of the PipelineRun and TaskRun reconcilers in the Tekton controller is that it will requeue a PipelineRun or TaskRun for re-evaluation, versus waiting for the next update, under certain conditions. The wait time for that re-queueing is the elapsed time subtracted from the timeout; however, if the timeout is set to ‘0’, that calculation produces a negative number, and the new reconciliation event will fire immediately, which can impact overall performance, which is counter to the intent of wait time calculation. So instead, the reconcilers will use the configured global timeout as the wait time when the associated timeout has been set to ‘0’.

Specifying `ServiceAccount` credentials

You can execute the Task in your TaskRun with a specific set of credentials by specifying a ServiceAccount object name in the serviceAccountName field in your TaskRun definition. If you do not explicitly specify this, the TaskRun executes with the credentials specified in the configmap-defaults ConfigMap. If this default is not specified, TaskRuns will execute with the default service account set for the target namespace.

For more information, see ServiceAccount.

`TaskRun` status

The status field defines the observed state of TaskRun

The `status` field

Required:
- status - The most relevant information about the TaskRun’s state. This field includes:
- status.conditions, which contains the latest observations of the TaskRun’s state. See here for information on typical status properties.
- podName - Name of the pod containing the containers responsible for executing this task’s steps.
- startTime - The time at which the TaskRun began executing, conforms to RFC3339 format.
- completionTime - The time at which the TaskRun finished executing, conforms to RFC3339 format.
- taskSpec - TaskSpec defines the desired state of the Task executed via the TaskRun.
Optional:
- results - List of results written out by the task’s containers.
- provenance - Provenance contains metadata about resources used in the TaskRun such as the source from where a remote task definition was fetched. It carries minimum amount of metadata in TaskRun status so that Tekton Chains can utilize it for provenance, its two subfields are:
  - refSource: the source from where a remote Task definition was fetched.
  - featureFlags: Identifies the feature flags used during the TaskRun.
- steps - Contains the state of each step container.
  - steps[].terminationReason - When the step is terminated, it stores the step’s final state.
- retriesStatus - Contains the history of TaskRun’s status in case of a retry in order to keep record of failures. No status stored within retriesStatus will have any date within as it is redundant.
- sidecars - This field is a list. The list has one entry per sidecar in the manifest. Each entry represents the imageid of the corresponding sidecar.
- spanContext - Contains tracing span context fields.

Monitoring execution status

As your TaskRun executes, its status field accumulates information on the execution of each Step as well as the TaskRun as a whole. This information includes start and stop times, exit codes, the fully-qualified name of the container image, and the corresponding digest.

Note: If any Pods have been OOMKilled by Kubernetes, the TaskRun is marked as failed even if its exit code is 0.

The following example shows the status field of a TaskRun that has executed successfully:

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
    terminationReason: Completed
    terminated:
      containerID: docker://d5a54f5bbb8e7a6fd3bc7761b78410403244cf4c9c5822087fb0209bf59e3621
      exitCode: 0
      finishedAt: "2019-08-12T18:22:56Z"
      reason: Completed
      startedAt: "2019-08-12T18:22:54Z"

The following tables shows how to read the overall status of a TaskRun:

`status`	`reason`	`message`	`completionTime` is set	Description
Unknown	Started	n/a	No	The TaskRun has just been picked up by the controller.
Unknown	Pending	n/a	No	The TaskRun is waiting on a Pod in status Pending.
Unknown	Running	n/a	No	The TaskRun has been validated and started to perform its work.
Unknown	TaskRunCancelled	n/a	No	The user requested the TaskRun to be cancelled. Cancellation has not been done yet.
True	Succeeded	n/a	Yes	The TaskRun completed successfully.
False	Failed	n/a	Yes	The TaskRun failed because one of the steps failed.
False	[Error message]	n/a	No	The TaskRun encountered a non-permanent error, and it’s still running. It may ultimately succeed.
False	[Error message]	n/a	Yes	The TaskRun failed with a permanent error (usually validation).
False	TaskRunCancelled	n/a	Yes	The TaskRun was cancelled successfully.
False	TaskRunCancelled	TaskRun cancelled as the PipelineRun it belongs to has timed out.	Yes	The TaskRun was cancelled because the PipelineRun timed out.
False	TaskRunTimeout	n/a	Yes	The TaskRun timed out.
False	TaskRunImagePullFailed	n/a	Yes	The TaskRun failed due to one of its steps not being able to pull the image.
False	FailureIgnored	n/a	Yes	The TaskRun failed but the failure was ignored.

When a TaskRun changes status, events are triggered accordingly.

The name of the Pod owned by a TaskRun is univocally associated to the owning resource. If a TaskRun resource is deleted and created with the same name, the child Pod will be created with the same name as before. The base format of the name is <taskrun-name>-pod. The name may vary according to the logic of kmeta.ChildName. In case of retries of a TaskRun triggered by the PipelineRun controller, the base format of the name is <taskrun-name>-pod-retry<N> starting from the first retry.

Some examples:

`TaskRun` Name	`Pod` Name
task-run	task-run-pod
task-run-0123456789-0123456789-0123456789-0123456789-0123456789-0123456789	task-run-0123456789-01234560d38957287bb0283c59440df14069f59-pod

Monitoring `Steps`

If multiple Steps are defined in the Task invoked by the TaskRun, you can monitor their execution status in the status.steps field using the following command, where <name> is the name of the target TaskRun:

kubectl get taskrun <name> -o yaml

The exact Task Spec used to instantiate the TaskRun is also included in the Status for full auditability.

Steps

The corresponding statuses appear in the status.steps list in the order in which the Steps have been specified in the Task definition.

Monitoring `Results`

If one or more results fields have been specified in the invoked Task, the TaskRun's execution status will include a Task Results section, in which the Results appear verbatim, including original line returns and whitespace. For example:

Status:
  # […]
  Steps:
  # […]
  Task Results:
    Name:   current-date-human-readable
    Value:  Thu Jan 23 16:29:06 UTC 2020

    Name:   current-date-unix-timestamp
    Value:  1579796946

Cancelling a `TaskRun`

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

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. The deletion of the TaskRun pod is necessary in order to stop TaskRun step containers from running.

Note: if keep-pod-on-cancel is set to "true" in the feature-flags, the pod associated with that TaskRun will not be deleted

Example of cancelling a TaskRun:

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

Debugging a `TaskRun`

Breakpoint on Failure

TaskRuns can be halted on failure for troubleshooting by providing the following spec patch as seen below.

spec:
  debug:
    breakpoints:
      onFailure: "enabled"

Breakpoint before step

If you want to set a breakpoint before the step is executed, you can add the step name to the beforeSteps field in the following way:

spec:
  debug:
    breakpoints:
      beforeSteps: 
        - {{ stepName }}

Upon failure of a step, the TaskRun Pod execution is halted. If this TaskRun Pod continues to run without any lifecycle change done by the user (running the debug-continue or debug-fail-continue script) the TaskRun would be subject to TaskRunTimeout. During this time, the user/client can get remote shell access to the step container with a command such as the following.

kubectl exec -it print-date-d7tj5-pod -c step-print-date-human-readable sh

Debug Environment

After the user/client has access to the container environment, they can scour for any missing parts because of which their step might have failed.

To control the lifecycle of the step to mark it as a success or a failure or close the breakpoint, there are scripts provided in the /tekton/debug/scripts directory in the container. The following are the scripts and the tasks they perform :-

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.

debug-beforestep-continue: Mark the step continue to execute

debug-beforestep-fail-continue: Mark the step not continue to execute

More information on the inner workings of debug can be found in the Debug documentation

Code examples

To better understand TaskRuns, study the following code examples:

Example `TaskRun` with a referenced `Task`

In this example, a TaskRun named read-repo-run invokes and executes an existing Task named read-task. This Task reads the repository from the “input” workspace.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
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 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: read-repo-run
spec:
  taskRef:
    name: read-task
  workspaces:
  - name: input
    persistentVolumeClaim:
      claimName: mypvc
    subPath: my-subdir

Example `TaskRun` with an embedded `Task`

In this example, a TaskRun named build-push-task-run-2 directly executes a Task from its definition embedded in the TaskRun's taskSpec field:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
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)
        # specifying DOCKER_CONFIG is required to allow kaniko to detect docker credential
        env:
          - name: "DOCKER_CONFIG"
            value: "/tekton/home/.docker/"
        command:
          - /kaniko/executor
        args:
          - --destination=gcr.io/my-project/gohelloworld

Example of Using custom `ServiceAccount` credentials

The example below illustrates how to specify a ServiceAccount to access a private git repository:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: test-task-with-serviceaccount-git-ssh
spec:
  serviceAccountName: test-task-robot-git-ssh
  workspaces:
  - name: source
    persistentVolumeClaim:
      claimName: repo-pvc
  - name: ssh-creds
    secret:
      secretName: test-git-ssh
  params:
    - name: url
      value: https://github.com/tektoncd/pipeline.git
  taskRef:
    name: git-clone

In the above code snippet, serviceAccountName: test-build-robot-git-ssh references the following ServiceAccount:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: test-task-robot-git-ssh
secrets:
  - name: test-git-ssh

And secretName: test-git-ssh references the following Secret:

apiVersion: v1
kind: Secret
metadata:
  name: test-git-ssh
  annotations:
    tekton.dev/git-0: github.com
type: kubernetes.io/ssh-auth
data:
  # Generated by:
  # cat id_rsa | base64 -w 0
  ssh-privatekey: LS0tLS1CRUdJTiBSU0EgUFJJVk.....[example]
  # Generated by:
  # ssh-keyscan github.com | base64 -w 0
  known_hosts: Z2l0aHViLmNvbSBzc2g.....[example]

Example of Running Step Containers as a Non Root User

All steps that do not require to be run as a root user should make use of TaskRun features to designate the container for a step runs as a user without root permissions. As a best practice, running containers as non root should be built into the container image to avoid any possibility of the container being run as root. However, as a further measure of enforcing this practice, TaskRun pod templates can be used to specify how containers should be run within a TaskRun pod.

An example of using a TaskRun pod template is shown below to specify that containers running via this TaskRun’s pod should run as non root and run as user 1001 if the container itself does not specify what user to run as:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: TaskRun
metadata:
  generateName: show-non-root-steps-run-
spec:
  taskRef:
    name: show-non-root-steps
  podTemplate:
    securityContext:
      runAsNonRoot: true
      runAsUser: 1001

If a Task step specifies that it is to run as a different user than what is specified in the pod template, the step’s securityContext will be applied instead of what is specified at the pod level. An example of this is available as a TaskRun example.

More information about Pod and Container Security Contexts can be found via the Kubernetes website.

Delegating reconciliation

The managedBy field allows you to delegate the responsibility of managing a TaskRun’s lifecycle to an external controller. When this field is set to a value other than "tekton.dev/pipeline", the Tekton Pipeline controller will ignore the TaskRun, allowing your external controller to take full control. This delegation enables several advanced use cases, such as implementing custom pipeline execution logic, integrating with external management tools, using advanced scheduling algorithms, or coordinating PipelineRuns across multiple clusters (like using MultiKueue).

Example

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: externally-managed-task
spec:
  taskRef:
    name: my-task
  managedBy: "my-custom-controller"

Behavior

When managedBy is empty: The Tekton Pipeline controller manages the TaskRun normally
When managedBy is set to "tekton.dev/pipeline": The Tekton Pipeline controller manages the TaskRun normally
When managedBy is set to any other value: The Tekton Pipeline controller ignores the TaskRun completely
Immutability: The managedBy field is immutable and cannot be changed after creation

External controller responsibilities

When you set managedBy to a custom value, your external controller is responsible for:

Creating and managing Pods
Updating TaskRun status
Handling timeouts and cancellations
Managing retries and error handling
Processing step results and artifacts

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Pipelines

Pipelines

Overview

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. Each Task in a Pipeline executes as a Pod on your Kubernetes cluster. You can configure various execution conditions to fit your business needs.

Configuring a `Pipeline`

A Pipeline definition supports the following fields:

Required:
- apiVersion - Specifies the API version, for example tekton.dev/v1beta1.
- kind - Identifies this resource object as a Pipeline object.
- metadata - Specifies metadata that uniquely identifies the Pipeline object. For example, a name.
- spec - Specifies the configuration information for this Pipeline object. This must include:
  - tasks - Specifies the Tasks that comprise the Pipeline and the details of their execution.
Optional:
- params - Specifies the Parameters that the Pipeline requires.
- workspaces - Specifies a set of Workspaces that the Pipeline requires.
- tasks:
  - name - the name of this Task within the context of this Pipeline.
  - displayName - a user-facing name of this Task within the context of this Pipeline.
  - description - a description of this Task within the context of this Pipeline.
  - taskRef - a reference to a Task definition.
  - taskSpec - a specification of a Task.
  - runAfter - Indicates that a Task should execute after one or more other Tasks without output linking.
  - retries - Specifies the number of times to retry the execution of a Task after a failure. Does not apply to execution cancellations.
  - when - Specifies when expressions that guard the execution of a Task; allow execution only when all when expressions evaluate to true.
  - timeout - Specifies the timeout before a Task fails.
  - params - Specifies the Parameters that a Task requires.
  - workspaces - Specifies the Workspaces that a Task requires.
  - matrix - Specifies the Parameters used to fan out a Task into multiple TaskRuns or Runs.
- results - Specifies the location to which the Pipeline emits its execution results.
- displayName - is a user-facing name of the pipeline that may be used to populate a UI.
- description - Holds an informative description of the Pipeline object.
- finally - Specifies one or more Tasks to be executed in parallel after all other tasks have completed.
  - name - the name of this Task within the context of this Pipeline.
  - displayName - a user-facing name of this Task within the context of this Pipeline.
  - description - a description of this Task within the context of this Pipeline.
  - taskRef - a reference to a Task definition.
  - taskSpec - a specification of a Task.
  - retries - Specifies the number of times to retry the execution of a Task after a failure. Does not apply to execution cancellations.
  - when - Specifies when expressions that guard the execution of a Task; allow execution only when all when expressions evaluate to true.
  - timeout - Specifies the timeout before a Task fails.
  - params - Specifies the Parameters that a Task requires.
  - workspaces - Specifies the Workspaces that a Task requires.
  - matrix - Specifies the Parameters used to fan out a Task into multiple TaskRuns or Runs.

Specifying `Workspaces`

Workspaces allow you to specify one or more volumes that each Task in the Pipeline requires during execution. You specify one or more Workspaces in the workspaces field. For example:

spec:
  workspaces:
    - name: pipeline-ws1 # The name of the workspace in the Pipeline
  tasks:
    - name: use-ws-from-pipeline
      taskRef:
        name: gen-code # gen-code expects a workspace with name "output"
      workspaces:
        - name: output
          workspace: pipeline-ws1
    - name: use-ws-again
      taskRef:
        name: commit # commit expects a workspace with name "src"
      runAfter:
        - use-ws-from-pipeline # important: use-ws-from-pipeline writes to the workspace first
      workspaces:
        - name: src
          workspace: pipeline-ws1

For simplicity you can also map the name of the Workspace in PipelineTask to match with the Workspace from the Pipeline. For example:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: pipeline
spec:
  workspaces:
    - name: source
  tasks:
    - name: gen-code
      taskRef:
        name: gen-code # gen-code expects a Workspace named "source"
      workspaces:
        - name: source # <- mapping workspace name
    - name: commit
      taskRef:
        name: commit # commit expects a Workspace named "source"
      workspaces:
        - name: source # <- mapping workspace name
      runAfter:
        - gen-code

For more information, see:

Using Workspaces in Pipelines
The Workspaces in a PipelineRun code example
The variables available in a PipelineRun, including workspaces.<name>.bound.
Mapping Workspaces

Specifying `Parameters`

You can specify global parameters, such as compilation flags or artifact names, that you want to supply to the Pipeline at execution time. Parameters are passed to the Pipeline from its corresponding PipelineRun and can replace template values specified within each Task in the Pipeline.

Parameter names:

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

For example, fooIs-Bar_ is a valid parameter name, but barIsBa$ or 0banana are not.

Each declared parameter has a type field, which can be set to either array or string. array is useful in cases where the number of compilation flags being supplied to the Pipeline varies throughout its execution. If no value is specified, the type field defaults to string. When the actual parameter value is supplied, its parsed type is validated against the type field. The description and default fields for a Parameter are optional.

The following example illustrates the use of Parameters in a Pipeline.

The following Pipeline declares two input parameters :

context which passes its value (a string) to the Task to set the value of the pathToContext parameter within the Task.
flags which passes its value (an array) to the Task to set the value of the flags parameter within the Task. The flags parameter within the Task must also be an array. If you specify a value for the default field and invoke this Pipeline in a PipelineRun without specifying a value for context, that value will be used.

Note: Input parameter values can be used as variables throughout the Pipeline by using variable substitution.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
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[*])"]

The following PipelineRun supplies a value for context:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun-with-parameters
spec:
  pipelineRef:
    name: pipeline-with-parameters
  params:
    - name: "context"
      value: "/workspace/examples/microservices/leeroy-web"
    - name: "flags"
      value:
        - "foo"
        - "bar"

Param enum

🌱 enum is an alpha feature. The enable-param-enum feature flag must be set to "true" to enable this feature.

Parameter declarations can include enum which is a predefine set of valid values that can be accepted by the Pipeline Param. If a Param has both enum and default value, the default value must be in the enum set. For example, the valid/allowed values for Param “message” is bounded to v1 and v2:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: pipeline-param-enum
spec:
  params:
  - name: message
    enum: ["v1", "v2"]
    default: "v1"
  tasks:
  - name: task1
    params:
      - name: message
        value: $(params.message)
    steps:
    - name: build
      image: bash:3.2
      script: |
                echo "$(params.message)"

If the Param value passed in by PipelineRun is NOT in the predefined enum list, the PipelineRun will fail with reason InvalidParamValue.

If a PipelineTask references a Task with enum, the enums specified in the Pipeline spec.params (pipeline-level enum) must be a subset of the enums specified in the referenced Task (task-level enum). An empty pipeline-level enum is invalid in this scenario since an empty enum set indicates a “universal set” which allows all possible values. The same rules apply to Pipelines with embbeded Tasks.

In the below example, the referenced Task accepts v1 and v2 as valid values, the Pipeline further restricts the valid value to v1.

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: param-enum-demo
spec:
  params:
  - name: message
    type: string
    enum: ["v1", "v2"]
  steps:
  - name: build
    image: bash:latest
    script: |
            echo "$(params.message)"

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: pipeline-param-enum
spec:
  params:
  - name: message
    enum: ["v1"]  # note that an empty enum set is invalid
  tasks:
  - name: task1
    params:
      - name: message
        value: $(params.message)
    taskRef:
      name: param-enum-demo

Note that this subset restriction only applies to the task-level params with a direct single reference to pipeline-level params. If a task-level param references multiple pipeline-level params, the subset validation is not applied.

apiVersion: tekton.dev/v1
kind: Pipeline
...
spec:
  params:
  - name: message1
    enum: ["v1"]
  - name: message2
    enum: ["v2"]
  tasks:
  - name: task1
    params:
      - name: message
        value: "$(params.message1) and $(params.message2)"
    taskSpec:
      params: message
      enum: [...] # the message enum is not required to be a subset of message1 or message2
    ...

Tekton validates user-provided values in a PipelineRun against the enum specified in the PipelineSpec.params. Tekton also validates any resolved param value against the enum specified in each PipelineTask before creating the TaskRun.

See usage in this example

Propagated Params

Like with embedded pipelineruns, you can propagate params declared in the pipeline down to the inlined pipelineTasks and its inlined Steps. Wherever a resource (e.g. a pipelineTask) or a StepAction is referenced, the parameters need to be passed explicitly.

For example, the following is a valid yaml.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: pipelien-propagated-params
spec:
  params:
    - name: HELLO
      default: "Hello World!"
    - name: BYE
      default: "Bye World!"
  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-action
            ref:
              name: step-action-echo
            params:
              - name: msg
                value: "$(params.BYE)"

The same rules defined in pipelineruns apply here.

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. For example:

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

Note: Using both apiVersion and kind will create CustomRun, don’t set apiVersion if only referring to Task.

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

Note that any task specified in taskSpec will be the same version as the Pipeline.

Specifying `displayName` in `PipelineTasks`

The displayName field is an optional field that allows you to add a user-facing name of the PipelineTask that can be used to populate and distinguish in the dashboard. For example:

spec:
  tasks:
    - name: scan
      displayName: "Code Scan"
      taskRef:
        name: sonar-scan

The displayName also allows you to parameterize the human-readable name of your choice based on the params, the task results, and the context variables. For example:

spec:
  params:
    - name: application
  tasks:
    - name: scan
      displayName: "Code Scan for $(params.application)"
      taskRef:
        name: sonar-scan
    - name: upload-scan-report
      displayName: "Upload Scan Report $(tasks.scan.results.report)"
      taskRef:
        name: upload

Specifying task results in the displayName does not introduce an inherent resource dependency among tasks. The pipeline author is responsible for specifying dependency explicitly either using runAfter or rely on whenExpressions or task results in params.

Fully resolved displayName is also available in the status as part of the pipelineRun.status.childReferences. The clients such as the dashboard, CLI, etc. can retrieve the displayName from the childReferences. The displayName mainly drives a better user experience and at the same time it is not validated for the content or length by the controller.

Specifying Remote Tasks

(beta feature)

tasks:
- name: "go-build"
  taskRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      # value can use params declared at the pipeline level or a static value like main
      value: $(params.gitRevision)
    - name: pathInRepo
      value: task/golang-build/0.3/golang-build.yaml

Specifying `Pipelines` in `PipelineTasks`

🌱 Specifying pipelines in PipelineTasks is an alpha feature. The enable-api-fields feature flag must be set to "alpha" to specify PipelineRef or PipelineSpec in a PipelineTask. This feature is in Preview Only mode and not yet supported/implemented.

Apart from taskRef and taskSpec, pipelineRef and pipelineSpec allows you to specify a pipeline in pipelineTask. This allows you to generate a child pipelineRun which is inherited by the parent pipelineRun.

kind: Pipeline
metadata:
  name: security-scans
spec:
  tasks:
    - name: scorecards
      taskSpec:
        steps:
          - image: alpine
            name: step-1
            script: |
              echo "Generating scorecard report ..."
    - name: codeql
      taskSpec:
        steps:
          - image: alpine
            name: step-1
            script: |
              echo "Generating codeql report ..."
---
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: clone-scan-notify
spec:
  tasks:
    - name: git-clone
      taskSpec:
        steps:
          - image: alpine
            name: step-1
            script: |
              echo "Cloning a repo to run security scans ..."
    - name: security-scans
      runAfter:
        - git-clone
      pipelineRef:
        name: security-scans
---

For further information read Pipelines in Pipelines

Specifying `Parameters` in `PipelineTasks`

You can also provide Parameters:

spec:
  tasks:
    - name: build-skaffold-web
      taskRef:
        name: build-push
      params:
        - name: pathToDockerFile
          value: Dockerfile
        - name: pathToContext
          value: /workspace/examples/microservices/leeroy-web

Specifying `Matrix` in `PipelineTasks`

🌱 Matrix is an beta feature. The enable-api-fields feature flag can be set to "beta" to specify Matrix in a PipelineTask.

You can also provide Parameters through the matrix field:

spec:
  tasks:
    - name: browser-test
      taskRef:
        name: browser-test
      matrix:
        params:
        - name: browser
          value:
          - chrome
          - safari
          - firefox
        include:
          - name: build-1
            params:
              - name: browser
                value: chrome
              - name: url
                value: some-url

For further information, read Matrix.

Specifying `Workspaces` in `PipelineTasks`

You can also provide Workspaces:

spec:
  tasks:
    - name: use-workspace
      taskRef:
        name: gen-code # gen-code expects a workspace with name "output"
      workspaces:
        - name: output
          workspace: shared-ws

Tekton Bundles

A Tekton Bundle is an OCI artifact that contains Tekton resources like Tasks which can be referenced within a taskRef.

There is currently a hard limit of 20 objects in a bundle.

spec:
  tasks:
    - name: hello-world
      taskRef:
        resolver: bundles
        params:
        - name: bundle
          value: docker.io/myrepo/mycatalog
        - name: name
          value: echo-task
        - name: kind
          value: Task

You may also specify a tag as you would with a Docker image which will give you a fixed, repeatable reference to a Task.

spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/myrepo/mycatalog:v1.0.1
    - name: name
      value: echo-task
    - name: kind
      value: Task

You may also specify a fixed digest instead of a tag.

spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/myrepo/mycatalog@sha256:abc123
    - name: name
      value: echo-task
    - name: kind
      value: Task

Any of the above options will fetch the image using the ImagePullSecrets attached to the ServiceAccount specified in the PipelineRun. See the Service Account section for details on how to configure a ServiceAccount on a PipelineRun. The PipelineRun will then run that Task without registering it in the cluster allowing multiple versions of the same named Task to be run at once.

Tekton Bundles may be constructed with any toolsets that produce valid OCI image artifacts so long as the artifact adheres to the contract.

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.

In the example below, we want to test the code before we build it. Since there is no output from the test-app Task, the build-app Task uses runAfter to indicate that test-app must run before it, regardless of the order in which they are referenced in the Pipeline definition.

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. When a Task fails, the corresponding TaskRun sets its Succeeded Condition to False. The retries field instructs Tekton to retry executing the Task when this happens. retries are executed even when other Tasks in the Pipeline have failed, unless the PipelineRun has been cancelled or gracefully cancelled.

If you expect a Task to encounter problems during execution (for example, you know that there will be issues with network connectivity or missing dependencies), set its retries field to a suitable value greater than 0. If you don’t explicitly specify a value, Tekton does not attempt to execute the failed Task again.

In the example below, the execution of the build-the-image Task will be retried once after a failure; if the retried execution fails, too, the Task execution fails as a whole.

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

Using the `onError` field

When a PipelineTask fails, the rest of the PipelineTasks are skipped and the PipelineRun is declared a failure. If you would like to ignore such PipelineTask failure and continue executing the rest of the PipelineTasks, you can specify onError for such a PipelineTask.

OnError can be set to stopAndFail (default) and continue. The failure of a PipelineTask with stopAndFail would stop and fail the whole PipelineRun. A PipelineTask fails with continue does not fail the whole PipelineRun, and the rest of the PipelineTask will continue to execute.

To ignore a PipelineTask failure, set onError to continue:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: demo
spec:
  tasks:
    - name: task1
      onError: continue
      taskSpec:
        steps:
          - name: step1
            image: alpine
            script: |
                            exit 1

At runtime, the failure is ignored to determine the PipelineRun status. The PipelineRun message contains the ignored failure info:

status:
  conditions:
  - lastTransitionTime: "2023-09-28T19:08:30Z"
    message: 'Tasks Completed: 1 (Failed: 1 (Ignored: 1), Cancelled 0), Skipped: 0'
    reason: Succeeded
    status: "True"
    type: Succeeded
  ...

Note that the TaskRun status remains as it is irrelevant to OnError. Failed but ignored TaskRuns result in a failed status with reason FailureIgnored.

For example, the TaskRun created by the above PipelineRun has the following status:

$ kubectl get tr demo-run-task1
NAME                                SUCCEEDED   REASON           STARTTIME   COMPLETIONTIME
demo-run-task1                      False       FailureIgnored   12m         12m

To specify onError for a step, please see specifying onError for a step.

Note: Setting Retry and OnError:continue at the same time is NOT allowed.

Produce results with `OnError`

When a PipelineTask is set to ignore error and the PipelineTask is able to initialize a result before failing, the result is made available to the consumer PipelineTasks.

  tasks:
    - name: task1
      onError: continue
      taskSpec:
        results:
          - name: result1
        steps:
          - name: step1
            image: alpine
            script: |
              echo -n 123 | tee $(results.result1.path)
              exit 1

The consumer PipelineTasks can access the result by referencing $(tasks.task1.results.result1).

If the result is NOT initialized before failing, and there is a PipelineTask consuming it:

  tasks:
    - name: task1
      onError: continue
      taskSpec:
        results:
          - name: result1
        steps:
          - name: step1
            image: alpine
            script: |
              exit 1
              echo -n 123 | tee $(results.result1.path)

If the consuming PipelineTask has OnError:stopAndFail, the PipelineRun will fail with InvalidTaskResultReference.
If the consuming PipelineTask has OnError:continue, the consuming PipelineTask will be skipped with reason Results were missing, and the PipelineRun will continue to execute.

Guard `Task` execution using `when` expressions

To run a Task only when certain conditions are met, it is possible to guard task execution using the when field. The when field allows you to list a series of references to when expressions.

The components of when expressions are input, operator and values:

Component	Description	Syntax
`input`	Input for the `when` expression, defaults to an empty string if not provided.	* Static values e.g. `"ubuntu"` * Variables (parameters or results) e.g. `"$(params.image)"` or `"$(tasks.task1.results.image)"` or `"$(tasks.task1.results.array-results[1])"`
`operator`	`operator` represents an `input`’s relationship to a set of `values`, a valid `operator` must be provided.	`in` or `notin`
`values`	An array of string values, the `values` array must be provided and has to be non-empty.	* An array param e.g. `["$(params.images[])"]` An array result of a task `["$(tasks.task1.results.array-results[])"]` `values` can contain static values e.g. `"ubuntu"` * `values` can contain variables (parameters or results) or a Workspaces’s `bound` state e.g. `["$(params.image)"]` or `["$(tasks.task1.results.image)"]` or `["$(tasks.task1.results.array-results[1])"]`

The Parameters are read from the Pipeline and Results are read directly from previous Tasks. Using Results in a when expression in a guarded Task introduces a resource dependency on the previous Task that produced the Result.

The declared when expressions are evaluated before the Task is run. If all the when expressions evaluate to True, the Task is run. If any of the when expressions evaluate to False, the Task is not run and the Task is listed in the Skipped Tasks section of the PipelineRunStatus.

In these examples, first-create-file task will only be executed if the path parameter is README.md, echo-file-exists task will only be executed if the exists result from check-file task is yes and run-lint task will only be executed if the lint-config optional workspace has been provided by a PipelineRun.

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
---
tasks:
  - name: deploy-in-blue
    when:
      - input: "blue"
        operator: in
        values: ["$(params.deployments[*])"]
    taskRef:
      name: deployment

For an end-to-end example, see PipelineRun with when expressions.

There are a lot of scenarios where when expressions can be really useful. Some of these are:

Checking if the name of a git branch matches
Checking if the Result of a previous Task is as expected
Checking if a git file has changed in the previous commits
Checking if an image exists in the registry
Checking if the name of a CI job matches
Checking if an optional Workspace has been provided

Use CEL expression in WhenExpression

🌱 CEL in WhenExpression is an alpha feature. The enable-cel-in-whenexpression feature flag must be set to "true" to enable the use of CEL in WhenExpression.

CEL (Common Expression Language) is a declarative language designed for simplicity, speed, safety, and portability which can be used to express a wide variety of conditions and computations.

You can define a CEL expression in WhenExpression to guard the execution of a Task. The CEL expression must evaluate to either true or false. You can use a single line of CEL string to replace current WhenExpressions’s input+operator+values. For example:

# current WhenExpressions
when:
  - input: "foo"
    operator: "in"
    values: ["foo", "bar"]
  - input: "duh"
    operator: "notin"
    values: ["foo", "bar"]

# with cel
when:
  - cel: "'foo' in ['foo', 'bar']"
  - cel: "!('duh' in ['foo', 'bar'])"

CEL can offer more conditional functions, such as numeric comparisons (e.g. >, <=, etc), logic operators (e.g. OR, AND), Regex Pattern Matching. For example:

  when:
    # test coverage result is larger than 90%
    - cel: "'$(tasks.unit-test.results.test-coverage)' > 0.9"
    # params is not empty, or params2 is 8.5 or 8.6
    - cel: "'$(params.param1)' != '' || '$(params.param2)' == '8.5' || '$(params.param2)' == '8.6'"
    # param branch matches pattern `release/.*`
    - cel: "'$(params.branch)'.matches('release/.*')"

Variable substitution in CEL

CEL supports string substitutions, you can reference string, array indexing or object value of a param/result. For example:

  when:
    # string result
    - cel: "$(tasks.unit-test.results.test-coverage) > 0.9"
    # array indexing result
    - cel: "$(tasks.unit-test.results.test-coverage[0]) > 0.9"
    # object result key
    - cel: "'$(tasks.objectTask.results.repo.url)'.matches('github.com/tektoncd/.*')"
    # string param
    - cel: "'$(params.foo)' == 'foo'"
    # array indexing
    - cel: "'$(params.branch[0])' == 'foo'"
    # object param key
    - cel: "'$(params.repo.url)'.matches('github.com/tektoncd/.*')"

Note: the reference needs to be wrapped with single quotes. Whole Array and Object replacements are not supported yet. The following usage is not supported:

  when:
    - cel: "'foo' in '$(params.array_params[*])'"
    - cel: "'foo' in '$(params.object_params[*])'"

In addition to the cases listed above, you can craft any valid CEL expression as defined by the cel-spec language definition

CEL expression is validated at admission webhook and a validation error will be returned if the expression is invalid.

Note: To use Tekton’s variable substitution, you need to wrap the reference with single quotes. This also means that if you pass another CEL expression via params or results, it won’t be executed. Therefore CEL injection is disallowed.

For example:

This is valid: '$(params.foo)' == 'foo'
This is invalid: $(params.foo) == 'foo'
CEL's variable substitution is not supported yet and thus invalid: params.foo == 'foo'

Guarding a `Task` and its dependent `Tasks`

To guard a Task and its dependent Tasks:

cascade the when expressions to the specific dependent Tasks to be guarded as well
compose the Task and its dependent Tasks as a unit to be guarded and executed together using Pipelines in Pipelines

Cascade `when` expressions to the specific dependent `Tasks`

Pick and choose which specific dependent Tasks to guard as well, and cascade the when expressions to those Tasks.

Taking the use case below, a user who wants to guard manual-approval and its dependent Tasks:

                                     tests
                                       |
                                       v
                                 manual-approval
                                 |            |
                                 v        (approver)
                            build-image       |
                                |             v
                                v          slack-msg
                            deploy-image

The user can design the Pipeline to solve their use case as such:

tasks:
#...
- name: manual-approval
  runAfter:
    - tests
  when:
    - input: $(params.git-action)
      operator: in
      values:
        - merge
  taskRef:
    name: manual-approval

- name: build-image
  when:
    - input: $(params.git-action)
      operator: in
      values:
        - merge
  runAfter:
    - manual-approval
  taskRef:
    name: build-image

- name: deploy-image
  when:
    - input: $(params.git-action)
      operator: in
      values:
        - merge
  runAfter:
    - build-image
  taskRef:
    name: deploy-image

- name: slack-msg
  params:
    - name: approver
      value: $(tasks.manual-approval.results.approver)
  taskRef:
    name: slack-msg

Compose using Pipelines in Pipelines

Compose a set of Tasks as a unit of execution using Pipelines in Pipelines, which allows for guarding a Task and its dependent Tasks (as a sub-Pipeline) using when expressions.

Note: Pipelines in Pipelines is an experimental feature

Taking the use case below, a user who wants to guard manual-approval and its dependent Tasks:

                                     tests
                                       |
                                       v
                                 manual-approval
                                 |            |
                                 v        (approver)
                            build-image       |
                                |             v
                                v          slack-msg
                            deploy-image

The user can design the Pipelines to solve their use case as such:

## sub pipeline (approve-build-deploy-slack)
tasks:
  - name: manual-approval
    runAfter:
      - integration-tests
    taskRef:
      name: manual-approval

  - name: build-image
    runAfter:
      - manual-approval
    taskRef:
      name: build-image

  - name: deploy-image
    runAfter:
      - build-image
    taskRef:
      name: deploy-image

  - name: slack-msg
    params:
      - name: approver
        value: $(tasks.manual-approval.results.approver)
    taskRef:
      name: slack-msg

---
## main pipeline
tasks:
#...
- name: approve-build-deploy-slack
  runAfter:
    - tests
  when:
    - input: $(params.git-action)
      operator: in
      values:
        - merge
  taskRef:
    apiVersion: tekton.dev/v1beta1
    kind: Pipeline
    name: approve-build-deploy-slack

Guarding a `Task` only

When when expressions evaluate to False, the Task will be skipped and:

The ordering-dependent Tasks will be executed
The resource-dependent Tasks (and their dependencies) will be skipped because of missing Results from the skipped parent Task. When we add support for default Results, then the resource-dependent Tasks may be executed if the default Results from the skipped parent Task are specified. In addition, if a resource-dependent Task needs a file from a guarded parent Task in a shared Workspace, make sure to handle the execution of the child Task in case the expected file is missing from the Workspace because the guarded parent Task is skipped.

On the other hand, the rest of the Pipeline will continue executing.

                                     tests
                                       |
                                       v
                                 manual-approval
                                 |            |
                                 v        (approver)
                            build-image       |
                                |             v
                                v          slack-msg
                            deploy-image

Taking the use case above, a user who wants to guard manual-approval only can design the Pipeline as such:

tasks:
#...
- name: manual-approval
  runAfter:
    - tests
  when:
    - input: $(params.git-action)
      operator: in
      values:
        - merge
  taskRef:
    name: manual-approval

- name: build-image
  runAfter:
    - manual-approval
  taskRef:
    name: build-image

- name: deploy-image
  runAfter:
    - build-image
  taskRef:
    name: deploy-image

- name: slack-msg
  params:
    - name: approver
      value: $(tasks.manual-approval.results.approver)
  taskRef:
    name: slack-msg

If manual-approval is skipped, execution of its dependent Tasks (slack-msg, build-image and deploy-image) would be unblocked regardless:

build-image and deploy-image should be executed successfully
slack-msg will be skipped because it is missing the approver Result from manual-approval
- dependents of slack-msg would have been skipped too if it had any of them
- if manual-approval specifies a default approver Result, such as “None”, then slack-msg would be executed (supporting default Results is in progress)

Configuring the failure timeout

You can use the Timeout field in the Task spec within the Pipeline to set the timeout of the TaskRun that executes that Task within the PipelineRun that executes your Pipeline. The Timeout value is a duration conforming to Go’s ParseDuration format. For example, valid values are 1h30m, 1h, 1m, and 60s.

Note: If you do not specify a Timeout value, Tekton instead honors the timeout for the PipelineRun.

Note: If the specified Task timeout is greater than the Pipeline timeout as configured in the PipelineRun, the Pipeline will time-out first causing the Task to timeout before its configured timeout. For example, if the PipelineRun sets timeouts.pipeline = 1h and the Pipeline sets tasks[0].timeout = 3h, the task will still timeout after 1h. See PipelineRun - Configuring a failure timeout for details.

Note: Task timeouts specified in the Pipeline can be overridden at runtime using the taskRunSpecs field in the PipelineRun. This provides flexibility to adjust timeouts for specific execution contexts without modifying the Pipeline definition.

In the example below, the build-the-image Task is configured to time out after 90 seconds:

spec:
  tasks:
    - name: build-the-image
      taskRef:
        name: build-push
      timeout: "0h1m30s"

Using variable substitution

Tekton provides variables to inject values into the contents of certain fields. The values you can inject come from a range of sources including other fields in the Pipeline, context-sensitive information that Tekton provides, and runtime information received from a PipelineRun.

The mechanism of variable substitution is quite simple - string replacement is performed by the Tekton Controller when a PipelineRun is executed.

See the complete list of variable substitutions for Pipelines and the list of fields that accept substitutions.

For an end-to-end example, see using context variables.

Using the `retries` and `retry-count` variable substitutions

Tekton supports variable substitution for the retries parameter of PipelineTask. Variables like context.pipelineTask.retries and context.task.retry-count can be added to the parameters of a PipelineTask. context.pipelineTask.retries will be replaced by retries of the PipelineTask, while context.task.retry-count will be replaced by current retry number of the PipelineTask.

params:
- name: pipelineTask-retries
  value: "$(context.pipelineTask.retries)"
taskSpec:
  params:
  - name: pipelineTask-retries
  steps:
  - image: ubuntu
    name: print-if-retries-exhausted
    script: |
      if [ "$(context.task.retry-count)" == "$(params.pipelineTask-retries)" ]
      then
        echo "This is the last retry."
      fi
      exit 1

Note: Every PipelineTask can only access its own retries and retry-count. These values aren’t accessible for other PipelineTasks.

Using `Results`

Tasks can emit Results when they execute. A Pipeline can use these Results for two different purposes:

A Pipeline can pass the Result of a Task into the Parameters or when expressions of another.
A Pipeline can itself emit Results and include data from the Results of its Tasks.

Note Tekton does not enforce that results are produced at Task level. If a pipeline attempts to consume a result that was declared by a Task, but not produced, it will fail. TEP-0048 propopses introducing default values for results to help Pipeline authors manage this case.

Passing one Task’s `Results` into the `Parameters` or `when` expressions of another

Sharing Results between Tasks in a Pipeline happens via variable substitution - one Task emits a Result and another receives it as a Parameter with a variable such as $(tasks.<task-name>.results.<result-name>). Pipeline support two new types of results and parameters: array []string and object map[string]string. Array result is a beta feature and can be enabled by setting enable-api-fields to alpha or beta.

Result Type	Parameter Type	Specification	`enable-api-fields`
string	string	`$(tasks.<task-name>.results.<result-name>)`	stable
array	array	`$(tasks.<task-name>.results.<result-name>[*])`	alpha or beta
array	string	`$(tasks.<task-name>.results.<result-name>[i])`	alpha or beta
object	object	`$(tasks.<task-name>.results.<result-name>[*])`	alpha or beta
object	string	`$(tasks.<task-name>.results.<result-name>.key)`	alpha or beta

Note: Whole Array and Object Results (using star notation) cannot be referred in script.

When one Task receives the Results of another, there is a dependency created between those two Tasks. In order for the receiving Task to get data from another Task's Result, the Task producing the Result must run first. Tekton enforces this Task ordering by ensuring that the Task emitting the Result executes before any Task that uses it.

In the snippet below, a param is provided its value from the commit Result emitted by the checkout-source Task. Tekton will make sure that the checkout-source Task runs before this one.

params:
  - name: foo
    value: "$(tasks.checkout-source.results.commit)"
  - name: array-params
    value: "$(tasks.checkout-source.results.array-results[*])"
  - name: array-indexing-params
    value: "$(tasks.checkout-source.results.array-results[1])"
  - name: object-params
    value: "$(tasks.checkout-source.results.object-results[*])"
  - name: object-element-params
    value: "$(tasks.checkout-source.results.object-results.objectkey)"

Note: If checkout-source exits successfully without initializing commit Result, the receiving Task fails and causes the Pipeline to fail with InvalidTaskResultReference:

unable to find result referenced by param 'foo' in 'task';: Could not find result with name 'commit' for task run 'checkout-source'

In the snippet below, a when expression is provided its value from the exists Result emitted by the check-file Task. Tekton will make sure that the check-file Task runs before this one.

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

For an end-to-end example, see Task Results in a PipelineRun.

Note that when expressions are whitespace-sensitive. In particular, when producing results intended for inputs to when expressions that may include newlines at their close (e.g. cat, jq), you may wish to truncate them.

taskSpec:
  params:
  - name: jsonQuery-check
  steps:
  - image: ubuntu
    name: store-name-in-results
    script: |
            curl -s https://my-json-server.typicode.com/typicode/demo/profile | jq -r .name | tr -d '\n' | tee $(results.name.path)

Emitting `Results` from a `Pipeline`

A Pipeline can emit Results of its own for a variety of reasons - an external system may need to read them when the Pipeline is complete, they might summarise the most important Results from the Pipeline's Tasks, or they might simply be used to expose non-critical messages generated during the execution of the Pipeline.

A Pipeline's Results can be composed of one or many Task Results emitted during the course of the Pipeline's execution. A Pipeline Result can refer to its Tasks' Results using a variable of the form $(tasks.<task-name>.results.<result-name>).

After a Pipeline has executed the PipelineRun will be populated with the Results emitted by the Pipeline. These will be written to the PipelineRun's status.pipelineResults field.

In the example below, the Pipeline specifies a results entry with the name sum that references the outputValue Result emitted by the calculate-sum Task.

results:
  - name: sum
    description: the sum of all three operands
    value: $(tasks.calculate-sum.results.outputValue)

For an end-to-end example, see Results in a PipelineRun.

In the example below, the Pipeline collects array and object results from Tasks.

    results:
      - name: array-results
        type: array
        description: whole array
        value: $(tasks.task1.results.array-results[*])
      - name: array-indexing-results
        type: string
        description: array element
        value: $(tasks.task1.results.array-results[1])
      - name: object-results
        type: object
        description: whole object
        value: $(tasks.task2.results.object-results[*])
      - name: object-element
        type: string
        description: object element
        value: $(tasks.task2.results.object-results.foo)

For an end-to-end example see Array and Object Results in a PipelineRun.

A Pipeline Result is not emitted if any of the following are true:

A PipelineTask referenced by the Pipeline Result failed. The PipelineRun will also have failed.
A PipelineTask referenced by the Pipeline Result was skipped.
A PipelineTask referenced by the Pipeline Result didn’t emit the referenced Task Result. This should be considered a bug in the Task and may fail a PipelineTask in future.
The Pipeline Result uses a variable that doesn’t point to an actual PipelineTask. This will result in an InvalidTaskResultReference validation error during PipelineRun execution.
The Pipeline Result uses a variable that doesn’t point to an actual result in a PipelineTask. This will cause an InvalidTaskResultReference validation error during PipelineRun execution.

Note: Since a Pipeline Result can contain references to multiple Task Results, if any of those Task Result references are invalid the entire Pipeline Result is not emitted. Note: If a PipelineTask referenced by the Pipeline Result was skipped, the Pipeline Result will not be emitted and the PipelineRun will not fail due to a missing result.

Configuring the `Task` execution order

You can connect Tasks in a Pipeline so that they execute in a Directed Acyclic Graph (DAG). Each Task in the Pipeline becomes a node on the graph that can be connected with an edge so that one will run before another and the execution of the Pipeline progresses to completion without getting stuck in an infinite loop.

This is done using:

resource dependencies:
- results of one Task being passed into params or when expressions of another
ordering dependencies:
- runAfter clauses on the corresponding Tasks

For example, the Pipeline defined as follows

tasks:
- name: lint-repo
  taskRef:
    name: pylint
- name: test-app
  taskRef:
    name: make-test
- name: build-app
  taskRef:
    name: kaniko-build-app
  runAfter:
    - test-app
- name: build-frontend
  taskRef:
    name: kaniko-build-frontend
  runAfter:
    - test-app
- name: deploy-all
  taskRef:
    name: deploy-kubectl
  runAfter:
    - build-app
    - build-frontend

executes according to the following graph:

        |            |
        v            v
     test-app    lint-repo
    /        \
   v          v
build-app  build-frontend
   \          /
    v        v
    deploy-all

In particular:

The lint-repo and test-app Tasks have no runAfter clauses and start executing simultaneously.
Once test-app completes, both build-app and build-frontend start executing simultaneously since they both runAfter the test-app Task.
The deploy-all Task executes once both build-app and build-frontend complete, since it is supposed to runAfter them both.
The entire Pipeline completes execution once both lint-repo and deploy-all complete execution.

Specifying a display name

The displayName field is an optional field that allows you to add a user-facing name of the Pipeline that can be used to populate a UI. For example:

spec:
  displayName: "Code Scan"
  tasks:
    - name: scan
      taskRef:
        name: sonar-scan

Adding a description

The description field is an optional field and can be used to provide description of the Pipeline.

Adding `Finally` to the `Pipeline`

You can specify a list of one or more final tasks under finally section. finally tasks are guaranteed to be executed in parallel after all PipelineTasks under tasks have completed regardless of success or error. finally tasks are very similar to PipelineTasks under tasks section and follow the same syntax. Each finally task must have a valid name and a taskRef or taskSpec. For example:

spec:
  tasks:
    - name: tests
      taskRef:
        name: integration-test
  finally:
    - name: cleanup-test
      taskRef:
        name: cleanup

Specifying `displayName` in `finally` tasks

Similar to specifying displayName in pipelineTasks, finally tasks also allows to add a user-facing name of the finally task that can be used to populate and distinguish in the dashboard. For example:

spec:
  finally:
    - name: notification
      displayName: "Notify"
      taskRef:
        name: notification
    - name: notification-using-context-variable
      displayName: "Notification from $(context.pipeline.name)"
      taskRef:
        name: notification

The displayName also allows you to parameterize the human-readable name of your choice based on the params, the task results, and the context variables.

Specifying `Workspaces` in `finally` tasks

finally tasks can specify workspaces which PipelineTasks might have utilized e.g. a mount point for credentials held in Secrets. To support that requirement, you can specify one or more Workspaces in the workspaces field for the finally tasks similar to tasks.

spec:
  workspaces:
    - name: shared-workspace
  tasks:
    - name: clone-app-source
      taskRef:
        name: clone-app-repo-to-workspace
      workspaces:
        - name: shared-workspace
          workspace: shared-workspace
  finally:
    - name: cleanup-workspace
      taskRef:
        name: cleanup-workspace
      workspaces:
        - name: shared-workspace
          workspace: shared-workspace

Specifying `Parameters` in `finally` tasks

Similar to tasks, you can specify Parameters in finally tasks:

spec:
  tasks:
    - name: tests
      taskRef:
        name: integration-test
  finally:
    - name: report-results
      taskRef:
        name: report-results
      params:
        - name: url
          value: "someURL"

Specifying `matrix` in `finally` tasks

🌱 Matrix is an beta feature. The enable-api-fields feature flag can be set to "beta" to specify Matrix in a PipelineTask.

Similar to tasks, you can also provide Parameters through matrix in finally tasks:

spec:
  tasks:
    - name: tests
      taskRef:
        name: integration-test
  finally:
    - name: report-results
      taskRef:
        name: report-results
      params:
        - name: url
          value: "someURL"
      matrix:
        params:
        - name: slack-channel
          value:
          - "foo"
          - "bar"
        include:
          - name: build-1
            params:
              - name: slack-channel
                value: "foo"
              - name: flags
                value: "-v"

For further information, read Matrix.

Consuming `Task` execution results in `finally`

finally tasks can be configured to consume Results of PipelineTask from the tasks section:

spec:
  tasks:
    - name: clone-app-repo
      taskRef:
        name: git-clone
  finally:
    - name: discover-git-commit
      params:
        - name: commit
          value: $(tasks.clone-app-repo.results.commit)

Note: The scheduling of such finally task does not change, it will still be executed in parallel with other finally tasks after all non-finally tasks are done.

The controller resolves task results before executing the finally task discover-git-commit. If the task clone-app-repo failed before initializing commit or skipped with when expression resulting in uninitialized task result commit, the finally Task discover-git-commit will be included in the list of skippedTasks and continues executing rest of the finally tasks. The pipeline exits with completion instead of success if a finally task is added to the list of skippedTasks.

Consuming `Pipeline` result with `finally`

finally tasks can emit Results and these results emitted from the finally tasks can be configured in the Pipeline Results. References of Results from finally will follow the same naming conventions as referencing Results from tasks: $(finally.<finally-pipelinetask-name>.result.<result-name>).

results:
  - name: comment-count-validate
    value: $(finally.check-count.results.comment-count-validate)
finally:
  - name: check-count
    taskRef:
      name: example-task-name

In this example, pipelineResults in status will show the name-value pair for the result comment-count-validate which is produced in the Task example-task-name.

`PipelineRun` Status with `finally`

With finally, PipelineRun status is calculated based on PipelineTasks under tasks section and finally tasks.

Without finally:

`PipelineTasks` under `tasks`	`PipelineRun` status	Reason
all `PipelineTasks` successful	`true`	`Succeeded`
one or more `PipelineTasks` skipped and rest successful	`true`	`Completed`
single failure of `PipelineTask`	`false`	`failed`

With finally:

`PipelineTasks` under `tasks`	`finally` tasks	`PipelineRun` status	Reason
all `PipelineTask` successful	all `finally` tasks successful	`true`	`Succeeded`
all `PipelineTask` successful	one or more failure of `finally` tasks	`false`	`Failed`
one or more `PipelineTask` skipped and rest successful	all `finally` tasks successful	`true`	`Completed`
one or more `PipelineTask` skipped and rest successful	one or more failure of `finally` tasks	`false`	`Failed`
single failure of `PipelineTask`	all `finally` tasks successful	`false`	`failed`
single failure of `PipelineTask`	one or more failure of `finally` tasks	`false`	`failed`

Overall, PipelineRun state transitioning is explained below for respective scenarios:

All PipelineTask and finally tasks are successful: Started -> Running -> Succeeded
At least one PipelineTask skipped and rest successful: Started -> Running -> Completed
One PipelineTask failed / one or more finally tasks failed: Started -> Running -> Failed

Please refer to the table under Monitoring Execution Status to learn about what kind of events are triggered based on the Pipelinerun status.

Using Execution `Status` of `pipelineTask`

A pipeline can check the status of a specific pipelineTask from the tasks section in finally through the task parameters:

finally:
  - name: finaltask
    params:
      - name: task1Status
        value: "$(tasks.task1.status)"
    taskSpec:
      params:
        - name: task1Status
      steps:
        - image: ubuntu
          name: print-task-status
          script: |
            if [ $(params.task1Status) == "Failed" ]
            then
              echo "Task1 has failed, continue processing the failure"
            fi

This kind of variable can have any one of the values from the following table:

Status	Description
`Succeeded`	`taskRun` for the `pipelineTask` completed successfully
`Failed`	`taskRun` for the `pipelineTask` completed with a failure or cancelled by the user
`None`	the `pipelineTask` has been skipped or no execution information available for the `pipelineTask`

For an end-to-end example, see status in a PipelineRun.

Using Aggregate Execution `Status` of All `Tasks`

A pipeline can check an aggregate status of all the tasks section in finally through the task parameters:

finally:
  - name: finaltask
    params:
      - name: aggregateTasksStatus
        value: "$(tasks.status)"
    taskSpec:
      params:
        - name: aggregateTasksStatus
      steps:
        - image: ubuntu
          name: check-task-status
          script: |
            if [ $(params.aggregateTasksStatus) == "Failed" ]
            then
              echo "Looks like one or more tasks returned failure, continue processing the failure"
            fi

This kind of variable can have any one of the values from the following table:

Status	Description
`Succeeded`	all `tasks` have succeeded
`Failed`	one ore more `tasks` failed
`Completed`	all `tasks` completed successfully including one or more skipped tasks
`None`	no aggregate execution status available (i.e. none of the above), one or more `tasks` could be pending/running/cancelled/timedout

For an end-to-end example, see $(tasks.status) usage in a Pipeline.

Guard `finally` `Task` execution using `when` expressions

Similar to Tasks, finally Tasks can be guarded using when expressions that operate on static inputs or variables. Like in Tasks, when expressions in finally Tasks can operate on Parameters and Results. Unlike in Tasks, when expressions in finally tasks can also operate on the Execution Status of Tasks.

`when` expressions using `Parameters` in `finally` `Tasks`

when expressions in finally Tasks can utilize Parameters as demonstrated using golang-build and send-to-channel-slack Catalog Tasks:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pipelinerun-
spec:
  pipelineSpec:
    params:
      - name: enable-notifications
        type: string
        description: a boolean indicating whether the notifications should be sent
    tasks:
      - name: golang-build
        taskRef:
          name: golang-build
      # […]
    finally:
      - name: notify-build-failure # executed only when build task fails and notifications are enabled
        when:
          - input: $(tasks.golang-build.status)
            operator: in
            values: ["Failed"]
          - input: $(params.enable-notifications)
            operator: in
            values: ["true"]
        taskRef:
          name: send-to-slack-channel
      # […]
  params:
    - name: enable-notifications
      value: true

`when` expressions using `Results` in `finally` ‘Tasks`

when expressions in finally tasks can utilize Results, as demonstrated using git-clone and github-add-comment Catalog Tasks:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pipelinerun-
spec:
  pipelineSpec:
    tasks:
      - name: git-clone
        taskRef:
          name: git-clone
      - name: go-build
      # […]
    finally:
      - name: notify-commit-sha # executed only when commit sha is not the expected sha
        when:
          - input: $(tasks.git-clone.results.commit)
            operator: notin
            values: [$(params.expected-sha)]
        taskRef:
          name: github-add-comment
      # […]
  params:
    - name: expected-sha
      value: 54dd3984affab47f3018852e61a1a6f9946ecfa

If the when expressions in a finally task use Results from a skipped or failed non-finally Tasks, then the finally task would also be skipped and be included in the list of Skipped Tasks in the Status, similarly to when using Results in other parts of the finally task.

`when` expressions using `Execution Status` of `PipelineTask` in `finally` `tasks`

when expressions in finally tasks can utilize Execution Status of PipelineTasks, as demonstrated using golang-build and send-to-channel-slack Catalog Tasks:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pipelinerun-
spec:
  pipelineSpec:
    tasks:
      - name: golang-build
        taskRef:
          name: golang-build
      # […]
    finally:
      - name: notify-build-failure # executed only when build task fails
        when:
          - input: $(tasks.golang-build.status)
            operator: in
            values: ["Failed"]
        taskRef:
          name: send-to-slack-channel
      # […]

For an end-to-end example, see PipelineRun with when expressions.

`when` expressions using `Aggregate Execution Status` of `Tasks` in `finally` `tasks`

when expressions in finally tasks can utilize Aggregate Execution Status of Tasks as demonstrated:

finally:
  - name: notify-any-failure # executed only when one or more tasks fail
    when:
      - input: $(tasks.status)
        operator: in
        values: ["Failed"]
    taskRef:
      name: notify-failure

For an end-to-end example, see PipelineRun with when expressions.

Known Limitations

Cannot configure the `finally` task execution order

It’s not possible to configure or modify the execution order of the finally tasks. Unlike Tasks in a Pipeline, all finally tasks run simultaneously and start executing once all PipelineTasks under tasks have settled which means no runAfter can be specified in finally tasks.

Using Custom Tasks

Custom Tasks have been promoted from v1alpha1 to v1beta1. Starting from v0.43.0 to v0.46.0, Pipeline Controller is able to create either v1alpha1 or v1beta1 Custom Task gated by a feature flag custom-task-version, defaulting to v1beta1. You can set custom-task-version to v1alpha1 or v1beta1 to control which version to create.

Starting from v0.47.0, feature flag custom-task-version is removed and only v1beta1 Custom Task will be supported. See the migration doc for details.

Custom Tasks can implement behavior that doesn’t correspond directly to running a workload in a Pod on the cluster. For example, a custom task might execute some operation outside of the cluster and wait for its execution to complete.

A PipelineRun starts a custom task by creating a CustomRun instead of a TaskRun. In order for a custom task to execute, there must be a custom task controller running on the cluster that is responsible for watching and updating CustomRuns which reference their type.

Specifying the target Custom Task

To specify the custom task type you want to execute, the taskRef field must include the custom task’s apiVersion and kind as shown below. Using apiVersion will always create a CustomRun. If apiVersion is set, kind is required as well.

spec:
  tasks:
    - name: run-custom-task
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example

This creates a Run/CustomRun of a custom task of type Example in the example.dev API group with the version v1alpha1.

Validation error will be returned if apiVersion or kind is missing.

You can also specify the name of a custom task resource object previously defined in the cluster.

spec:
  tasks:
    - name: run-custom-task
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample

If the taskRef specifies a name, the custom task controller should look up the Example resource with that name and use that object to configure the execution.

If the taskRef does not specify a name, the custom task controller might support some default behavior for executing unnamed tasks.

Specifying a Custom Task Spec in-line (or embedded)

For v1alpha1.Run

spec:
  tasks:
    - name: run-custom-task
      taskSpec:
        apiVersion: example.dev/v1alpha1
        kind: Example
        spec:
          field1: value1
          field2: value2

For v1beta1.CustomRun

spec:
  tasks:
    - name: run-custom-task
      taskSpec:
        apiVersion: example.dev/v1alpha1
        kind: Example
        customSpec:
          field1: value1
          field2: value2

If the custom task controller supports the in-line or embedded task spec, this will create a Run/CustomRun of a custom task of type Example in the example.dev API group with the version v1alpha1.

If the taskSpec is not supported, the custom task controller should produce proper validation errors.

Please take a look at the developer guide for custom controllers supporting taskSpec:

taskSpec support for pipelineRun was designed and discussed in TEP-0061

Specifying parameters

If a custom task supports parameters, you can use the params field to specify their values:

spec:
  tasks:
    - name: run-custom-task
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample
      params:
        - name: foo
          value: bah

Context Variables

The Parameters in the Params field will accept context variables that will be substituted, including:

PipelineRun name, namespace and uid
Pipeline name
PipelineTask retries

spec:
  tasks:
    - name: run-custom-task
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample
      params:
        - name: foo
          value: $(context.pipeline.name)

Specifying matrix

🌱 Matrix is an alpha feature. The enable-api-fields feature flag must be set to "alpha" to specify Matrix in a PipelineTask.

If a custom task supports parameters, you can use the matrix field to specify their values, if you want to fan:

spec:
  tasks:
    - name: run-custom-task
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample
      params:
        - name: foo
          value: bah
      matrix:
        params:
        - name: bar
          value:
            - qux
            - thud
        include:
          - name: build-1
            params:
            - name: common-package
              value: path-to-common-pkg

For further information, read Matrix.

Specifying workspaces

If the custom task supports it, you can provide Workspaces to share data with the custom task.

spec:
  tasks:
    - name: run-custom-task
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample
      workspaces:
        - name: my-workspace

Consult the documentation of the custom task that you are using to determine whether it supports workspaces and how to name them.

Using `Results`

If the custom task produces results, you can reference them in a Pipeline using the normal syntax, $(tasks.<task-name>.results.<result-name>).

Specifying `Timeout`

`v1alpha1.Run`

If the custom task supports it as we recommended, you can provide timeout to specify the maximum running time of a CustomRun (including all retry attempts or other operations).

`v1beta1.CustomRun`

If the custom task supports it as we recommended, you can provide timeout to specify the maximum running time of one CustomRun execution.

spec:
  tasks:
    - name: run-custom-task
      timeout: 2s
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample

Consult the documentation of the custom task that you are using to determine whether it supports Timeout.

Specifying `Retries`

If the custom task supports it, you can provide retries to specify how many times you want to retry the custom task.

spec:
  tasks:
    - name: run-custom-task
      retries: 2
      taskRef:
        apiVersion: example.dev/v1alpha1
        kind: Example
        name: myexample

Consult the documentation of the custom task that you are using to determine whether it supports Retries.

Known Custom Tasks

We try to list as many known Custom Tasks as possible here so that users can easily find what they want. Please feel free to share the Custom Task you implemented in this table.

v1beta1.CustomRun

Custom Task	Description
Wait Task Beta	Waits a given amount of time before succeeding, specified by an input parameter named duration. Support `timeout` and `retries`.
Approvals	Pauses the execution of `PipelineRuns` and waits for manual approvals. Version 0.6.0 and up.

v1alpha1.Run

Custom Task	Description
Pipeline Loops	Runs a `Pipeline` in a loop with varying `Parameter` values.
Common Expression Language	Provides Common Expression Language support in Tekton Pipelines.
Wait	Waits a given amount of time, specified by a `Parameter` named “duration”, before succeeding.
Approvals	Pauses the execution of `PipelineRuns` and waits for manual approvals. Version up to (and including) 0.5.0
Pipelines in Pipelines	Defines and executes a `Pipeline` in a `Pipeline`.
Task Group	Groups `Tasks` together as a `Task`.
Pipeline in a Pod	Runs `Pipeline` in a `Pod`.

Code examples

For a better understanding of Pipelines, study our code examples.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

PipelineRuns

PipelineRuns

Overview

A PipelineRun allows you to instantiate and execute a Pipeline on-cluster. 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.

Note: 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.

Configuring a `PipelineRun`

A PipelineRun definition supports the following fields:

Required:
- apiVersion - Specifies the API version. For example tekton.dev/v1beta1.
- kind - Indicates that this resource object is a PipelineRun object.
- metadata - Specifies the metadata that uniquely identifies the PipelineRun object. For example, a name.
- spec - Specifies the configuration information for this PipelineRun object.
  - pipelineRef or pipelineSpec - Specifies the target Pipeline.
Optional:
- params - Specifies the desired execution parameters for the Pipeline.
- serviceAccountName - Specifies a ServiceAccount object that supplies specific execution credentials for the Pipeline.
- status - Specifies options for cancelling a PipelineRun.
- taskRunSpecs - Specifies a list of PipelineTaskRunSpec which allows for setting ServiceAccountName, Pod template, and Metadata for each task. This overrides the Pod template set for the entire Pipeline.
- timeout - Specifies the timeout before the PipelineRun fails. timeout is deprecated and will eventually be removed, so consider using timeouts instead.
- timeouts - Specifies the timeout before the PipelineRun fails. timeouts allows more granular timeout configuration, at the pipeline, tasks, and finally levels
- podTemplate - Specifies a Pod template to use as the basis for the configuration of the Pod that executes each Task.
- workspaces - Specifies a set of workspace bindings which must match the names of workspaces declared in the pipeline being used.
- managedBy - Specifies the controller responsible for managing this PipelineRun’s lifecycle.

Specifying the target `Pipeline`

You must specify the target Pipeline that you want the PipelineRun to execute, either by referencing an existing Pipeline definition, or embedding a Pipeline definition directly in the PipelineRun.

To specify the target Pipeline by reference, use the pipelineRef field:

spec:
  pipelineRef:
    name: mypipeline

To embed a Pipeline definition in the PipelineRun, use the pipelineSpec field:

spec:
  pipelineSpec:
    tasks:
      - name: task1
        taskRef:
          name: mytask

The Pipeline in the pipelineSpec example example displays morning and evening greetings. Once you create and execute it, you can check the logs for its Pods:

kubectl logs $(kubectl get pods -o name | grep pipelinerun-echo-greetings-echo-good-morning)
Good Morning, Bob!

kubectl logs $(kubectl get pods -o name | grep pipelinerun-echo-greetings-echo-good-night)
Good Night, Bob!

You can also embed a Task definition the embedded Pipeline definition:

spec:
  pipelineSpec:
    tasks:
      - name: task1
        taskSpec:
          steps: ...

In the taskSpec in pipelineSpec example it’s Tasks all the way down!

You can also specify labels and annotations with taskSpec which are propagated to each taskRun and then to the respective pods. These labels can be used to identify and filter pods for further actions (such as collecting pod metrics, and cleaning up completed pod with certain labels, etc) even being part of one single Pipeline.

spec:
  pipelineSpec:
    tasks:
      - name: task1
        taskSpec:
          metadata:
            labels:
              pipeline-sdk-type: kfp
        # ...
      - name: task2
        taskSpec:
          metadata:
            labels:
              pipeline-sdk-type: tfx
        # ...

Tekton Bundles

A Tekton Bundle is an OCI artifact that contains Tekton resources like Tasks which can be referenced within a taskRef.

spec:
  pipelineRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/myrepo/mycatalog:v1.0
    - name: name
      value: mypipeline
    - name: kind
      value: Pipeline

The syntax and caveats are similar to using Tekton Bundles for Task references in Pipelines or TaskRuns.

Tekton Bundles may be constructed with any toolsets that produce valid OCI image artifacts so long as the artifact adheres to the contract.

Remote Pipelines

(beta feature)

A pipelineRef field may specify a Pipeline in a remote location such as git. Support for specific types of remote will depend on the Resolvers your cluster’s operator has installed. For more information including a tutorial, please check resolution docs. The below example demonstrates referencing a Pipeline in git:

spec:
  pipelineRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      value: abc123
    - name: pathInRepo
      value: /pipeline/buildpacks/0.1/buildpacks.yaml

Specifying Task-level `ComputeResources`

(alpha only)

Task-level compute resources can be configured in PipelineRun.TaskRunSpecs.ComputeResources or TaskRun.ComputeResources.

e.g.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: pipeline
spec:
  tasks:
    - name: task
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun
spec:
  pipelineRef:
    name: pipeline
  taskRunSpecs:
    - pipelineTaskName: task
      computeResources:
        requests:
          cpu: 2

Further details and examples could be found in Compute Resources in Tekton.

Specifying `Parameters`

You can specify Parameters that you want to pass to the Pipeline during execution, including different values of the same parameter for different Tasks in the Pipeline.

Note: 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.

For example:

spec:
  params:
    - name: pl-param-x
      value: "100"
    - name: pl-param-y
      value: "500"

You can pass in extra Parameters if needed depending on your use cases. An example use case is when your CI system autogenerates PipelineRuns and it has Parameters it wants to provide to all PipelineRuns. Because you can pass in extra Parameters, you don’t have to go through the complexity of checking each Pipeline and providing only the required params.

Parameter Enums

🌱 enum is an alpha feature. The enable-param-enum feature flag must be set to "true" to enable this feature.

If a Parameter is guarded by Enum in the Pipeline, you can only provide Parameter values in the PipelineRun that are predefined in the Param.Enum in the Pipeline. The PipelineRun will fail with reason InvalidParamValue otherwise.

Tekton will also the validate the param values passed to any referenced Tasks (via taskRef) if Enum is specified for the Task. The PipelineRun will fail with reason InvalidParamValue if Enum validation is failed for any of the PipelineTask.

You can also specify Enum in an embedded Pipeline in a PipelineRun. The same Param validation will be executed in this scenario.

See more details in Param.Enum.

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. This allows authors to simplify specs by automatically propagating top-level parameters down to other inlined resources.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
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)"

On executing the pipeline run, the parameters will be interpolated during resolution. The specifications are not mutated before storage and so it remains the same. The status is updated.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pr-echo-szzs9
  ...
spec:
  params:
  - name: HELLO
    value: Hello World!
  - name: BYE
    value: Bye World!
  pipelineSpec:
    tasks:
    - name: echo-hello
      taskSpec:
        steps:
        - image: ubuntu
          name: echo
          script: |
            #!/usr/bin/env bash
            echo "$(params.HELLO)"            
    - name: echo-bye
      taskSpec:
        steps:
        - image: ubuntu
          name: echo
          script: |
            #!/usr/bin/env bash
            echo "$(params.BYE)"            
status:
  conditions:
  - lastTransitionTime: "2022-04-07T12:34:58Z"
    message: 'Tasks Completed: 2 (Failed: 0, Canceled 0), Skipped: 0'
    reason: Succeeded
    status: "True"
    type: Succeeded
  pipelineSpec:
    ...
  childReferences:
  - name: pr-echo-szzs9-echo-hello
    pipelineTaskName: echo-hello
    kind: TaskRun
  - name: pr-echo-szzs9-echo-bye
    pipelineTaskName: echo-bye
    kind: TaskRun

Scope and Precedence

When Parameters names conflict, the inner scope would take precedence as shown in this example:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pr-echo-
spec:
  params:
  - name: HELLO
    value: "Hello World!"
  - name: BYE
    value: "Bye World!"
  pipelineSpec:
    tasks:
      - name: echo-hello
        params:
        - name: HELLO
          value: "Sasa World!"
        taskSpec:
          params:
            - name: HELLO
              type: string
          steps:
            - name: echo
              image: ubuntu
              script: |
                #!/usr/bin/env bash
                echo "$(params.HELLO)"                
    ...

resolves to

# Successful execution of the above PipelineRun
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pr-echo-szzs9
  ...
spec:
  ...
status:
  conditions:
    - lastTransitionTime: "2022-04-07T12:34:58Z"
      message: 'Tasks Completed: 2 (Failed: 0, Canceled 0), Skipped: 0'
      reason: Succeeded
      status: "True"
      type: Succeeded
  ...
  childReferences:
  - name: pr-echo-szzs9-echo-hello
    pipelineTaskName: echo-hello
    kind: TaskRun
  ...

Default Values

When Parameter specifications have default values, the Parameter value provided at runtime would take precedence to give users control, as shown in this example:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pr-echo-
spec:
  params:
  - name: HELLO
    value: "Hello World!"
  - name: BYE
    value: "Bye World!"
  pipelineSpec:
    tasks:
      - name: echo-hello
        taskSpec:
          params:
          - name: HELLO
            type: string
            default: "Sasa World!"
          steps:
            - name: echo
              image: ubuntu
              script: |
                #!/usr/bin/env bash
                echo "$(params.HELLO)"                
    ...

resolves to

# Successful execution of the above PipelineRun
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pr-echo-szzs9
  ...
spec:
  ...
status:
  conditions:
    - lastTransitionTime: "2022-04-07T12:34:58Z"
      message: 'Tasks Completed: 2 (Failed: 0, Canceled 0), Skipped: 0'
      reason: Succeeded
      status: "True"
      type: Succeeded
  ...
  childReferences:
  - name: pr-echo-szzs9-echo-hello
    pipelineTaskName: echo-hello
    kind: TaskRun
  ...

Referenced Resources

When a PipelineRun definition has referenced specifications but does not explicitly pass Parameters, the PipelineRun will be created but the execution will fail because of missing Parameters.

# Invalid PipelineRun attempting to propagate Parameters to referenced Tasks
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pr-echo-
spec:
  params:
  - name: HELLO
    value: "Hello World!"
  - name: BYE
    value: "Bye World!"
  pipelineSpec:
    tasks:
      - name: echo-hello
        taskRef:
          name: echo-hello
      - name: echo-bye
        taskRef:
          name: echo-bye
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: echo-hello
spec:
  steps:
    - name: echo
      image: ubuntu
      script: |
        #!/usr/bin/env bash
        echo "$(params.HELLO)"        
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: echo-bye
spec:
  steps:
    - name: echo
      image: ubuntu
      script: |
        #!/usr/bin/env bash
        echo "$(params.BYE)"

Fails as follows:

# Failed execution of the above PipelineRun
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pr-echo-24lmf
  ...
spec:
  params:
  - name: HELLO
    value: Hello World!
  - name: BYE
    value: Bye World!
  pipelineSpec:
    tasks:
    - name: echo-hello
      taskRef:
        kind: Task
        name: echo-hello
    - name: echo-bye
      taskRef:
        kind: Task
        name: echo-bye
status:
  conditions:
  - lastTransitionTime: "2022-04-07T20:24:51Z"
    message: 'invalid input params for task echo-hello: missing values for
              these params which have no default values: [HELLO]'
    reason: PipelineValidationFailed
    status: "False"
    type: Succeeded
  ...

Object Parameters

When using an inlined spec, object parameters from the parent PipelineRun will also be propagated to any inlined specs without needing to be explicitly defined. This allows authors to simplify specs by automatically propagating top-level parameters down to other inlined resources. When propagating object parameters, scope and precedence also holds as shown below.

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: pipelinerun-object-param-result
spec:
  params:
    - name: gitrepo
      value:
        url: abc.com
        commit: sha123
  pipelineSpec:
    tasks:
      - name: task1
        params:
          - name: gitrepo
            value:
              branch: main
              url: xyz.com
        taskSpec:
          steps:
            - name: write-result
              image: bash
              args: [
                "echo",
                "--url=$(params.gitrepo.url)",
                "--commit=$(params.gitrepo.commit)",
                "--branch=$(params.gitrepo.branch)",
              ]

resolves to

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun-object-param-resultpxp59
  ...
spec:
  params:
  - name: gitrepo
    value:
      commit: sha123
      url: abc.com
  pipelineSpec:
    tasks:
    - name: task1
      params:
      - name: gitrepo
        value:
          branch: main
          url: xyz.com
      taskSpec:
        metadata: {}
        spec: null
        steps:
        - args:
          - echo
          - --url=$(params.gitrepo.url)
          - --commit=$(params.gitrepo.commit)
          - --branch=$(params.gitrepo.branch)
          image: bash
          name: write-result
status:
  completionTime: "2022-09-08T17:22:01Z"
  conditions:
  - lastTransitionTime: "2022-09-08T17:22:01Z"
    message: 'Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 0'
    reason: Succeeded
    status: "True"
    type: Succeeded
  pipelineSpec:
    tasks:
    - name: task1
      params:
      - name: gitrepo
        value:
          branch: main
          url: xyz.com
      taskSpec:
        metadata: {}
        spec: null
        steps:
        - args:
          - echo
          - --url=xyz.com
          - --commit=sha123
          - --branch=main
          image: bash
          name: write-result
  startTime: "2022-09-08T17:21:57Z"
  childReferences:
  - name: pipelinerun-object-param-resultpxp59-task1
    pipelineTaskName: task1
    kind: TaskRun
          ...
	taskSpec:
          steps:
          - args:
            - echo
            - --url=xyz.com
            - --commit=sha123
            - --branch=main
            image: bash
            name: write-result

Specifying custom `ServiceAccount` credentials

You can execute the Pipeline in your PipelineRun with a specific set of credentials by specifying a ServiceAccount object name in the serviceAccountName field in your PipelineRun definition. If you do not explicitly specify this, the TaskRuns created by your PipelineRun will execute with the credentials specified in the configmap-defaults ConfigMap. If this default is not specified, the TaskRuns will execute with the default service account set for the target namespace.

For more information, see ServiceAccount.

Note: When using Affinity Assistants, the Affinity Assistant pods automatically inherit the serviceAccountName specified here, ensuring proper permissions in security-restricted environments like OpenShift. See Affinity Assistant ServiceAccount Configuration for details.

Custom tasks may or may not use a service account name. Consult the documentation of the custom task that you are using to determine whether it supports a service account name.

Mapping `ServiceAccount` credentials to `Tasks`

If you require more granularity in specifying execution credentials, use the taskRunSpecs[].taskServiceAccountName field to map a specific serviceAccountName value to a specific Task in the Pipeline. This overrides the global serviceAccountName you may have set for the Pipeline as described in the previous section.

For example, if you specify these mappings:

v1
v1beta1

spec:
  taskRunTemplate:
    serviceAccountName: sa-1
  taskRunSpecs:
    - pipelineTaskName: build-task
      serviceAccountName: sa-for-build

spec:
  serviceAccountName: sa-1
  taskRunSpecs:
    - pipelineTaskName: build-task
      taskServiceAccountName: sa-for-build

for this Pipeline:

kind: Pipeline
spec:
  tasks:
    - name: build-task
      taskRef:
        name: build-push
    - name: test-task
      taskRef:
        name: test

then test-task will execute using the sa-1 account while build-task will execute with sa-for-build.

Propagated Results

When using an embedded spec, Results from the parent PipelineRun will be propagated to any inlined specs without needing to be explicitly defined. This allows authors to simplify specs by automatically propagating top-level results down to other inlined resources. Result substitutions will only be made for name, commands, args, env and script fields of steps, sidecars.

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: uid-pipeline-run
spec:
  pipelineSpec:
    tasks:
    - name: add-uid
      taskSpec:
        results:
          - name: uid
            type: string
        steps:
          - name: add-uid
            image: busybox
            command: ["/bin/sh", "-c"]
            args:
              - echo "1001" | tee $(results.uid.path)
    - name: show-uid
      # params:
      #   - name: uid
      #     value: $(tasks.add-uid.results.uid)
      taskSpec:
        steps:
          - name: show-uid
            image: busybox
            command: ["/bin/sh", "-c"]
            args:
              - echo $(tasks.add-uid.results.uid)
              # - echo $(params.uid)

On executing the PipelineRun, the Results will be interpolated during resolution.

name:         uid-pipeline-run-show-uid
apiVersion:  tekton.dev/v1
kind:         TaskRun
metadata:
  ...
spec:
  taskSpec:
    steps:
      args:
        echo 1001
      command:
        - /bin/sh
        - -c
      image:  busybox
      name:   show-uid
status:
  completionTime:  2023-09-11T07:34:28Z
  conditions:
    lastTransitionTime:  2023-09-11T07:34:28Z
    message:               All Steps have completed executing
    reason:                Succeeded
    status:                True
    type:                  Succeeded
  podName:                uid-pipeline-run-show-uid-pod
  steps:
    container:  step-show-uid
    name:       show-uid
  taskSpec:
    steps:
      args:
        echo 1001
      command:
        /bin/sh
        -c
      computeResources:
      image:  busybox
      name:   show-uid

Specifying a `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. This allows you to customize the Pod configuration specifically for each TaskRun.

In the following example, the Task defines a volumeMount object named my-cache. The PipelineRun provisions this object for the Task using a persistentVolumeClaim and executes it as user 1001.

v1
v1beta1

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: mytask
spec:
  steps:
    - name: writesomething
      image: ubuntu
      command: ["bash", "-c"]
      args: ["echo 'foo' > /my-cache/bar"]
      volumeMounts:
        - name: my-cache
          mountPath: /my-cache
---
apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: mypipeline
spec:
  tasks:
    - name: task1
      taskRef:
        name: mytask
---
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

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: mytask
spec:
  steps:
    - name: writesomething
      image: ubuntu
      command: ["bash", "-c"]
      args: ["echo 'foo' > /my-cache/bar"]
      volumeMounts:
        - name: my-cache
          mountPath: /my-cache
---
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: mypipeline
spec:
  tasks:
    - name: task1
      taskRef:
        name: mytask
---
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: mypipelinerun
spec:
  pipelineRef:
    name: mypipeline
  podTemplate:
    securityContext:
      runAsNonRoot: true
      runAsUser: 1001
    volumes:
      - name: my-cache
        persistentVolumeClaim:
          claimName: my-volume-claim

Custom tasks may or may not use a pod template. Consult the documentation of the custom task that you are using to determine whether it supports a pod template.

Specifying taskRunSpecs

Specifies a list of PipelineTaskRunSpec which contains TaskServiceAccountName, TaskPodTemplate and PipelineTaskName. Mapping the specs to the corresponding Task based upon the TaskName a PipelineTask will run with the configured TaskServiceAccountName and TaskPodTemplate overwriting the pipeline wide ServiceAccountName and podTemplate configuration, for example:

v1
v1beta1

spec:
  podTemplate:
    securityContext:
      runAsUser: 1000
      runAsGroup: 2000
      fsGroup: 3000
  taskRunSpecs:
    - pipelineTaskName: build-task
      serviceAccountName: sa-for-build
      podTemplate:
        nodeSelector:
          disktype: ssd
      timeout: "1h30m"

spec:
  podTemplate:
    securityContext:
      runAsUser: 1000
      runAsGroup: 2000
      fsGroup: 3000
  taskRunSpecs:
    - pipelineTaskName: build-task
      taskServiceAccountName: sa-for-build
      taskPodTemplate:
        nodeSelector:
          disktype: ssd
      timeout: "1h30m"

If used with this Pipeline, build-task will use the task specific PodTemplate (where nodeSelector has disktype equal to ssd) along with securityContext from the pipelineRun.spec.podTemplate. The task will also have a specific timeout of 1 hour and 30 minutes. This overrides any existing timeout already defined by the pipelineTask as well, though the specified pipelineRun.spec.timeouts.tasks will still take precedence.

For more details on timeout overrides, precedence rules, validation, and practical examples, see Overriding Individual Task Timeouts in the failure timeout section.

PipelineTaskRunSpec may also contain StepSpecs and SidecarSpecs; see Overriding Task Steps and Sidecars for more information.

The optional annotations and labels can be added under a Metadata field as for a specific running context.

e.g.

Rendering needed secrets with Vault:

spec:
  pipelineRef:
    name: pipeline-name
  taskRunSpecs:
    - pipelineTaskName: task-name
      metadata:
        annotations:
          vault.hashicorp.com/agent-inject-secret-foo: "/path/to/foo"
          vault.hashicorp.com/role: role-name

Updating labels applied in a runtime context:

spec:
  pipelineRef:
    name: pipeline-name
  taskRunSpecs:
    - pipelineTaskName: task-name
      metadata:
        labels:
          app: cloudevent

If a metadata key is present in different levels, the value that will be used in the PipelineRun is determined using this precedence order: PipelineRun.spec.taskRunSpec.metadata > PipelineRun.metadata > Pipeline.spec.tasks.taskSpec.metadata.

Parameter Substitution in taskRunSpecs

The taskRunSpecs supports parameter substitution in the podTemplate fields. This allows you to dynamically configure pod templates based on pipeline parameters, including those from Matrix tasks.

For example, you can use parameter substitution to configure node selectors based on architecture parameters:

spec:
  taskRunSpecs:
    - pipelineTaskName: build-task
      podTemplate:
        nodeSelector:
          kubernetes.io/arch: $(params.arch)
        tolerations:
          - key: "environment"
            operator: "Equal"
            value: "$(params.env)"
            effect: "NoSchedule"

Matrix Support with taskRunSpecs

When using Matrix to fan out PipelineTasks, the taskRunSpecs can reference matrix parameters for dynamic pod template configuration. Each matrix combination will create a separate TaskRun with the appropriate parameter values substituted in the pod template.

Here’s an example showing how to use taskRunSpecs with matrix parameters:

spec:
  taskRunSpecs:
    - pipelineTaskName: build-and-push-manifest
      podTemplate:
        nodeSelector:
          kubernetes.io/arch: $(params.arch)
  pipelineSpec:
    tasks:
      - name: build-and-push-manifest
        matrix:
          params:
            - name: arch
              value: ["amd64", "arm64"]
        taskSpec:
          params:
            - name: arch
          steps:
            - name: build-and-push
              image: ubuntu
              script: |
                                echo "building on $(params.arch)"

In this example, the matrix will create two TaskRuns - one for amd64 and one for arm64. Each will have its pod scheduled on the appropriate node architecture using the nodeSelector with the substituted parameter value.

For a complete example, see pipelinerun-with-taskrunspecs-matrix-param-substitution.yaml.

Specifying `Workspaces`

If your Pipeline specifies one or more Workspaces, you must map those Workspaces to the corresponding physical volumes in your PipelineRun definition. For example, you can map a PersistentVolumeClaim volume to a Workspace as follows:

workspaces:
  - name: myworkspace # must match workspace name in Task
    persistentVolumeClaim:
      claimName: mypvc # this PVC must already exist
    subPath: my-subdir

workspaces[].subPath can be an absolute value or can reference pipelineRun context variables, such as, $(context.pipelineRun.name) or $(context.pipelineRun.uid).

You can pass in extra Workspaces if needed depending on your use cases. An example use case is when your CI system autogenerates PipelineRuns and it has Workspaces it wants to provide to all PipelineRuns. Because you can pass in extra Workspaces, you don’t have to go through the complexity of checking each Pipeline and providing only the required Workspaces:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: pipeline
spec:
  tasks:
    - name: task
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pipelinerun
spec:
  pipelineRef:
    name: pipeline
  workspaces:
    - name: unusedworkspace
      persistentVolumeClaim:
        claimName: mypvc

For more information, see the following topics:

For information on mapping Workspaces to Volumes, see Specifying Workspaces in PipelineRuns.
For a list of supported Volume types, see Specifying VolumeSources in Workspaces.
For an end-to-end example, see Workspaces in a PipelineRun.

Custom tasks may or may not use workspaces. Consult the documentation of the custom task that you are using to determine whether it supports workspaces.

Propagated Workspaces

When using an embedded spec, workspaces from the parent PipelineRun will be propagated to any inlined specs without needing to be explicitly defined. This allows authors to simplify specs by automatically propagating top-level workspaces down to other inlined resources. Workspace substutions will only be made for commands, args and script fields of steps, stepTemplates, and sidecars.

# Inline specifications of a PipelineRun
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: recipe-time-
spec:
  workspaces:
    - name: shared-data
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 16Mi
          volumeMode: Filesystem
  pipelineSpec:
    #workspaces:
    #  - name: shared-data
    tasks:
    - name: fetch-secure-data
      # workspaces:
      #   - name: shared-data
      taskSpec:
        # workspaces:
        #   - name: shared-data
        steps:
        - name: fetch-and-write-secure
          image: ubuntu
          script: |
                        echo hi >> $(workspaces.shared-data.path)/recipe.txt
    - name: print-the-recipe
      # workspaces:
      #   - name: shared-data
      runAfter:
        - fetch-secure-data
      taskSpec:
        # workspaces:
        #   - name: shared-data
        steps:
        - name: print-secrets
          image: ubuntu
          script: cat $(workspaces.shared-data.path)/recipe.txt

On executing the pipeline run, the workspaces will be interpolated during resolution.

# Successful execution of the above PipelineRun
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: recipe-time-
  ...
spec:
  pipelineSpec:
  ...
status:
  completionTime: "2022-06-02T18:17:02Z"
  conditions:
  - lastTransitionTime: "2022-06-02T18:17:02Z"
    message: 'Tasks Completed: 2 (Failed: 0, Canceled 0), Skipped: 0'
    reason: Succeeded
    status: "True"
    type: Succeeded
  pipelineSpec:
    ...
  childReferences:
  - name: recipe-time-lslt9-fetch-secure-data
    pipelineTaskName: fetch-secure-data
    kind: TaskRun
  - name: recipe-time-lslt9-print-the-recipe
    pipelineTaskName: print-the-recipe
    kind: TaskRun

Workspace Referenced Resources

Workspaces cannot be propagated to referenced specifications. For example, the following Pipeline will fail when executed because the workspaces defined in the PipelineRun cannot be propagated to the referenced Pipeline.

# PipelineRun attempting to propagate Workspaces to referenced Tasks
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: shared-task-storage
spec:
  resources:
    requests:
      storage: 16Mi
  volumeMode: Filesystem
  accessModes:
    - ReadWriteOnce
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: fetch-and-print-recipe
spec:
  tasks:
  - name: fetch-the-recipe
    taskRef:
      name: fetch-secure-data
  - name: print-the-recipe
    taskRef:
      name: print-data
    runAfter:
      - fetch-the-recipe
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: recipe-time-
spec:
  pipelineRef:
    name: fetch-and-print-recipe
  workspaces:
  - name: shared-data
    persistentVolumeClaim:
      claimName: shared-task-storage

Upon execution, this will cause failures:

# Failed execution of the above PipelineRun

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: recipe-time-
  ...
spec:
  pipelineRef:
    name: fetch-and-print-recipe
  workspaces:
  - name: shared-data
    persistentVolumeClaim:
      claimName: shared-task-storage
status:
  completionTime: "2022-06-02T19:02:58Z"
  conditions:
  - lastTransitionTime: "2022-06-02T19:02:58Z"
    message: 'Tasks Completed: 1 (Failed: 1, Canceled 0), Skipped: 1'
    reason: Failed
    status: "False"
    type: Succeeded
  pipelineSpec:
    ...
  childReferences:
  - name: recipe-time-v5scg-fetch-the-recipe
    pipelineTaskName: fetch-the-recipe
    kind: TaskRun

Referenced TaskRuns within Embedded PipelineRuns

As mentioned in the Workspace Referenced Resources, workspaces can only be propagated from PipelineRuns to embedded Pipeline specs, not Pipeline references. Similarly, workspaces can only be propagated from a Pipeline to embedded Task specs, not referenced Tasks. For example:

# PipelineRun attempting to propagate Workspaces to referenced Tasks
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: Task
metadata:
  name: fetch-secure-data
spec:
  workspaces: # If Referenced, Workspaces need to be explicitly declared
  - name: shared-data
  steps:
  - name: fetch-and-write
    image: ubuntu
    script: |
            echo $(workspaces.shared-data.path)
---
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: recipe-time-
spec:
  workspaces:
  - name: shared-data
    persistentVolumeClaim:
      claimName: shared-task-storage
  pipelineSpec:
    # workspaces: # Since this is embedded specs, Workspaces don’t need to be declared
    #    ...
    tasks:
    - name: fetch-the-recipe
      workspaces: # If referencing resources, Workspaces need to be explicitly declared
      - name: shared-data
      taskRef: # Referencing a resource
        name: fetch-secure-data
    - name: print-the-recipe
      # workspaces: # Since this is embedded specs, Workspaces don’t need to be declared
      #    ...
      taskSpec:
        # workspaces: # Since this is embedded specs, Workspaces don’t need to be declared
        #    ...
        steps:
        - name: print-secrets
          image: ubuntu
          script: cat $(workspaces.shared-data.path)/recipe.txt
      runAfter:
        - fetch-the-recipe

The above pipelinerun successfully resolves to:

# Successful execution of the above PipelineRun
apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  generateName: recipe-time-
  ...
spec:
  pipelineSpec:
    ...
  workspaces:
  - name: shared-data
    persistentVolumeClaim:
      claimName: shared-task-storage
status:
  completionTime: "2022-06-09T18:42:14Z"
  conditions:
  - lastTransitionTime: "2022-06-09T18:42:14Z"
    message: 'Tasks Completed: 2 (Failed: 0, Cancelled 0), Skipped: 0'
    reason: Succeeded
    status: "True"
    type: Succeeded
  pipelineSpec:
    ...
  childReferences:
  - name: recipe-time-pj6l7-fetch-the-recipe
    pipelineTaskName: fetch-the-recipe
    kind: TaskRun
  - name: recipe-time-pj6l7-print-the-recipe
    pipelineTaskName: print-the-recipe
    kind: TaskRun

Specifying `LimitRange` values

For more information, see the LimitRange support in Pipeline.

Configuring a failure timeout

You can use the timeouts field to set the PipelineRun's desired timeout value in minutes. There are three sub-fields:

pipeline: specifies the timeout for the entire PipelineRun. Defaults to to the global configurable default timeout of 60 minutes. When timeouts.pipeline has elapsed, any running child TaskRuns will be canceled, regardless of whether they are normal Tasks or finally Tasks, and the PipelineRun will fail.
tasks: specifies the timeout for the cumulative time taken by non-finally Tasks specified in pipeline.spec.tasks. To specify a timeout for an individual Task, use pipeline.spec.tasks[].timeout. When timeouts.tasks has elapsed, any running child TaskRuns will be canceled, finally Tasks will run if timeouts.finally is specified, and the PipelineRun will fail.
finally: the timeout for the cumulative time taken by finally Tasks specified in pipeline.spec.finally. (Since all finally Tasks run in parallel, this is functionally equivalent to the timeout for any finally Task.) When timeouts.finally has elapsed, any running finally TaskRuns will be canceled, and the PipelineRun will fail.

For example:

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

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.

If any of the sub-fields are set to “0”, there is no timeout for that section of the PipelineRun, meaning that it will run until it completes successfully or encounters an error. To set timeouts.tasks or timeouts.finally to “0”, you must also set timeouts.pipeline to “0”.

Overriding Individual Task Timeouts

You can use taskRunSpecs to override individual task timeouts at runtime without modifying the Pipeline definition.

Timeout Precedence (highest to lowest):

taskRunSpecs[].timeout - runtime override per task
pipeline.spec.tasks[].timeout - Pipeline spec timeout
timeouts.tasks or timeouts.pipeline - PipelineRun constraints
Global default timeout

apiVersion: tekton.dev/v1
kind: PipelineRun
spec:
  timeouts:
    pipeline: "10m"    # 3. PipelineRun constraint
  pipelineSpec:
    tasks:
    - name: task-a
      timeout: "8m"     # 2. Pipeline spec timeout
      taskSpec: { ... }
    - name: task-b  
      taskSpec: { ... } # 4. Uses global default (60m)
  taskRunSpecs:
  - pipelineTaskName: task-a
    timeout: "5m"       # 1. Highest priority - overrides 8m Pipeline timeout

Note: taskRunSpecs timeouts cannot exceed pipeline-level constraints and will fail validation if they do.

Example timeouts usages are as follows:

Combination 1: Set the timeout for the entire pipeline and reserve a portion of it for tasks.

kind: PipelineRun
spec:
  timeouts:
    pipeline: "0h4m0s"
    tasks: "0h1m0s"

Combination 2: Set the timeout for the entire pipeline and reserve a portion of it for finally.

kind: PipelineRun
spec:
  timeouts:
    pipeline: "0h4m0s"
    finally: "0h3m0s"

Combination 3: Set only a tasks timeout, with no timeout for the entire pipeline.

kind: PipelineRun
spec:
  timeouts:
    pipeline: "0"  # No timeout
    tasks: "0h3m0s"

Combination : Set only a finally timeout, with no timeout for the entire pipeline.

kind: PipelineRun
spec:
  timeouts:
    pipeline: "0"  # No timeout
    finally: "0h3m0s"

You can also use the Deprecated timeout field to set the PipelineRun's desired timeout value in minutes. If you do not specify this value in the PipelineRun, the global default timeout value applies. If you set the timeout to 0, the PipelineRun fails immediately upon encountering an error.

⚠️ ** timeout is deprecated and will be removed in future versions. Consider using timeouts instead.

:note: An internal detail of the PipelineRun and TaskRun reconcilers in the Tekton controller is that it will requeue a PipelineRun or TaskRun for re-evaluation, versus waiting for the next update, under certain conditions. The wait time for that re-queueing is the elapsed time subtracted from the timeout; however, if the timeout is set to ‘0’, that calculation produces a negative number, and the new reconciliation event will fire immediately, which can impact overall performance, which is counter to the intent of wait time calculation. So instead, the reconcilers will use the configured global timeout as the wait time when the associated timeout has been set to ‘0’.

`PipelineRun` status

The `status` field

Your PipelineRun’s status field can contain the following fields:

Required:
- status - Most relevant, status.conditions, which contains the latest observations of the PipelineRun’s state. See here for information on typical status properties.
- startTime - The time at which the PipelineRun began executing, in RFC3339 format.
- completionTime - The time at which the PipelineRun finished executing, in RFC3339 format.
- pipelineSpec - The exact PipelineSpec used when starting the PipelineRun.
Optional:
- pipelineResults - Results emitted by this PipelineRun.
- skippedTasks - A list of Tasks which were skipped when running this PipelineRun due to when expressions, including the when expressions applying to the skipped task.
- childReferences - A list of references to each TaskRun or Run in this PipelineRun, which can be used to look up the status of the underlying TaskRun or Run. Each entry contains the following:
  - kind - Generally either TaskRun or Run.
  - apiVersion - The API version for the underlying TaskRun or Run.
  - whenExpressions - The list of when expressions guarding the execution of this task.
- provenance - Metadata about the runtime configuration and the resources used in the PipelineRun. The data in the provenance field will be recorded into the build provenance by the provenance generator i.e. (Tekton Chains). Currently, there are 2 subfields:
  - refSource: the source from where a remote pipeline definition was fetched.
  - featureFlags: the configuration data of the feature-flags configmap.
- finallyStartTime- The time at which the PipelineRun’s finally Tasks, if any, began executing, in RFC3339 format.

Monitoring execution status

As your PipelineRun executes, its status field accumulates information on the execution of each TaskRun as well as the PipelineRun as a whole. This information includes the name of the pipeline Task associated to a TaskRun, the complete status of the TaskRun and details about whenExpressions that may be associated to a TaskRun.

The following example shows an extract from the status field of a PipelineRun that has executed successfully:

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

The following tables shows how to read the overall status of a PipelineRun. Completion time is set once a PipelineRun reaches status True or False:

`status`	`reason`	`completionTime` is set	Description
Unknown	Started	No	The `PipelineRun` has just been picked up by the controller.
Unknown	Running	No	The `PipelineRun` has been validate and started to perform its work.
Unknown	Cancelled	No	The user requested the PipelineRun to be cancelled. Cancellation has not be done yet.
True	Succeeded	Yes	The `PipelineRun` completed successfully.
True	Completed	Yes	The `PipelineRun` completed successfully, one or more Tasks were skipped.
False	Failed	Yes	The `PipelineRun` failed because one of the `TaskRuns` failed.
False	[Error message]	Yes	The `PipelineRun` failed with a permanent error (usually validation).
False	Cancelled	Yes	The `PipelineRun` was cancelled successfully.
False	PipelineRunTimeout	Yes	The `PipelineRun` timed out.
False	CreateRunFailed	Yes	The `PipelineRun` create run resources failed.

When a PipelineRun changes status, events are triggered accordingly.

When a PipelineRun has Tasks that were skipped, the reason for skipping the task will be listed in the Skipped Tasks section of the status of the PipelineRun.

When a PipelineRun has Tasks with when expressions:

If the when expressions evaluate to true, the Task is executed then the TaskRun and its resolved when expressions will be listed in the Task Runs section of the status of the PipelineRun.
If the when expressions evaluate to false, the Task is skipped then its name and its resolved when expressions will be listed in the Skipped Tasks section of the status of the PipelineRun.

Conditions:
  Last Transition Time:  2020-08-27T15:07:34Z
  Message:               Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 1
  Reason:                Completed
  Status:                True
  Type:                  Succeeded
Skipped Tasks:
  Name:       skip-this-task
  Reason:     When Expressions evaluated to false
  When Expressions:
    Input:     foo
    Operator:  in
    Values:
      bar
    Input:     foo
    Operator:  notin
    Values:
      foo
ChildReferences:
- Name: pipelinerun-to-skip-task-run-this-task
  Pipeline Task Name:  run-this-task
  Kind: TaskRun

The name of the TaskRuns and Runs owned by a PipelineRun are univocally associated to the owning resource. If a PipelineRun resource is deleted and created with the same name, the child TaskRuns will be created with the same name as before. The base format of the name is <pipelinerun-name>-<pipelinetask-name>. If the PipelineTask has a Matrix, the name will have an int suffix with format <pipelinerun-name>-<pipelinetask-name>-<combination-id>. The name may vary according the logic of kmeta.ChildName.

Some examples:

`PipelineRun` Name	`PipelineTask` Name	`TaskRun` Names
pipeline-run	task1	pipeline-run-task1
pipeline-run	task2-0123456789-0123456789-0123456789-0123456789-0123456789	pipeline-runee4a397d6eab67777d4e6f9991cd19e6-task2-0123456789-0
pipeline-run-0123456789-0123456789-0123456789-0123456789	task3	pipeline-run-0123456789-0123456789-0123456789-0123456789-task3
pipeline-run-0123456789-0123456789-0123456789-0123456789	task2-0123456789-0123456789-0123456789-0123456789-0123456789	pipeline-run-0123456789-012345607ad8c7aac5873cdfabe472a68996b5c
pipeline-run	task4 (with 2x2 `Matrix`)	pipeline-run-task1-0, pipeline-run-task1-2, pipeline-run-task1-3, pipeline-run-task1-4

Marking off user errors

A user error in Tekton is any mistake made by user, such as a syntax error when specifying pipelines, tasks. User errors can occur in various stages of the Tekton pipeline, from authoring the pipeline configuration to executing the pipelines. They are currently explicitly labeled in the Run’s conditions message, for example:

# Failed PipelineRun with message labeled "[User error]"
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  ...
spec:
  ...
status:
  ...
  conditions:
  - lastTransitionTime: "2022-06-02T19:02:58Z"
    message: '[User error] PipelineRun default parameters is missing some parameters required by
      Pipeline pipelinerun-with-params''s parameters: pipelineRun missing parameters:
      [pl-param-x]'
    reason: 'ParameterMissing'
    status: "False"
    type: Succeeded

~/pipeline$ tkn pr list
NAME                      STARTED         DURATION   STATUS
pipelinerun-with-params   5 seconds ago   0s         Failed(ParameterMissing)

Delegating reconciliation

The managedBy field allows you to delegate the responsibility of managing a PipelineRun’s lifecycle to an external controller. When this field is set to a value other than "tekton.dev/pipeline", the Tekton Pipeline controller will ignore the PipelineRun, allowing your external controller to take full control. This delegation enables several advanced use cases, such as implementing custom pipeline execution logic, integrating with external management tools, using advanced scheduling algorithms, or coordinating PipelineRuns across multiple clusters (like using MultiKueue).

Example

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: externally-managed-pipeline
spec:
  pipelineRef:
    name: my-pipeline
  managedBy: "my-custom-controller"

Behavior

When managedBy is empty: The Tekton Pipeline controller manages the PipelineRun normally
When managedBy is set to "tekton.dev/pipeline": The Tekton Pipeline controller manages the PipelineRun normally
When managedBy is set to any other value: The Tekton Pipeline controller ignores the PipelineRun completely
Immutability: The managedBy field is immutable and cannot be changed after creation

External controller responsibilities

When you set managedBy to a custom value, your external controller is responsible for:

Creating and managing TaskRuns
Updating PipelineRun status
Handling timeouts and cancellations
Managing retries and error handling

Cancelling a `PipelineRun`

To cancel a PipelineRun that’s currently executing, update its definition to mark it as “Cancelled”. When you do so, the spawned TaskRuns are also marked as cancelled, all associated Pods are deleted, and their Retries are not executed. Pending finally tasks are not scheduled.

For example:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # […]
  status: "Cancelled"

Gracefully cancelling a `PipelineRun`

To gracefully cancel a PipelineRun that’s currently executing, update its definition to mark it as “CancelledRunFinally”. When you do so, the spawned TaskRuns are also marked as cancelled, all associated Pods are deleted, and their Retries are not executed. finally tasks are scheduled normally.

For example:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # […]
  status: "CancelledRunFinally"

Gracefully stopping a `PipelineRun`

To gracefully stop a PipelineRun that’s currently executing, update its definition to mark it as “StoppedRunFinally”. When you do so, the spawned TaskRuns are completed normally, including executing their retries, but no new non-finally task is scheduled. finally tasks are executed afterwards. For example:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # […]
  status: "StoppedRunFinally"

Pending `PipelineRuns`

A PipelineRun can be created as a “pending” PipelineRun meaning that it will not actually be started until the pending status is cleared.

Note that a PipelineRun can only be marked “pending” before it has started, this setting is invalid after the PipelineRun has been started.

To mark a PipelineRun as pending, set .spec.status to PipelineRunPending when creating it:

apiVersion: tekton.dev/v1 # or tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # […]
  status: "PipelineRunPending"

To start the PipelineRun, clear the .spec.status field. Alternatively, update the value to Cancelled to cancel it.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

CustomRuns

Overview

v1beta1.CustomRun has replaced v1alpha1.Run for executing Custom Tasks. Please refer to the migration doc for details on updating v1alpha1.Run to v1beta1.CustomRun before upgrading to a release that does not support v1alpha1.Run.

A CustomRun allows you to instantiate and execute a Custom Task, which can be implemented by a custom task controller running on-cluster. Custom Tasks can implement behavior that’s independent of how Tekton TaskRun is implemented.

In order for a CustomRun to actually execute, there must be a custom task controller running on the cluster that is responsible for watching and updating CustomRuns which reference their type. If no such controller is running, CustomRuns will have no .status value and no further action will be taken.

Configuring a `CustomRun`

A CustomRun definition supports the following fields:

Required:
- apiVersion - Specifies the API version. Currently,only tekton.dev/v1beta1 is supported.
- kind - Identifies this resource object as a CustomRun object.
- metadata - Specifies the metadata that uniquely identifies the CustomRun, such as a name.
- spec - Specifies the configuration for the CustomRun.
  - customRef - Specifies the type and (optionally) name of the custom task type to execute.
  - customSpec - Embed the custom task resource spec directly in a CustomRun.
Optional:
- timeout - specifies the maximum duration of a single execution of a CustomRun.
- retries - specifies the number of retries to execute upon CustomRunfailure.
- params - Specifies the desired execution parameters for the custom task.
- serviceAccountName - Specifies a ServiceAccount object for executing the CustomRun.
- workspaces - Specifies the physical volumes to use for the Workspaces required by a custom task.

Specifying the target Custom Task

A custom task resource’s CustomSpec may be directly embedded in the CustomRun or it may be referred to by a CustomRef. But, not both at the same time.

Specifying the target Custom Task with customRef Referring a custom task (i.e. CustomRef ) promotes reuse of custom task definitions.
Specifying the target Custom Task by embedding its spec Embedding a custom task (i.e. CustomSpec ) helps in avoiding name collisions with other users within the same namespace. Additionally, in a pipeline with multiple embedded custom tasks, the details of entire pipeline can be fetched in a single API request.

Specifying the target Custom Task with customRef

To specify the custom task type you want to execute in your CustomRun, use the customRef field as shown below:

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1beta1
    kind: MyCustomKind
  params:
  - name: duration
    value: 10s

When this CustomRun is created, the Custom Task controller responsible for reconciling objects of kind “MyCustomKind” in the “example.dev/v1beta1” api group will execute it based on the input params.

You can also specify the name and optional namespace (default is default) of a custom task resource object previously defined in the cluster.

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1beta1
    kind: Example
    name: an-existing-example-task

If the customRef specifies a name, the custom task controller should look up the Example resource with that name, and use that object to configure the execution.

If the customRef does not specify a name, the custom task controller might support some default behavior for executing unnamed tasks.

In either case, if the named resource cannot be found, or if unnamed tasks are not supported, the custom task controller should update the CustomRun’s status to indicate the error.

Specifying the target Custom Task by embedding its customSpec

To specify the custom task spec, it can be embedded directly into a CustomRun’s spec as shown below:

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: embedded-run
spec:
  customSpec:
    apiVersion: example.dev/v1beta1
    kind: Example
    spec:
      field1: value1
      field2: value2

When this CustomRun is created, the custom task controller responsible for reconciling objects of kind Example in the example.dev api group will execute it.

Developer guide for custom controllers supporting `customSpec`.

A custom controller may or may not support a Spec. In cases where it is not supported the custom controller should respond with proper validation error.
Validation of the fields of the custom task is delegated to the custom task controller. It is recommended to implement validations as asynchronous (i.e. at reconcile time), rather than part of the webhook. Using a webhook for validation is problematic because, it is not possible to filter custom task resource objects before validation step, as a result each custom task resource has to undergo validation by all the installed custom task controllers.
A custom task may have an empty spec, but cannot have an empty ApiVersion and Kind. Custom task controllers should handle an empty spec, either with a default behaviour, in a case no default behaviour is supported then, appropriate validation error should be updated to the CustomRun’s status.

Cancellation

The custom task is responsible for implementing cancellation to support pipelineRun level timeouts and cancellation. If the Custom Task implementor does not support cancellation via .spec.status, Pipeline can not timeout within the specified interval/duration and can not be cancelled as expected upon request.

Pipeline Controller sets the spec.Status and spec.StatusMessage to signal CustomRuns about the Cancellation, while CustomRun controller updates its status.conditions as following once noticed the change on spec.Status.

status
  conditions:
  - type: Succeeded
    status: False
    reason: CustomRunCancelled

Specifying `Timeout`

A custom task specification can be created with Timeout as follows:

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  generateName: simpleexample
spec:
  timeout: 10s # set timeouts here.
  params:
    - name: searching
      value: the purpose of my existence
  customRef:
    apiVersion: custom.tekton.dev/v1alpha1
    kind: Example
    name: exampleName

Supporting timeouts is optional but recommended.

Developer guide for custom controllers supporting `Timeout`

Tekton controllers will never directly update the status of the CustomRun, it is the responsibility of the custom task controller to support timeout. If timeout is not supported, it’s the responsibility of the custom task controller to reject CustomRuns that specify a timeout value.
When CustomRun.Spec.Status is updated to RunCancelled, the custom task controller MUST cancel the CustomRun. Otherwise, pipeline-level Timeout and Cancellation won’t work for the Custom Task.
A Custom Task controller can watch for this status update (i.e. CustomRun.Spec.Status == RunCancelled) and or CustomRun.HasTimedOut() and take any corresponding actions (i.e. a clean up e.g., cancel a cloud build, stop the waiting timer, tear down the approval listener).
Once resources or timers are cleaned up, while it is REQUIRED to set a conditions on the CustomRun’s status of Succeeded/False with an optional Reason of CustomRunTimedOut.
Timeout is specified for each retry attempt instead of all retries.

Specifying `Retries`

A custom task specification can be created with Retries as follows:

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  generateName: simpleexample
spec:
  retries: 3 # set retries
  params:
    - name: searching
      value: the purpose of my existence
  customRef:
    apiVersion: custom.tekton.dev/v1alpha1
    kind: Example
    name: exampleName

Supporting retries is optional but recommended.

Developer guide for custom controllers supporting `retries`

Tekton controller only depends on ConditionSucceeded to determine the termination status of a CustomRun, therefore Custom task implementors MUST NOT set ConditionSucceeded to False until all retries are exhausted.
Those custom tasks who do not wish to support retry, can simply ignore it.
It is recommended, that custom task should update the field RetriesStatus of a CustomRun on each retry performed by the custom task.
Tekton controller does not validate that number of entries in RetriesStatus is same as specified value of retries count.

Specifying `Parameters`

If a custom task supports parameters, you can use the params field in the CustomRun to specify their values:

spec:
  params:
    - name: my-param
      value: chicken

If the custom task controller knows how to interpret the parameter value, it will do so. It might enforce that some parameter values must be specified, or reject unknown parameter values.

Specifying workspaces

If the custom task supports it, you can provide Workspaces to share data with the custom task .

spec:
  workspaces:
    - name: my-workspace
      emptyDir: {}

Consult the documentation of the custom task that you are using to determine whether it supports workspaces and how to name them.

Specifying a ServiceAccount

If the custom task supports it, you can execute the CustomRun with a specific set of credentials by specifying a ServiceAccount object name in the serviceAccountName field in your CustomRun definition. If you do not explicitly specify this, the CustomRun executes with the service account specified in the configmap-defaults ConfigMap. If this default is not specified, CustomRuns will execute with the default service account set for the target namespace.

spec:
  serviceAccountName: my-account

Consult the documentation of the custom task that you are using to determine whether it supports a service account name.

Monitoring execution status

As your CustomRun executes, its status field accumulates information on the execution of the CustomRun. This information includes the current state of the CustomRun, start and completion times, and any output results reported by the custom task controller.

Status Reporting

When the CustomRun<Example> is validated and created, the Custom Task controller will be notified and is expected to begin doing some operation. When the operation begins, the controller MUST update the CustomRun’s .status.conditions to report that it’s ongoing:

status
  conditions:
  - type: Succeeded
    status: Unknown

When the operation completes, if it was successful, the condition MUST report status: True, and optionally a brief reason and human-readable message:

status
  conditions:
  - type: Succeeded
    status: True
    reason: ExampleComplete # optional
    message: Yay, good times # optional

If the operation was unsuccessful, the condition MUST report status: False, and optionally a reason and human-readable message:

status
  conditions:
  - type: Succeeded
    status: False
    reason: ExampleFailed # optional
    message: Oh no bad times # optional

If the CustomRun was cancelled, the condition MUST report status: False, reason: CustomRunCancelled, and optionally a human-readable message:

status
  conditions:
  - type: Succeeded
    status: False
    reason: CustomRunCancelled
    message: Oh it's cancelled # optional

The following tables shows the overall status of a CustomRun:

`status`	Description
	The custom task controller has not taken any action on the `CustomRun`.
Unknown	The custom task controller has started execution and the `CustomRun` is ongoing.
True	The `CustomRun` completed successfully.
False	The `CustomRun` completed unsuccessfully, and all retries were exhausted.

The CustomRun type’s .status will also allow controllers to report other fields, such as startTime, completionTime, results (see below), and arbitrary context-dependent fields the Custom Task author wants to report. A fully-specified CustomRun status might look like:

status
  conditions:
  - type: Succeeded
    status: True
    reason: ExampleComplete
    message: Yay, good times
  completionTime: "2020-06-18T11:55:01Z"
  startTime: "2020-06-18T11:55:01Z"
  results:
  - name: first-name
    value: Bob
  - name: last-name
    value: Smith
  arbitraryField: hello world
  arbitraryStructuredField:
    listOfThings: ["a", "b", "c"]

Monitoring `Results`

After the CustomRun completes, the custom task controller can report output values in the results field:

results:
- name: my-result
  value: chicken

Code examples

To better understand CustomRuns, study the following code examples:

Example `CustomRun` with a referenced custom task

In this example, a CustomRun named my-example-run invokes a custom task of the v1alpha1 version of the Example kind in the example.dev API group, with the name my-example-task.

In this case the custom task controller is expected to look up the Example resource named my-example-task and to use that configuration to configure the execution of the CustomRun.

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example-task

Example `CustomRun` with an unnamed custom task

In this example, a CustomRun named my-example-run invokes a custom task of the v1alpha1 version of the Example kind in the example.dev API group, without a specified name.

In this case the custom task controller is expected to provide some default behavior when the referenced task is unnamed.

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1alpha1
    kind: Example

Example of specifying parameters

In this example, a CustomRun named my-example-run invokes a custom task, and specifies some parameter values to further configure the execution’s behavior.

In this case the custom task controller is expected to validate and interpret these parameter values and use them to configure the CustomRun’s execution.

apiVersion: tekton.dev/v1alpha1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example-task
  params:
    - name: my-first-param
      value: i'm number one
    - name: my-second-param
      value: close second

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Replacing PipelineResources with Tasks

PipelineResources remained in alpha while the other resource kinds were promoted to beta. Since then, PipelineResources have been removed. Read more about the deprecation in TEP-0074.

More on the reasoning and what’s left to do in Why aren’t PipelineResources in Beta?.

To ease migration away from PipelineResources some types have an equivalent Task in the Catalog. To use these replacement Tasks you will need to combine them with your existing Tasks via a Pipeline.

For example, if you were using this Task which was fetching from git and building with Kaniko:

apiVersion: tekton.dev/v1alpha1
kind: Task
metadata:
  name: build-push-kaniko
spec:
  inputs:
    resources:
      - name: workspace
        type: git
    params:
      - name: pathToDockerFile
        description: The path to the dockerfile to build
        default: /workspace/workspace/Dockerfile
      - name: pathToContext
        description: The build context used by Kaniko
        default: /workspace/workspace
  outputs:
    resources:
      - name: builtImage
        type: image
  steps:
    - name: build-and-push
      image: gcr.io/kaniko-project/executor:v0.17.1
      env:
        - name: "DOCKER_CONFIG"
          value: "/tekton/home/.docker/"
      args:
        - --dockerfile=$(inputs.params.pathToDockerFile)
        - --destination=$(outputs.resources.builtImage.url)
        - --context=$(inputs.params.pathToContext)
        - --oci-layout-path=$(inputs.resources.builtImage.path)
      securityContext:
        runAsUser: 0

To do the same thing with the git catalog Task and the kaniko Task you will need to combine them in a Pipeline.

For example this Pipeline uses the Kaniko and git catalog Tasks:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: kaniko-pipeline
spec:
  params:
    - name: git-url
    - name: git-revision
    - name: image-name
    - name: path-to-image-context
    - name: path-to-dockerfile
  workspaces:
    - name: git-source
  tasks:
    - name: fetch-from-git
      taskRef:
        name: git-clone
      params:
        - name: url
          value: $(params.git-url)
        - name: revision
          value: $(params.git-revision)
      workspaces:
        - name: output
          workspace: git-source
    - name: build-image
      taskRef:
        name: kaniko
      params:
        - name: IMAGE
          value: $(params.image-name)
        - name: CONTEXT
          value: $(params.path-to-image-context)
        - name: DOCKERFILE
          value: $(params.path-to-dockerfile)
      workspaces:
        - name: source
          workspace: git-source
  # If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
  # via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
  # able to fully deliver with the Image PipelineResource!

Note that the image PipelineResource is gone in this example (replaced with a result), and also that now the Task doesn’t need to know anything about where the files come from that it builds from.

Replacing a `git` resource

You can replace a git resource with the git-clone Catalog Task.

Replacing a `pullrequest` resource

You can replace a pullrequest resource with the pullrequest Catalog Task.

Replacing a `gcs` resource

You can replace a gcs resource with the gcs Catalog Task.

Replacing an `image` resource

Since the image resource is simply a way to share the digest of a built image with subsequent Tasks in your Pipeline, you can use Task results to achieve equivalent functionality.

For examples of replacing an image resource, see the following Catalog Tasks:

The Kaniko Catalog Task illustrates how to write the digest of an image to a result.
The Buildah Catalog Task illustrates how to accept an image digest as a parameter.

Replacing a `cluster` resource

You can replace a cluster resource with the kubeconfig-creator Catalog Task.

Replacing a `cloudEvent` resource

You can replace a cloudEvent resource with the CloudEvent Catalog Task.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

PipelineResources

⚠️ PipelineResources are deprecated.

Consider using replacement features instead. Read more in documentation and TEP-0074.

Note: PipelineResources have not been promoted to Beta in tandem with Pipeline’s other CRDs. This means that the level of support for PipelineResources remains Alpha. PipelineResources are now deprecated.**

For Beta-supported alternatives to PipelineResources see the v1alpha1 to v1beta1 migration guide which lists each PipelineResource type and a suggested option for replacing it.

For more information on why PipelineResources are remaining alpha see the description of their problems, along with next steps, below.

Why Aren’t PipelineResources in Beta?

Why Aren’t PipelineResources in Beta?

The short answer is that they’re not ready to be given a Beta level of support by Tekton’s developers. The long answer is, well, longer:

Their behaviour can be opaque.

They’re implemented as a mixture of injected Task Steps, volume configuration and type-specific code in Tekton Pipeline’s controller. This means errors from PipelineResources can manifest in quite a few different ways and it’s not always obvious whether an error directly relates to PipelineResource behaviour. This problem is compounded by the fact that, while our docs explain each Resource type’s “happy path”, there never seems to be enough info available to explain error cases sufficiently.
When they fail they’re difficult to debug.

Several PipelineResources inject their own Steps before a Task's Steps. It’s extremely difficult to manually insert Steps before them to inspect the state of a container before they run.
There aren’t enough of them.

The six types of existing PipelineResources only cover a tiny subset of the possible systems and side-effects we want to support with Tekton Pipelines.
Adding extensibility to them makes them really similar to Tasks:
- User-definable Steps? This is what Tasks provide.
- User-definable params? Tasks already have these.
- User-definable “resource results”? Tasks have Task Results.
- Sharing data between Tasks using PVCs? workspaces provide this for Tasks.
They make Tasks less reusable.
- A Task has to choose the type of PipelineResource it will accept.
- If a Task accepts a git PipelineResource then it’s not able to accept a gcs PipelineResource from a TaskRun or PipelineRun even though both the git and gcs PipelineResources fetch files. They should technically be interchangeable: all they do is write files from somewhere remote onto disk. Yet with the existing PipelineResources implementation they aren’t interchangeable.

They also present challenges from a documentation perspective:

Their purpose is ambiguous and it’s difficult to articulate what the CRD is precisely for.
Four of the types interact with external systems (git, pull-request, gcs, gcs-build).
Five of them write files to a Task’s disk (git, pull-request, gcs, gcs-build, cluster).
One tells the Pipelines controller to emit CloudEvents to a specific endpoint (cloudEvent).
One writes config to disk for a Task to use (cluster).
One writes a digest in one Task and then reads it back in another Task (image).
Perhaps the one thing you can say about the PipelineResource CRD is that it can create side-effects for your Tasks.

What’s still missing

So what are PipelineResources still good for? We think we’ve identified some of the most important things:

You can augment Task-only workflows with PipelineResources that, without them, can only be done with Pipelines.
- For example, let’s say you want to checkout a git repo for your Task to test. You have two options. First, you could use a git PipelineResource and add it directly to your test Task. Second, you could write a Pipeline that has a git-clone Task which checks out the code onto a PersistentVolumeClaim workspace and then passes that PVC workspace to your test Task. For a lot of users the second workflow is totally acceptable but for others it isn’t. Some of the most notable reasons we’ve heard are:
  - Some users simply cannot allocate storage on their platform, meaning PersistentVolumeClaims are out of the question.
  - Expanding a single Task workflow into a Pipeline is labor-intensive and feels unnecessary.
Despite being difficult to explain the whole CRD clearly each individual type is relatively easy to explain.
- For example, users can build a pretty good “hunch” for what a git PipelineResource is without really reading any docs.
Configuring CloudEvents to be emitted by the Tekton Pipelines controller.
- Work is ongoing to get notifications support into the Pipelines controller which should hopefully be able to replace the cloudEvents PipelineResource.

For each of these there is some amount of ongoing work or discussion. We have deprecated PipelineResources and are actively working to cover the missing replacement features. Read more about the deprecation in TEP-0074.

For Beta-supported alternatives to PipelineResources see the v1alpha1 to v1beta1 migration guide which lists each PipelineResource type and a suggested option for replacing it.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Authentication at Run Time

This document describes how Tekton handles authentication when executing TaskRuns and PipelineRuns. Since authentication concepts and processes apply to both of those entities in the same manner, this document collectively refers to TaskRuns and PipelineRuns as Runs for the sake of brevity.

Overview

Tekton supports authentication via the Kubernetes first-class Secret types listed below.

Git	Docker
`kubernetes.io/basic-auth` `kubernetes.io/ssh-auth`	`kubernetes.io/basic-auth` `kubernetes.io/dockercfg` `kubernetes.io/dockerconfigjson`

A Run gains access to these Secrets through its associated ServiceAccount. Tekton requires that each supported Secret includes a Tekton-specific annotation.

Tekton converts properly annotated Secrets of the supported types and stores them in a Step's container as follows:

Git: Tekton produces a ~/.gitconfig file or a ~/.ssh directory.
Docker: Tekton produces a ~/.docker/config.json file.

Each Secret type supports multiple credentials covering multiple domains and establishes specific rules governing credential formatting and merging. Tekton follows those rules when merging credentials of each supported type.

To consume these Secrets, Tekton performs credential initialization within every Pod it instantiates, before executing any Steps in the Run. During credential initialization, Tekton accesses each Secret associated with the Run and aggregates them into a /tekton/creds directory. Tekton then copies or symlinks files from this directory into the user’s $HOME directory.

TODO(#5357): Update docs to explain recommended methods of passing secrets in via workspaces

Understanding credential selection

A Run might require multiple types of authentication. For example, a Run might require access to multiple private Git and Docker repositories. You must properly annotate each Secret to specify the domains for which Tekton can use the credentials that the Secret contains. Tekton ignores all Secrets that are not properly annotated.

A credential annotation key must begin with tekton.dev/git- or tekton.dev/docker- and its value is the URL of the host for which you want Tekton to use that credential. In the following example, Tekton uses a basic-auth (username/password pair) Secret to access Git repositories at github.com and gitlab.com as well as Docker repositories at gcr.io:

apiVersion: v1
kind: Secret
metadata:
  annotations:
    tekton.dev/git-0: https://github.com
    tekton.dev/git-1: https://gitlab.com
    tekton.dev/docker-0: https://gcr.io
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>

And in this example, Tekton uses an ssh-auth Secret to access Git repositories at github.com only:

apiVersion: v1
kind: Secret
metadata:
  annotations:
    tekton.dev/git-0: github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  # This is non-standard, but its use is encouraged to make this more secure.
  # Omitting this results in the server's public key being blindly accepted.

Using `Secrets` as a non-root user

In certain scenarios you might need to use Secrets as a non-root user. For example:

Your platform randomizes the user and/or groups that your containers use to execute.
The Steps in your Task define a non-root securityContext.
Your Task specifies a global non-root securityContext that applies to all Steps in the Task.

The following are considerations for executing Runs as a non-root user:

ssh-auth for Git requires the user to have a valid home directory configured in /etc/passwd. Specifying a UID that has no valid home directory results in authentication failure.
Since SSH authentication ignores the $HOME environment variable, you must either move or symlink the appropriate Secret files from the $HOME directory defined by Tekton (/tekton/home) to the non-root user’s valid home directory to use SSH authentication for either Git or Docker.

For an example of configuring SSH authentication in a non-root securityContext, see authenticating-git-commands.

Limiting `Secret` access to specific `Steps`

As described earlier in this document, Tekton stores supported Secrets in $HOME/tekton/home and makes them available to all Steps within a Task.

If you want to limit a Secret to only be accessible to specific Steps but not others, you must explicitly specify a Volume using the Secret definition and manually VolumeMount it into the desired Steps instead of using the procedures described later in this document.

Configuring authentication for Git

This section describes how to configure the following authentication schemes for use with Git:

Configuring `basic-auth` authentication for Git

This section describes how to configure a basic-auth type Secret for use with Git. In the example below, before executing any Steps in the Run, Tekton creates a ~/.gitconfig file containing the credentials specified in the Secret.

Note: Github deprecated basic authentication with username and password. You can still use basic authentication, but you wil need to use a personal access token instead of the cleartext password in the following example. You can find out how to create such a token on the Github documentation site.

In secret.yaml, define a Secret that specifies the username and password that you want Tekton to use to access the target Git repository:
```
apiVersion: v1
kind: Secret
metadata:
  name: basic-user-pass
  annotations:
    tekton.dev/git-0: https://github.com # Described below
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>
```
In the above example, the value for tekton.dev/git-0 specifies the URL for which Tekton will use this Secret, as described in Understanding credential selection.

In serviceaccount.yaml, associate the Secret with the desired ServiceAccount:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: basic-user-pass

In run.yaml, associate the ServiceAccount with your Run by doing one of the following:

Associate the ServiceAccount with your TaskRun:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  serviceAccountName: build-bot
  taskRef:
    name: build-push

Associate the ServiceAccount with your PipelineRun:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline

Execute the Run:

kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml

Configuring `ssh-auth` authentication for Git

This section describes how to configure an ssh-auth type Secret for use with Git. In the example below, before executing any Steps in the Run, Tekton creates a ~/.ssh/config file containing the SSH key specified in the Secret.

In secret.yaml, define a Secret that specifies your SSH private key:

apiVersion: v1
kind: Secret
metadata:
  name: ssh-key
  annotations:
    tekton.dev/git-0: github.com # Described below
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  # This is non-standard, but its use is encouraged to make this more secure.
  # If it is not provided then the git server's public key will be requested
  # when the repo is first fetched.
  known_hosts: <known-hosts>

In the above example, the value for tekton.dev/git-0 specifies the URL for which Tekton will use this Secret, as described in Understanding credential selection.

Generate the ssh-privatekey value. For example:

cat ~/.ssh/id_rsa
Set the value of the known_hosts field to the generated ssh-privatekey value from the previous step.

In serviceaccount.yaml, associate the Secret with the desired ServiceAccount:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: ssh-key

In run.yaml, associate the ServiceAccount with your Run by doing one of the following:

Associate the ServiceAccount with your TaskRun:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  serviceAccountName: build-bot
  taskRef:
    name: build-push

Associate the ServiceAccount with your PipelineRun:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline

Execute the Run:

kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml

Using a custom port for SSH authentication

You can specify a custom SSH port in your Secret.

apiVersion: v1
kind: Secret
metadata:
  name: ssh-key-custom-port
  annotations:
    tekton.dev/git-0: example.com:2222
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: <private-key>
  known_hosts: <known-hosts>

Using SSH authentication in `git` type `Tasks`

You can use SSH authentication as described earlier in this document when invoking git commands directly in the Steps of a Task. Since ssh ignores the $HOME variable and only uses the user’s home directory specified in /etc/passwd, each Step must symlink /tekton/home/.ssh to the home directory of its associated user.

Note: This explicit symlinking is not necessary when using the git-clone Task from Tekton Catalog.

For example usage, see authenticating-git-commands.

Configuring authentication for Docker

This section describes how to configure the following authentication schemes for use with Docker:

Configuring `basic-auth` authentication for Docker

This section describes how to configure the basic-auth (username/password pair) type Secret for use with Docker.

In the example below, before executing any Steps in the Run, Tekton creates a ~/.docker/config.json file containing the credentials specified in the Secret.

In secret.yaml, define a Secret that specifies the username and password that you want Tekton to use to access the target Docker registry:
```
apiVersion: v1
kind: Secret
metadata:
  name: basic-user-pass
  annotations:
    tekton.dev/docker-0: https://gcr.io # Described below
type: kubernetes.io/basic-auth
stringData:
  username: <cleartext username>
  password: <cleartext password>
```
In the above example, the value for tekton.dev/docker-0 specifies the URL for which Tekton will use this Secret, as described in Understanding credential selection.

In serviceaccount.yaml, associate the Secret with the desired ServiceAccount:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: basic-user-pass

In run.yaml, associate the ServiceAccount with your Run by doing one of the following:

Associate the ServiceAccount with your TaskRun:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  serviceAccountName: build-bot
  taskRef:
    name: build-push

Associate the ServiceAccount with your PipelineRun:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline

Execute the Run:

kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml

Configuring `docker*` authentication for Docker

This section describes how to configure authentication using the dockercfg and dockerconfigjson type Secrets for use with Docker. In the example below, before executing any Steps in the Run, Tekton creates a ~/.docker/config.json file containing the credentials specified in the Secret. When the Steps execute, Tekton uses those credentials to access the target Docker registry. f Note: If you specify both the Tekton basic-auth and the above Kubernetes Secrets, Tekton merges all credentials from all specified Secrets but Tekton’s basic-auth Secret overrides either of the Kubernetes Secrets.

Define a Secret based on your Docker client configuration file.
```
kubectl create secret generic regcred \
 --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
 --type=kubernetes.io/dockerconfigjson
```
For more information, see Pull an Image from a Private Registry in the Kubernetes documentation.

In serviceaccount.yaml, associate the Secret with the desired ServiceAccount:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: regcred

In run.yaml, associate the ServiceAccount with your Run by doing one of the following:

Associate the ServiceAccount with your TaskRun:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: build-with-basic-auth
spec:
  serviceAccountName: build-bot
  steps:
  # ...

Associate the ServiceAccount with your PipelineRun:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline

Execute the build:

kubectl apply --filename secret.yaml --filename serviceaccount.yaml --filename taskrun.yaml

Technical reference

This section provides a technical reference for the implementation of the authentication mechanisms described earlier in this document.

`basic-auth` for Git

Given URLs, usernames, and passwords of the form: https://url{n}.com, user{n}, and pass{n}, Tekton generates the following:

=== ~/.gitconfig ===
[credential]
    helper = store
[credential "https://url1.com"]
    username = "user1"
[credential "https://url2.com"]
    username = "user2"
...
=== ~/.git-credentials ===
https://user1:pass1@url1.com
https://user2:pass2@url2.com
...

`ssh-auth` for Git

Given hostnames, private keys, and known_hosts of the form: url{n}.com, key{n}, and known_hosts{n}, Tekton generates the following.

By default, if no value is specified for known_hosts, Tekton configures SSH to accept any public key returned by the server on first query. Tekton does this by setting Git’s core.sshCommand variable to ssh -o StrictHostKeyChecking=accept-new. This behaviour can be prevented using a feature-flag: require-git-ssh-secret-known-hosts. Set this flag to true and all Git SSH Secrets must include a known_hosts.

=== ~/.ssh/id_key1 ===
{contents of key1}
=== ~/.ssh/id_key2 ===
{contents of key2}
...
=== ~/.ssh/config ===
Host url1.com
    HostName url1.com
    IdentityFile ~/.ssh/id_key1
Host url2.com
    HostName url2.com
    IdentityFile ~/.ssh/id_key2
...
=== ~/.ssh/known_hosts ===
{contents of known_hosts1}
{contents of known_hosts2}
...

`basic-auth` for Docker

Given URLs, usernames, and passwords of the form: https://url{n}.com, user{n}, and pass{n}, Tekton generates the following. Since Docker doesn’t support the kubernetes.io/ssh-auth type Secret, Tekton ignores annotations on Secrets of that type.

=== ~/.docker/config.json ===
{
  "auths": {
    "https://url1.com": {
      "auth": "$(echo -n user1:pass1 | base64)",
      "email": "not@val.id",
    },
    "https://url2.com": {
      "auth": "$(echo -n user2:pass2 | base64)",
      "email": "not@val.id",
    },
    ...
  }
}

Errors and their meaning

“unsuccessful cred copy” Warning

This message has the following format:

warning: unsuccessful cred copy: ".docker" from "/tekton/creds" to "/tekton/home": unable to open destination: open /tekton/home/.docker/config.json: permission denied

The precise credential and paths mentioned can vary. This message is only a warning but can be indicative of the following problems:

Multiple Steps with varying UIDs

Multiple Steps with different users / UIDs are trying to initialize docker or git credentials in the same Task. If those Steps need access to the credentials then they may fail as they might not have permission to access them.

This happens because, by default, /tekton/home is set to be a Step user’s home directory and Tekton makes this directory a shared volume that all Steps in a Task have access to. Any credentials initialized by one Step are overwritten by subsequent Steps also initializing credentials.

If the Steps reporting this warning do not use the credentials mentioned in the message then you can safely ignore it.

This can most easily be resolved by ensuring that each Step executing in your Task and TaskRun runs with the same UID. A blanket UID can be set with a TaskRun’s Pod template field.

If you require Steps to run with different UIDs then you should disable Tekton’s built-in credential initialization and use Workspaces to mount credentials from Secrets instead. See the section on disabling Tekton’s credential initialization.

A Workspace or Volume is also Mounted for the same credentials

A Task has mounted both a Workspace (or Volume) for credentials and the TaskRun has attached a service account with git or docker credentials that Tekton will try to initialize.

The simplest solution to this problem is to not mix credentials mounted via Workspace with those initialized using the process described in this document. See the section on disabling Tekton’s credential initialization.

A Task employs a read-only Workspace or Volume for `$HOME`

A Task has mounted a read-only Workspace (or Volume) for the user’s HOME directory and the TaskRun attaches a service account with git or docker credentials that Tekton will try to initialize.

The contents of `$HOME` are `chown`ed to a different user

A Task Step that modifies the ownership of files in the user home directory may prevent subsequent Steps from initializing credentials in that same home directory. The simplest solution to this problem is to avoid running chown on files and directories under /tekton. Another option is to run all Steps with the same UID.

The Step is named `image-digest-exporter`

If you see this warning reported specifically by an image-digest-exporter Step you can safely ignore this message. The reason it appears is that this Step is injected by Tekton and it runs with a non-root UID that can differ from those of the Steps in the Task. The Step does not use these credentials.

Disabling Tekton’s Built-In Auth

Why would an organization want to do this?

There are a number of reasons that an organization may want to disable Tekton’s built-in credential handling:

The mechanism can be quite difficult to debug.
There are an extremely limited set of supported credential types.
Tasks with Steps that have different UIDs can break if multiple Steps are trying to share access to the same credentials.
Tasks with Steps that have different UIDs can log more warning messages, creating more noise in TaskRun logs. Again this is because multiple Steps with differing UIDs cannot share access to the same credential files.

What are the effects of making this change?

Credentials must now be passed explicitly to Tasks either with Workspaces, environment variables (using envFrom in your Steps and a Task param to specify a Secret), or a custom volume and volumeMount definition.

How to disable the built-in auth

To disable Tekton’s built-in auth, edit the feature-flag ConfigMap in the tekton-pipelines namespace and update the value of disable-creds-init from "false" to "true".

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Events in Tekton

Tekton’s controllers emits Kubernetes events when TaskRuns and PipelineRuns execute. This allows you to monitor and react to what’s happening during execution by retrieving those events using the kubectl describe command. Tekton can also emit CloudEvents.

Note: Conditions do not emit events but the underlying TaskRun do.

Events in `TaskRuns`

TaskRuns emit events for the following Reasons:

Started: emitted the first time the TaskRun is picked by the reconciler from its work queue, so it only happens if webhook validation was successful. This event in itself does not indicate that a Step is executing; the Step executes once the following conditions are satisfied:
- Validation of the Task and its associated resources must succeed, and
- Checks for associated Conditions must succeed, and
- Scheduling of the associated Pod must succeed.
Succeeded: emitted once all steps in the TaskRun have executed successfully, including post-steps injected by Tekton.
Failed: emitted if the TaskRun finishes running unsuccessfully because a Step failed, or the TaskRun timed out or was cancelled. A TaskRun also emits Failed events if it cannot execute at all due to failing validation.

Events in `PipelineRuns`

PipelineRuns emit events for the following Reasons:

Started: emitted the first time the PipelineRun is picked by the reconciler from its work queue, so it only happens if webhook validation was successful. This event in itself does not indicate that a Step is executing; the Step executes once validation for the Pipeline as well as all associated Tasks and Resources is successful.
Running: emitted when the PipelineRun passes validation and actually begins execution.
Succeeded: emitted once all Tasks reachable via the DAG have executed successfully.
Failed: emitted if the PipelineRun finishes running unsuccessfully because a Task failed or the PipelineRun timed out or was cancelled. A PipelineRun also emits Failed events if it cannot execute at all due to failing validation.

Events via `CloudEvents`

When you configure a sink, Tekton emits events as described in the table below.

Tekton sends cloud events in a parallel routine to allow for retries without blocking the reconciler. A routine is started every time the Succeeded condition changes - either state, reason or message. Retries are sent using an exponential back-off strategy. Because of retries, events are not guaranteed to be sent to the target sink in the order they happened.

Resource	Event	Event Type
`TaskRun`	`Started`	`dev.tekton.event.taskrun.started.v1`
`TaskRun`	`Running`	`dev.tekton.event.taskrun.running.v1`
`TaskRun`	`Condition Change while Running`	`dev.tekton.event.taskrun.unknown.v1`
`TaskRun`	`Succeed`	`dev.tekton.event.taskrun.successful.v1`
`TaskRun`	`Failed`	`dev.tekton.event.taskrun.failed.v1`
`PipelineRun`	`Started`	`dev.tekton.event.pipelinerun.started.v1`
`PipelineRun`	`Running`	`dev.tekton.event.pipelinerun.running.v1`
`PipelineRun`	`Condition Change while Running`	`dev.tekton.event.pipelinerun.unknown.v1`
`PipelineRun`	`Succeed`	`dev.tekton.event.pipelinerun.successful.v1`
`PipelineRun`	`Failed`	`dev.tekton.event.pipelinerun.failed.v1`
`Run`	`Started`	`dev.tekton.event.run.started.v1`
`Run`	`Running`	`dev.tekton.event.run.running.v1`
`Run`	`Succeed`	`dev.tekton.event.run.successful.v1`
`Run`	`Failed`	`dev.tekton.event.run.failed.v1`

CloudEvents for Runs are only sent when enabled in the configuration.

Note: CloudEvents for Runs rely on an ephemeral cache to avoid duplicate events. In case of controller restart, the cache is reset and duplicate events may be sent.

Format of `CloudEvents`

According to the CloudEvents spec, HTTP headers are included to match the context fields. For example:

"Ce-Id": "77f78ae7-ff6d-4e39-9d05-b9a0b7850527",
"Ce-Source": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk",
"Ce-Specversion": "1.0",
"Ce-Subject": "curl-run-6gplk",
"Ce-Time": "2021-01-29T14:47:58.157819Z",
"Ce-Type": "dev.tekton.event.taskrun.unknown.v1",

Other HTTP headers are:

"Accept-Encoding": "gzip",
"Connection": "close",
"Content-Length": "3519",
"Content-Type": "application/json",
"User-Agent": "Go-http-client/1.1"

The payload is JSON, a map with a single root key taskRun or pipelineRun, depending on the source of the event. Inside the root key, the whole spec and status of the resource is included. For example:

{
  "taskRun": {
    "metadata": {
      "annotations": {
        "pipeline.tekton.dev/release": "v0.20.1",
        "tekton.dev/pipelines.minVersion": "0.12.1",
        "tekton.dev/tags": "search"
      },
      "creationTimestamp": "2021-01-29T14:47:57Z",
      "generateName": "curl-run-",
      "generation": 1,
      "labels": {
        "app.kubernetes.io/managed-by": "tekton-pipelines",
        "app.kubernetes.io/version": "0.1",
        "tekton.dev/task": "curl"
      },
      "managedFields": "(...)",
      "name": "curl-run-6gplk",
      "namespace": "default",
      "resourceVersion": "156770",
      "selfLink": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/curl-run-6gplk",
      "uid": "4ccb4f01-3ecc-4eb4-87e1-76f04efeee5c"
    },
    "spec": {
      "params": [
        {
          "name": "url",
          "value": "https://artifacthub.io/packages/tekton-task/tekton-catalog-tasks/git-clone"
        }
      ],
      "resources": {},
      "serviceAccountName": "default",
      "taskRef": {
        "kind": "Task",
        "name": "curl"
      },
      "timeout": "1h0m0s"
    },
    "status": {
      "conditions": [
        {
          "lastTransitionTime": "2021-01-29T14:47:58Z",
          "message": "pod status \"Initialized\":\"False\"; message: \"containers with incomplete status: [place-tools]\"",
          "reason": "Pending",
          "status": "Unknown",
          "type": "Succeeded"
        }
      ],
      "podName": "curl-run-6gplk-pod",
      "startTime": "2021-01-29T14:47:57Z",
      "steps": [
        {
          "container": "step-curl",
          "name": "curl",
          "waiting": {
            "reason": "PodInitializing"
          }
        }
      ],
      "taskSpec": {
        "description": "This task performs curl operation to transfer data from internet.",
        "params": [
          {
            "description": "URL to curl'ed",
            "name": "url",
            "type": "string"
          },
          {
            "default": [],
            "description": "options of url",
            "name": "options",
            "type": "array"
          },
          {
            "default": "docker.io/curlimages/curl:7.72.0@sha256:3c3ff0c379abb1150bb586c7d55848ed4dcde4a6486b6f37d6815aed569332fe",
            "description": "option of curl image",
            "name": "curl-image",
            "type": "string"
          }
        ],
        "steps": [
          {
            "args": [
              "$(params.options[*])",
              "$(params.url)"
            ],
            "command": [
              "curl"
            ],
            "image": "$(params.curl-image)",
            "name": "curl",
            "resources": {}
          }
        ]
      }
    }
  }
}

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Execution Logs

Tekton stores execution logs for TaskRuns and PipelineRuns within the Pod holding the containers that run the Steps for your TaskRun or PipelineRun.

You can get execution logs using one of the following methods:

Get the logs directly from the Pod. For example, you can use the kubectl as follows:

# Get the Pod name from the TaskRun instance.
kubectl get taskruns -o yaml | grep podName

# Or, get the Pod name from the PipelineRun.
kubectl get pipelineruns -o yaml | grep podName

# Get the logs for all containers in the Pod.
kubectl logs $POD_NAME --all-containers

# Or, get the logs for a specific container in the Pod.
kubectl logs $POD_NAME -c $CONTAINER_NAME
kubectl logs $POD_NAME -c step-run-kubectl

Get the logs using Tekton’s tkn CLI.
Get the logs using Tekton Dashboard.
Configure an external service to consume and display the logs. For example, ElasticSearch, Beats, and Kibana.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Pipeline Controller Metrics

The following pipeline metrics are available at controller-service on port 9090.

We expose several kinds of exporters, including Prometheus, Google Stackdriver, and many others. You can set them up using observability configuration.

Name	Type	Labels/Tags	Status
`tekton_pipelines_controller_pipelinerun_duration_seconds_[bucket, sum, count]`	Histogram/LastValue(Gauge)	`pipeline`=<pipeline_name> `pipelinerun`=<pipelinerun_name> `status`=<status> `namespace`=<pipelinerun-namespace>	experimental
`tekton_pipelines_controller_pipelinerun_taskrun_duration_seconds_[bucket, sum, count]`	Histogram/LastValue(Gauge)	`pipeline`=<pipeline_name> `pipelinerun`=<pipelinerun_name> `status`=<status> `task`=<task_name> `taskrun`=<taskrun_name> `namespace`=<pipelineruns-taskruns-namespace> `*reason`=<reason>	experimental
`tekton_pipelines_controller_pipelinerun_total`	Counter	`status`=<status>	experimental
`tekton_pipelines_controller_running_pipelineruns`	Gauge		experimental
`tekton_pipelines_controller_taskrun_duration_seconds_[bucket, sum, count]`	Histogram/LastValue(Gauge)	`status`=<status> `task`=<task_name> `taskrun`=<taskrun_name> `namespace`=<pipelineruns-taskruns-namespace> `*reason`=<reason>	experimental
`tekton_pipelines_controller_taskrun_total`	Counter	`status`=<status>	experimental
`tekton_pipelines_controller_running_taskruns`	Gauge		experimental
`tekton_pipelines_controller_running_taskruns_throttled_by_quota`	Gauge	`namespace`=<pipelinerun-namespace>	experimental
`tekton_pipelines_controller_running_taskruns_throttled_by_node`	Gauge	`namespace`=<pipelinerun-namespace>	experimental
`tekton_pipelines_controller_client_latency_[bucket, sum, count]`	Histogram		experimental

The Labels/Tag marked as “*” are optional. And there’s a choice between Histogram and LastValue(Gauge) for pipelinerun and taskrun duration metrics.

Configuring Metrics using `config-observability` configmap

A sample config-map has been provided as config-observability. By default, taskrun and pipelinerun metrics have these values:

    metrics.taskrun.level: "task"
    metrics.taskrun.duration-type: "histogram"
    metrics.pipelinerun.level: "pipeline"
    metrics.running-pipelinerun.level: ""
    metrics.pipelinerun.duration-type: "histogram"
    metrics.count.enable-reason: "false"

Following values are available in the configmap:

configmap data	value	description
metrics.taskrun.level	`taskrun`	Level of metrics is taskrun
metrics.taskrun.level	`task`	Level of metrics is task and taskrun label isn’t present in the metrics
metrics.taskrun.level	`namespace`	Level of metrics is namespace, and task and taskrun label isn’t present in the metrics
metrics.pipelinerun.level	`pipelinerun`	Level of metrics is pipelinerun
metrics.pipelinerun.level	`pipeline`	Level of metrics is pipeline and pipelinerun label isn’t present in the metrics
metrics.pipelinerun.level	`namespace`	Level of metrics is namespace, pipeline and pipelinerun label isn’t present in the metrics
metrics.running-pipelinerun.level	`pipelinerun`	Level of running-pipelinerun metrics is pipelinerun
metrics.running-pipelinerun.level	`pipeline`	Level of running-pipelinerun metrics is pipeline and pipelinerun label isn’t present in the metrics
metrics.running-pipelinerun.level	`namespace`	Level of running-pipelinerun metrics is namespace, pipeline and pipelinerun label isn’t present in the metrics
metrics.running-pipelinerun.level	``	Level of running-pipelinerun metrics is cluster, namespace, pipeline and pipelinerun label isn’t present in the metrics.
metrics.taskrun.duration-type	`histogram`	`tekton_pipelines_controller_pipelinerun_taskrun_duration_seconds` and `tekton_pipelines_controller_taskrun_duration_seconds` is of type histogram
metrics.taskrun.duration-type	`lastvalue`	`tekton_pipelines_controller_pipelinerun_taskrun_duration_seconds` and `tekton_pipelines_controller_taskrun_duration_seconds` is of type gauge or lastvalue
metrics.pipelinerun.duration-type	`histogram`	`tekton_pipelines_controller_pipelinerun_duration_seconds` is of type histogram
metrics.pipelinerun.duration-type	`lastvalue`	`tekton_pipelines_controller_pipelinerun_duration_seconds` is of type gauge or lastvalue
metrics.count.enable-reason	`false`	Sets if the `reason` label should be included on count metrics
metrics.taskrun.throttle.enable-namespace	`false`	Sets if the `namespace` label should be included on the `tekton_pipelines_controller_running_taskruns_throttled_by_quota` metric

Histogram value isn’t available when pipelinerun or taskrun labels are selected. The Lastvalue or Gauge will be provided. Histogram would serve no purpose because it would generate a single bar. TaskRun and PipelineRun level metrics aren’t recommended because they lead to an unbounded cardinality which degrades the observability database.

To check that appropriate values have been applied in response to configmap changes, use the following commands:

kubectl port-forward -n tekton-pipelines service/tekton-pipelines-controller 9090

And then check that changes have been applied to metrics coming from http://127.0.0.1:9090/metrics

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Labels and Annotations

Tekton allows you to use custom Kubernetes Labels to easily mark Tekton entities belonging to the same conceptual execution chain. Tekton also automatically adds select labels to more easily identify resource relationships. This document describes the label propagation scheme, automatic labeling, and provides usage examples.

Label propagation

Labels propagate among Tekton entities as follows:

For Pipelines instantiated using a PipelineRun, labels propagate automatically from Pipelines to PipelineRuns to TaskRuns, and then to the associated Pods. If a label is present in both Pipeline and PipelineRun, the label in PipelineRun takes precedence.
Labels from Tasks referenced by TaskRuns within a PipelineRun propagate to the corresponding TaskRuns, and then to the associated Pods. As for Pipeline and PipelineRun, if a label is present in both Task and TaskRun, the label in TaskRun takes precedence.
For standalone TaskRuns (that is, ones not executing as part of a Pipeline), labels propagate from the referenced Task, if one exists, to the corresponding TaskRun, and then to the associated Pod. The same as above applies.

Automatic labeling

Tekton automatically adds labels to Tekton entities as described in the following table.

Note: *.tekton.dev labels are reserved for Tekton’s internal use only. Do not add or remove them manually.

Label	Added To	Propagates To	Contains
`tekton.dev/pipeline`	`PipelineRuns`	`TaskRuns, Pods`	Name of the `Pipeline` that the `PipelineRun` references.
`tekton.dev/pipelineRun`	`TaskRuns` that are created automatically during the execution of a `PipelineRun`.	`TaskRuns, Pods`	Name of the `PipelineRun` that triggered the creation of the `TaskRun`.
`tekton.dev/task`	`TaskRuns` that reference an existing Task.	`Pods`	Name of the `Task` that the `TaskRun` references.
`tekton.dev/taskRun`	`Pods`	No propagation.	Name of the `TaskRun` that created the `Pod`.
`tekton.dev/memberOf`	`TaskRuns` that are created automatically during the execution of a `PipelineRun`.	`TaskRuns, Pods`	`tasks` or `finally` depending on the `PipelineTask`'s membership in the `Pipeline`.
`app.kubernetes.io/instance`, `app.kubernetes.io/component`	`Pods`, `StatefulSets` (Affinity Assistant)	No propagation.	`Pod` affinity values for `TaskRuns`.

Usage examples

Below are some examples of using labels:

The following command finds all Pods created by a PipelineRun named test-pipelinerun:

kubectl get pods --all-namespaces -l tekton.dev/pipelineRun=test-pipelinerun

The following command finds all TaskRuns that reference a Task named test-task:

kubectl get taskruns --all-namespaces -l tekton.dev/task=test-task

Annotations propagation

Annotation propagate among Tekton entities as follows (similar to Labels):

For Pipelines instantiated using a PipelineRun, annotations propagate automatically from Pipelines to PipelineRuns to TaskRuns, and then to the associated Pods. If a annotation is present in both Pipeline and PipelineRun, the annotation in PipelineRun takes precedence.
Annotations from Tasks referenced by TaskRuns within a PipelineRun propagate to the corresponding TaskRuns, and then to the associated Pods. As for Pipeline and PipelineRun, if a annotation is present in both Task and TaskRun, the annotation in TaskRun takes precedence.
For standalone TaskRuns (that is, ones not executing as part of a Pipeline), annotations propagate from the referenced Task, if one exists, to the corresponding TaskRun, and then to the associated Pod. The same as above applies.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Windows

Overview

If you need a Windows environment as part of a Tekton Task or Pipeline, you can include Windows container images in your Task steps. Because Windows containers can only run on a Windows host, you will need to have Windows nodes available in your Kubernetes cluster. You should read Windows support in Kubernetes to understand the functionality and limitations of Kubernetes on Windows.

Some important things to note about Windows containers and Kubernetes:

Windows containers cannot run on a Linux host.
Kubernetes does not support Windows only clusters. The Kubernetes control plane components can only run on Linux.
Kubernetes currently only supports process isolated containers, which means a container’s base image OS version must match that of the host OS. See Windows container version compatibility for more information.
A Kubernetes Pod cannot contain both Windows and Linux containers.

Some important things to note about Windows support in Tekton:

A Task can only have Windows or Linux containers, but not both.
A Pipeline can contain both Windows and Linux Tasks.
In a mixed-OS cluster, TaskRuns and PipelineRuns will need to be scheduled to the correct node using one of the methods described below.
Tekton’s controller components can only run on Linux nodes.

Scheduling Tasks on Windows Nodes

In order to ensure that Tasks are scheduled to a node with the correct host OS, you will need to update the TaskRun or PipelineRun spec with rules to define this behaviour. This can be done in a couple of different ways, but the simplest option is to specify a node selector.

Node Selectors

Node selectors are the simplest way to schedule pods to a Windows or Linux node. By default, Kubernetes nodes include a label kubernetes.io/os to identify the host OS. The Kubelet populates this with runtime.GOOS as defined by Go. Use spec.podTemplate.nodeSelector (or spec.taskRunSpecs[i].podTemplate.nodeSelector in a PipelineRun) to schedule Tasks to a node with a specific label and value.

For example:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: windows-taskrun
spec:
  taskRef:
    name: windows-task
  podTemplate:
    nodeSelector:
      kubernetes.io/os: windows
---
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: linux-taskrun
spec:
  taskRef:
    name: linux-task
  podTemplate:
    nodeSelector:
      kubernetes.io/os: linux

Node Affinity

Node affinity can be used as an alternative method of defining the OS requirement of a Task. These rules can be set under spec.podTemplate.affinity.nodeAffinity in a TaskRun definition. The example below produces the same result as the previous example which used node selectors.

For example:

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: windows-taskrun
spec:
  taskRef:
    name: windows-task
  podTemplate:
    affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                - key: kubernetes.io/os
                  operator: In
                  values:
                  - windows
---
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: linux-taskrun
spec:
  taskRef:
    name: linux-task
  podTemplate:
    affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                - key: kubernetes.io/os
                  operator: In
                  values:
                  - linux

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Pipeline Remote Resolution

Remote Resolution is a Tekton beta feature that allows users to fetch tasks and pipelines from remote sources outside the cluster. Tekton provides a few built-in resolvers that can fetch from git repositories, OCI registries etc as well as a framework for writing custom resolvers.

Remote Resolution was initially created as a separate project in TEP-060 and migrated into the core pipelines project in #4710.

Getting Started Tutorial

For new users getting started with Tekton Pipeline remote resolution, check out the resolution-getting-started.md tutorial.

Configuring Built-in Resolvers

These resolvers are enabled by setting the appropriate feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace. See the section in install.md for details.

The default resolver type can be configured by the default-resolver-type field in the config-defaults ConfigMap (alpha feature). See additional-configs.md for details.

Developer Howto: Writing a Resolver From Scratch

For a developer getting started with writing a new Resolver, see how-to-write-a-resolver.md and the accompanying resolver-template.

Resolver Reference: The interfaces and methods to implement

For a table of the interfaces and methods a resolver must implement along with those that are optional, see resolver-reference.md.

Resolver Cache Configuration

The resolver cache is used to improve performance by caching resolved resources for bundle and git resolver. By default, the cache uses:

5 minutes (“5m”) as the time-to-live (TTL) for cache entries
1000 entries as the maximum cache size

You can override these defaults by editing the resolver-cache-config.yaml ConfigMap in the tekton-pipelines-resolvers namespace. Set the following keys:

max-size: Set the maximum number of cache entries (e.g., “500”)
default-ttl: Set the default TTL for cache entries (e.g., “10m”, “30s”)

If these values are missing or invalid, the defaults will be used.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Bundles Resolver

Resolver Type

This Resolver responds to type bundles.

Parameters

Param Name	Description	Example Value
`secret`	The name of the secret to use when constructing registry credentials	`default`
`bundle`	The bundle url pointing at the image to fetch	`gcr.io/tekton-releases/catalog/upstream/golang-build:0.1`
`name`	The name of the resource to pull out of the bundle	`golang-build`
`kind`	The resource kind to pull out of the bundle	`task`
`cache`	Controls caching behavior for the resolved resource	`always`, `never`, `auto`

Requirements

A cluster running Tekton Pipeline v0.41.0 or later.
The built-in remote resolvers installed.
The enable-bundles-resolver feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace set to true.
Beta features enabled.

Configuration

This resolver uses a ConfigMap for its settings. See ../config/resolvers/bundleresolver-config.yaml for the name, namespace and defaults that the resolver ships with.

Options

Option Name	Description	Example Values
`backoff-duration`	The initial duration for a backoff.	`500ms`, `2s`
`backoff-factor`	The factor by which the sleep duration increases every step.	`2.5`, `4.0`
`backoff-jitter`	A random amount of additioan sleep between 0 andduration * jitter.	`0.1`, `0.5`
`backoff-steps`	The number of backoffs to attempt.	`3`, `7`
`backoff-cap`	The maxumum backoff duration. If reached, remaining steps are zeroed.	`10s`, `20s`
`default-kind`	The default layer kind in the bundle image.	`task`, `pipeline`

Caching Options

The bundle resolver supports caching of resolved resources to improve performance. The caching behavior can be configured using the cache option:

Cache Value	Description
`always`	Always cache resolved resources. This is the most aggressive caching strategy and will cache all resolved resources regardless of their source.
`never`	Never cache resolved resources. This disables caching completely.
`auto`	Caching will only occur for bundles pulled by digest. (default)

Cache Configuration

The resolver cache can be configured globally using the resolver-cache-config ConfigMap. This ConfigMap controls the cache size and TTL (time-to-live) for all resolvers.

Option Name	Description	Default Value	Example Values
`max-size`	Maximum number of entries in the cache	`1000`	`500`, `2000`
`ttl`	Time-to-live for cache entries	`5m`	`10m`, `1h`

The ConfigMap name can be customized using the RESOLVER_CACHE_CONFIG_MAP_NAME environment variable. If not set, it defaults to resolver-cache-config.

Additionally, you can set a default cache mode for the bundle resolver by adding the default-cache-mode option to the bundleresolver-config ConfigMap. This overrides the system default (auto) for this resolver:

Option Name	Description	Valid Values	Default
`default-cache-mode`	Default caching behavior when `cache` parameter is not specified	`always`, `never`, `auto`	`auto`

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: bundleresolver-config
  namespace: tekton-pipelines-resolvers
data:
  default-cache-mode: "always"  # Always cache unless task/pipeline specifies otherwise

Usage

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828
    - name: name
      value: hello-world
    - name: kind
      value: task

Pipeline Resolution

Unfortunately the Tekton Catalog does not publish pipelines at the moment. Here’s an example PipelineRun that talks to a private registry but won’t work unless you tweak the bundle field to point to a registry with a pipeline in it:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: bundle-demo
spec:
  pipelineRef:
    resolver: bundles
    params:
    - name: bundle
      value: 10.96.190.208:5000/simple/pipeline:latest
    - name: name
      value: hello-pipeline
    - name: kind
      value: pipeline
  params:
  - name: username
    value: "tekton pipelines"

`ResolutionRequest` Status

ResolutionRequest.Status.RefSource field captures the source where the remote resource came from. It includes the 3 subfields: url, digest and entrypoint.

uri: The image repository URI
digest: The map of the algorithm portion -> the hex encoded portion of the image digest.
entrypoint: The resource name in the OCI bundle image.

Example:

TaskRun Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: gcr.io/tekton-releases/catalog/upstream/git-clone:0.7
    - name: name
      value: git-clone
    - name: kind
      value: task
  params:
    - name: url
      value: https://github.com/octocat/Hello-World
  workspaces:
    - name: output
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 500Mi

ResolutionRequest

apiVersion: resolution.tekton.dev/v1beta1
kind: ResolutionRequest
metadata:
  ...
  labels:
    resolution.tekton.dev/type: bundles
  name: bundles-21ad80ec13f3e8b73fed5880a64d4611
  ...
spec:
  params:
  - name: bundle
    value: gcr.io/tekton-releases/catalog/upstream/git-clone:0.7
  - name: name
    value: git-clone
  - name: kind
    value: task
status:
  annotations: ...
  ...
  data: xxx
  observedGeneration: 1
  refSource:
    digest:
      sha256: f51ca50f1c065acba8290ef14adec8461915ecc5f70a8eb26190c6e8e0ededaf
    entryPoint: git-clone
    uri: gcr.io/tekton-releases/catalog/upstream/git-clone

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Simple Git Resolver

Resolver Type

This Resolver responds to type git.

Parameters

Param Name	Description	Example Value
`url`	URL of the repo to fetch and clone anonymously. Either `url`, or `repo` (with `org`) must be specified, but not both.	`https://github.com/tektoncd/catalog.git`
`repo`	The repository to find the resource in. Either `url`, or `repo` (with `org`) must be specified, but not both.	`pipeline`, `test-infra`
`org`	The organization to find the repository in. Default can be set in configuration.	`tektoncd`, `kubernetes`
`token`	An optional secret name in the `PipelineRun` namespace to fetch the token from. Defaults to empty, meaning it will try to use the configuration from the global configmap.	`secret-name`, (empty)
`tokenKey`	An optional key in the token secret name in the `PipelineRun` namespace to fetch the token from. Defaults to `token`.	`token`
`gitToken`	An optional secret name in the `PipelineRun` namespace to fetch the token from when doing opration with the `git clone`. When empty it will use anonymous cloning.	`secret-gitauth-token`
`gitTokenKey`	An optional key in the token secret name in the `PipelineRun` namespace to fetch the token from when using the `git clone`. Defaults to `token`.	`token`
`revision`	Git revision to checkout a file from. This can be commit SHA, branch or tag.	`aeb957601cf41c012be462827053a21a420befca` `main` `v0.38.2`
`pathInRepo`	Where to find the file in the repo.	`task/golang-build/0.3/golang-build.yaml`
`serverURL`	An optional server URL (that includes the https:// prefix) to connect for API operations	`https:/github.mycompany.com`
`scmType`	An optional SCM type to use for API operations	`github`, `gitlab`, `gitea`
`cache`	Controls caching behavior for the resolved resource	`always`, `never`, `auto`

Requirements

A cluster running Tekton Pipeline v0.41.0 or later.
The built-in remote resolvers installed.
The enable-git-resolver feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace set to true.
Beta features enabled.

Configuration

This resolver uses a ConfigMap for its settings. See ../config/resolvers/git-resolver-config.yaml for the name, namespace and defaults that the resolver ships with.

Options

Option Name	Description	Example Values
`default-revision`	The default git revision to use if none is specified	`main`
`fetch-timeout`	The maximum time any single git clone resolution may take. Note: a global maximum timeout of 1 minute is currently enforced on all resolution requests.	`1m`, `2s`, `700ms`
`default-url`	The default git repository URL to use for anonymous cloning if none is specified.	`https://github.com/tektoncd/catalog.git`
`scm-type`	The SCM provider type. Required if using the authenticated API with `org` and `repo`.	`github`, `gitlab`, `gitea`, `bitbucketcloud`, `bitbucketserver`
`server-url`	The SCM provider’s base URL for use with the authenticated API. Not needed if using github.com, gitlab.com, or BitBucket Cloud	`api.internal-github.com`
`api-token-secret-name`	The Kubernetes secret containing the SCM provider API token. Required if using the authenticated API with `org` and `repo`.	`bot-token-secret`
`api-token-secret-key`	The key within the token secret containing the actual secret. Required if using the authenticated API with `org` and `repo`.	`oauth`, `token`
`api-token-secret-namespace`	The namespace containing the token secret, if not `default`.	`other-namespace`
`default-org`	The default organization to look for repositories under when using the authenticated API, if not specified in the resolver parameters. Optional.	`tektoncd`, `kubernetes`

Caching Options

The git resolver supports caching of resolved resources to improve performance. The caching behavior can be configured using the cache option:

Cache Value	Description
`always`	Always cache resolved resources. This is the most aggressive caching strategy and will cache all resolved resources regardless of their source.
`never`	Never cache resolved resources. This disables caching completely.
`auto`	Caching will only occur when revision is a commit hash. (default)

Cache Configuration

The resolver cache can be configured globally using the resolver-cache-config ConfigMap. This ConfigMap controls the cache size and TTL (time-to-live) for all resolvers.

Option Name	Description	Default Value	Example Values
`max-size`	Maximum number of entries in the cache	`1000`	`500`, `2000`
`ttl`	Time-to-live for cache entries	`5m`	`10m`, `1h`

The ConfigMap name can be customized using the RESOLVER_CACHE_CONFIG_MAP_NAME environment variable. If not set, it defaults to resolver-cache-config.

Additionally, you can set a default cache mode for the git resolver by adding the default-cache-mode option to the git-resolver-config ConfigMap. This overrides the system default (auto) for this resolver:

Option Name	Description	Valid Values	Default
`default-cache-mode`	Default caching behavior when `cache` parameter is not specified	`always`, `never`, `auto`	`auto`

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: git-resolver-config
  namespace: tekton-pipelines-resolvers
data:
  default-cache-mode: "always"  # Always cache unless task/pipeline specifies otherwise

Usage

The git resolver has two modes: cloning a repository with git clone (with the go-git library), or fetching individual files via an SCM provider’s API using an API token.

The differences between the two modes are:

The git clone method support anonymous cloning and authenticated cloning.
When it comes to throughput, git clone is a more efficient option because it is not subject to the same rate limits as API calls. This is a key difference between the two modes: git clone supports both anonymous and authenticated cloning, and depending on the Git provider, it often has a higher rate limit compared to authenticated API calls.
The git clone method is inefficient for larger repositories, as it clones the entire repository in memory, whereas the authenticated API fetches only the files at the specified path.

Git Clone with git clone

Git clone with git clone is supported for anonymous and authenticated cloning. This mode shallow clones the git repo before fetching and checking out the provided revision.

Note: if the revision is a commit SHA which is not pointed-at by a Branch or Tag ref, the revision might not be able to be fetched, depending on the git provider’s uploadpack.allowReachableSHA1InWant setting. This is not an issue for major git providers such as Github and Gitlab, but may be of note for smaller or self-hosted providers such as Gitea.

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-clone-demo-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml
    # Uncomment the following lines to use a secret with a token
    # - name: gitToken
    #   value: "secret-with-token"
    # - name: gitTokenKey (optional, defaults to "token")
    #   value: "token"

Pipeline resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: git-clone-demo-pr
spec:
  pipelineRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/tektoncd/catalog.git
    - name: revision
      value: main
    - name: pathInRepo
      value: pipeline/simple/0.1/simple.yaml
    # Uncomment the following lines to use a secret with a token
    # - name: gitToken
    #   value: "secret-with-token"
    # - name: gitTokenKey (optional, defaults to "token")
    #   value: "token"
  params:
  - name: name
    value: Ranni

Authenticated API

The authenticated API supports private repositories, and fetches only the file at the specified path rather than doing a full clone.

When using the authenticated API, providers with implementations in go-scm can be used. Note that not all go-scm implementations have been tested with the git resolver, but it is known to work with:

github.com and GitHub Enterprise
gitlab.com and self-hosted Gitlab
Gitea
BitBucket Server
BitBucket Cloud

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-api-demo-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml

Task Resolution with a custom token to a custom SCM provider

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-api-demo-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml
    # my-secret-token should be created in the namespace where the
    # pipelinerun is created and contain a GitHub personal access
    # token in the token key of the secret.
    - name: token
      value: my-secret-token
    - name: tokenKey
      value: token
    - name: scmType
      value: github
    - name: serverURL
      value: https://ghe.mycompany.com

Pipeline resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: git-api-demo-pr
spec:
  pipelineRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: pipeline/simple/0.1/simple.yaml
  params:
  - name: name
    value: Ranni

Specifying Configuration for Multiple Git Providers

It is possible to specify configurations for multiple providers and even multiple configurations for same provider to use in different tekton resources. Firstly, details need to be added in configmap with the unique identifier key prefix. To use them in tekton resources, pass the unique key mentioned in configmap as an extra param to resolver with key configKey and value will be the unique key. If no configKey param is passed, default will be used. Default configuration to be used for git resolver can be specified in configmap by either mentioning no unique identifier or using identifier default

Note: configKey should not contain . while specifying configurations in configmap

Example Configmap

Multiple configurations can be specified in git-resolver-config configmap like this. All keys mentioned above are supported.

apiVersion: v1
kind: ConfigMap
metadata:
  name: git-resolver-config
  namespace: tekton-pipelines-resolvers
  labels:
    app.kubernetes.io/component: resolvers
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  # configuration 1, default one to use if no configKey provided or provided with value default
  fetch-timeout: "1m"
  default-url: "https://github.com/tektoncd/catalog.git"
  default-revision: "main"
  scm-type: "github"
  server-url: ""
  api-token-secret-name: ""
  api-token-secret-key: ""
  api-token-secret-namespace: "default"
  default-org: ""

  # configuration 2, will be used if configKey param passed with value test1
  test1.fetch-timeout: "5m"
  test1.default-url: ""
  test1.default-revision: "stable"
  test1.scm-type: "github"
  test1.server-url: "api.internal-github.com"
  test1.api-token-secret-name: "test1-secret"
  test1.api-token-secret-key: "token"
  test1.api-token-secret-namespace: "test1"
  test1.default-org: "tektoncd"

  # configuration 3, will be used if configKey param passed with value test2
  test2.fetch-timeout: "10m"
  test2.default-url: ""
  test2.default-revision: "stable"
  test2.scm-type: "gitlab"
  test2.server-url: "api.internal-gitlab.com"
  test2.api-token-secret-name: "test2-secret"
  test2.api-token-secret-key: "pat"
  test2.api-token-secret-namespace: "test2"
  test2.default-org: "tektoncd-infra"

Task Resolution

A specific configurations from the configMap can be selected by passing the parameter configKey with the value matching one of the configuration keys used in the configMap.

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: git-api-demo-tr
spec:
  taskRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: task/git-clone/0.6/git-clone.yaml
    - name: configKey
      value: test1

Pipeline resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: git-api-demo-pr
spec:
  pipelineRef:
    resolver: git
    params:
    - name: org
      value: tektoncd
    - name: repo
      value: catalog
    - name: revision
      value: main
    - name: pathInRepo
      value: pipeline/simple/0.1/simple.yaml
    - name: configKey
      value: test2
  params:
  - name: name
    value: Ranni

`ResolutionRequest` Status

ResolutionRequest.Status.RefSource field captures the source where the remote resource came from. It includes the 3 subfields: url, digest and entrypoint.

url
- If users choose to use anonymous cloning, the url is just user-provided value for the url param in the SPDX download format.
- If scm api is used, it would be the clone URL of the repo fetched from scm repository service in the SPDX download format.
digest
- The algorithm name is fixed “sha1”, but subject to be changed to “sha256” once Git eventually uses SHA256 at some point later. See https://git-scm.com/docs/hash-function-transition for more details.
- The value is the actual commit sha at the moment of resolving the resource even if a user provides a tag/branch name for the param revision.
entrypoint: the user-provided value for the path param.

Example:

Pipeline Resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: git-demo
spec:
  pipelineRef:
    resolver: git
    params:
    - name: url
      value: https://github.com/<username>/<reponame>.git
    - name: revision
      value: main
    - name: pathInRepo
      value: pipeline.yaml

ResolutionRequest

apiVersion: resolution.tekton.dev/v1alpha1
kind: ResolutionRequest
metadata:
  labels:
    resolution.tekton.dev/type: git
  ...
spec:
  params:
    pathInRepo: pipeline.yaml
    revision: main
    url: https://github.com/<username>/<reponame>.git
status:
  refSource:
    uri: git+https://github.com/<username>/<reponame>.git
    digest:
      sha1: <The latest commit sha on main at the moment of resolving>
    entrypoint: pipeline.yaml
  data: a2luZDogUGxxxx...

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Cluster Resolver

Resolver Type

This Resolver responds to type cluster.

Parameters

Param Name	Description	Example Value
`kind`	The kind of resource to fetch.	`task`, `pipeline`, `stepaction`
`name`	The name of the resource to fetch.	`some-pipeline`, `some-task`
`namespace`	The namespace in the cluster containing the resource.	`default`, `other-namespace`
`cache`	Optional cache mode for the resolver.	`always`, `never`, `auto`

Cache Parameter

The cache parameter controls whether the cluster resolver caches resolved resources:

Cache Mode	Description
`always`	Always cache the resolved resource, regardless of whether it has an immutable reference.
`never`	Never cache the resolved resource.
`auto`	Cluster resolver behavior: Never cache (cluster resources lack immutable references).
(not specified)	Default behavior: Never cache (same as `auto` for cluster resolver).

Note: The cluster resolver only caches when cache: always is explicitly specified. This is because cluster resources (Tasks, Pipelines, etc.) do not have immutable references like Git commit hashes or bundle digests, making automatic caching unreliable.

Cache Configuration

The resolver cache can be configured globally using the resolver-cache-config ConfigMap. This ConfigMap controls the cache size and TTL (time-to-live) for all resolvers.

Option Name	Description	Default Value	Example Values
`max-size`	Maximum number of entries in the cache	`1000`	`500`, `2000`
`ttl`	Time-to-live for cache entries	`5m`	`10m`, `1h`

The ConfigMap name can be customized using the RESOLVER_CACHE_CONFIG_MAP_NAME environment variable. If not set, it defaults to resolver-cache-config.

Additionally, you can set a default cache mode for the cluster resolver by adding the default-cache-mode option to the cluster-resolver-config ConfigMap. This overrides the system default (auto) for this resolver:

Option Name	Description	Valid Values	Default
`default-cache-mode`	Default caching behavior when `cache` parameter is not specified	`always`, `never`, `auto`	`auto`

Example:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-resolver-config
  namespace: tekton-pipelines-resolvers
data:
  default-cache-mode: "never"  # Never cache by default (since cluster resources are mutable)

Requirements

A cluster running Tekton Pipeline v0.41.0 or later.
The built-in remote resolvers installed.
The enable-cluster-resolver feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace set to true.
Beta features enabled.

Configuration

This resolver uses a ConfigMap for its settings. See ../config/resolvers/cluster-resolver-config.yaml for the name, namespace and defaults that the resolver ships with.

Options

Option Name	Description	Example Values
`default-kind`	The default resource kind to fetch if not specified in parameters.	`task`, `pipeline`, `stepaction`
`default-namespace`	The default namespace to fetch resources from if not specified in parameters.	`default`, `some-namespace`
`allowed-namespaces`	An optional comma-separated list of namespaces which the resolver is allowed to access. Defaults to empty, meaning all namespaces are allowed.	`default,some-namespace`, (empty)
`blocked-namespaces`	An optional comma-separated list of namespaces which the resolver is blocked from accessing. If the value is a `*` all namespaces will be disallowed and allowed namespace will need to be explicitely listed in `allowed-namespaces`. Defaults to empty, meaning all namespaces are allowed.	`default,other-namespace`, `*`, (empty)

Usage

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: some-task
    - name: namespace
      value: namespace-containing-task

Task Resolution with Caching

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference-cached
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: some-task
    - name: namespace
      value: namespace-containing-task
    - name: cache
      value: always

Task Resolution without Caching

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference-no-cache
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: some-task
    - name: namespace
      value: namespace-containing-task
    - name: cache
      value: never

StepAction Resolution

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: remote-stepaction-reference
spec:
  steps:
  - name: step-action-example
    ref
      resolver: cluster
      params:
      - name: kind
        value: stepaction
      - name: name
        value: some-stepaction
      - name: namespace
        value: namespace-containing-stepaction

Pipeline resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: remote-pipeline-reference
spec:
  pipelineRef:
    resolver: cluster
    params:
    - name: kind
      value: pipeline
    - name: name
      value: some-pipeline
    - name: namespace
      value: namespace-containing-pipeline

`ResolutionRequest` Status

ResolutionRequest.Status.RefSource field captures the source where the remote resource came from. It includes the 3 subfields: url, digest and entrypoint.

url: url is the unique full identifier for the resource in the cluster. It is in the format of <resource uri>@<uid>. Resource URI part is the namespace-scoped uri i.e. /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME. See K8s Resource URIs for more details.
digest: hex-encoded sha256 checksum of the content in the in-cluster resource’s spec field. The reason why it’s the checksum of the spec content rather than the whole object is because the metadata of in-cluster resources might be modified i.e. annotations. Therefore, the checksum of the spec content should be sufficient for source verifiers to verify if things have been changed maliciously even though the metadata is modified with good intentions.
entrypoint: empty because the path information is already available in the url field.

Example:

TaskRun Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: cluster-demo
spec:
  taskRef:
    resolver: cluster
    params:
    - name: kind
      value: task
    - name: name
      value: a-simple-task
    - name: namespace
      value: default

ResolutionRequest

apiVersion: resolution.tekton.dev/v1beta1
kind: ResolutionRequest
metadata:
  labels:
    resolution.tekton.dev/type: cluster
  name: cluster-7a04be6baa3eeedd232542036b7f3b2d
  namespace: default
  ownerReferences: ...
spec:
  params:
  - name: kind
    value: task
  - name: name
    value: a-simple-task
  - name: namespace
    value: default
status:
  annotations: ...
  conditions: ...
  data: xxx
  refSource:
    digest:
      sha256: 245b1aa918434cc8195b4d4d026f2e43df09199e2ed31d4dfd9c2cbea1c7ce54
    uri: /apis/tekton.dev/v1beta1/namespaces/default/task/a-simple-task@3b82d8c4-f89e-47ea-a49d-3be0dca4c038

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

HTTP Resolver

This resolver responds to type http.

Parameters

Param Name	Description	Example Value
`url`	The URL to fetch from	https://raw.githubusercontent.com/tektoncd-catalog/git-clone/main/task/git-clone/git-clone.yaml
`http-username`	An optional username when fetching a task with credentials (need to be used in conjunction with `http-password-secret`)	`git`
`http-password-secret`	An optional secret in the PipelineRun namespace with a reference to a password when fetching a task with credentials (need to be used in conjunction with `http-username`)	`http-password`
`http-password-secret-key`	An optional key in the `http-password-secret` to be used when fetching a task with credentials	Default: `password`
`digest`	An optional digest to verify the integrity of the fetched content. The value must be in the format `<algorithm>:<hash>`, where the supported algorithms are `sha256` and `sha512`.	`sha256:f37cdd0e86...`

You can calculate the hash of your Tekton resource using the following command:

# Calculate sha256 digest
curl -sL https://raw.githubusercontent.com/owner/private-repo/main/task/task.yaml | sha256sum

# Calculate sha512 digest
curl -sL https://raw.githubusercontent.com/owner/private-repo/main/task/task.yaml | sha512sum


`sha265sum` and `sha512sum` are available on all major Linux distributions and macOS

A valid URL must be provided. Only HTTP or HTTPS URLs are supported.

Requirements

A cluster running Tekton Pipeline v0.41.0 or later.
The built-in remote resolvers installed.
The enable-http-resolver feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace set to true.
Beta features enabled.

Configuration

This resolver uses a ConfigMap for its settings. See ../config/resolvers/http-resolver-config.yaml for the name, namespace and defaults that the resolver ships with.

Options

Option Name	Description	Example Values
`fetch-timeout`	The maximum time any fetching of URL resolution may take. Note: a global maximum timeout of 1 minute is currently enforced on all resolution requests.	`1m`, `2s`, `700ms`

Usage

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference
spec:
  taskRef:
    resolver: http
    params:
    - name: url
      value: https://raw.githubusercontent.com/tektoncd-catalog/git-clone/main/task/git-clone/git-clone.yaml

Task Resolution with Basic Auth

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference
spec:
  taskRef:
    resolver: http
    params:
    - name: url
      value: https://raw.githubusercontent.com/owner/private-repo/main/task/task.yaml
    - name: http-username
      value: git
    - name: http-password-secret
      value: git-secret
    - name: http-password-secret-key
      value: git-token

Pipeline Resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: http-demo
spec:
  pipelineRef:
    resolver: http
    params:
    - name: url
      value: https://raw.githubusercontent.com/tektoncd/catalog/main/pipeline/build-push-gke-deploy/0.1/build-push-gke-deploy.yaml

Pipeline Resolution with Digest

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: http-demo
spec:
  pipelineRef:
    resolver: http
    params:
      - name: url
        value: https://raw.githubusercontent.com/tektoncd/catalog/main/pipeline/build-push-gke-deploy/0.1/build-push-gke-deploy.yaml
      - name: digest
        value: sha256:e1a86b942e85ce5558fc737a3b4a82d7425ca392741d20afa3b7fb426e96c66b

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Hub Resolver

Use resolver type hub.

Parameters

Param Name	Description	Example Value
`catalog`	The catalog from where to pull the resource (Optional)	Default: `tekton-catalog-tasks` (for `task` kind); `tekton-catalog-pipelines` (for `pipeline` kind)
`type`	The type of Hub from where to pull the resource (Optional). Either `artifact` or `tekton`	Default: `artifact` (recommended). Note: `tekton` type is deprecated.
`kind`	Either `task` or `pipeline` (Optional)	Default: `task`
`name`	The name of the task or pipeline to fetch from the hub	`golang-build`
`version`	Version or a Constraint (see below of a task or a pipeline to pull in from. Wrap the number in quotes!	`"0.5.0"`, `">= 0.5.0"`

The Catalogs in the Artifact Hub follows the semVer (i.e. <major-version>.<minor-version>.0) and the Catalogs in the Tekton Hub follows the simplified semVer (i.e. <major-version>.<minor-version>). Both full and simplified semantic versioning will be accepted by the version parameter. The Hub Resolver will map the version to the format expected by the target Hub type.

Requirements

A cluster running Tekton Pipeline v0.41.0 or later.
The built-in remote resolvers installed.
The enable-hub-resolver feature flag in the resolvers-feature-flags ConfigMap in the tekton-pipelines-resolvers namespace set to true.
Beta features enabled.

Configuration

This resolver uses a ConfigMap for its settings. See ../config/resolvers/hubresolver-config.yaml for the name, namespace and defaults that the resolver ships with.

Options

Option Name	Description	Example Values
`default-tekton-hub-catalog`	The default tekton hub catalog from where to pull the resource.	`Tekton`
`default-artifact-hub-task-catalog`	The default artifact hub catalog from where to pull the resource for task kind.	`tekton-catalog-tasks`
`default-artifact-hub-pipeline-catalog`	The default artifact hub catalog from where to pull the resource for pipeline kind.	`tekton-catalog-pipelines`
`default-kind`	The default object kind for references.	`task`, `pipeline`
`default-type`	The default hub from where to pull the resource.	`artifact`, `tekton`

Configuring the Hub API endpoint

The Hub Resolver supports to resolve resources from the Artifact Hub and the Tekton Hub, which can be configured by setting the type field of the resolver.

** DEPRECATION NOTICE: Tekton Hub is deprecated. Users should migrate to Artifact Hub for discovering and managing Tekton resources. See the migration guide for more information.**

When setting the type field to artifact, the resolver will hit the public hub api at https://artifacthub.io/ by default but you can configure your own (for example to use a private hub instance) by setting the ARTIFACT_HUB_API environment variable in ../config/resolvers/resolvers-deployment.yaml. Example:

env
- name: ARTIFACT_HUB_API
  value: "https://artifacthub.io/"

When setting the type field to tekton, the resolver will hit the public tekton catalog api at https://api.hub.tekton.dev by default but you can configure your own instance of the Tekton Hub by setting the TEKTON_HUB_API environment variable in ../config/resolvers/resolvers-deployment.yaml. Example:

env
- name: TEKTON_HUB_API
  value: "https://api.private.hub.instance.dev"

The Tekton Hub deployment guide can be found here.

Usage

Task Resolution

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: remote-task-reference
spec:
  taskRef:
    resolver: hub
    params:
    - name: catalog # optional
      value: tekton-catalog-tasks
    - name: type # optional
      value: artifact 
    - name: kind
      value: task
    - name: name
      value: git-clone
    - name: version
      value: "0.6"

Pipeline Resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: hub-demo
spec:
  pipelineRef:
    resolver: hub
    params:
    - name: catalog # optional
      value: tekton-catalog-pipelines 
    - name: type # optional
      value: artifact
    - name: kind
      value: pipeline
    - name: name
      value: buildpacks
    - name: version
      value: "0.1"
  # Note: the buildpacks pipeline requires parameters.
  # Resolution of the pipeline will succeed but the PipelineRun
  # overall will not succeed without those parameters.

Version constraint

Instead of a version you can specify a constraint to choose from. The constraint is a string as documented in the go-version library.

Some examples:

params:
  - name: name
    value: git-clone
  - name: version
    value: ">=0.7.0"

Will only choose the git-clone task that is greater than version 0.7.0

params:
  - name: name
    value: git-clone
  - name: version
    value: ">=0.7.0, < 2.0.0"

Will select the latest git-clone task that is greater than version 0.7.0 and less than version 2.0.0, so if the latest task is the version 0.9.0 it will be selected.

Other operators for selection are available for comparisons, see the go-version source code.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Trusted Resources

Overview

Trusted Resources is a feature which can be used to sign Tekton Resources and verify them. Details of design can be found at TEP–0091. This is an alpha feature and supports v1beta1 and v1 version of Task and Pipeline.

Note: Currently, trusted resources only support verifying Tekton resources that come from remote places i.e. git, OCI registry and Artifact Hub. To use cluster resolver for in-cluster resources, make sure to set all default values for the resources before applied to cluster, because the mutating webhook will update the default fields if not given and fail the verification.

Verification failure will mark corresponding taskrun/pipelinerun as Failed status and stop the execution.

Instructions

Sign Resources

We have added sign and verify into Tekton Cli as a subcommand in release v0.28.0 and later. Please refer to cli docs to sign and Tekton resources.

A signed task example:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  annotations:
    tekton.dev/signature: MEYCIQDM8WHQAn/yKJ6psTsa0BMjbI9IdguR+Zi6sPTVynxv6wIhAMy8JSETHP7A2Ncw7MyA7qp9eLsu/1cCKOjRL1mFXIKV
  creationTimestamp: null
  name: example-task
  namespace: tekton-trusted-resources
spec:
  steps:
  - image: ubuntu
    name: echo

Enable Trusted Resources

Enable feature flag

Update the config map:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  trusted-resources-verification-no-match-policy: "fail"

trusted-resources-verification-no-match-policy configurations:

ignore: if no matching policies are found, skip the verification, don’t log, and don’t fail the taskrun/pipelinerun
warn: if no matching policies are found, skip the verification, log a warning, and don’t fail the taskrun/pipelinerun
fail: Fail the taskrun/pipelinerun if no matching policies are found.

Notes:

To skip the verification: make sure no policies exist and trusted-resources-verification-no-match-policy is set to warn or ignore.
To enable the verification: install VerificationPolicy to match the resources.

Or patch the new values:

kubectl patch configmap feature-flags -n tekton-pipelines -p='{"data":{"trusted-resources-verification-no-match-policy":"fail"}}

TaskRun and PipelineRun status update

Trusted resources will update the taskrun’s condition to indicate if it passes verification or not.

The following tables illustrate how the conditions are impacted by feature flag and verification result. Note that if not true or false means this case doesn’t update the corresponding condition. No Matching Policies:

	`Conditions.TrustedResourcesVerified`	`Conditions.Succeeded`
`no-match-policy`: “ignore”
`no-match-policy`: “warn”	False
`no-match-policy`: “fail”	False	False

Matching Policies(no matter what trusted-resources-verification-no-match-policy value is):

	`Conditions.TrustedResourcesVerified`	`Conditions.Succeeded`
all policies pass	True
any enforce policy fails	False	False
only warn policies fail	False

A successful sample TrustedResourcesVerified condition is:

status:
  conditions:
  - lastTransitionTime: "2023-03-01T18:17:05Z"
    message: Trusted resource verification passed
    status: "True"
    type: TrustedResourcesVerified

Failed sample TrustedResourcesVerified and Succeeded conditions are:

status:
  conditions:
  - lastTransitionTime: "2023-03-01T18:17:05Z"
    message: resource verification failed # This will be filled with detailed error message.
    status: "False"
    type: TrustedResourcesVerified
  - lastTransitionTime: "2023-03-01T18:17:10Z"
    message: resource verification failed
    status: "False"
    type: Succeeded

Config key at VerificationPolicy

VerificationPolicy supports SecretRef or encoded public key data.

How does VerificationPolicy work? You can create multiple VerificationPolicy and apply them to the cluster.

Trusted resources will look up policies from the resource namespace (usually this is the same as taskrun/pipelinerun namespace).
If multiple policies are found. For each policy we will check if the resource url is matching any of the patterns in the resources list. If matched then this policy will be used for verification.
If multiple policies are matched, the resource must pass all the “enforce” mode policies. If the resource only matches policies in “warn” mode and fails to pass the “warn” policy, it will not fail the taskrun or pipelinerun, but log a warning instead.
To pass one policy, the resource can pass any public keys in the policy.

Take the following VerificationPolicies for example, a resource from “https://github.com/tektoncd/catalog.git", needs to pass both verification-policy-a and verification-policy-b, to pass verification-policy-a the resource needs to pass either key1 or key2.

Example:

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-a
  namespace: resource-namespace
spec:
  # resources defines a list of patterns
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"  #git resource pattern
    - pattern: "gcr.io/tekton-releases/catalog/upstream/git-clone"  # bundle resource pattern
    - pattern: " https://artifacthub.io/"  # hub resource pattern
  # authorities defines a list of public keys
  authorities:
    - name: key1
      key:
        # secretRef refers to a secret in the cluster, this secret should contain public keys data
        secretRef:
          name: secret-name-a
          namespace: secret-namespace
        hashAlgorithm: sha256
    - name: key2
      key:
        # data stores the inline public key data
        data: "STRING_ENCODED_PUBLIC_KEY"
  # mode can be set to "enforce" (default) or "warn".
  mode: enforce

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-b
  namespace: resource-namespace
spec:
  resources:
    - pattern: "https://github.com/tektoncd/catalog.git"
  authorities:
    - name: key3
      key:
        # data stores the inline public key data
        data: "STRING_ENCODED_PUBLIC_KEY"

namespace should be the same of corresponding resources’ namespace.

pattern is used to filter out remote resources by their sources URL. e.g. git resources pattern can be set to https://github.com/tektoncd/catalog.git. The pattern should follow regex schema, we use go regex library’s Match to match the pattern from VerificationPolicy to the ConfigSource URL resolved by remote resolution. Note that .* will match all resources. To learn more about regex syntax please refer to syntax. To learn more about ConfigSource please refer to resolvers doc for more context. e.g. gitresolver

key is used to store the public key, key can be configured with secretRef, data, kms note that only 1 of these 3 fields can be configured.

secretRef: refers to secret in cluster to store the public key.
data: contains the inline data of the pubic key in “PEM-encoded byte slice” format.
kms: refers to the uri of the public key, it should follow the format defined in sigstore.

hashAlgorithm is the algorithm for the public key, by default is sha256. It also supports SHA224, SHA384, SHA512.

mode controls whether a failing policy will fail the taskrun/pipelinerun, or only log the a warning

enforce (default) - fail the taskrun/pipelinerun if verification fails
warn - don’t fail the taskrun/pipelinerun if verification fails but log a warning

Migrate Config key at configmap to VerificationPolicy

Note: key configuration in configmap is deprecated, The following usage of public keys in configmap can be migrated to VerificationPolicy/

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-trusted-resources
  namespace: tekton-pipelines
  labels:
    app.kubernetes.io/instance: default
    app.kubernetes.io/part-of: tekton-pipelines
data:
  publickeys: "/etc/verification-secrets/cosign.pub, /etc/verification-secrets/cosign2.pub"

To migrate to VerificationPolicy: Stores the public key files in a secret, and configure the secret ref in VerificationPolicy

apiVersion: tekton.dev/v1alpha1
kind: VerificationPolicy
metadata:
  name: verification-policy-name
  namespace: resource-namespace
spec:
  authorities:
    - name: key1
      key:
        # secretRef refers to a secret in the cluster, this secret should contain public keys data
        secretRef:
          name: secret-name-cosign
          namespace: secret-namespace
        hashAlgorithm: sha256
    - name: key2
      key:
        secretRef:
          name: secret-name-cosign2
          namespace: secret-namespace
        hashAlgorithm: sha256

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Container Contract

Each container image that executes a Step in a Task must comply with the container contract described in this document.

When a Task instantiates and runs containers that execute the Steps in the Task, each container’s entrypoint is overwritten with a custom binary that ensures the containers within the Task's Pod are executed in the order specified in the Task definition. Because of this, we highly recommend that you always specify a command value. However, if you’re using the script field to embed a script within a Step, do not specify a command value. For example:

        - name: setup-comment
          image: python:3-alpine
          script: |
            #!/usr/bin/env python
            import json
            (...)

If you do not specify a command value, the Pipelines controller performs a lookup for the entrypoint value in the associated remote container registry. If the image is in a private registry, you must include an ImagePullSecret value in the service account definition used by the Task. The Pipelines controller uses this value unless the service account is not defined, at which point it assumes the value of default.

The final fallback occurs to the Docker config specified in the $HOME/.docker/config.json file. If no credentials are specified in any of the locations described above, the Pipelines controller performs an anonymous lookup of the image.

For example, consider the following Task, which uses two images named gcr.io/cloud-builders/gcloud and gcr.io/cloud-builders/docker. In this example, the Pipelines controller retrieves the entrypoint value from the registry, which means the container will execute using the default entrypoint defined in the image.

spec:
  steps:
    - image: gcr.io/cloud-builders/gcloud
      # No command specified, so the default entrypoint `/builder/notice.sh` from the image will be used
      # command: ["/builder/notice.sh"]
    - image: gcr.io/cloud-builders/docker
      # No command specified, so the default entrypoint `/usr/bin/docker` from the image will be used
      # command: ["/usr/bin/docker"]

However, if you specify a custom command value, the controller uses that value instead:

spec:
  steps:
    - image: gcr.io/cloud-builders/gcloud
      command:
        - bash
        - -c
        - echo "Hello!"

You also have the option to specify args to go with your command value:

steps:
  - image: ubuntu
    command: ["/bin/bash"]
    args: ["-c", "echo hello $FOO"]
    env:
      - name: "FOO"
        value: "world"

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault:

Mon, 01 Jan 0001 00:00:00 +0000

Tekton Bundle Contract v0.1

When using a Tekton Bundle in a task or pipeline reference, the OCI artifact backing the bundle must adhere to the following contract.

Contract

Only Tekton CRDs (eg, Task or Pipeline) may reside in a Tekton Bundle used as a Tekton bundle reference.

Each layer of the image must map 1:1 with a single Tekton resource (eg Task).

No more than 20 individual layers (Pipelines and/or Tasks) maybe placed in a single image.

Each layer must contain all of the following annotations:

dev.tekton.image.name => ObjectMeta.Name of the resource
dev.tekton.image.kind => TypeMeta.Kind of the resource, all lower-cased and singular (eg, task)
dev.tekton.image.apiVersion => TypeMeta.APIVersion of the resource (eg “tekton.dev/v1beta1”)

The union of the { dev.tekton.image.apiVersion, dev.tekton.image.kind, dev.tekton.image.name } annotations on a given layer must be unique among all layers of that image. In practical terms, this means no two “tasks” can have the same name for example.

Each layer must be compressed and stored with a supported OCI MIME type except for +zstd types. For list of the supported types see

the official spec.

Furthermore, each layer must contain a YAML or JSON representation of the underlying resource. If the resource is missing any identifying fields (missing an apiVersion for instance) then it will be considered invalid.

Any tool creating a Tekton bundle must enforce this format and ensure that the annotations and contents all match and conform to this spec. Additionally, the Tekton controller will reject non-conforming Tekton Bundles.

Examples

Say you wanted to create a Tekton Bundle out of the following resources:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: foo
---
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: bar
---
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: foobar

If we imagine what the contents of the resulting bundle look like, it would look something like this (YAML is just for illustrative purposes):

# my-bundle
layers:
  - annotations:
    - name: "dev.tekton.image.name"
      value: "foo"
    - name: "dev.tekton.image.kind"
      value: "Task"
    - name: "dev.tekton.image.apiVersion"
      value: "tekton.dev/v1beta1"
    contents: <compressed bytes of Task object>
  - annotations:
    - name: "dev.tekton.image.name"
      value: "bar"
    - name: "dev.tekton.image.kind"
      value: "Task"
    - name: "dev.tekton.image.apiVersion"
      value: "tekton.dev/v1beta1"
    contents: <compressed bytes of Task object>
  - annotations:
    - name: "dev.tekton.image.name"
      value: "foobar"
    - name: "dev.tekton.image.kind"
      value: "Pipeline"
    - name: "dev.tekton.image.apiVersion"
      value: "tekton.dev/v1beta1"
    contents: <compressed bytes of Pipeline object>

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.

Vault: Pipeline API

Mon, 01 Jan 0001 00:00:00 +0000

Packages:

resolution.tekton.dev/v1alpha1

Resource Types:

ResolutionRequest

ResolutionRequest is an object for requesting the content of a Tekton resource like a pipeline.yaml.

Field Description

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
ResolutionRequestSpec

(Optional)

Spec holds the information for the request part of the resource request.

params
map[string]string

(Optional)

Parameters are the runtime attributes passed to the resolver to help it figure out how to resolve the resource being requested. For example: repo URL, commit SHA, path to file, the kind of authentication to leverage, etc.

status
ResolutionRequestStatus

(Optional)

Status communicates the state of the request and, ultimately, the content of the resolved resource.

ResolutionRequestSpec

(Appears on:ResolutionRequest)

ResolutionRequestSpec are all the fields in the spec of the ResolutionRequest CRD.

Field	Description
`params` map[string]string	(Optional) Parameters are the runtime attributes passed to the resolver to help it figure out how to resolve the resource being requested. For example: repo URL, commit SHA, path to file, the kind of authentication to leverage, etc.

ResolutionRequestStatus

(Appears on:ResolutionRequest)

ResolutionRequestStatus are all the fields in a ResolutionRequest’s status subresource.

Field	Description
`Status` knative.dev/pkg/apis/duck/v1.Status	(Members of `Status` are embedded into this type.)
`ResolutionRequestStatusFields` ResolutionRequestStatusFields	(Members of `ResolutionRequestStatusFields` are embedded into this type.)

ResolutionRequestStatusFields

(Appears on:ResolutionRequestStatus)

ResolutionRequestStatusFields are the ResolutionRequest-specific fields for the status subresource.

Field	Description
`data` string	Data is a string representation of the resolved content of the requested resource in-lined into the ResolutionRequest object.
`refSource` RefSource	RefSource is the source reference of the remote data that records where the remote file came from including the url, digest and the entrypoint.

resolution.tekton.dev/v1beta1

Resource Types:

ResolutionRequest

ResolutionRequest is an object for requesting the content of a Tekton resource like a pipeline.yaml.

Field Description

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
ResolutionRequestSpec

(Optional)

Spec holds the information for the request part of the resource request.

`params` []Param	(Optional) Parameters are the runtime attributes passed to the resolver to help it figure out how to resolve the resource being requested. For example: repo URL, commit SHA, path to file, the kind of authentication to leverage, etc.
`url` string	(Optional) URL is the runtime url passed to the resolver to help it figure out how to resolver the resource being requested. This is currently at an ALPHA stability level and subject to alpha API compatibility policies.

status
ResolutionRequestStatus

(Optional)

Status communicates the state of the request and, ultimately, the content of the resolved resource.

ResolutionRequestSpec

(Appears on:ResolutionRequest)

ResolutionRequestSpec are all the fields in the spec of the ResolutionRequest CRD.

Field	Description
`params` []Param	(Optional) Parameters are the runtime attributes passed to the resolver to help it figure out how to resolve the resource being requested. For example: repo URL, commit SHA, path to file, the kind of authentication to leverage, etc.
`url` string	(Optional) URL is the runtime url passed to the resolver to help it figure out how to resolver the resource being requested. This is currently at an ALPHA stability level and subject to alpha API compatibility policies.

ResolutionRequestStatus

(Appears on:ResolutionRequest)

ResolutionRequestStatus are all the fields in a ResolutionRequest’s status subresource.

Field	Description
`Status` knative.dev/pkg/apis/duck/v1.Status	(Members of `Status` are embedded into this type.)
`ResolutionRequestStatusFields` ResolutionRequestStatusFields	(Members of `ResolutionRequestStatusFields` are embedded into this type.)

ResolutionRequestStatusFields

(Appears on:ResolutionRequestStatus)

ResolutionRequestStatusFields are the ResolutionRequest-specific fields for the status subresource.

Field	Description
`data` string	Data is a string representation of the resolved content of the requested resource in-lined into the ResolutionRequest object.
`source` RefSource	Deprecated: Use RefSource instead
`refSource` RefSource	RefSource is the source reference of the remote data that records the url, digest and the entrypoint.

tekton.dev/v1

Package v1 contains API Schema definitions for the pipeline v1 API group

Resource Types:

Pipeline

Pipeline describes a list of Tasks to execute. It expresses how outputs of tasks feed into inputs of subsequent tasks.

Field Description

apiVersion
string tekton.dev/v1

kind
string Pipeline

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
PipelineSpec

(Optional)

Spec holds the desired state of the Pipeline from the client

`displayName` string	(Optional) DisplayName is a user-facing name of the pipeline that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the pipeline that may be used to populate a UI.
`tasks` []PipelineTask	Tasks declares the graph of Tasks that execute when this Pipeline is run.
`params` ParamSpecs	Params declares a list of input parameters that must be supplied when this Pipeline is run.
`workspaces` []PipelineWorkspaceDeclaration	(Optional) Workspaces declares a set of named workspaces that are expected to be provided by a PipelineRun.
`results` []PipelineResult	(Optional) Results are values that this pipeline can output once run
`finally` []PipelineTask	Finally declares the list of Tasks that execute just before leaving the Pipeline i.e. either after all Tasks are finished executing successfully or after a failure which would result in ending the Pipeline

PipelineRun

PipelineRun represents a single execution of a Pipeline. PipelineRuns are how the graph of Tasks declared in a Pipeline are executed; they specify inputs to Pipelines such as parameter values and capture operational aspects of the Tasks execution such as service account and tolerations. Creating a PipelineRun creates TaskRuns for Tasks in the referenced Pipeline.

Field Description

apiVersion
string tekton.dev/v1

kind
string PipelineRun

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
PipelineRunSpec

(Optional)

`pipelineRef` PipelineRef	(Optional)
`pipelineSpec` PipelineSpec	(Optional) Specifying PipelineSpec can be disabled by setting `disable-inline-spec` feature flag. See Pipeline.spec (API version: tekton.dev/v1)
`params` Params	Params is a list of parameter names and values.
`status` PipelineRunSpecStatus	(Optional) Used for cancelling a pipelinerun (and maybe more later on)
`timeouts` TimeoutFields	(Optional) Time after which the Pipeline times out. Currently three keys are accepted in the map pipeline, tasks and finally with Timeouts.pipeline >= Timeouts.tasks + Timeouts.finally
`taskRunTemplate` PipelineTaskRunTemplate	(Optional) TaskRunTemplate represent template of taskrun
`workspaces` []WorkspaceBinding	(Optional) Workspaces holds a set of workspace bindings that must match names with those declared in the pipeline.
`taskRunSpecs` []PipelineTaskRunSpec	(Optional) TaskRunSpecs holds a set of runtime specs
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

status
PipelineRunStatus (Optional)

Task

Task represents a collection of sequential steps that are run as part of a Pipeline using a set of inputs and producing a set of outputs. Tasks execute when TaskRuns are created that provide the input parameters and resources and output resources the Task requires.

Field Description

apiVersion
string tekton.dev/v1

kind
string Task

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TaskSpec

(Optional)

Spec holds the desired state of the Task from the client

`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the task. Params must be supplied as inputs in TaskRuns unless they declare a default value.
`displayName` string	(Optional) DisplayName is a user-facing name of the task that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the task that may be used to populate a UI.
`steps` []Step	Steps are the steps of the build; each step is run sequentially with the source mounted into /workspace.
`volumes` Volumes	Volumes is a collection of volumes that are available to mount into the steps of the build. See Pod.spec.volumes (API version: v1)
`stepTemplate` StepTemplate	StepTemplate can be used as the basis for all step containers within the Task, so that the steps inherit settings on the base container.
`sidecars` []Sidecar	Sidecars are run alongside the Task’s step containers. They begin before the steps start and end after the steps complete.
`workspaces` []WorkspaceDeclaration	Workspaces are the volumes that this Task requires.
`results` []TaskResult	Results are values that this Task can output

TaskRun

TaskRun represents a single execution of a Task. TaskRuns are how the steps specified in a Task are executed; they specify the parameters and resources used to run the steps in a Task.

Field Description

apiVersion
string tekton.dev/v1

kind
string TaskRun

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TaskRunSpec

(Optional)

`debug` TaskRunDebug	(Optional)
`params` Params	(Optional)
`serviceAccountName` string	(Optional)
`taskRef` TaskRef	(Optional) no more than one of the TaskRef and TaskSpec may be specified.
`taskSpec` TaskSpec	(Optional) Specifying TaskSpec can be disabled by setting `disable-inline-spec` feature flag. See Task.spec (API version: tekton.dev/v1)
`status` TaskRunSpecStatus	(Optional) Used for cancelling a TaskRun (and maybe more later on)
`statusMessage` TaskRunSpecStatusMessage	(Optional) Status message for cancellation.
`retries` int	(Optional) Retries represents how many times this TaskRun should be retried in the event of task failure.
`timeout` Kubernetes meta/v1.Duration	(Optional) Time after which one retry attempt times out. Defaults to 1 hour. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`podTemplate` PodTemplate	PodTemplate holds pod specific configuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces is a list of WorkspaceBindings from volumes to workspaces.
`stepSpecs` []TaskRunStepSpec	(Optional) Specs to apply to Steps in this TaskRun. If a field is specified in both a Step and a StepSpec, the value from the StepSpec will be used. This field is only supported when the alpha feature gate is enabled.
`sidecarSpecs` []TaskRunSidecarSpec	(Optional) Specs to apply to Sidecars in this TaskRun. If a field is specified in both a Sidecar and a SidecarSpec, the value from the SidecarSpec will be used. This field is only supported when the alpha feature gate is enabled.
`computeResources` Kubernetes core/v1.ResourceRequirements	Compute resources to use for this TaskRun
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

status
TaskRunStatus (Optional)

Algorithm (`string` alias)

Algorithm Standard cryptographic hash algorithm

Artifact

(Appears on:Artifacts)

Artifact represents an artifact within a system, potentially containing multiple values associated with it.

Field	Description
`name` string	The artifact’s identifying category name
`values` []ArtifactValue	A collection of values related to the artifact
`buildOutput` bool	Indicate if the artifact is a build output or a by-product

ArtifactValue

(Appears on:Artifact)

ArtifactValue represents a specific value or data element within an Artifact.

Field	Description
`digest` map[github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.Algorithm]string
`uri` string	Algorithm-specific digests for verifying the content (e.g., SHA256)

Artifacts

(Appears on:TaskRunStatusFields)

Artifacts represents the collection of input and output artifacts associated with a task run or a similar process. Artifacts in this context are units of data or resources that the process either consumes as input or produces as output.

Field	Description
`inputs` []Artifact
`outputs` []Artifact

ChildStatusReference

(Appears on:PipelineRunStatusFields)

ChildStatusReference is used to point to the statuses of individual TaskRuns and Runs within this PipelineRun.

Field	Description
`name` string	Name is the name of the TaskRun or Run this is referencing.
`displayName` string	DisplayName is a user-facing name of the pipelineTask that may be used to populate a UI.
`pipelineTaskName` string	PipelineTaskName is the name of the PipelineTask this is referencing.
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

Combination (`map[string]string` alias)

Combination is a map, mainly defined to hold a single combination from a Matrix with key as param.Name and value as param.Value

Combinations (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.Combination` alias)

Combinations is a Combination list

EmbeddedTask

(Appears on:PipelineTask)

EmbeddedTask is used to define a Task inline within a Pipeline’s PipelineTasks.

Field Description

spec
k8s.io/apimachinery/pkg/runtime.RawExtension

(Optional)

Spec is a specification of a custom task

-
[]byte

Raw is the underlying serialization of this object.

TODO: Determine how to detect ContentType and ContentEncoding of ‘Raw’ data.

-
k8s.io/apimachinery/pkg/runtime.Object

Object can hold a representation of this extension - useful for working with versioned structs.

metadata
PipelineTaskMetadata (Optional)

TaskSpec
TaskSpec

(Members of TaskSpec are embedded into this type.)

(Optional)

TaskSpec is a specification of a task

IncludeParams

IncludeParams allows passing in a specific combinations of Parameters into the Matrix.

Field	Description
`name` string	Name the specified combination
`params` Params	Params takes only `Parameters` of type `"string"` The names of the `params` must match the names of the `params` in the underlying `Task`

Matrix

(Appears on:PipelineTask)

Matrix is used to fan out Tasks in a Pipeline

Field	Description
`params` Params	Params is a list of parameters used to fan out the pipelineTask Params takes only `Parameters` of type `"array"` Each array element is supplied to the `PipelineTask` by substituting `params` of type `"string"` in the underlying `Task`. The names of the `params` in the `Matrix` must match the names of the `params` in the underlying `Task` that they will be substituting.
`include` IncludeParamsList	(Optional) Include is a list of IncludeParams which allows passing in specific combinations of Parameters into the Matrix.

OnErrorType (`string` alias)

(Appears on:Step)

OnErrorType defines a list of supported exiting behavior of a container on error

Value	Description
"continue"	Continue indicates continue executing the rest of the steps irrespective of the container exit code
"stopAndFail"	StopAndFail indicates exit the taskRun if the container exits with non-zero exit code

Param

(Appears on:ResolutionRequestSpec)

Param declares an ParamValues to use for the parameter called name.

Field	Description
`name` string
`value` ParamValue

ParamSpec

ParamSpec defines arbitrary parameters needed beyond typed inputs (such as resources). Parameter values are provided by users as inputs on a TaskRun or PipelineRun.

Field	Description
`name` string	Name declares the name by which a parameter is referenced.
`type` ParamType	(Optional) Type is the user-specified type of the parameter. The possible types are currently “string”, “array” and “object”, and “string” is the default.
`description` string	(Optional) Description is a user-facing description of the parameter that may be used to populate a UI.
`properties` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.PropertySpec	(Optional) Properties is the JSON Schema properties to support key-value pairs parameter.
`default` ParamValue	(Optional) Default is the value a parameter takes if no input value is supplied. If default is set, a Task may be executed without a supplied value for the parameter.
`enum` []string	(Optional) Enum declares a set of allowed param input values for tasks/pipelines that can be validated. If Enum is not set, no input validation is performed for the param.

ParamSpecs (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.ParamSpec` alias)

(Appears on:PipelineSpec, TaskSpec, StepActionSpec, StepActionSpec)

ParamSpecs is a list of ParamSpec

ParamType (`string` alias)

(Appears on:ParamSpec, ParamValue, PropertySpec)

ParamType indicates the type of an input parameter; Used to distinguish between a single string and an array of strings.

Value	Description
"array"
"object"
"string"

ParamValue

(Appears on:Param, ParamSpec)

ParamValue is a type that can hold a single string, string array, or string map. Used in JSON unmarshalling so that a single JSON field can accept either an individual string or an array of strings.

Field	Description
`Type` ParamType
`StringVal` string	Represents the stored type of ParamValues.
`ArrayVal` []string
`ObjectVal` map[string]string

Params (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.Param` alias)

(Appears on:IncludeParams, Matrix, PipelineRunSpec, PipelineTask, ResolverRef, Step, TaskRunInputs, TaskRunSpec)

Params is a list of Param

PipelineRef

(Appears on:PipelineRunSpec, PipelineTask)

PipelineRef can be used to refer to a specific instance of a Pipeline.

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`apiVersion` string	(Optional) API version of the referent
`ResolverRef` ResolverRef	(Optional) ResolverRef allows referencing a Pipeline in a remote location like a git repo. This field is only supported when the alpha feature gate is enabled.

PipelineResult

(Appears on:PipelineSpec)

PipelineResult used to describe the results of a pipeline

Field	Description
`name` string	Name the given name
`type` ResultsType	Type is the user-specified type of the result. The possible types are ‘string’, ‘array’, and ‘object’, with ‘string’ as the default. ‘array’ and ‘object’ types are alpha features.
`description` string	(Optional) Description is a human-readable description of the result
`value` ResultValue	Value the expression used to retrieve the value

PipelineRunReason (`string` alias)

PipelineRunReason represents a reason for the pipeline run “Succeeded” condition

Value	Description
"CELEvaluationFailed"	ReasonCELEvaluationFailed indicates the pipeline fails the CEL evaluation
"Cancelled"	PipelineRunReasonCancelled is the reason set when the PipelineRun cancelled by the user This reason may be found with a corev1.ConditionFalse status, if the cancellation was processed successfully This reason may be found with a corev1.ConditionUnknown status, if the cancellation is being processed or failed
"CancelledRunningFinally"	PipelineRunReasonCancelledRunningFinally indicates that pipeline has been gracefully cancelled and no new Tasks will be scheduled by the controller, but final tasks are now running
"Completed"	PipelineRunReasonCompleted is the reason set when the PipelineRun completed successfully with one or more skipped Tasks
"PipelineRunCouldntCancel"	ReasonCouldntCancel indicates that a PipelineRun was cancelled but attempting to update all of the running TaskRuns as cancelled failed.
"CouldntGetPipeline"	ReasonCouldntGetPipeline indicates that the reason for the failure status is that the associated Pipeline couldn’t be retrieved
"CouldntGetPipelineResult"	PipelineRunReasonCouldntGetPipelineResult indicates that the pipeline fails to retrieve the referenced result. This could be due to failed TaskRuns or Runs that were supposed to produce the results
"CouldntGetTask"	ReasonCouldntGetTask indicates that the reason for the failure status is that the associated Pipeline’s Tasks couldn’t all be retrieved
"PipelineRunCouldntTimeOut"	ReasonCouldntTimeOut indicates that a PipelineRun was timed out but attempting to update all of the running TaskRuns as timed out failed.
"CreateRunFailed"	ReasonCreateRunFailed indicates that the pipeline fails to create the taskrun or other run resources
"Failed"	PipelineRunReasonFailed is the reason set when the PipelineRun completed with a failure
"PipelineValidationFailed"	ReasonFailedValidation indicates that the reason for failure status is that pipelinerun failed runtime validation
"InvalidPipelineResourceBindings"	ReasonInvalidBindings indicates that the reason for the failure status is that the PipelineResources bound in the PipelineRun didn’t match those declared in the Pipeline
"PipelineInvalidGraph"	ReasonInvalidGraph indicates that the reason for the failure status is that the associated Pipeline is an invalid graph (a.k.a wrong order, cycle, …)
"InvalidMatrixParameterTypes"	ReasonInvalidMatrixParameterTypes indicates a matrix contains invalid parameter types
"InvalidParamValue"	PipelineRunReasonInvalidParamValue indicates that the PipelineRun Param input value is not allowed.
"InvalidPipelineResultReference"	PipelineRunReasonInvalidPipelineResultReference indicates a pipeline result was declared by the pipeline but not initialized in the pipelineTask
"InvalidTaskResultReference"	ReasonInvalidTaskResultReference indicates a task result was declared but was not initialized by that task
"InvalidTaskRunSpecs"	ReasonInvalidTaskRunSpec indicates that PipelineRun.Spec.TaskRunSpecs[].PipelineTaskName is defined with a not exist taskName in pipelineSpec.
"InvalidWorkspaceBindings"	ReasonInvalidWorkspaceBinding indicates that a Pipeline expects a workspace but a PipelineRun has provided an invalid binding.
"ObjectParameterMissKeys"	ReasonObjectParameterMissKeys indicates that the object param value provided from PipelineRun spec misses some keys required for the object param declared in Pipeline spec.
"ParamArrayIndexingInvalid"	ReasonParamArrayIndexingInvalid indicates that the use of param array indexing is out of bound.
"ParameterMissing"	ReasonParameterMissing indicates that the reason for the failure status is that the associated PipelineRun didn’t provide all the required parameters
"ParameterTypeMismatch"	ReasonParameterTypeMismatch indicates that the reason for the failure status is that parameter(s) declared in the PipelineRun do not have the some declared type as the parameters(s) declared in the Pipeline that they are supposed to override.
"PipelineRunPending"	PipelineRunReasonPending is the reason set when the PipelineRun is in the pending state
"RequiredWorkspaceMarkedOptional"	ReasonRequiredWorkspaceMarkedOptional indicates an optional workspace has been passed to a Task that is expecting a non-optional workspace
"ResolvingPipelineRef"	ReasonResolvingPipelineRef indicates that the PipelineRun is waiting for its pipelineRef to be asynchronously resolved.
"ResourceVerificationFailed"	ReasonResourceVerificationFailed indicates that the pipeline fails the trusted resource verification, it could be the content has changed, signature is invalid or public key is invalid
"Running"	PipelineRunReasonRunning is the reason set when the PipelineRun is running
"Started"	PipelineRunReasonStarted is the reason set when the PipelineRun has just started
"StoppedRunningFinally"	PipelineRunReasonStoppedRunningFinally indicates that pipeline has been gracefully stopped and no new Tasks will be scheduled by the controller, but final tasks are now running
"PipelineRunStopping"	PipelineRunReasonStopping indicates that no new Tasks will be scheduled by the controller, and the pipeline will stop once all running tasks complete their work
"Succeeded"	PipelineRunReasonSuccessful is the reason set when the PipelineRun completed successfully
"PipelineRunTimeout"	PipelineRunReasonTimedOut is the reason set when the PipelineRun has timed out

PipelineRunResult

(Appears on:PipelineRunStatusFields)

PipelineRunResult used to describe the results of a pipeline

Field	Description
`name` string	Name is the result’s name as declared by the Pipeline
`value` ResultValue	Value is the result returned from the execution of this PipelineRun

PipelineRunRunStatus

PipelineRunRunStatus contains the name of the PipelineTask for this Run and the Run’s Status

Field	Description
`pipelineTaskName` string	PipelineTaskName is the name of the PipelineTask.
`status` CustomRunStatus	(Optional) Status is the RunStatus for the corresponding Run
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

PipelineRunSpec

(Appears on:PipelineRun)

PipelineRunSpec defines the desired state of PipelineRun

Field	Description
`pipelineRef` PipelineRef	(Optional)
`pipelineSpec` PipelineSpec	(Optional) Specifying PipelineSpec can be disabled by setting `disable-inline-spec` feature flag. See Pipeline.spec (API version: tekton.dev/v1)
`params` Params	Params is a list of parameter names and values.
`status` PipelineRunSpecStatus	(Optional) Used for cancelling a pipelinerun (and maybe more later on)
`timeouts` TimeoutFields	(Optional) Time after which the Pipeline times out. Currently three keys are accepted in the map pipeline, tasks and finally with Timeouts.pipeline >= Timeouts.tasks + Timeouts.finally
`taskRunTemplate` PipelineTaskRunTemplate	(Optional) TaskRunTemplate represent template of taskrun
`workspaces` []WorkspaceBinding	(Optional) Workspaces holds a set of workspace bindings that must match names with those declared in the pipeline.
`taskRunSpecs` []PipelineTaskRunSpec	(Optional) TaskRunSpecs holds a set of runtime specs
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

PipelineRunSpecStatus (`string` alias)

(Appears on:PipelineRunSpec)

PipelineRunSpecStatus defines the pipelinerun spec status the user can provide

PipelineRunStatus

(Appears on:PipelineRun)

PipelineRunStatus defines the observed state of PipelineRun

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

PipelineRunStatusFields
PipelineRunStatusFields

(Members of PipelineRunStatusFields are embedded into this type.)

PipelineRunStatusFields inlines the status fields.

PipelineRunStatusFields

(Appears on:PipelineRunStatus)

PipelineRunStatusFields holds the fields of PipelineRunStatus’ status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

Field	Description
`startTime` Kubernetes meta/v1.Time	StartTime is the time the PipelineRun is actually started.
`completionTime` Kubernetes meta/v1.Time	CompletionTime is the time the PipelineRun completed.
`results` []PipelineRunResult	(Optional) Results are the list of results written out by the pipeline task’s containers
`pipelineSpec` PipelineSpec	PipelineSpec contains the exact spec used to instantiate the run. See Pipeline.spec (API version: tekton.dev/v1)
`skippedTasks` []SkippedTask	(Optional) list of tasks that were skipped due to when expressions evaluating to false
`childReferences` []ChildStatusReference	(Optional) list of TaskRun and Run names, PipelineTask names, and API versions/kinds for children of this PipelineRun.
`finallyStartTime` Kubernetes meta/v1.Time	(Optional) FinallyStartTime is when all non-finally tasks have been completed and only finally tasks are being executed.
`provenance` Provenance	(Optional) Provenance contains some key authenticated metadata about how a software artifact was built (what sources, what inputs/outputs, etc.).
`spanContext` map[string]string	SpanContext contains tracing span context fields

PipelineRunTaskRunStatus

PipelineRunTaskRunStatus contains the name of the PipelineTask for this TaskRun and the TaskRun’s Status

Field	Description
`pipelineTaskName` string	PipelineTaskName is the name of the PipelineTask.
`status` TaskRunStatus	(Optional) Status is the TaskRunStatus for the corresponding TaskRun
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

PipelineSpec

(Appears on:Pipeline, PipelineRunSpec, PipelineRunStatusFields, PipelineTask)

PipelineSpec defines the desired state of Pipeline.

Field	Description
`displayName` string	(Optional) DisplayName is a user-facing name of the pipeline that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the pipeline that may be used to populate a UI.
`tasks` []PipelineTask	Tasks declares the graph of Tasks that execute when this Pipeline is run.
`params` ParamSpecs	Params declares a list of input parameters that must be supplied when this Pipeline is run.
`workspaces` []PipelineWorkspaceDeclaration	(Optional) Workspaces declares a set of named workspaces that are expected to be provided by a PipelineRun.
`results` []PipelineResult	(Optional) Results are values that this pipeline can output once run
`finally` []PipelineTask	Finally declares the list of Tasks that execute just before leaving the Pipeline i.e. either after all Tasks are finished executing successfully or after a failure which would result in ending the Pipeline

PipelineTask

(Appears on:PipelineSpec)

PipelineTask defines a task in a Pipeline, passing inputs from both Params and from the output of previous tasks.

Field	Description
`name` string	Name is the name of this task within the context of a Pipeline. Name is used as a coordinate with the `from` and `runAfter` fields to establish the execution order of tasks relative to one another.
`displayName` string	(Optional) DisplayName is the display name of this task within the context of a Pipeline. This display name may be used to populate a UI.
`description` string	(Optional) Description is the description of this task within the context of a Pipeline. This description may be used to populate a UI.
`taskRef` TaskRef	(Optional) TaskRef is a reference to a task definition.
`taskSpec` EmbeddedTask	(Optional) TaskSpec is a specification of a task Specifying TaskSpec can be disabled by setting `disable-inline-spec` feature flag. See Task.spec (API version: tekton.dev/v1)
`when` WhenExpressions	(Optional) When is a list of when expressions that need to be true for the task to run
`retries` int	(Optional) Retries represents how many times this task should be retried in case of task failure: ConditionSucceeded set to False
`runAfter` []string	(Optional) RunAfter is the list of PipelineTask names that should be executed before this Task executes. (Used to force a specific ordering in graph execution.)
`params` Params	(Optional) Parameters declares parameters passed to this task.
`matrix` Matrix	(Optional) Matrix declares parameters used to fan out this task.
`workspaces` []WorkspacePipelineTaskBinding	(Optional) Workspaces maps workspaces from the pipeline spec to the workspaces declared in the Task.
`timeout` Kubernetes meta/v1.Duration	(Optional) Duration after which the TaskRun times out. Defaults to 1 hour. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`pipelineRef` PipelineRef	(Optional) PipelineRef is a reference to a pipeline definition Note: PipelineRef is in preview mode and not yet supported
`pipelineSpec` PipelineSpec	(Optional) PipelineSpec is a specification of a pipeline Note: PipelineSpec is in preview mode and not yet supported Specifying PipelineSpec can be disabled by setting `disable-inline-spec` feature flag. See Pipeline.spec (API version: tekton.dev/v1)
`onError` PipelineTaskOnErrorType	(Optional) OnError defines the exiting behavior of a PipelineRun on error can be set to [ continue \| stopAndFail ]

PipelineTaskMetadata

(Appears on:EmbeddedTask, PipelineTaskRunSpec)

PipelineTaskMetadata contains the labels or annotations for an EmbeddedTask

Field	Description
`labels` map[string]string	(Optional)
`annotations` map[string]string	(Optional)

PipelineTaskOnErrorType (`string` alias)

(Appears on:PipelineTask)

PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error

Value	Description
"continue"	PipelineTaskContinue indicates to continue executing the rest of the DAG when the PipelineTask fails
"stopAndFail"	PipelineTaskStopAndFail indicates to stop and fail the PipelineRun if the PipelineTask fails

PipelineTaskParam

PipelineTaskParam is used to provide arbitrary string parameters to a Task.

Field	Description
`name` string
`value` string

PipelineTaskRun

PipelineTaskRun reports the results of running a step in the Task. Each task has the potential to succeed or fail (based on the exit code) and produces logs.

Field	Description
`name` string

PipelineTaskRunSpec

(Appears on:PipelineRunSpec)

PipelineTaskRunSpec can be used to configure specific specs for a concrete Task

Field	Description
`pipelineTaskName` string
`serviceAccountName` string
`podTemplate` PodTemplate
`stepSpecs` []TaskRunStepSpec
`sidecarSpecs` []TaskRunSidecarSpec
`metadata` PipelineTaskMetadata	(Optional)
`computeResources` Kubernetes core/v1.ResourceRequirements	Compute resources to use for this TaskRun
`timeout` Kubernetes meta/v1.Duration	(Optional) Duration after which the TaskRun times out. Overrides the timeout specified on the Task’s spec if specified. Takes lower precedence to PipelineRun’s `spec.timeouts.tasks` Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration

PipelineTaskRunTemplate

(Appears on:PipelineRunSpec)

PipelineTaskRunTemplate is used to specify run specifications for all Task in pipelinerun.

Field	Description
`podTemplate` PodTemplate	(Optional)
`serviceAccountName` string	(Optional)

PipelineWorkspaceDeclaration

(Appears on:PipelineSpec)

PipelineWorkspaceDeclaration creates a named slot in a Pipeline that a PipelineRun is expected to populate with a workspace binding.

Field	Description
`name` string	Name is the name of a workspace to be provided by a PipelineRun.
`description` string	(Optional) Description is a human readable string describing how the workspace will be used in the Pipeline. It can be useful to include a bit of detail about which tasks are intended to have access to the data on the workspace.
`optional` bool	Optional marks a Workspace as not being required in PipelineRuns. By default this field is false and so declared workspaces are required.

PropertySpec

(Appears on:ParamSpec, StepResult, TaskResult)

PropertySpec defines the struct for object keys

Field	Description
`type` ParamType

Provenance

(Appears on:PipelineRunStatusFields, StepState, TaskRunStatusFields)

Provenance contains metadata about resources used in the TaskRun/PipelineRun such as the source from where a remote build definition was fetched. This field aims to carry minimum amoumt of metadata in *Run status so that Tekton Chains can capture them in the provenance.

Field	Description
`refSource` RefSource	RefSource identifies the source where a remote task/pipeline came from.
`featureFlags` github.com/tektoncd/pipeline/pkg/apis/config.FeatureFlags	FeatureFlags identifies the feature flags that were used during the task/pipeline run

Ref

(Appears on:Step)

Ref can be used to refer to a specific instance of a StepAction.

Field	Description
`name` string	Name of the referenced step
`ResolverRef` ResolverRef	(Optional) ResolverRef allows referencing a StepAction in a remote location like a git repo.

RefSource

(Appears on:Provenance, ResolutionRequestStatusFields, ResolutionRequestStatusFields)

RefSource contains the information that can uniquely identify where a remote built definition came from i.e. Git repositories, Tekton Bundles in OCI registry and hub.

Field	Description
`uri` string	URI indicates the identity of the source of the build definition. Example: “https://github.com/tektoncd/catalog”
`digest` map[string]string	Digest is a collection of cryptographic digests for the contents of the artifact specified by URI. Example: {“sha1”: “f99d13e554ffcb696dee719fa85b695cb5b0f428”}
`entryPoint` string	EntryPoint identifies the entry point into the build. This is often a path to a build definition file and/or a target label within that file. Example: “task/git-clone/0.10/git-clone.yaml”

ResolverName (`string` alias)

(Appears on:ResolverRef)

ResolverName is the name of a resolver from which a resource can be requested.

ResolverRef

(Appears on:PipelineRef, Ref, TaskRef)

ResolverRef can be used to refer to a Pipeline or Task in a remote location like a git repo. This feature is in beta and these fields are only available when the beta feature gate is enabled.

Field	Description
`resolver` ResolverName	(Optional) Resolver is the name of the resolver that should perform resolution of the referenced Tekton resource, such as “git”.
`params` Params	(Optional) Params contains the parameters used to identify the referenced Tekton resource. Example entries might include “repo” or “path” but the set of params ultimately depends on the chosen resolver.

ResultRef

ResultRef is a type that represents a reference to a task run result

Field	Description
`pipelineTask` string
`result` string
`resultsIndex` int
`property` string

ResultValue

(Appears on:PipelineResult, PipelineRunResult, TaskResult, TaskRunResult)

ResultValue is a type alias of ParamValue

ResultsType (`string` alias)

(Appears on:PipelineResult, StepResult, TaskResult, TaskRunResult)

ResultsType indicates the type of a result; Used to distinguish between a single string and an array of strings. Note that there is ResultType used to find out whether a RunResult is from a task result or not, which is different from this ResultsType.

Value	Description
"array"
"object"
"string"

RetriesStatus (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.TaskRunStatus` alias)

(Appears on:TaskRunStatusFields)

Sidecar

(Appears on:TaskSpec)

Sidecar has nearly the same data structure as Step but does not have the ability to timeout.

Field	Description
`name` string	Name of the Sidecar specified as a DNS_LABEL. Each Sidecar in a Task must have a unique name (DNS_LABEL). Cannot be updated.
`image` string	(Optional) Image reference name. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Sidecar’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Sidecar’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`workingDir` string	(Optional) Sidecar’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`ports` []Kubernetes core/v1.ContainerPort	(Optional) List of ports to expose from the Sidecar. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default “0.0.0.0” address inside a container will be accessible from the network. Cannot be updated.
`envFrom` []Kubernetes core/v1.EnvFromSource	(Optional) List of sources to populate environment variables in the Sidecar. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the Sidecar. Cannot be updated.
`computeResources` Kubernetes core/v1.ResourceRequirements	(Optional) ComputeResources required by this Sidecar. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Sidecar’s filesystem. Cannot be updated.
`volumeDevices` []Kubernetes core/v1.VolumeDevice	(Optional) volumeDevices is the list of block devices to be used by the Sidecar.
`livenessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of Sidecar liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
`readinessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of Sidecar service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
`startupProbe` Kubernetes core/v1.Probe	(Optional) StartupProbe indicates that the Pod the Sidecar is running in has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod’s lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
`lifecycle` Kubernetes core/v1.Lifecycle	(Optional) Actions that the management system should take in response to Sidecar lifecycle events. Cannot be updated.
`terminationMessagePath` string	(Optional) Optional: Path at which the file to which the Sidecar’s termination message will be written is mounted into the Sidecar’s filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated.
`terminationMessagePolicy` Kubernetes core/v1.TerminationMessagePolicy	(Optional) Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the Sidecar status message on both success and failure. FallbackToLogsOnError will use the last chunk of Sidecar log output if the termination message file is empty and the Sidecar exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated.
`imagePullPolicy` Kubernetes core/v1.PullPolicy	(Optional) Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Sidecar should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
`stdin` bool	(Optional) Whether this Sidecar should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the Sidecar will always result in EOF. Default is false.
`stdinOnce` bool	(Optional) Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on Sidecar start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the Sidecar is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false
`tty` bool	(Optional) Whether this Sidecar should allocate a TTY for itself, also requires ‘stdin’ to be true. Default is false.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command or Args.
`workspaces` []WorkspaceUsage	(Optional) This is an alpha field. You must set the “enable-api-fields” feature flag to “alpha” for this field to be supported. Workspaces is a list of workspaces from the Task that this Sidecar wants exclusive access to. Adding a workspace to this list means that any other Step or Sidecar that does not also request this Workspace will not have access to it.
`restartPolicy` Kubernetes core/v1.ContainerRestartPolicy	(Optional) RestartPolicy refers to kubernetes RestartPolicy. It can only be set for an initContainer and must have it’s policy set to “Always”. It is currently left optional to help support Kubernetes versions prior to 1.29 when this feature was introduced.

SidecarState

(Appears on:TaskRunStatusFields)

SidecarState reports the results of running a sidecar in a Task.

Field	Description
`ContainerState` Kubernetes core/v1.ContainerState	(Members of `ContainerState` are embedded into this type.)
`name` string
`container` string
`imageID` string

SkippedTask

(Appears on:PipelineRunStatusFields)

SkippedTask is used to describe the Tasks that were skipped due to their When Expressions evaluating to False. This is a struct because we are looking into including more details about the When Expressions that caused this Task to be skipped.

Field	Description
`name` string	Name is the Pipeline Task name
`reason` SkippingReason	Reason is the cause of the PipelineTask being skipped.
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

SkippingReason (`string` alias)

(Appears on:SkippedTask)

SkippingReason explains why a PipelineTask was skipped.

Value	Description
"Matrix Parameters have an empty array"	EmptyArrayInMatrixParams means the task was skipped because Matrix parameters contain empty array.
"PipelineRun Finally timeout has been reached"	FinallyTimedOutSkip means the task was skipped because the PipelineRun has passed its Timeouts.Finally.
"PipelineRun was gracefully cancelled"	GracefullyCancelledSkip means the task was skipped because the pipeline run has been gracefully cancelled
"PipelineRun was gracefully stopped"	GracefullyStoppedSkip means the task was skipped because the pipeline run has been gracefully stopped
"Results were missing"	MissingResultsSkip means the task was skipped because it’s missing necessary results
"None"	None means the task was not skipped
"Parent Tasks were skipped"	ParentTasksSkip means the task was skipped because its parent was skipped
"PipelineRun timeout has been reached"	PipelineTimedOutSkip means the task was skipped because the PipelineRun has passed its overall timeout.
"PipelineRun was stopping"	StoppingSkip means the task was skipped because the pipeline run is stopping
"PipelineRun Tasks timeout has been reached"	TasksTimedOutSkip means the task was skipped because the PipelineRun has passed its Timeouts.Tasks.
"When Expressions evaluated to false"	WhenExpressionsSkip means the task was skipped due to at least one of its when expressions evaluating to false

Step

(Appears on:TaskSpec)

Step runs a subcomponent of a Task

Field	Description
`name` string	Name of the Step specified as a DNS_LABEL. Each Step in a Task must have a unique name.
`displayName` string	(Optional) DisplayName is a user-facing name of the step that may be used to populate a UI.
`image` string	(Optional) Docker image name. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`envFrom` []Kubernetes core/v1.EnvFromSource	(Optional) List of sources to populate environment variables in the Step. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the Step is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the Step. Cannot be updated.
`computeResources` Kubernetes core/v1.ResourceRequirements	(Optional) ComputeResources required by this Step. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.
`volumeDevices` []Kubernetes core/v1.VolumeDevice	(Optional) volumeDevices is the list of block devices to be used by the Step.
`imagePullPolicy` Kubernetes core/v1.PullPolicy	(Optional) Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.
`timeout` Kubernetes meta/v1.Duration	(Optional) Timeout is the time after which the step times out. Defaults to never. Refer to Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`workspaces` []WorkspaceUsage	(Optional) This is an alpha field. You must set the “enable-api-fields” feature flag to “alpha” for this field to be supported. Workspaces is a list of workspaces from the Task that this Step wants exclusive access to. Adding a workspace to this list means that any other Step or Sidecar that does not also request this Workspace will not have access to it.
`onError` OnErrorType	OnError defines the exiting behavior of a container on error can be set to [ continue \| stopAndFail ]
`stdoutConfig` StepOutputConfig	(Optional) Stores configuration for the stdout stream of the step.
`stderrConfig` StepOutputConfig	(Optional) Stores configuration for the stderr stream of the step.
`ref` Ref	(Optional) Contains the reference to an existing StepAction.
`params` Params	(Optional) Params declares parameters passed to this step action.
`results` []StepResult	(Optional) Results declares StepResults produced by the Step. It can be used in an inlined Step when used to store Results to $(step.results.resultName.path). It cannot be used when referencing StepActions using [v1.Step.Ref]. The Results declared by the StepActions will be stored here instead.
`when` StepWhenExpressions	(Optional) When is a list of when expressions that need to be true for the task to run

StepOutputConfig

(Appears on:Step)

StepOutputConfig stores configuration for a step output stream.

Field	Description
`path` string	(Optional) Path to duplicate stdout stream to on container’s local filesystem.

StepResult

(Appears on:Step, StepActionSpec, Step, StepActionSpec)

StepResult used to describe the Results of a Step.

Field	Description
`name` string	Name the given name
`type` ResultsType	(Optional) The possible types are ‘string’, ‘array’, and ‘object’, with ‘string’ as the default.
`properties` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.PropertySpec	(Optional) Properties is the JSON Schema properties to support key-value pairs results.
`description` string	(Optional) Description is a human-readable description of the result

StepState

(Appears on:TaskRunStatusFields)

StepState reports the results of running a step in a Task.

Field	Description
`ContainerState` Kubernetes core/v1.ContainerState	(Members of `ContainerState` are embedded into this type.)
`name` string
`container` string
`imageID` string
`results` []TaskRunStepResult
`provenance` Provenance
`terminationReason` string
`inputs` []TaskRunStepArtifact
`outputs` []TaskRunStepArtifact

StepTemplate

(Appears on:TaskSpec)

StepTemplate is a template for a Step

Field	Description
`image` string	(Optional) Image reference name. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Step’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Step’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`envFrom` []Kubernetes core/v1.EnvFromSource	(Optional) List of sources to populate environment variables in the Step. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the Step is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the Step. Cannot be updated.
`computeResources` Kubernetes core/v1.ResourceRequirements	(Optional) ComputeResources required by this Step. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.
`volumeDevices` []Kubernetes core/v1.VolumeDevice	(Optional) volumeDevices is the list of block devices to be used by the Step.
`imagePullPolicy` Kubernetes core/v1.PullPolicy	(Optional) Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/

StepWhenExpressions

(Appears on:Step)

TaskBreakpoints

(Appears on:TaskRunDebug)

TaskBreakpoints defines the breakpoint config for a particular Task

Field	Description
`onFailure` string	(Optional) if enabled, pause TaskRun on failure of a step failed step will not exit
`beforeSteps` []string	(Optional)

TaskKind (`string` alias)

(Appears on:TaskRef)

TaskKind defines the type of Task used by the pipeline.

Value	Description
"Task"	NamespacedTaskKind indicates that the task type has a namespaced scope.

TaskRef

(Appears on:PipelineTask, TaskRunSpec)

TaskRef can be used to refer to a specific instance of a task.

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`kind` TaskKind	TaskKind indicates the Kind of the Task: 1. Namespaced Task when Kind is set to “Task”. If Kind is “”, it defaults to “Task”. 2. Custom Task when Kind is non-empty and APIVersion is non-empty
`apiVersion` string	(Optional) API version of the referent Note: A Task with non-empty APIVersion and Kind is considered a Custom Task
`ResolverRef` ResolverRef	(Optional) ResolverRef allows referencing a Task in a remote location like a git repo. This field is only supported when the alpha feature gate is enabled.

TaskResult

(Appears on:TaskSpec)

TaskResult used to describe the results of a task

Field	Description
`name` string	Name the given name
`type` ResultsType	(Optional) Type is the user-specified type of the result. The possible type is currently “string” and will support “array” in following work.
`properties` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.PropertySpec	(Optional) Properties is the JSON Schema properties to support key-value pairs results.
`description` string	(Optional) Description is a human-readable description of the result
`value` ResultValue	(Optional) Value the expression used to retrieve the value of the result from an underlying Step.

TaskRunDebug

(Appears on:TaskRunSpec)

TaskRunDebug defines the breakpoint config for a particular TaskRun

Field	Description
`breakpoints` TaskBreakpoints	(Optional)

TaskRunInputs

TaskRunInputs holds the input values that this task was invoked with.

Field	Description
`params` Params	(Optional)

TaskRunReason (`string` alias)

TaskRunReason is an enum used to store all TaskRun reason for the Succeeded condition that are controlled by the TaskRun itself. Failure reasons that emerge from underlying resources are not included here

Value	Description
"TaskRunCancelled"	TaskRunReasonCancelled is the reason set when the TaskRun is cancelled by the user
"CreateContainerConfigError"	TaskRunReasonCreateContainerConfigError is the reason set when the step of a task fails due to config error (e.g., missing ConfigMap or Secret)
"Failed"	TaskRunReasonFailed is the reason set when the TaskRun completed with a failure
"TaskRunResolutionFailed"	TaskRunReasonFailedResolution indicated that the reason for failure status is that references within the TaskRun could not be resolved
"TaskRunValidationFailed"	TaskRunReasonFailedValidation indicated that the reason for failure status is that taskrun failed runtime validation
"FailureIgnored"	TaskRunReasonFailureIgnored is the reason set when the Taskrun has failed due to pod execution error and the failure is ignored for the owning PipelineRun. TaskRuns failed due to reconciler/validation error should not use this reason.
"TaskRunImagePullFailed"	TaskRunReasonImagePullFailed is the reason set when the step of a task fails due to image not being pulled
"InvalidParamValue"	TaskRunReasonInvalidParamValue indicates that the TaskRun Param input value is not allowed.
"PodCreationFailed"	TaskRunReasonPodCreationFailed is the reason set when the pod backing the TaskRun fails to be created (e.g., CreateContainerError)
"ResourceVerificationFailed"	TaskRunReasonResourceVerificationFailed indicates that the task fails the trusted resource verification, it could be the content has changed, signature is invalid or public key is invalid
"TaskRunResultLargerThanAllowedLimit"	TaskRunReasonResultLargerThanAllowedLimit is the reason set when one of the results exceeds its maximum allowed limit of 1 KB
"Running"	TaskRunReasonRunning is the reason set when the TaskRun is running
"Started"	TaskRunReasonStarted is the reason set when the TaskRun has just started
"TaskRunStopSidecarFailed"	TaskRunReasonStopSidecarFailed indicates that the sidecar is not properly stopped.
"Succeeded"	TaskRunReasonSuccessful is the reason set when the TaskRun completed successfully
"TaskValidationFailed"	TaskRunReasonTaskFailedValidation indicated that the reason for failure status is that task failed runtime validation
"TaskRunTimeout"	TaskRunReasonTimedOut is the reason set when one TaskRun execution has timed out
"ToBeRetried"	TaskRunReasonToBeRetried is the reason set when the last TaskRun execution failed, and will be retried

TaskRunResult

(Appears on:TaskRunStatusFields)

TaskRunResult used to describe the results of a task

Field	Description
`name` string	Name the given name
`type` ResultsType	(Optional) Type is the user-specified type of the result. The possible type is currently “string” and will support “array” in following work.
`value` ResultValue	Value the given value of the result

TaskRunSidecarSpec

(Appears on:PipelineTaskRunSpec, TaskRunSpec)

TaskRunSidecarSpec is used to override the values of a Sidecar in the corresponding Task.

Field	Description
`name` string	The name of the Sidecar to override.
`computeResources` Kubernetes core/v1.ResourceRequirements	The resource requirements to apply to the Sidecar.

TaskRunSpec

(Appears on:TaskRun)

TaskRunSpec defines the desired state of TaskRun

Field	Description
`debug` TaskRunDebug	(Optional)
`params` Params	(Optional)
`serviceAccountName` string	(Optional)
`taskRef` TaskRef	(Optional) no more than one of the TaskRef and TaskSpec may be specified.
`taskSpec` TaskSpec	(Optional) Specifying TaskSpec can be disabled by setting `disable-inline-spec` feature flag. See Task.spec (API version: tekton.dev/v1)
`status` TaskRunSpecStatus	(Optional) Used for cancelling a TaskRun (and maybe more later on)
`statusMessage` TaskRunSpecStatusMessage	(Optional) Status message for cancellation.
`retries` int	(Optional) Retries represents how many times this TaskRun should be retried in the event of task failure.
`timeout` Kubernetes meta/v1.Duration	(Optional) Time after which one retry attempt times out. Defaults to 1 hour. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`podTemplate` PodTemplate	PodTemplate holds pod specific configuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces is a list of WorkspaceBindings from volumes to workspaces.
`stepSpecs` []TaskRunStepSpec	(Optional) Specs to apply to Steps in this TaskRun. If a field is specified in both a Step and a StepSpec, the value from the StepSpec will be used. This field is only supported when the alpha feature gate is enabled.
`sidecarSpecs` []TaskRunSidecarSpec	(Optional) Specs to apply to Sidecars in this TaskRun. If a field is specified in both a Sidecar and a SidecarSpec, the value from the SidecarSpec will be used. This field is only supported when the alpha feature gate is enabled.
`computeResources` Kubernetes core/v1.ResourceRequirements	Compute resources to use for this TaskRun
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

TaskRunSpecStatus (`string` alias)

(Appears on:TaskRunSpec)

TaskRunSpecStatus defines the TaskRun spec status the user can provide

TaskRunSpecStatusMessage (`string` alias)

(Appears on:TaskRunSpec)

TaskRunSpecStatusMessage defines human readable status messages for the TaskRun.

Value	Description
"TaskRun cancelled as the PipelineRun it belongs to has been cancelled."	TaskRunCancelledByPipelineMsg indicates that the PipelineRun of which this TaskRun was a part of has been cancelled.
"TaskRun cancelled as the PipelineRun it belongs to has timed out."	TaskRunCancelledByPipelineTimeoutMsg indicates that the TaskRun was cancelled because the PipelineRun running it timed out.

TaskRunStatus

(Appears on:TaskRun, PipelineRunTaskRunStatus)

TaskRunStatus defines the observed state of TaskRun

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

TaskRunStatusFields
TaskRunStatusFields

(Members of TaskRunStatusFields are embedded into this type.)

TaskRunStatusFields inlines the status fields.

TaskRunStatusFields

(Appears on:TaskRunStatus)

TaskRunStatusFields holds the fields of TaskRun’s status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

Field	Description
`podName` string	PodName is the name of the pod responsible for executing this task’s steps.
`startTime` Kubernetes meta/v1.Time	StartTime is the time the build is actually started.
`completionTime` Kubernetes meta/v1.Time	CompletionTime is the time the build completed.
`steps` []StepState	(Optional) Steps describes the state of each build step container.
`retriesStatus` RetriesStatus	(Optional) RetriesStatus contains the history of TaskRunStatus in case of a retry in order to keep record of failures. All TaskRunStatus stored in RetriesStatus will have no date within the RetriesStatus as is redundant.
`results` []TaskRunResult	(Optional) Results are the list of results written out by the task’s containers
`artifacts` Artifacts	(Optional) Artifacts are the list of artifacts written out by the task’s containers
`sidecars` []SidecarState	The list has one entry per sidecar in the manifest. Each entry is represents the imageid of the corresponding sidecar.
`taskSpec` TaskSpec	TaskSpec contains the Spec from the dereferenced Task definition used to instantiate this TaskRun.
`provenance` Provenance	(Optional) Provenance contains some key authenticated metadata about how a software artifact was built (what sources, what inputs/outputs, etc.).
`spanContext` map[string]string	SpanContext contains tracing span context fields

TaskRunStepArtifact

(Appears on:StepState)

TaskRunStepArtifact represents an artifact produced or used by a step within a task run. It directly uses the Artifact type for its structure.

TaskRunStepResult

(Appears on:StepState)

TaskRunStepResult is a type alias of TaskRunResult

TaskRunStepSpec

(Appears on:PipelineTaskRunSpec, TaskRunSpec)

TaskRunStepSpec is used to override the values of a Step in the corresponding Task.

Field	Description
`name` string	The name of the Step to override.
`computeResources` Kubernetes core/v1.ResourceRequirements	The resource requirements to apply to the Step.

TaskSpec

(Appears on:Task, EmbeddedTask, TaskRunSpec, TaskRunStatusFields)

TaskSpec defines the desired state of Task.

Field	Description
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the task. Params must be supplied as inputs in TaskRuns unless they declare a default value.
`displayName` string	(Optional) DisplayName is a user-facing name of the task that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the task that may be used to populate a UI.
`steps` []Step	Steps are the steps of the build; each step is run sequentially with the source mounted into /workspace.
`volumes` Volumes	Volumes is a collection of volumes that are available to mount into the steps of the build. See Pod.spec.volumes (API version: v1)
`stepTemplate` StepTemplate	StepTemplate can be used as the basis for all step containers within the Task, so that the steps inherit settings on the base container.
`sidecars` []Sidecar	Sidecars are run alongside the Task’s step containers. They begin before the steps start and end after the steps complete.
`workspaces` []WorkspaceDeclaration	Workspaces are the volumes that this Task requires.
`results` []TaskResult	Results are values that this Task can output

TimeoutFields

(Appears on:PipelineRunSpec)

TimeoutFields allows granular specification of pipeline, task, and finally timeouts

Field	Description
`pipeline` Kubernetes meta/v1.Duration	Pipeline sets the maximum allowed duration for execution of the entire pipeline. The sum of individual timeouts for tasks and finally must not exceed this value.
`tasks` Kubernetes meta/v1.Duration	Tasks sets the maximum allowed duration of this pipeline’s tasks
`finally` Kubernetes meta/v1.Duration	Finally sets the maximum allowed duration of this pipeline’s finally

Volumes (`[]k8s.io/api/core/v1.Volume` alias)

(Appears on:TaskSpec)

WhenExpression

(Appears on:ChildStatusReference, PipelineRunRunStatus, PipelineRunTaskRunStatus, SkippedTask)

WhenExpression allows a PipelineTask to declare expressions to be evaluated before the Task is run to determine whether the Task should be executed or skipped

Field	Description
`input` string	Input is the string for guard checking which can be a static input or an output from a parent Task
`operator` k8s.io/apimachinery/pkg/selection.Operator	Operator that represents an Input’s relationship to the values
`values` []string	Values is an array of strings, which is compared against the input, for guard checking It must be non-empty
`cel` string	(Optional) CEL is a string of Common Language Expression, which can be used to conditionally execute the task based on the result of the expression evaluation More info about CEL syntax: https://github.com/google/cel-spec/blob/master/doc/langdef.md

WhenExpressions (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.WhenExpression` alias)

(Appears on:PipelineTask)

WhenExpressions are used to specify whether a Task should be executed or skipped All of them need to evaluate to True for a guarded Task to be executed.

WorkspaceBinding

(Appears on:PipelineRunSpec, TaskRunSpec)

WorkspaceBinding maps a Task’s declared workspace to a Volume.

Field	Description
`name` string	Name is the name of the workspace populated by the volume.
`subPath` string	(Optional) SubPath is optionally a directory on the volume which should be used for this binding (i.e. the volume will be mounted at this sub directory).
`volumeClaimTemplate` Kubernetes core/v1.PersistentVolumeClaim	(Optional) VolumeClaimTemplate is a template for a claim that will be created in the same namespace. The PipelineRun controller is responsible for creating a unique claim for each instance of PipelineRun. See PersistentVolumeClaim (API version: v1)
`persistentVolumeClaim` Kubernetes core/v1.PersistentVolumeClaimVolumeSource	(Optional) PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. Either this OR EmptyDir can be used.
`emptyDir` Kubernetes core/v1.EmptyDirVolumeSource	(Optional) EmptyDir represents a temporary directory that shares a Task’s lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir Either this OR PersistentVolumeClaim can be used.
`configMap` Kubernetes core/v1.ConfigMapVolumeSource	(Optional) ConfigMap represents a configMap that should populate this workspace.
`secret` Kubernetes core/v1.SecretVolumeSource	(Optional) Secret represents a secret that should populate this workspace.
`projected` Kubernetes core/v1.ProjectedVolumeSource	(Optional) Projected represents a projected volume that should populate this workspace.
`csi` Kubernetes core/v1.CSIVolumeSource	(Optional) CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers.

WorkspaceDeclaration

(Appears on:TaskSpec)

WorkspaceDeclaration is a declaration of a volume that a Task requires.

Field	Description
`name` string	Name is the name by which you can bind the volume at runtime.
`description` string	(Optional) Description is an optional human readable description of this volume.
`mountPath` string	(Optional) MountPath overrides the directory that the volume will be made available at.
`readOnly` bool	ReadOnly dictates whether a mounted volume is writable. By default this field is false and so mounted volumes are writable.
`optional` bool	Optional marks a Workspace as not being required in TaskRuns. By default this field is false and so declared workspaces are required.

WorkspacePipelineDeclaration

WorkspacePipelineDeclaration creates a named slot in a Pipeline that a PipelineRun is expected to populate with a workspace binding.

Deprecated: use PipelineWorkspaceDeclaration type instead

WorkspacePipelineTaskBinding

(Appears on:PipelineTask)

WorkspacePipelineTaskBinding describes how a workspace passed into the pipeline should be mapped to a task’s declared workspace.

Field	Description
`name` string	Name is the name of the workspace as declared by the task
`workspace` string	(Optional) Workspace is the name of the workspace declared by the pipeline
`subPath` string	(Optional) SubPath is optionally a directory on the volume which should be used for this binding (i.e. the volume will be mounted at this sub directory).

WorkspaceUsage

(Appears on:Sidecar, Step)

WorkspaceUsage is used by a Step or Sidecar to declare that it wants isolated access to a Workspace defined in a Task.

Field	Description
`name` string	Name is the name of the workspace this Step or Sidecar wants access to.
`mountPath` string	MountPath is the path that the workspace should be mounted to inside the Step or Sidecar, overriding any MountPath specified in the Task’s WorkspaceDeclaration.

tekton.dev/v1alpha1

Package v1alpha1 contains API Schema definitions for the pipeline v1alpha1 API group

Resource Types:

Run

Run represents a single execution of a Custom Task.

Field Description

apiVersion
string tekton.dev/v1alpha1

kind
string Run

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
RunSpec

(Optional)

ref
TaskRef (Optional)

spec
EmbeddedRunSpec

(Optional)

Spec is a specification of a custom task

params
Params (Optional)

status
RunSpecStatus

(Optional)

Used for cancelling a run (and maybe more later on)

statusMessage
RunSpecStatusMessage

(Optional)

Status message for cancellation.

retries
int

(Optional)

Used for propagating retries count to custom tasks

serviceAccountName
string (Optional)

podTemplate
PodTemplate

(Optional)

PodTemplate holds pod specific configuration

timeout
Kubernetes meta/v1.Duration

(Optional)

Time after which the custom-task times out. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration

workspaces
[]WorkspaceBinding

(Optional)

Workspaces is a list of WorkspaceBindings from volumes to workspaces.

status
RunStatus (Optional)

StepAction

StepAction represents the actionable components of Step. The Step can only reference it from the cluster or using remote resolution.

Field Description

apiVersion
string tekton.dev/v1alpha1

kind
string StepAction

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
StepActionSpec

(Optional)

Spec holds the desired state of the Step from the client

`description` string	(Optional) Description is a user-facing description of the stepaction that may be used to populate a UI.
`image` string	(Optional) Image reference name to run for this StepAction. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the container. Cannot be updated.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the stepAction. Params must be supplied as inputs in Steps unless they declare a defaultvalue.
`results` []StepResult	(Optional) Results are values that this StepAction can output
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ The value set in StepAction will take precedence over the value from Task.
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.

VerificationPolicy

VerificationPolicy defines the rules to verify Tekton resources. VerificationPolicy can config the mapping from resources to a list of public keys, so when verifying the resources we can use the corresponding public keys.

Field Description

apiVersion
string tekton.dev/v1alpha1

kind
string VerificationPolicy

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
VerificationPolicySpec

Spec holds the desired state of the VerificationPolicy.

`resources` []ResourcePattern	Resources defines the patterns of resources sources that should be subject to this policy. For example, we may want to apply this Policy from a certain GitHub repo. Then the ResourcesPattern should be valid regex. E.g. If using gitresolver, and we want to config keys from a certain git repo. `ResourcesPattern` can be `https://github.com/tektoncd/catalog.git`, we will use regex to filter out those resources.
`authorities` []Authority	Authorities defines the rules for validating signatures.
`mode` ModeType	(Optional) Mode controls whether a failing policy will fail the taskrun/pipelinerun, or only log the warnings enforce - fail the taskrun/pipelinerun if verification fails (default) warn - don’t fail the taskrun/pipelinerun if verification fails but log warnings

PipelineResource

PipelineResource describes a resource that is an input to or output from a Task.

Deprecated: Unused, preserved only for backwards compatibility

Field Description

apiVersion
string tekton.dev/v1alpha1

kind
string PipelineResource

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
PipelineResourceSpec

Spec holds the desired state of the PipelineResource from the client

`description` string	(Optional) Description is a user-facing description of the resource that may be used to populate a UI.
`type` PipelineResourceType
`params` []ResourceParam
`secrets` []SecretParam	(Optional) Secrets to fetch to populate some of resource fields

status
PipelineResourceStatus

(Optional)

Status is used to communicate the observed state of the PipelineResource from the controller, but was unused as there is no controller for PipelineResource.

Authority

(Appears on:VerificationPolicySpec)

The Authority block defines the keys for validating signatures.

Field	Description
`name` string	Name is the name for this authority.
`key` KeyRef	Key contains the public key to validate the resource.

EmbeddedRunSpec

(Appears on:RunSpec)

EmbeddedRunSpec allows custom task definitions to be embedded

Field Description

metadata
PipelineTaskMetadata (Optional)

spec
k8s.io/apimachinery/pkg/runtime.RawExtension

(Optional)

Spec is a specification of a custom task

-
[]byte

Raw is the underlying serialization of this object.

TODO: Determine how to detect ContentType and ContentEncoding of ‘Raw’ data.

-
k8s.io/apimachinery/pkg/runtime.Object

Object can hold a representation of this extension - useful for working with versioned structs.

HashAlgorithm (`string` alias)

(Appears on:KeyRef)

HashAlgorithm defines the hash algorithm used for the public key

KeyRef

(Appears on:Authority)

KeyRef defines the reference to a public key

Field	Description
`secretRef` Kubernetes core/v1.SecretReference	(Optional) SecretRef sets a reference to a secret with the key.
`data` string	(Optional) Data contains the inline public key.
`kms` string	(Optional) KMS contains the KMS url of the public key Supported formats differ based on the KMS system used. One example of a KMS url could be: gcpkms://projects/[PROJECT]/locations/[LOCATION]>/keyRings/[KEYRING]/cryptoKeys/[KEY]/cryptoKeyVersions/[KEY_VERSION] For more examples please refer https://docs.sigstore.dev/cosign/kms_support. Note that the KMS is not supported yet.
`hashAlgorithm` HashAlgorithm	(Optional) HashAlgorithm always defaults to sha256 if the algorithm hasn’t been explicitly set

ModeType (`string` alias)

(Appears on:VerificationPolicySpec)

ModeType indicates the type of a mode for VerificationPolicy

ResourcePattern

(Appears on:VerificationPolicySpec)

ResourcePattern defines the pattern of the resource source

Field	Description
`pattern` string	Pattern defines a resource pattern. Regex is created to filter resources based on `Pattern` Example patterns: GitHub resource: https://github.com/tektoncd/catalog.git, https://github.com/tektoncd/* Bundle resource: gcr.io/tekton-releases/catalog/upstream/git-clone, gcr.io/tekton-releases/catalog/upstream/* Hub resource: https://artifacthub.io/*,

RunReason (`string` alias)

RunReason is an enum used to store all Run reason for the Succeeded condition that are controlled by the Run itself.

RunResult

RunResult used to describe the results of a task

RunSpec

(Appears on:Run)

RunSpec defines the desired state of Run

Field Description

ref
TaskRef (Optional)

spec
EmbeddedRunSpec

(Optional)

Spec is a specification of a custom task

params
Params (Optional)

status
RunSpecStatus

(Optional)

Used for cancelling a run (and maybe more later on)

statusMessage
RunSpecStatusMessage

(Optional)

Status message for cancellation.

retries
int

(Optional)

Used for propagating retries count to custom tasks

serviceAccountName
string (Optional)

podTemplate
PodTemplate

(Optional)

PodTemplate holds pod specific configuration

timeout
Kubernetes meta/v1.Duration

(Optional)

Time after which the custom-task times out. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration

workspaces
[]WorkspaceBinding

(Optional)

Workspaces is a list of WorkspaceBindings from volumes to workspaces.

RunSpecStatus (`string` alias)

(Appears on:RunSpec)

RunSpecStatus defines the taskrun spec status the user can provide

RunSpecStatusMessage (`string` alias)

(Appears on:RunSpec)

RunSpecStatusMessage defines human readable status messages for the TaskRun.

RunStatus

(Appears on:Run)

RunStatus defines the observed state of Run.

RunStatusFields

RunStatusFields holds the fields of Run’s status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

StepActionObject

StepActionObject is implemented by StepAction

StepActionSpec

(Appears on:StepAction)

StepActionSpec contains the actionable components of a step.

Field	Description
`description` string	(Optional) Description is a user-facing description of the stepaction that may be used to populate a UI.
`image` string	(Optional) Image reference name to run for this StepAction. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the container. Cannot be updated.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the stepAction. Params must be supplied as inputs in Steps unless they declare a defaultvalue.
`results` []StepResult	(Optional) Results are values that this StepAction can output
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ The value set in StepAction will take precedence over the value from Task.
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.

VerificationPolicySpec

(Appears on:VerificationPolicy)

VerificationPolicySpec defines the patterns and authorities.

Field	Description
`resources` []ResourcePattern	Resources defines the patterns of resources sources that should be subject to this policy. For example, we may want to apply this Policy from a certain GitHub repo. Then the ResourcesPattern should be valid regex. E.g. If using gitresolver, and we want to config keys from a certain git repo. `ResourcesPattern` can be `https://github.com/tektoncd/catalog.git`, we will use regex to filter out those resources.
`authorities` []Authority	Authorities defines the rules for validating signatures.
`mode` ModeType	(Optional) Mode controls whether a failing policy will fail the taskrun/pipelinerun, or only log the warnings enforce - fail the taskrun/pipelinerun if verification fails (default) warn - don’t fail the taskrun/pipelinerun if verification fails but log warnings

PipelineResourceSpec

(Appears on:PipelineResource, PipelineResourceBinding)

PipelineResourceSpec defines an individual resources used in the pipeline.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`description` string	(Optional) Description is a user-facing description of the resource that may be used to populate a UI.
`type` PipelineResourceType
`params` []ResourceParam
`secrets` []SecretParam	(Optional) Secrets to fetch to populate some of resource fields

PipelineResourceStatus

(Appears on:PipelineResource)

PipelineResourceStatus does not contain anything because PipelineResources on their own do not have a status

Deprecated: Unused, preserved only for backwards compatibility

PipelineResourceType

(Appears on:PipelineResourceSpec, ResourceDeclaration)

PipelineResourceType represents the type of endpoint the pipelineResource is, so that the controller will know this pipelineResource shouldx be fetched and optionally what additional metatdata should be provided for it.

Deprecated: Unused, preserved only for backwards compatibility

ResourceDeclaration

ResourceDeclaration defines an input or output PipelineResource declared as a requirement by another type such as a Task or Condition. The Name field will be used to refer to these PipelineResources within the type’s definition, and when provided as an Input, the Name will be the path to the volume mounted containing this PipelineResource as an input (e.g. an input Resource named workspace will be mounted at /workspace).

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string	Name declares the name by which a resource is referenced in the definition. Resources may be referenced by name in the definition of a Task’s steps.
`type` PipelineResourceType	Type is the type of this resource;
`description` string	(Optional) Description is a user-facing description of the declared resource that may be used to populate a UI.
`targetPath` string	(Optional) TargetPath is the path in workspace directory where the resource will be copied.
`optional` bool	Optional declares the resource as optional. By default optional is set to false which makes a resource required. optional: true - the resource is considered optional optional: false - the resource is considered required (equivalent of not specifying it)

ResourceParam

(Appears on:PipelineResourceSpec)

ResourceParam declares a string value to use for the parameter called Name, and is used in the specific context of PipelineResources.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string
`value` string

SecretParam

(Appears on:PipelineResourceSpec)

SecretParam indicates which secret can be used to populate a field of the resource

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`fieldName` string
`secretKey` string
`secretName` string

RunResult

(Appears on:RunStatusFields)

RunResult used to describe the results of a task

Field	Description
`name` string	Name the given name
`value` string	Value the given value of the result

RunStatus

(Appears on:RunStatusFields)

RunStatus defines the observed state of Run

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

RunStatusFields
RunStatusFields

(Members of RunStatusFields are embedded into this type.)

RunStatusFields inlines the status fields.

RunStatusFields

(Appears on:RunStatus)

RunStatusFields holds the fields of Run’s status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

Field	Description
`startTime` Kubernetes meta/v1.Time	(Optional) StartTime is the time the build is actually started.
`completionTime` Kubernetes meta/v1.Time	(Optional) CompletionTime is the time the build completed.
`results` []RunResult	(Optional) Results reports any output result values to be consumed by later tasks in a pipeline.
`retriesStatus` []RunStatus	(Optional) RetriesStatus contains the history of RunStatus, in case of a retry.
`extraFields` k8s.io/apimachinery/pkg/runtime.RawExtension	ExtraFields holds arbitrary fields provided by the custom task controller.

tekton.dev/v1beta1

Package v1beta1 contains API Schema definitions for the pipeline v1beta1 API group

Resource Types:

CustomRun

CustomRun represents a single execution of a Custom Task.

Field Description

apiVersion
string tekton.dev/v1beta1

kind
string CustomRun

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
CustomRunSpec

(Optional)

`customRef` TaskRef	(Optional)
`customSpec` EmbeddedCustomRunSpec	(Optional) Spec is a specification of a custom task
`params` Params	(Optional)
`status` CustomRunSpecStatus	(Optional) Used for cancelling a customrun (and maybe more later on)
`statusMessage` CustomRunSpecStatusMessage	(Optional) Status message for cancellation.
`retries` int	(Optional) Used for propagating retries count to custom tasks
`serviceAccountName` string	(Optional)
`timeout` Kubernetes meta/v1.Duration	(Optional) Time after which the custom-task times out. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces is a list of WorkspaceBindings from volumes to workspaces.

status
CustomRunStatus (Optional)

Pipeline

Pipeline describes a list of Tasks to execute. It expresses how outputs of tasks feed into inputs of subsequent tasks.

Deprecated: Please use v1.Pipeline instead.

Field Description

apiVersion
string tekton.dev/v1beta1

kind
string Pipeline

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
PipelineSpec

(Optional)

Spec holds the desired state of the Pipeline from the client

`displayName` string	(Optional) DisplayName is a user-facing name of the pipeline that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the pipeline that may be used to populate a UI.
`resources` []PipelineDeclaredResource	Deprecated: Unused, preserved only for backwards compatibility
`tasks` []PipelineTask	Tasks declares the graph of Tasks that execute when this Pipeline is run.
`params` ParamSpecs	Params declares a list of input parameters that must be supplied when this Pipeline is run.
`workspaces` []PipelineWorkspaceDeclaration	(Optional) Workspaces declares a set of named workspaces that are expected to be provided by a PipelineRun.
`results` []PipelineResult	(Optional) Results are values that this pipeline can output once run
`finally` []PipelineTask	Finally declares the list of Tasks that execute just before leaving the Pipeline i.e. either after all Tasks are finished executing successfully or after a failure which would result in ending the Pipeline

PipelineRun

Deprecated: Please use v1.PipelineRun instead.

Field Description

apiVersion
string tekton.dev/v1beta1

kind
string PipelineRun

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
PipelineRunSpec

(Optional)

`pipelineRef` PipelineRef	(Optional)
`pipelineSpec` PipelineSpec	(Optional) Specifying PipelineSpec can be disabled by setting `disable-inline-spec` feature flag. See Pipeline.spec (API version: tekton.dev/v1beta1)
`resources` []PipelineResourceBinding	Resources is a list of bindings specifying which actual instances of PipelineResources to use for the resources the Pipeline has declared it needs. Deprecated: Unused, preserved only for backwards compatibility
`params` Params	Params is a list of parameter names and values.
`serviceAccountName` string	(Optional)
`status` PipelineRunSpecStatus	(Optional) Used for cancelling a pipelinerun (and maybe more later on)
`timeouts` TimeoutFields	(Optional) Time after which the Pipeline times out. Currently three keys are accepted in the map pipeline, tasks and finally with Timeouts.pipeline >= Timeouts.tasks + Timeouts.finally
`timeout` Kubernetes meta/v1.Duration	(Optional) Timeout is the Time after which the Pipeline times out. Defaults to never. Refer to Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration Deprecated: use pipelineRunSpec.Timeouts.Pipeline instead
`podTemplate` PodTemplate	PodTemplate holds pod specific configuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces holds a set of workspace bindings that must match names with those declared in the pipeline.
`taskRunSpecs` []PipelineTaskRunSpec	(Optional) TaskRunSpecs holds a set of runtime specs
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

status
PipelineRunStatus (Optional)

StepAction

StepAction represents the actionable components of Step. The Step can only reference it from the cluster or using remote resolution.

Field Description

apiVersion
string tekton.dev/v1beta1

kind
string StepAction

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
StepActionSpec

(Optional)

Spec holds the desired state of the Step from the client

`description` string	(Optional) Description is a user-facing description of the stepaction that may be used to populate a UI.
`image` string	(Optional) Image reference name to run for this StepAction. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` Args	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the container. Cannot be updated.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the stepAction. Params must be supplied as inputs in Steps unless they declare a defaultvalue.
`results` []StepResult	(Optional) Results are values that this StepAction can output
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ The value set in StepAction will take precedence over the value from Task.
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.

Task

Deprecated: Please use v1.Task instead.

Field Description

apiVersion
string tekton.dev/v1beta1

kind
string Task

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TaskSpec

(Optional)

Spec holds the desired state of the Task from the client

`resources` TaskResources	(Optional) Resources is a list input and output resource to run the task Resources are represented in TaskRuns as bindings to instances of PipelineResources. Deprecated: Unused, preserved only for backwards compatibility
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the task. Params must be supplied as inputs in TaskRuns unless they declare a default value.
`displayName` string	(Optional) DisplayName is a user-facing name of the task that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the task that may be used to populate a UI.
`steps` []Step	Steps are the steps of the build; each step is run sequentially with the source mounted into /workspace.
`volumes` Volumes	Volumes is a collection of volumes that are available to mount into the steps of the build. See Pod.spec.volumes (API version: v1)
`stepTemplate` StepTemplate	StepTemplate can be used as the basis for all step containers within the Task, so that the steps inherit settings on the base container.
`sidecars` []Sidecar	Sidecars are run alongside the Task’s step containers. They begin before the steps start and end after the steps complete.
`workspaces` []WorkspaceDeclaration	Workspaces are the volumes that this Task requires.
`results` []TaskResult	Results are values that this Task can output

TaskRun

TaskRun represents a single execution of a Task. TaskRuns are how the steps specified in a Task are executed; they specify the parameters and resources used to run the steps in a Task.

Deprecated: Please use v1.TaskRun instead.

Field Description

apiVersion
string tekton.dev/v1beta1

kind
string TaskRun

metadata
Kubernetes meta/v1.ObjectMeta (Optional) Refer to the Kubernetes API documentation for the fields of the metadata field.

spec
TaskRunSpec

(Optional)

`debug` TaskRunDebug	(Optional)
`params` Params	(Optional)
`resources` TaskRunResources	(Optional) Deprecated: Unused, preserved only for backwards compatibility
`serviceAccountName` string	(Optional)
`taskRef` TaskRef	(Optional) no more than one of the TaskRef and TaskSpec may be specified.
`taskSpec` TaskSpec	(Optional) Specifying TaskSpec can be disabled by setting `disable-inline-spec` feature flag. See Task.spec (API version: tekton.dev/v1beta1)
`status` TaskRunSpecStatus	(Optional) Used for cancelling a TaskRun (and maybe more later on)
`statusMessage` TaskRunSpecStatusMessage	(Optional) Status message for cancellation.
`retries` int	(Optional) Retries represents how many times this TaskRun should be retried in the event of Task failure.
`timeout` Kubernetes meta/v1.Duration	(Optional) Time after which one retry attempt times out. Defaults to 1 hour. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`podTemplate` PodTemplate	PodTemplate holds pod specific configuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces is a list of WorkspaceBindings from volumes to workspaces.
`stepOverrides` []TaskRunStepOverride	(Optional) Overrides to apply to Steps in this TaskRun. If a field is specified in both a Step and a StepOverride, the value from the StepOverride will be used. This field is only supported when the alpha feature gate is enabled.
`sidecarOverrides` []TaskRunSidecarOverride	(Optional) Overrides to apply to Sidecars in this TaskRun. If a field is specified in both a Sidecar and a SidecarOverride, the value from the SidecarOverride will be used. This field is only supported when the alpha feature gate is enabled.
`computeResources` Kubernetes core/v1.ResourceRequirements	Compute resources to use for this TaskRun
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

status
TaskRunStatus (Optional)

Algorithm (`string` alias)

Algorithm Standard cryptographic hash algorithm

Args (`[]string` alias)

(Appears on:StepActionSpec)

ArrayOrString

ArrayOrString is deprecated, this is to keep backward compatibility

Deprecated: Use ParamValue instead.

Artifact

(Appears on:Artifacts)

Artifact represents an artifact within a system, potentially containing multiple values associated with it.

Field	Description
`name` string	The artifact’s identifying category name
`values` []ArtifactValue	A collection of values related to the artifact
`buildOutput` bool	Indicate if the artifact is a build output or a by-product

ArtifactValue

(Appears on:Artifact)

ArtifactValue represents a specific value or data element within an Artifact.

Field	Description
`digest` map[github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Algorithm]string
`uri` string	Algorithm-specific digests for verifying the content (e.g., SHA256)

Artifacts

Field	Description
`inputs` []Artifact
`outputs` []Artifact

ChildStatusReference

(Appears on:PipelineRunStatusFields)

ChildStatusReference is used to point to the statuses of individual TaskRuns and Runs within this PipelineRun.

Field	Description
`name` string	Name is the name of the TaskRun or Run this is referencing.
`displayName` string	DisplayName is a user-facing name of the pipelineTask that may be used to populate a UI.
`pipelineTaskName` string	PipelineTaskName is the name of the PipelineTask this is referencing.
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

CloudEventCondition (`string` alias)

(Appears on:CloudEventDeliveryState)

CloudEventCondition is a string that represents the condition of the event.

CloudEventDelivery

(Appears on:TaskRunStatusFields)

CloudEventDelivery is the target of a cloud event along with the state of delivery.

Field	Description
`target` string	Target points to an addressable
`status` CloudEventDeliveryState

CloudEventDeliveryState

(Appears on:CloudEventDelivery)

CloudEventDeliveryState reports the state of a cloud event to be sent.

Field	Description
`condition` CloudEventCondition	Current status
`sentAt` Kubernetes meta/v1.Time	(Optional) SentAt is the time at which the last attempt to send the event was made
`message` string	Error is the text of error (if any)
`retryCount` int32	RetryCount is the number of attempts of sending the cloud event

Combination (`map[string]string` alias)

Combination is a map, mainly defined to hold a single combination from a Matrix with key as param.Name and value as param.Value

Combinations (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Combination` alias)

Combinations is a Combination list

ConfigSource

(Appears on:Provenance)

ConfigSource contains the information that can uniquely identify where a remote built definition came from i.e. Git repositories, Tekton Bundles in OCI registry and hub.

Field	Description
`uri` string	URI indicates the identity of the source of the build definition. Example: “https://github.com/tektoncd/catalog”
`digest` map[string]string	Digest is a collection of cryptographic digests for the contents of the artifact specified by URI. Example: {“sha1”: “f99d13e554ffcb696dee719fa85b695cb5b0f428”}
`entryPoint` string	EntryPoint identifies the entry point into the build. This is often a path to a build definition file and/or a target label within that file. Example: “task/git-clone/0.10/git-clone.yaml”

CustomRunReason (`string` alias)

CustomRunReason is an enum used to store all Run reason for the Succeeded condition that are controlled by the CustomRun itself.

CustomRunResult

CustomRunResult used to describe the results of a task

CustomRunSpec

(Appears on:CustomRun)

CustomRunSpec defines the desired state of CustomRun

Field	Description
`customRef` TaskRef	(Optional)
`customSpec` EmbeddedCustomRunSpec	(Optional) Spec is a specification of a custom task
`params` Params	(Optional)
`status` CustomRunSpecStatus	(Optional) Used for cancelling a customrun (and maybe more later on)
`statusMessage` CustomRunSpecStatusMessage	(Optional) Status message for cancellation.
`retries` int	(Optional) Used for propagating retries count to custom tasks
`serviceAccountName` string	(Optional)
`timeout` Kubernetes meta/v1.Duration	(Optional) Time after which the custom-task times out. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces is a list of WorkspaceBindings from volumes to workspaces.

CustomRunSpecStatus (`string` alias)

(Appears on:CustomRunSpec)

CustomRunSpecStatus defines the taskrun spec status the user can provide

CustomRunSpecStatusMessage (`string` alias)

(Appears on:CustomRunSpec)

CustomRunSpecStatusMessage defines human readable status messages for the TaskRun.

CustomRunStatus

(Appears on:CustomRun, PipelineRunRunStatus)

CustomRunStatus defines the observed state of CustomRun.

CustomRunStatusFields

CustomRunStatusFields holds the fields of CustomRun’s status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

EmbeddedCustomRunSpec

(Appears on:CustomRunSpec)

EmbeddedCustomRunSpec allows custom task definitions to be embedded

Field Description

metadata
PipelineTaskMetadata (Optional)

spec
k8s.io/apimachinery/pkg/runtime.RawExtension

(Optional)

Spec is a specification of a custom task

-
[]byte

Raw is the underlying serialization of this object.

TODO: Determine how to detect ContentType and ContentEncoding of ‘Raw’ data.

-
k8s.io/apimachinery/pkg/runtime.Object

Object can hold a representation of this extension - useful for working with versioned structs.

EmbeddedTask

(Appears on:PipelineTask)

EmbeddedTask is used to define a Task inline within a Pipeline’s PipelineTasks.

Field Description

spec
k8s.io/apimachinery/pkg/runtime.RawExtension

(Optional)

Spec is a specification of a custom task

-
[]byte

Raw is the underlying serialization of this object.

TODO: Determine how to detect ContentType and ContentEncoding of ‘Raw’ data.

-
k8s.io/apimachinery/pkg/runtime.Object

Object can hold a representation of this extension - useful for working with versioned structs.

metadata
PipelineTaskMetadata (Optional)

TaskSpec
TaskSpec

(Members of TaskSpec are embedded into this type.)

(Optional)

TaskSpec is a specification of a task

IncludeParams

IncludeParams allows passing in a specific combinations of Parameters into the Matrix.

Field	Description
`name` string	Name the specified combination
`params` Params	Params takes only `Parameters` of type `"string"` The names of the `params` must match the names of the `params` in the underlying `Task`

InternalTaskModifier

InternalTaskModifier implements TaskModifier for resources that are built-in to Tekton Pipelines.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`stepsToPrepend` []Step
`stepsToAppend` []Step
`volumes` []Kubernetes core/v1.Volume

Matrix

(Appears on:PipelineTask)

Matrix is used to fan out Tasks in a Pipeline

Field	Description
`params` Params	Params is a list of parameters used to fan out the pipelineTask Params takes only `Parameters` of type `"array"` Each array element is supplied to the `PipelineTask` by substituting `params` of type `"string"` in the underlying `Task`. The names of the `params` in the `Matrix` must match the names of the `params` in the underlying `Task` that they will be substituting.
`include` IncludeParamsList	(Optional) Include is a list of IncludeParams which allows passing in specific combinations of Parameters into the Matrix.

OnErrorType (`string` alias)

(Appears on:Step)

OnErrorType defines a list of supported exiting behavior of a container on error

Param

(Appears on:TaskRunInputs)

Param declares an ParamValues to use for the parameter called name.

Field	Description
`name` string
`value` ParamValue

ParamSpec

ParamSpec defines arbitrary parameters needed beyond typed inputs (such as resources). Parameter values are provided by users as inputs on a TaskRun or PipelineRun.

Field	Description
`name` string	Name declares the name by which a parameter is referenced.
`type` ParamType	(Optional) Type is the user-specified type of the parameter. The possible types are currently “string”, “array” and “object”, and “string” is the default.
`description` string	(Optional) Description is a user-facing description of the parameter that may be used to populate a UI.
`properties` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.PropertySpec	(Optional) Properties is the JSON Schema properties to support key-value pairs parameter.
`default` ParamValue	(Optional) Default is the value a parameter takes if no input value is supplied. If default is set, a Task may be executed without a supplied value for the parameter.
`enum` []string	(Optional) Enum declares a set of allowed param input values for tasks/pipelines that can be validated. If Enum is not set, no input validation is performed for the param.

ParamSpecs (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.ParamSpec` alias)

(Appears on:PipelineSpec, TaskSpec)

ParamSpecs is a list of ParamSpec

ParamType (`string` alias)

(Appears on:ParamSpec, ParamValue, PropertySpec)

ParamType indicates the type of an input parameter; Used to distinguish between a single string and an array of strings.

ParamValue

(Appears on:Param, ParamSpec)

ParamValue is a type that can hold a single string or string array. Used in JSON unmarshalling so that a single JSON field can accept either an individual string or an array of strings.

Field	Description
`Type` ParamType
`StringVal` string	Represents the stored type of ParamValues.
`ArrayVal` []string
`ObjectVal` map[string]string

Params (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.Param` alias)

(Appears on:RunSpec, CustomRunSpec, IncludeParams, Matrix, PipelineRunSpec, PipelineTask, ResolverRef, Step, TaskRunSpec)

Params is a list of Param

PipelineDeclaredResource

(Appears on:PipelineSpec)

PipelineDeclaredResource is used by a Pipeline to declare the types of the PipelineResources that it will required to run and names which can be used to refer to these PipelineResources in PipelineTaskResourceBindings.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string	Name is the name that will be used by the Pipeline to refer to this resource. It does not directly correspond to the name of any PipelineResources Task inputs or outputs, and it does not correspond to the actual names of the PipelineResources that will be bound in the PipelineRun.
`type` PipelineResourceType	Type is the type of the PipelineResource.
`optional` bool	Optional declares the resource as optional. optional: true - the resource is considered optional optional: false - the resource is considered required (default/equivalent of not specifying it)

PipelineObject

PipelineObject is implemented by Pipeline

PipelineRef

(Appears on:PipelineRunSpec, PipelineTask)

PipelineRef can be used to refer to a specific instance of a Pipeline.

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`apiVersion` string	(Optional) API version of the referent
`bundle` string	(Optional) Bundle url reference to a Tekton Bundle. Deprecated: Please use ResolverRef with the bundles resolver instead. The field is staying there for go client backward compatibility, but is not used/allowed anymore.
`ResolverRef` ResolverRef	(Optional) ResolverRef allows referencing a Pipeline in a remote location like a git repo. This field is only supported when the alpha feature gate is enabled.

PipelineResourceBinding

(Appears on:PipelineRunSpec, TaskResourceBinding)

PipelineResourceBinding connects a reference to an instance of a PipelineResource with a PipelineResource dependency that the Pipeline has declared

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string	Name is the name of the PipelineResource in the Pipeline’s declaration
`resourceRef` PipelineResourceRef	(Optional) ResourceRef is a reference to the instance of the actual PipelineResource that should be used
`resourceSpec` PipelineResourceSpec	(Optional) ResourceSpec is specification of a resource that should be created and consumed by the task

PipelineResourceInterface

PipelineResourceInterface interface to be implemented by different PipelineResource types

Deprecated: Unused, preserved only for backwards compatibility

PipelineResourceRef

(Appears on:PipelineResourceBinding)

PipelineResourceRef can be used to refer to a specific instance of a Resource

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`apiVersion` string	(Optional) API version of the referent

PipelineResourceResult

(Appears on:TaskRunStatusFields)

PipelineResourceResult has been deprecated with the migration of PipelineResources Deprecated: Use RunResult instead

PipelineResourceType

(Appears on:PipelineDeclaredResource)

PipelineResourceType represents the type of endpoint the pipelineResource is, so that the controller will know this pipelineResource should be fetched and optionally what additional metatdata should be provided for it.

Deprecated: Unused, preserved only for backwards compatibility

PipelineResult

(Appears on:PipelineSpec)

PipelineResult used to describe the results of a pipeline

Field	Description
`name` string	Name the given name
`type` ResultsType	Type is the user-specified type of the result. The possible types are ‘string’, ‘array’, and ‘object’, with ‘string’ as the default. ‘array’ and ‘object’ types are alpha features.
`description` string	(Optional) Description is a human-readable description of the result
`value` ResultValue	Value the expression used to retrieve the value

PipelineRunReason (`string` alias)

PipelineRunReason represents a reason for the pipeline run “Succeeded” condition

PipelineRunResult

(Appears on:PipelineRunStatusFields)

PipelineRunResult used to describe the results of a pipeline

Field	Description
`name` string	Name is the result’s name as declared by the Pipeline
`value` ResultValue	Value is the result returned from the execution of this PipelineRun

PipelineRunRunStatus

(Appears on:PipelineRunStatusFields)

PipelineRunRunStatus contains the name of the PipelineTask for this CustomRun or Run and the CustomRun or Run’s Status

Field	Description
`pipelineTaskName` string	PipelineTaskName is the name of the PipelineTask.
`status` CustomRunStatus	(Optional) Status is the CustomRunStatus for the corresponding CustomRun or Run
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

PipelineRunSpec

(Appears on:PipelineRun)

PipelineRunSpec defines the desired state of PipelineRun

Field	Description
`pipelineRef` PipelineRef	(Optional)
`pipelineSpec` PipelineSpec	(Optional) Specifying PipelineSpec can be disabled by setting `disable-inline-spec` feature flag. See Pipeline.spec (API version: tekton.dev/v1beta1)
`resources` []PipelineResourceBinding	Resources is a list of bindings specifying which actual instances of PipelineResources to use for the resources the Pipeline has declared it needs. Deprecated: Unused, preserved only for backwards compatibility
`params` Params	Params is a list of parameter names and values.
`serviceAccountName` string	(Optional)
`status` PipelineRunSpecStatus	(Optional) Used for cancelling a pipelinerun (and maybe more later on)
`timeouts` TimeoutFields	(Optional) Time after which the Pipeline times out. Currently three keys are accepted in the map pipeline, tasks and finally with Timeouts.pipeline >= Timeouts.tasks + Timeouts.finally
`timeout` Kubernetes meta/v1.Duration	(Optional) Timeout is the Time after which the Pipeline times out. Defaults to never. Refer to Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration Deprecated: use pipelineRunSpec.Timeouts.Pipeline instead
`podTemplate` PodTemplate	PodTemplate holds pod specific configuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces holds a set of workspace bindings that must match names with those declared in the pipeline.
`taskRunSpecs` []PipelineTaskRunSpec	(Optional) TaskRunSpecs holds a set of runtime specs
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

PipelineRunSpecStatus (`string` alias)

(Appears on:PipelineRunSpec)

PipelineRunSpecStatus defines the pipelinerun spec status the user can provide

PipelineRunStatus

(Appears on:PipelineRun)

PipelineRunStatus defines the observed state of PipelineRun

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

PipelineRunStatusFields
PipelineRunStatusFields

(Members of PipelineRunStatusFields are embedded into this type.)

PipelineRunStatusFields inlines the status fields.

PipelineRunStatusFields

(Appears on:PipelineRunStatus)

PipelineRunStatusFields holds the fields of PipelineRunStatus’ status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

Field	Description
`startTime` Kubernetes meta/v1.Time	StartTime is the time the PipelineRun is actually started.
`completionTime` Kubernetes meta/v1.Time	CompletionTime is the time the PipelineRun completed.
`taskRuns` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.PipelineRunTaskRunStatus*	(Optional) TaskRuns is a map of PipelineRunTaskRunStatus with the taskRun name as the key. Deprecated: use ChildReferences instead. As of v0.45.0, this field is no longer populated and is only included for backwards compatibility with older server versions.
`runs` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.PipelineRunRunStatus*	(Optional) Runs is a map of PipelineRunRunStatus with the run name as the key Deprecated: use ChildReferences instead. As of v0.45.0, this field is no longer populated and is only included for backwards compatibility with older server versions.
`pipelineResults` []PipelineRunResult	(Optional) PipelineResults are the list of results written out by the pipeline task’s containers
`pipelineSpec` PipelineSpec	PipelineSpec contains the exact spec used to instantiate the run. See Pipeline.spec (API version: tekton.dev/v1beta1)
`skippedTasks` []SkippedTask	(Optional) list of tasks that were skipped due to when expressions evaluating to false
`childReferences` []ChildStatusReference	(Optional) list of TaskRun and Run names, PipelineTask names, and API versions/kinds for children of this PipelineRun.
`finallyStartTime` Kubernetes meta/v1.Time	(Optional) FinallyStartTime is when all non-finally tasks have been completed and only finally tasks are being executed.
`provenance` Provenance	(Optional) Provenance contains some key authenticated metadata about how a software artifact was built (what sources, what inputs/outputs, etc.).
`spanContext` map[string]string	SpanContext contains tracing span context fields

PipelineRunTaskRunStatus

(Appears on:PipelineRunStatusFields)

PipelineRunTaskRunStatus contains the name of the PipelineTask for this TaskRun and the TaskRun’s Status

Field	Description
`pipelineTaskName` string	PipelineTaskName is the name of the PipelineTask.
`status` TaskRunStatus	(Optional) Status is the TaskRunStatus for the corresponding TaskRun
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

PipelineSpec

(Appears on:Pipeline, PipelineRunSpec, PipelineRunStatusFields, PipelineTask)

PipelineSpec defines the desired state of Pipeline.

Field	Description
`displayName` string	(Optional) DisplayName is a user-facing name of the pipeline that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the pipeline that may be used to populate a UI.
`resources` []PipelineDeclaredResource	Deprecated: Unused, preserved only for backwards compatibility
`tasks` []PipelineTask	Tasks declares the graph of Tasks that execute when this Pipeline is run.
`params` ParamSpecs	Params declares a list of input parameters that must be supplied when this Pipeline is run.
`workspaces` []PipelineWorkspaceDeclaration	(Optional) Workspaces declares a set of named workspaces that are expected to be provided by a PipelineRun.
`results` []PipelineResult	(Optional) Results are values that this pipeline can output once run
`finally` []PipelineTask	Finally declares the list of Tasks that execute just before leaving the Pipeline i.e. either after all Tasks are finished executing successfully or after a failure which would result in ending the Pipeline

PipelineTask

(Appears on:PipelineSpec)

PipelineTask defines a task in a Pipeline, passing inputs from both Params and from the output of previous tasks.

Field	Description
`name` string	Name is the name of this task within the context of a Pipeline. Name is used as a coordinate with the `from` and `runAfter` fields to establish the execution order of tasks relative to one another.
`displayName` string	(Optional) DisplayName is the display name of this task within the context of a Pipeline. This display name may be used to populate a UI.
`description` string	(Optional) Description is the description of this task within the context of a Pipeline. This description may be used to populate a UI.
`taskRef` TaskRef	(Optional) TaskRef is a reference to a task definition.
`taskSpec` EmbeddedTask	(Optional) TaskSpec is a specification of a task Specifying TaskSpec can be disabled by setting `disable-inline-spec` feature flag. See Task.spec (API version: tekton.dev/v1beta1)
`when` WhenExpressions	(Optional) WhenExpressions is a list of when expressions that need to be true for the task to run
`retries` int	(Optional) Retries represents how many times this task should be retried in case of task failure: ConditionSucceeded set to False
`runAfter` []string	(Optional) RunAfter is the list of PipelineTask names that should be executed before this Task executes. (Used to force a specific ordering in graph execution.)
`resources` PipelineTaskResources	(Optional) Deprecated: Unused, preserved only for backwards compatibility
`params` Params	(Optional) Parameters declares parameters passed to this task.
`matrix` Matrix	(Optional) Matrix declares parameters used to fan out this task.
`workspaces` []WorkspacePipelineTaskBinding	(Optional) Workspaces maps workspaces from the pipeline spec to the workspaces declared in the Task.
`timeout` Kubernetes meta/v1.Duration	(Optional) Duration after which the TaskRun times out. Defaults to 1 hour. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`pipelineRef` PipelineRef	(Optional) PipelineRef is a reference to a pipeline definition Note: PipelineRef is in preview mode and not yet supported
`pipelineSpec` PipelineSpec	(Optional) PipelineSpec is a specification of a pipeline Note: PipelineSpec is in preview mode and not yet supported Specifying PipelineSpec can be disabled by setting `disable-inline-spec` feature flag. See Pipeline.spec (API version: tekton.dev/v1beta1)
`onError` PipelineTaskOnErrorType	(Optional) OnError defines the exiting behavior of a PipelineRun on error can be set to [ continue \| stopAndFail ]

PipelineTaskInputResource

(Appears on:PipelineTaskResources)

PipelineTaskInputResource maps the name of a declared PipelineResource input dependency in a Task to the resource in the Pipeline’s DeclaredPipelineResources that should be used. This input may come from a previous task.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string	Name is the name of the PipelineResource as declared by the Task.
`resource` string	Resource is the name of the DeclaredPipelineResource to use.
`from` []string	(Optional) From is the list of PipelineTask names that the resource has to come from. (Implies an ordering in the execution graph.)

PipelineTaskMetadata

(Appears on:EmbeddedRunSpec, EmbeddedCustomRunSpec, EmbeddedTask, PipelineTaskRunSpec)

PipelineTaskMetadata contains the labels or annotations for an EmbeddedTask

Field	Description
`labels` map[string]string	(Optional)
`annotations` map[string]string	(Optional)

PipelineTaskOnErrorType (`string` alias)

(Appears on:PipelineTask)

PipelineTaskOnErrorType defines a list of supported failure handling behaviors of a PipelineTask on error

PipelineTaskOutputResource

(Appears on:PipelineTaskResources)

PipelineTaskOutputResource maps the name of a declared PipelineResource output dependency in a Task to the resource in the Pipeline’s DeclaredPipelineResources that should be used.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`name` string	Name is the name of the PipelineResource as declared by the Task.
`resource` string	Resource is the name of the DeclaredPipelineResource to use.

PipelineTaskParam

PipelineTaskParam is used to provide arbitrary string parameters to a Task.

Field	Description
`name` string
`value` string

PipelineTaskResources

(Appears on:PipelineTask)

PipelineTaskResources allows a Pipeline to declare how its DeclaredPipelineResources should be provided to a Task as its inputs and outputs.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`inputs` []PipelineTaskInputResource	Inputs holds the mapping from the PipelineResources declared in DeclaredPipelineResources to the input PipelineResources required by the Task.
`outputs` []PipelineTaskOutputResource	Outputs holds the mapping from the PipelineResources declared in DeclaredPipelineResources to the input PipelineResources required by the Task.

PipelineTaskRun

PipelineTaskRun reports the results of running a step in the Task. Each task has the potential to succeed or fail (based on the exit code) and produces logs.

Field	Description
`name` string

PipelineTaskRunSpec

(Appears on:PipelineRunSpec)

PipelineTaskRunSpec can be used to configure specific specs for a concrete Task

Field	Description
`pipelineTaskName` string
`taskServiceAccountName` string
`taskPodTemplate` PodTemplate
`stepOverrides` []TaskRunStepOverride
`sidecarOverrides` []TaskRunSidecarOverride
`metadata` PipelineTaskMetadata	(Optional)
`computeResources` Kubernetes core/v1.ResourceRequirements	Compute resources to use for this TaskRun
`timeout` Kubernetes meta/v1.Duration	(Optional) Duration after which the TaskRun times out. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration

PipelineWorkspaceDeclaration

(Appears on:PipelineSpec)

PipelineWorkspaceDeclaration creates a named slot in a Pipeline that a PipelineRun is expected to populate with a workspace binding.

Field	Description
`name` string	Name is the name of a workspace to be provided by a PipelineRun.
`description` string	(Optional) Description is a human readable string describing how the workspace will be used in the Pipeline. It can be useful to include a bit of detail about which tasks are intended to have access to the data on the workspace.
`optional` bool	Optional marks a Workspace as not being required in PipelineRuns. By default this field is false and so declared workspaces are required.

PropertySpec

(Appears on:ParamSpec, TaskResult)

PropertySpec defines the struct for object keys

Field	Description
`type` ParamType

Provenance

(Appears on:PipelineRunStatusFields, StepState, TaskRunStatusFields)

Field	Description
`configSource` ConfigSource	Deprecated: Use RefSource instead
`refSource` RefSource	RefSource identifies the source where a remote task/pipeline came from.
`featureFlags` github.com/tektoncd/pipeline/pkg/apis/config.FeatureFlags	FeatureFlags identifies the feature flags that were used during the task/pipeline run

Ref

(Appears on:Step)

Ref can be used to refer to a specific instance of a StepAction.

Field	Description
`name` string	Name of the referenced step
`ResolverRef` ResolverRef	(Optional) ResolverRef allows referencing a StepAction in a remote location like a git repo.

RefSource

(Appears on:Provenance)

RefSource contains the information that can uniquely identify where a remote built definition came from i.e. Git repositories, Tekton Bundles in OCI registry and hub.

Field	Description
`uri` string	URI indicates the identity of the source of the build definition. Example: “https://github.com/tektoncd/catalog”
`digest` map[string]string	Digest is a collection of cryptographic digests for the contents of the artifact specified by URI. Example: {“sha1”: “f99d13e554ffcb696dee719fa85b695cb5b0f428”}
`entryPoint` string	EntryPoint identifies the entry point into the build. This is often a path to a build definition file and/or a target label within that file. Example: “task/git-clone/0.10/git-clone.yaml”

ResolverName (`string` alias)

(Appears on:ResolverRef)

ResolverName is the name of a resolver from which a resource can be requested.

ResolverRef

(Appears on:PipelineRef, Ref, TaskRef)

ResolverRef can be used to refer to a Pipeline or Task in a remote location like a git repo.

Field	Description
`resolver` ResolverName	(Optional) Resolver is the name of the resolver that should perform resolution of the referenced Tekton resource, such as “git”.
`params` Params	(Optional) Params contains the parameters used to identify the referenced Tekton resource. Example entries might include “repo” or “path” but the set of params ultimately depends on the chosen resolver.

ResourceDeclaration

(Appears on:TaskResource)

Deprecated: Unused, preserved only for backwards compatibility

ResourceParam

ResourceParam declares a string value to use for the parameter called Name, and is used in the specific context of PipelineResources.

Deprecated: Unused, preserved only for backwards compatibility

ResultRef

ResultRef is a type that represents a reference to a task run result

Field	Description
`pipelineTask` string
`result` string
`resultsIndex` int
`property` string

ResultType

ResultType of PipelineResourceResult has been deprecated with the migration of PipelineResources Deprecated: v1beta1.ResultType is only kept for backward compatibility

ResultValue

(Appears on:PipelineResult, PipelineRunResult, TaskResult, TaskRunResult)

ResultValue is a type alias of ParamValue

ResultsType (`string` alias)

(Appears on:PipelineResult, TaskResult, TaskRunResult)

RetriesStatus (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.TaskRunStatus` alias)

(Appears on:TaskRunStatusFields)

RunObject

RunObject is implemented by CustomRun and Run

RunResult

RunResult is used to write key/value pairs to TaskRun pod termination messages. It has been migrated to the result package and kept for backward compatibility

Sidecar

(Appears on:TaskSpec)

Sidecar has nearly the same data structure as Step but does not have the ability to timeout.

Field	Description
`name` string	Name of the Sidecar specified as a DNS_LABEL. Each Sidecar in a Task must have a unique name (DNS_LABEL). Cannot be updated.
`image` string	(Optional) Image name to be used by the Sidecar. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Sidecar’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`workingDir` string	(Optional) Sidecar’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`ports` []Kubernetes core/v1.ContainerPort	(Optional) List of ports to expose from the Sidecar. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default “0.0.0.0” address inside a container will be accessible from the network. Cannot be updated.
`envFrom` []Kubernetes core/v1.EnvFromSource	(Optional) List of sources to populate environment variables in the Sidecar. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the Sidecar is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the Sidecar. Cannot be updated.
`resources` Kubernetes core/v1.ResourceRequirements	(Optional) Compute Resources required by this Sidecar. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Sidecar’s filesystem. Cannot be updated.
`volumeDevices` []Kubernetes core/v1.VolumeDevice	(Optional) volumeDevices is the list of block devices to be used by the Sidecar.
`livenessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of Sidecar liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
`readinessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of Sidecar service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
`startupProbe` Kubernetes core/v1.Probe	(Optional) StartupProbe indicates that the Pod the Sidecar is running in has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod’s lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes
`lifecycle` Kubernetes core/v1.Lifecycle	(Optional) Actions that the management system should take in response to Sidecar lifecycle events. Cannot be updated.
`terminationMessagePath` string	(Optional) Optional: Path at which the file to which the Sidecar’s termination message will be written is mounted into the Sidecar’s filesystem. Message written is intended to be brief final status, such as an assertion failure message. Will be truncated by the node if greater than 4096 bytes. The total message length across all containers will be limited to 12kb. Defaults to /dev/termination-log. Cannot be updated.
`terminationMessagePolicy` Kubernetes core/v1.TerminationMessagePolicy	(Optional) Indicate how the termination message should be populated. File will use the contents of terminationMessagePath to populate the Sidecar status message on both success and failure. FallbackToLogsOnError will use the last chunk of Sidecar log output if the termination message file is empty and the Sidecar exited with an error. The log output is limited to 2048 bytes or 80 lines, whichever is smaller. Defaults to File. Cannot be updated.
`imagePullPolicy` Kubernetes core/v1.PullPolicy	(Optional) Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Sidecar should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
`stdin` bool	(Optional) Whether this Sidecar should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the Sidecar will always result in EOF. Default is false.
`stdinOnce` bool	(Optional) Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on Sidecar start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the Sidecar is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false
`tty` bool	(Optional) Whether this Sidecar should allocate a TTY for itself, also requires ‘stdin’ to be true. Default is false.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command or Args.
`workspaces` []WorkspaceUsage	(Optional) This is an alpha field. You must set the “enable-api-fields” feature flag to “alpha” for this field to be supported. Workspaces is a list of workspaces from the Task that this Sidecar wants exclusive access to. Adding a workspace to this list means that any other Step or Sidecar that does not also request this Workspace will not have access to it.
`restartPolicy` Kubernetes core/v1.ContainerRestartPolicy	(Optional) RestartPolicy refers to kubernetes RestartPolicy. It can only be set for an initContainer and must have it’s policy set to “Always”. It is currently left optional to help support Kubernetes versions prior to 1.29 when this feature was introduced.

SidecarState

(Appears on:TaskRunStatusFields)

SidecarState reports the results of running a sidecar in a Task.

Field	Description
`ContainerState` Kubernetes core/v1.ContainerState	(Members of `ContainerState` are embedded into this type.)
`name` string
`container` string
`imageID` string

SkippedTask

(Appears on:PipelineRunStatusFields)

Field	Description
`name` string	Name is the Pipeline Task name
`reason` SkippingReason	Reason is the cause of the PipelineTask being skipped.
`whenExpressions` []WhenExpression	(Optional) WhenExpressions is the list of checks guarding the execution of the PipelineTask

SkippingReason (`string` alias)

(Appears on:SkippedTask)

SkippingReason explains why a PipelineTask was skipped.

Step

(Appears on:InternalTaskModifier, TaskSpec)

Step runs a subcomponent of a Task

Field	Description
`name` string	Name of the Step specified as a DNS_LABEL. Each Step in a Task must have a unique name.
`displayName` string	(Optional) DisplayName is a user-facing name of the step that may be used to populate a UI.
`image` string	(Optional) Image reference name to run for this Step. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`ports` []Kubernetes core/v1.ContainerPort	(Optional) List of ports to expose from the Step’s container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default “0.0.0.0” address inside a container will be accessible from the network. Cannot be updated. Deprecated: This field will be removed in a future release.
`envFrom` []Kubernetes core/v1.EnvFromSource	(Optional) List of sources to populate environment variables in the container. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the container. Cannot be updated.
`resources` Kubernetes core/v1.ResourceRequirements	(Optional) Compute Resources required by this Step. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.
`volumeDevices` []Kubernetes core/v1.VolumeDevice	(Optional) volumeDevices is the list of block devices to be used by the Step.
`livenessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of container liveness. Step will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes Deprecated: This field will be removed in a future release.
`readinessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of container service readiness. Step will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes Deprecated: This field will be removed in a future release.
`startupProbe` Kubernetes core/v1.Probe	(Optional) DeprecatedStartupProbe indicates that the Pod this Step runs in has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod’s lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes Deprecated: This field will be removed in a future release.
`lifecycle` Kubernetes core/v1.Lifecycle	(Optional) Actions that the management system should take in response to container lifecycle events. Cannot be updated. Deprecated: This field will be removed in a future release.
`terminationMessagePath` string	(Optional) Deprecated: This field will be removed in a future release and can’t be meaningfully used.
`terminationMessagePolicy` Kubernetes core/v1.TerminationMessagePolicy	(Optional) Deprecated: This field will be removed in a future release and can’t be meaningfully used.
`imagePullPolicy` Kubernetes core/v1.PullPolicy	(Optional) Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
`stdin` bool	(Optional) Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in EOF. Default is false. Deprecated: This field will be removed in a future release.
`stdinOnce` bool	(Optional) Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false Deprecated: This field will be removed in a future release.
`tty` bool	(Optional) Whether this container should allocate a DeprecatedTTY for itself, also requires ‘stdin’ to be true. Default is false. Deprecated: This field will be removed in a future release.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.
`timeout` Kubernetes meta/v1.Duration	(Optional) Timeout is the time after which the step times out. Defaults to never. Refer to Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`workspaces` []WorkspaceUsage	(Optional) This is an alpha field. You must set the “enable-api-fields” feature flag to “alpha” for this field to be supported. Workspaces is a list of workspaces from the Task that this Step wants exclusive access to. Adding a workspace to this list means that any other Step or Sidecar that does not also request this Workspace will not have access to it.
`onError` OnErrorType	OnError defines the exiting behavior of a container on error can be set to [ continue \| stopAndFail ]
`stdoutConfig` StepOutputConfig	(Optional) Stores configuration for the stdout stream of the step.
`stderrConfig` StepOutputConfig	(Optional) Stores configuration for the stderr stream of the step.
`ref` Ref	(Optional) Contains the reference to an existing StepAction.
`params` Params	(Optional) Params declares parameters passed to this step action.
`results` []StepResult	(Optional) Results declares StepResults produced by the Step. It can be used in an inlined Step when used to store Results to $(step.results.resultName.path). It cannot be used when referencing StepActions using [v1beta1.Step.Ref]. The Results declared by the StepActions will be stored here instead.
`when` StepWhenExpressions

StepActionObject

StepActionObject is implemented by StepAction

StepActionSpec

(Appears on:StepAction)

StepActionSpec contains the actionable components of a step.

Field	Description
`description` string	(Optional) Description is a user-facing description of the stepaction that may be used to populate a UI.
`image` string	(Optional) Image reference name to run for this StepAction. More info: https://kubernetes.io/docs/concepts/containers/images
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` Args	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the container’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the container. Cannot be updated.
`script` string	(Optional) Script is the contents of an executable file to execute. If Script is not empty, the Step cannot have an Command and the Args will be passed to the Script.
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the stepAction. Params must be supplied as inputs in Steps unless they declare a defaultvalue.
`results` []StepResult	(Optional) Results are values that this StepAction can output
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ The value set in StepAction will take precedence over the value from Task.
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.

StepOutputConfig

(Appears on:Step)

StepOutputConfig stores configuration for a step output stream.

Field	Description
`path` string	(Optional) Path to duplicate stdout stream to on container’s local filesystem.

StepState

(Appears on:TaskRunStatusFields)

StepState reports the results of running a step in a Task.

Field	Description
`ContainerState` Kubernetes core/v1.ContainerState	(Members of `ContainerState` are embedded into this type.)
`name` string
`container` string
`imageID` string
`results` []TaskRunStepResult
`provenance` Provenance
`inputs` []TaskRunStepArtifact
`outputs` []TaskRunStepArtifact

StepTemplate

(Appears on:TaskSpec)

StepTemplate is a template for a Step

Field	Description
`name` string	Default name for each Step specified as a DNS_LABEL. Each Step in a Task must have a unique name. Cannot be updated. Deprecated: This field will be removed in a future release.
`image` string	(Optional) Default image name to use for each Step. More info: https://kubernetes.io/docs/concepts/containers/images This field is optional to allow higher level config management to default or override container images in workload controllers like Deployments and StatefulSets.
`command` []string	(Optional) Entrypoint array. Not executed within a shell. The docker image’s ENTRYPOINT is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Step’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`args` []string	(Optional) Arguments to the entrypoint. The image’s CMD is used if this is not provided. Variable references $(VAR_NAME) are expanded using the Step’s environment. If a variable cannot be resolved, the reference in the input string will be unchanged. Double $$ are reduced to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e. “$$(VAR_NAME)” will produce the string literal “$(VAR_NAME)”. Escaped references will never be expanded, regardless of whether the variable exists or not. Cannot be updated. More info: https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/#running-a-command-in-a-shell
`workingDir` string	(Optional) Step’s working directory. If not specified, the container runtime’s default will be used, which might be configured in the container image. Cannot be updated.
`ports` []Kubernetes core/v1.ContainerPort	(Optional) List of ports to expose from the Step’s container. Exposing a port here gives the system additional information about the network connections a container uses, but is primarily informational. Not specifying a port here DOES NOT prevent that port from being exposed. Any port which is listening on the default “0.0.0.0” address inside a container will be accessible from the network. Cannot be updated. Deprecated: This field will be removed in a future release.
`envFrom` []Kubernetes core/v1.EnvFromSource	(Optional) List of sources to populate environment variables in the Step. The keys defined within a source must be a C_IDENTIFIER. All invalid keys will be reported as an event when the container is starting. When a key exists in multiple sources, the value associated with the last source will take precedence. Values defined by an Env with a duplicate key will take precedence. Cannot be updated.
`env` []Kubernetes core/v1.EnvVar	(Optional) List of environment variables to set in the container. Cannot be updated.
`resources` Kubernetes core/v1.ResourceRequirements	(Optional) Compute Resources required by this Step. Cannot be updated. More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
`volumeMounts` []Kubernetes core/v1.VolumeMount	(Optional) Volumes to mount into the Step’s filesystem. Cannot be updated.
`volumeDevices` []Kubernetes core/v1.VolumeDevice	(Optional) volumeDevices is the list of block devices to be used by the Step.
`livenessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of container liveness. Container will be restarted if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes Deprecated: This field will be removed in a future release.
`readinessProbe` Kubernetes core/v1.Probe	(Optional) Periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails. Cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes Deprecated: This field will be removed in a future release.
`startupProbe` Kubernetes core/v1.Probe	(Optional) DeprecatedStartupProbe indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod’s lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. This cannot be updated. More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes Deprecated: This field will be removed in a future release.
`lifecycle` Kubernetes core/v1.Lifecycle	(Optional) Actions that the management system should take in response to container lifecycle events. Cannot be updated. Deprecated: This field will be removed in a future release.
`terminationMessagePath` string	(Optional) Deprecated: This field will be removed in a future release and cannot be meaningfully used.
`terminationMessagePolicy` Kubernetes core/v1.TerminationMessagePolicy	(Optional) Deprecated: This field will be removed in a future release and cannot be meaningfully used.
`imagePullPolicy` Kubernetes core/v1.PullPolicy	(Optional) Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. Cannot be updated. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
`securityContext` Kubernetes core/v1.SecurityContext	(Optional) SecurityContext defines the security options the Step should be run with. If set, the fields of SecurityContext override the equivalent fields of PodSecurityContext. More info: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
`stdin` bool	(Optional) Whether this Step should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the Step will always result in EOF. Default is false. Deprecated: This field will be removed in a future release.
`stdinOnce` bool	(Optional) Whether the container runtime should close the stdin channel after it has been opened by a single attach. When stdin is true the stdin stream will remain open across multiple attach sessions. If stdinOnce is set to true, stdin is opened on container start, is empty until the first client attaches to stdin, and then remains open and accepts data until the client disconnects, at which time stdin is closed and remains closed until the container is restarted. If this flag is false, a container processes that reads from stdin will never receive an EOF. Default is false Deprecated: This field will be removed in a future release.
`tty` bool	(Optional) Whether this Step should allocate a DeprecatedTTY for itself, also requires ‘stdin’ to be true. Default is false. Deprecated: This field will be removed in a future release.

StepWhenExpressions

(Appears on:Step)

TaskBreakpoints

(Appears on:TaskRunDebug)

TaskBreakpoints defines the breakpoint config for a particular Task

Field	Description
`onFailure` string	(Optional) if enabled, pause TaskRun on failure of a step failed step will not exit
`beforeSteps` []string	(Optional)

TaskKind (`string` alias)

(Appears on:TaskRef)

TaskKind defines the type of Task used by the pipeline.

TaskModifier

TaskModifier is an interface to be implemented by different PipelineResources

Deprecated: Unused, preserved only for backwards compatibility

TaskObject

TaskObject is implemented by Task

TaskRef

(Appears on:RunSpec, CustomRunSpec, PipelineTask, TaskRunSpec)

TaskRef can be used to refer to a specific instance of a task.

Field	Description
`name` string	Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names
`kind` TaskKind	TaskKind indicates the Kind of the Task: 1. Namespaced Task when Kind is set to “Task”. If Kind is “”, it defaults to “Task”. 2. Custom Task when Kind is non-empty and APIVersion is non-empty
`apiVersion` string	(Optional) API version of the referent Note: A Task with non-empty APIVersion and Kind is considered a Custom Task
`bundle` string	(Optional) Bundle url reference to a Tekton Bundle. Deprecated: Please use ResolverRef with the bundles resolver instead. The field is staying there for go client backward compatibility, but is not used/allowed anymore.
`ResolverRef` ResolverRef	(Optional) ResolverRef allows referencing a Task in a remote location like a git repo. This field is only supported when the alpha feature gate is enabled.

TaskResource

(Appears on:TaskResources)

TaskResource defines an input or output Resource declared as a requirement by a Task. The Name field will be used to refer to these Resources within the Task definition, and when provided as an Input, the Name will be the path to the volume mounted containing this Resource as an input (e.g. an input Resource named workspace will be mounted at /workspace).

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`ResourceDeclaration` ResourceDeclaration	(Members of `ResourceDeclaration` are embedded into this type.)

TaskResourceBinding

(Appears on:TaskRunInputs, TaskRunOutputs, TaskRunResources)

TaskResourceBinding points to the PipelineResource that will be used for the Task input or output called Name.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`PipelineResourceBinding` PipelineResourceBinding	(Members of `PipelineResourceBinding` are embedded into this type.)
`paths` []string	(Optional) Paths will probably be removed in #1284, and then PipelineResourceBinding can be used instead. The optional Path field corresponds to a path on disk at which the Resource can be found (used when providing the resource via mounted volume, overriding the default logic to fetch the Resource).

TaskResources

(Appears on:TaskSpec)

TaskResources allows a Pipeline to declare how its DeclaredPipelineResources should be provided to a Task as its inputs and outputs.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`inputs` []TaskResource	Inputs holds the mapping from the PipelineResources declared in DeclaredPipelineResources to the input PipelineResources required by the Task.
`outputs` []TaskResource	Outputs holds the mapping from the PipelineResources declared in DeclaredPipelineResources to the input PipelineResources required by the Task.

TaskResult

(Appears on:TaskSpec)

TaskResult used to describe the results of a task

Field	Description
`name` string	Name the given name
`type` ResultsType	(Optional) Type is the user-specified type of the result. The possible type is currently “string” and will support “array” in following work.
`properties` map[string]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.PropertySpec	(Optional) Properties is the JSON Schema properties to support key-value pairs results.
`description` string	(Optional) Description is a human-readable description of the result
`value` ResultValue	(Optional) Value the expression used to retrieve the value of the result from an underlying Step.

TaskRunConditionType (`string` alias)

TaskRunConditionType is an enum used to store TaskRun custom conditions such as one used in spire results verification

TaskRunDebug

(Appears on:TaskRunSpec)

TaskRunDebug defines the breakpoint config for a particular TaskRun

Field	Description
`breakpoints` TaskBreakpoints	(Optional)

TaskRunInputs

TaskRunInputs holds the input values that this task was invoked with.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`resources` []TaskResourceBinding	(Optional)
`params` []Param	(Optional)

TaskRunOutputs

TaskRunOutputs holds the output values that this task was invoked with.

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`resources` []TaskResourceBinding	(Optional)

TaskRunReason (`string` alias)

TaskRunResources

(Appears on:TaskRunSpec)

TaskRunResources allows a TaskRun to declare inputs and outputs TaskResourceBinding

Deprecated: Unused, preserved only for backwards compatibility

Field	Description
`inputs` []TaskResourceBinding	Inputs holds the inputs resources this task was invoked with
`outputs` []TaskResourceBinding	Outputs holds the inputs resources this task was invoked with

TaskRunResult

(Appears on:TaskRunStatusFields)

TaskRunResult used to describe the results of a task

Field	Description
`name` string	Name the given name
`type` ResultsType	(Optional) Type is the user-specified type of the result. The possible type is currently “string” and will support “array” in following work.
`value` ResultValue	Value the given value of the result

TaskRunSidecarOverride

(Appears on:PipelineTaskRunSpec, TaskRunSpec)

TaskRunSidecarOverride is used to override the values of a Sidecar in the corresponding Task.

Field	Description
`name` string	The name of the Sidecar to override.
`resources` Kubernetes core/v1.ResourceRequirements	The resource requirements to apply to the Sidecar.

TaskRunSpec

(Appears on:TaskRun)

TaskRunSpec defines the desired state of TaskRun

Field	Description
`debug` TaskRunDebug	(Optional)
`params` Params	(Optional)
`resources` TaskRunResources	(Optional) Deprecated: Unused, preserved only for backwards compatibility
`serviceAccountName` string	(Optional)
`taskRef` TaskRef	(Optional) no more than one of the TaskRef and TaskSpec may be specified.
`taskSpec` TaskSpec	(Optional) Specifying TaskSpec can be disabled by setting `disable-inline-spec` feature flag. See Task.spec (API version: tekton.dev/v1beta1)
`status` TaskRunSpecStatus	(Optional) Used for cancelling a TaskRun (and maybe more later on)
`statusMessage` TaskRunSpecStatusMessage	(Optional) Status message for cancellation.
`retries` int	(Optional) Retries represents how many times this TaskRun should be retried in the event of Task failure.
`timeout` Kubernetes meta/v1.Duration	(Optional) Time after which one retry attempt times out. Defaults to 1 hour. Refer Go’s ParseDuration documentation for expected format: https://golang.org/pkg/time/#ParseDuration
`podTemplate` PodTemplate	PodTemplate holds pod specific configuration
`workspaces` []WorkspaceBinding	(Optional) Workspaces is a list of WorkspaceBindings from volumes to workspaces.
`stepOverrides` []TaskRunStepOverride	(Optional) Overrides to apply to Steps in this TaskRun. If a field is specified in both a Step and a StepOverride, the value from the StepOverride will be used. This field is only supported when the alpha feature gate is enabled.
`sidecarOverrides` []TaskRunSidecarOverride	(Optional) Overrides to apply to Sidecars in this TaskRun. If a field is specified in both a Sidecar and a SidecarOverride, the value from the SidecarOverride will be used. This field is only supported when the alpha feature gate is enabled.
`computeResources` Kubernetes core/v1.ResourceRequirements	Compute resources to use for this TaskRun
`managedBy` string	(Optional) ManagedBy indicates which controller is responsible for reconciling this resource. If unset or set to “tekton.dev/pipeline”, the default Tekton controller will manage this resource. This field is immutable.

TaskRunSpecStatus (`string` alias)

(Appears on:TaskRunSpec)

TaskRunSpecStatus defines the TaskRun spec status the user can provide

TaskRunSpecStatusMessage (`string` alias)

(Appears on:TaskRunSpec)

TaskRunSpecStatusMessage defines human readable status messages for the TaskRun.

TaskRunStatus

(Appears on:TaskRun, PipelineRunTaskRunStatus)

TaskRunStatus defines the observed state of TaskRun

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

TaskRunStatusFields
TaskRunStatusFields

(Members of TaskRunStatusFields are embedded into this type.)

TaskRunStatusFields inlines the status fields.

TaskRunStatusFields

(Appears on:TaskRunStatus)

TaskRunStatusFields holds the fields of TaskRun’s status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

Field	Description
`podName` string	PodName is the name of the pod responsible for executing this task’s steps.
`startTime` Kubernetes meta/v1.Time	StartTime is the time the build is actually started.
`completionTime` Kubernetes meta/v1.Time	CompletionTime is the time the build completed.
`steps` []StepState	(Optional) Steps describes the state of each build step container.
`cloudEvents` []CloudEventDelivery	(Optional) CloudEvents describe the state of each cloud event requested via a CloudEventResource. Deprecated: Removed in v0.44.0.
`retriesStatus` RetriesStatus	(Optional) RetriesStatus contains the history of TaskRunStatus in case of a retry in order to keep record of failures. All TaskRunStatus stored in RetriesStatus will have no date within the RetriesStatus as is redundant. See TaskRun.status (API version: tekton.dev/v1beta1)
`resourcesResult` []PipelineResourceResult	(Optional) Results from Resources built during the TaskRun. This is tomb-stoned along with the removal of pipelineResources Deprecated: this field is not populated and is preserved only for backwards compatibility
`taskResults` []TaskRunResult	(Optional) TaskRunResults are the list of results written out by the task’s containers
`sidecars` []SidecarState	The list has one entry per sidecar in the manifest. Each entry is represents the imageid of the corresponding sidecar.
`taskSpec` TaskSpec	TaskSpec contains the Spec from the dereferenced Task definition used to instantiate this TaskRun. See Task.spec (API version tekton.dev/v1beta1)
`provenance` Provenance	(Optional) Provenance contains some key authenticated metadata about how a software artifact was built (what sources, what inputs/outputs, etc.).
`spanContext` map[string]string	SpanContext contains tracing span context fields

TaskRunStepArtifact

(Appears on:StepState)

TaskRunStepArtifact represents an artifact produced or used by a step within a task run. It directly uses the Artifact type for its structure.

TaskRunStepOverride

(Appears on:PipelineTaskRunSpec, TaskRunSpec)

TaskRunStepOverride is used to override the values of a Step in the corresponding Task.

Field	Description
`name` string	The name of the Step to override.
`resources` Kubernetes core/v1.ResourceRequirements	The resource requirements to apply to the Step.

TaskRunStepResult

(Appears on:StepState)

TaskRunStepResult is a type alias of TaskRunResult

TaskSpec

(Appears on:Task, EmbeddedTask, TaskRunSpec, TaskRunStatusFields)

TaskSpec defines the desired state of Task.

Field	Description
`resources` TaskResources	(Optional) Resources is a list input and output resource to run the task Resources are represented in TaskRuns as bindings to instances of PipelineResources. Deprecated: Unused, preserved only for backwards compatibility
`params` ParamSpecs	(Optional) Params is a list of input parameters required to run the task. Params must be supplied as inputs in TaskRuns unless they declare a default value.
`displayName` string	(Optional) DisplayName is a user-facing name of the task that may be used to populate a UI.
`description` string	(Optional) Description is a user-facing description of the task that may be used to populate a UI.
`steps` []Step	Steps are the steps of the build; each step is run sequentially with the source mounted into /workspace.
`volumes` Volumes	Volumes is a collection of volumes that are available to mount into the steps of the build. See Pod.spec.volumes (API version: v1)
`stepTemplate` StepTemplate	StepTemplate can be used as the basis for all step containers within the Task, so that the steps inherit settings on the base container.
`sidecars` []Sidecar	Sidecars are run alongside the Task’s step containers. They begin before the steps start and end after the steps complete.
`workspaces` []WorkspaceDeclaration	Workspaces are the volumes that this Task requires.
`results` []TaskResult	Results are values that this Task can output

TimeoutFields

(Appears on:PipelineRunSpec)

TimeoutFields allows granular specification of pipeline, task, and finally timeouts

Field	Description
`pipeline` Kubernetes meta/v1.Duration	Pipeline sets the maximum allowed duration for execution of the entire pipeline. The sum of individual timeouts for tasks and finally must not exceed this value.
`tasks` Kubernetes meta/v1.Duration	Tasks sets the maximum allowed duration of this pipeline’s tasks
`finally` Kubernetes meta/v1.Duration	Finally sets the maximum allowed duration of this pipeline’s finally

Volumes (`[]k8s.io/api/core/v1.Volume` alias)

(Appears on:TaskSpec)

WhenExpression

(Appears on:ChildStatusReference, PipelineRunRunStatus, PipelineRunTaskRunStatus, SkippedTask)

WhenExpression allows a PipelineTask to declare expressions to be evaluated before the Task is run to determine whether the Task should be executed or skipped

Field	Description
`input` string	Input is the string for guard checking which can be a static input or an output from a parent Task
`operator` k8s.io/apimachinery/pkg/selection.Operator	Operator that represents an Input’s relationship to the values
`values` []string	Values is an array of strings, which is compared against the input, for guard checking It must be non-empty
`cel` string	(Optional) CEL is a string of Common Language Expression, which can be used to conditionally execute the task based on the result of the expression evaluation More info about CEL syntax: https://github.com/google/cel-spec/blob/master/doc/langdef.md

WhenExpressions (`[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1.WhenExpression` alias)

(Appears on:PipelineTask)

WhenExpressions are used to specify whether a Task should be executed or skipped All of them need to evaluate to True for a guarded Task to be executed.

WorkspaceBinding

(Appears on:RunSpec, CustomRunSpec, PipelineRunSpec, TaskRunSpec)

WorkspaceBinding maps a Task’s declared workspace to a Volume.

Field	Description
`name` string	Name is the name of the workspace populated by the volume.
`subPath` string	(Optional) SubPath is optionally a directory on the volume which should be used for this binding (i.e. the volume will be mounted at this sub directory).
`volumeClaimTemplate` Kubernetes core/v1.PersistentVolumeClaim	(Optional) VolumeClaimTemplate is a template for a claim that will be created in the same namespace. The PipelineRun controller is responsible for creating a unique claim for each instance of PipelineRun. See PersistentVolumeClaim (API version: v1)
`persistentVolumeClaim` Kubernetes core/v1.PersistentVolumeClaimVolumeSource	(Optional) PersistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. Either this OR EmptyDir can be used.
`emptyDir` Kubernetes core/v1.EmptyDirVolumeSource	(Optional) EmptyDir represents a temporary directory that shares a Task’s lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir Either this OR PersistentVolumeClaim can be used.
`configMap` Kubernetes core/v1.ConfigMapVolumeSource	(Optional) ConfigMap represents a configMap that should populate this workspace.
`secret` Kubernetes core/v1.SecretVolumeSource	(Optional) Secret represents a secret that should populate this workspace.
`projected` Kubernetes core/v1.ProjectedVolumeSource	(Optional) Projected represents a projected volume that should populate this workspace.
`csi` Kubernetes core/v1.CSIVolumeSource	(Optional) CSI (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers.

WorkspaceDeclaration

(Appears on:TaskSpec)

WorkspaceDeclaration is a declaration of a volume that a Task requires.

Field	Description
`name` string	Name is the name by which you can bind the volume at runtime.
`description` string	(Optional) Description is an optional human readable description of this volume.
`mountPath` string	(Optional) MountPath overrides the directory that the volume will be made available at.
`readOnly` bool	ReadOnly dictates whether a mounted volume is writable. By default this field is false and so mounted volumes are writable.
`optional` bool	Optional marks a Workspace as not being required in TaskRuns. By default this field is false and so declared workspaces are required.

WorkspacePipelineDeclaration

WorkspacePipelineDeclaration creates a named slot in a Pipeline that a PipelineRun is expected to populate with a workspace binding.

Deprecated: use PipelineWorkspaceDeclaration type instead

WorkspacePipelineTaskBinding

(Appears on:PipelineTask)

WorkspacePipelineTaskBinding describes how a workspace passed into the pipeline should be mapped to a task’s declared workspace.

Field	Description
`name` string	Name is the name of the workspace as declared by the task
`workspace` string	(Optional) Workspace is the name of the workspace declared by the pipeline
`subPath` string	(Optional) SubPath is optionally a directory on the volume which should be used for this binding (i.e. the volume will be mounted at this sub directory).

WorkspaceUsage

(Appears on:Sidecar, Step)

WorkspaceUsage is used by a Step or Sidecar to declare that it wants isolated access to a Workspace defined in a Task.

Field	Description
`name` string	Name is the name of the workspace this Step or Sidecar wants access to.
`mountPath` string	MountPath is the path that the workspace should be mounted to inside the Step or Sidecar, overriding any MountPath specified in the Task’s WorkspaceDeclaration.

CustomRunResult

(Appears on:CustomRunStatusFields)

CustomRunResult used to describe the results of a task

Field	Description
`name` string	Name the given name
`value` string	Value the given value of the result

CustomRunStatus

(Appears on:PipelineRunRunStatus, CustomRunStatusFields)

CustomRunStatus defines the observed state of CustomRun

Field Description

Status
knative.dev/pkg/apis/duck/v1.Status

(Members of Status are embedded into this type.)

CustomRunStatusFields
CustomRunStatusFields

(Members of CustomRunStatusFields are embedded into this type.)

CustomRunStatusFields inlines the status fields.

CustomRunStatusFields

(Appears on:CustomRunStatus)

CustomRunStatusFields holds the fields of CustomRun’s status. This is defined separately and inlined so that other types can readily consume these fields via duck typing.

Field	Description
`startTime` Kubernetes meta/v1.Time	(Optional) StartTime is the time the build is actually started.
`completionTime` Kubernetes meta/v1.Time	(Optional) CompletionTime is the time the build completed.
`results` []CustomRunResult	(Optional) Results reports any output result values to be consumed by later tasks in a pipeline.
`retriesStatus` []CustomRunStatus	(Optional) RetriesStatus contains the history of CustomRunStatus, in case of a retry. See CustomRun.status (API version: tekton.dev/v1beta1)
`extraFields` k8s.io/apimachinery/pkg/runtime.RawExtension	ExtraFields holds arbitrary fields provided by the custom task controller.

Generated with gen-crd-api-reference-docs .

Tekton – Tasks and Pipelines

Vault: Install Tekton Pipelines

Prerequisites

Installation

Additional configuration options

Next steps

Vault:

Resolver Reference

The Resolver Interface

The ConfigWatcher Interface

The TimedResolution Interface

Vault:

Migrating From Tekton v1alpha1 to Tekton v1beta1

Changes to fields

Changes to input parameters

Replacing PipelineResources with Tasks

Changes to PipelineResources

Vault:

Getting Started with Resolvers

Introduction

Prerequisites

Step 1: Install Tekton Pipelines and the Resolvers

Step 2: Ensure Pipelines is configured to enable resolvers

Step 3: Try it out!

Step 4: Monitor the PipelineRun

Vault:

How to write a Resolver

What’s a Resolver?

Just want to see the working example?

Pre-requisites

First Steps

Initializing the resolver’s binary

Writing the Resolver

The Initialize method

The GetName method

The GetSelector method

The Validate method

The Resolve method

The deployment configuration

Trying it out

Next Steps

Vault:

Tekton Controller Performance Configuration

Overview

Performance Configuration

Configure Thread, QPS and Burst

Vault:

Tekton Controllers flags

Common set of flags

controller

Vault:

HA Support for Tekton Pipeline Controllers

Overview

Controller HA

Configuring Controller Replicas

Configuring Leader Election

Disabling Controller HA

Webhook HA

Configuring Webhook Replicas

Avoiding Disruptions

Vault:

Deprecations

Introduction

Deprecation Table

v1beta1 deprecation

Removed features

Removed PipelineResources related features:

Vault:

Debug

Overview

Debugging TaskRuns

Breakpoint on Failure

Failure of a Step

Halting a Step on failure

Exiting onfailure breakpoint

Breakpoint before step

Debug Environment

Mounts

Debug Scripts

Vault: Additional Configuration Options

The `Resolver` Interface

The `ConfigWatcher` Interface

The `TimedResolution` Interface

Migrating From Tekton `v1alpha1` to Tekton `v1beta1`

Replacing `PipelineResources` with `Tasks`

The `Initialize` method

The `GetName` method

The `GetSelector` method

The `Validate` method

The `Resolve` method

`controller`

`default-sidecar-log-polling-interval`

Verify signatures using `cosign`

Verify the transparency logs using `rekor-cli`

TaskRuns with `imagePullBackOff` Timeout

Configuring a `StepAction`

Defining `Steps`

Running scripts within `Steps`

Specifying `onError` for a `step`

Accessing Step’s `exitCode` in subsequent `Steps`

Produce a task result with `onError`

Breakpoint on failure with `onError`

Redirecting step output streams with `stdoutConfig` and `stderrConfig`

Guarding `Step` execution using `when` expressions