Tekton Pipelines | The Garnet Wiki

Tekton Pipelines is a Kubernetes-native continuous integration and delivery (CI/CD) framework for building, testing, and deploying applications on Kubernetes clusters. It provides a set of standard resources for defining and executing workflows, including Tasks, Pipelines, and Triggers, that can be composed into complex automation patterns. This framework matters when you need to orchestrate multi-stage build, test, and deployment processes within Kubernetes environments.

Defining and Running Pipelines

Creating a Basic Pipeline

A pipeline consists of a sequence of tasks that execute in order or in parallel. The fundamental resource is the Pipeline custom resource:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: example-pipeline
spec:
  tasks:
    - name: build
      taskRef:
        name: build-task
    - name: test
      taskRef:
        name: test-task
      runAfter:
        - build

Creating a Task

Tasks are reusable components that define specific actions:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: build-task
spec:
  steps:
    - name: build
      image: gcr.io/cloud-builders/docker
      command:
        - docker
      args:
        - build
        - -t
        - $(params.image-name)
        - .

Running a Pipeline

Use PipelineRun to execute a pipeline:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: example-pipeline-run
spec:
  pipelineRef:
    name: example-pipeline
  params:
    - name: image-name
      value: my-app:latest

Executing Pipeline Runs

kubectl apply -f pipeline-run.yaml

The pipeline will create pods for each task. Check the status:

kubectl get pipelinerun example-pipeline-run -o jsonpath='{.status.conditions[?(@.type=="Succeeded")].status}'

Working with Parameters and Variables

Pipeline Parameters

Pipelines can accept parameters that are passed at runtime:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: parameterized-pipeline
spec:
  params:
    - name: image-tag
      type: string
      default: latest
  tasks:
    - name: build
      taskRef:
        name: build-task
      params:
        - name: image-tag
          value: $(params.image-tag)

Using Pipeline Resources

Pipeline resources are inputs or outputs that represent artifacts:

apiVersion: tekton.dev/v1beta1
kind: PipelineResource
metadata:
  name: source-repo
spec:
  type: git
  params:
    - name: url
      value: https://github.com/example/repo.git
    - name: revision
      value: main

Referencing Resources in Tasks

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: clone-task
spec:
  inputs:
    resources:
      - name: source
        type: git
  steps:
    - name: clone
      image: alpine/git
      command:
        - git
      args:
        - clone
        - $(inputs.resources.source.url)
        - /workspace/source

Managing Task Dependencies

Sequential Execution

Tasks can run in sequence using runAfter:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: sequential-pipeline
spec:
  tasks:
    - name: fetch
      taskRef:
        name: git-clone
    - name: build
      taskRef:
        name: build-image
      runAfter:
        - fetch
    - name: test
      taskRef:
        name: run-tests
      runAfter:
        - build

Parallel Execution

Tasks can run in parallel by omitting runAfter:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: parallel-pipeline
spec:
  tasks:
    - name: fetch
      taskRef:
        name: git-clone
    - name: build-image
      taskRef:
        name: build-image
    - name: lint-code
      taskRef:
        name: code-linter

Conditional Execution

Use when conditions to control execution:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: conditional-pipeline
spec:
  tasks:
    - name: build
      taskRef:
        name: build-task
    - name: deploy-to-staging
      taskRef:
        name: deploy-task
      when:
        - input: $(tasks.build.results.image-name)
          operator: in
          values:
            - my-app:staging

Working with Results and Artifacts

Task Results

Tasks can emit results that are available to subsequent tasks:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: build-task
spec:
  steps:
    - name: build
      image: gcr.io/cloud-builders/docker
      command:
        - docker
      args:
        - build
        - -t
        - $(params.image-name)
        - .
  results:
    - name: image-digest
      description: Image digest

Consuming Results

Access results in downstream tasks:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: deploy-task
spec:
  steps:
    - name: deploy
      image: gcr.io/cloud-builders/kubectl
      command:
        - kubectl
      args:
        - set
        - image
        - deployment/my-app
        - my-app=$(tasks.build-task.results.image-digest)

Handling Errors and Timeouts

Setting Timeouts

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: timed-pipeline-run
spec:
  pipelineRef:
    name: example-pipeline
  timeout: 30m

Task Timeout

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: long-running-task
spec:
  steps:
    - name: run-long-process
      image: alpine
      command:
        - sleep
      args:
        - "3600"

Error Handling

Tasks can fail gracefully and continue execution:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: resilient-pipeline
spec:
  tasks:
    - name: build
      taskRef:
        name: build-task
    - name: test
      taskRef:
        name: test-task
      continueOn:
        failures: true

Working with Secrets and Configuration

Using Secrets in Tasks

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: deploy-task
spec:
  steps:
    - name: deploy
      image: gcr.io/cloud-builders/kubectl
      env:
        - name: KUBECONFIG
          value: /var/secrets/kubeconfig

Mounting Secrets

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: secret-pipeline-run
spec:
  pipelineRef:
    name: example-pipeline
  workspaces:
    - name: kubeconfig
      secret:
        secretName: my-kubeconfig

Using ConfigMaps

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: config-task
spec:
  steps:
    - name: process-config
      image: alpine
      command:
        - cat
      args:
        - /workspace/config/application.properties

Advanced Pipeline Patterns

Dynamic Task Creation

Use TaskRun resources to dynamically create tasks:

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: dynamic-pipeline-run
spec:
  pipelineRef:
    name: example-pipeline
  taskSpecs:
    - name: custom-task
      steps:
        - name: echo
          image: alpine
          command:
            - echo
          args:
            - "Hello from custom task"

Pipeline Templates

Use PipelineTemplate resources to define reusable patterns:

apiVersion: tekton.dev/v1beta1
kind: PipelineTemplate
metadata:
  name: standard-pipeline-template
spec:
  params:
    - name: app-name
      type: string
  tasks:
    - name: build
      taskRef:
        name: build-task
    - name: test
      taskRef:
        name: test-task

Nested Pipelines

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: parent-pipeline
spec:
  tasks:
    - name: build
      taskRef:
        name: build-task
    - name: sub-pipeline
      pipelineRef:
        name: child-pipeline

Troubleshooting and Debugging

Checking Pipeline Status

kubectl get pipelinerun example-pipeline-run -o yaml

Viewing Task Logs

kubectl logs -l tekton.dev/pipelineRun=example-pipeline-run

Common Failure Conditions

Pipeline runs can fail with various status conditions:

Succeeded: False indicates a failure in one or more tasks
Ready: False means the pipeline cannot start due to missing resources
Cancelled: True shows a manually cancelled pipeline run

Debugging Task Failures

Check specific task execution:

kubectl get taskrun example-task-run -o jsonpath='{.status.conditions[?(@.type=="Succeeded")].status}'

Resource Cleanup

Pipeline runs do not automatically clean up resources. Use:

kubectl delete pipelinerun example-pipeline-run

Common Issues

Task Pod Not Starting: Check pod status and events:

kubectl describe pod -l tekton.dev/pipelineRun=example-pipeline-run

Missing Dependencies: Ensure all referenced tasks exist in the namespace:

kubectl get task build-task

Resource Not Found: Verify PipelineResources are correctly defined:

kubectl get pipelineresource source-repo

Silent Failures

Tekton does not validate that all runAfter dependencies are actually used. If you specify a task that never executes, it silently passes through without error. Always verify task execution order by examining logs.

The continueOn field only affects the pipeline's decision to proceed when a task fails. It does not prevent the overall pipeline from failing if other tasks depend on the failed one.

Tekton does not support nested conditional expressions in when clauses. Each when condition must be a simple comparison, limiting complex logic expression within pipelines.

This page was rewritten on 15 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.