Configuration Options

Tekton Pipelines provides extensive configuration options through ConfigMaps in the tekton-pipelines namespace. This guide covers all available configuration options.

ConfigMap Overview

Tekton Pipelines uses the following ConfigMaps for configuration:

config-defaults - Default values for TaskRuns and PipelineRuns
feature-flags - Feature gates and experimental features
config-events - CloudEvents configuration
config-observability - Metrics and observability settings
config-spire - SPIRE security configuration
config-leader-election-controller - Leader election settings
config-wait-exponential-backoff - Retry backoff configuration

Default Configuration (config-defaults)

The config-defaults ConfigMap controls default values for TaskRuns and PipelineRuns.

Timeout Settings

default-timeout-minutes

string

default:"60"

Default timeout in minutes for TaskRuns and PipelineRuns when none is specified.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
data:
  default-timeout-minutes: "60"

default-imagepullbackoff-timeout

duration

Duration to wait before declaring failure when image pull fails with imagePullBackOff. Setting to "0" enables fail-fast behavior.

data:
  default-imagepullbackoff-timeout: "5m"

Service Account

default-service-account

string

default:"default"

Default service account name for TaskRuns and PipelineRuns when none is specified.

data:
  default-service-account: "tekton"

Pod Template

default-pod-template

string

Default pod template applied to all TaskRun pods. Can include node selectors, tolerations, and other pod specifications.

data:
  default-pod-template: |
    nodeSelector:
      kops.k8s.io/instancegroup: build-instance-group

default-affinity-assistant-pod-template

string

Default pod template for affinity assistant pods.

Workspace Configuration

default-task-run-workspace-binding

string

Default workspace binding for workspaces declared by Tasks but not provided by TaskRuns.

data:
  default-task-run-workspace-binding: |
    emptyDir: {}

Matrix Configuration

default-max-matrix-combinations-count

string

default:"256"

Maximum number of parameter combinations in a Matrix that can be used to fan out a PipelineTask.

data:
  default-max-matrix-combinations-count: "1024"

Environment Variables

default-forbidden-env

string

Comma-separated list of environment variables that cannot be overridden by podTemplate.

data:
  default-forbidden-env: "TEST_TEKTON,CI_BUILD"

Labels

default-managed-by-label-value

string

default:"tekton-pipelines"

Default value for the app.kubernetes.io/managed-by label applied to all pods created for TaskRuns.

data:
  default-managed-by-label-value: "my-tekton-installation"

Resolver Configuration

default-resolver-type

string

Default resolver type to use in the cluster (e.g., git, bundles, hub, cluster).

data:
  default-resolver-type: "git"

default-maximum-resolution-timeout

duration

Maximum duration for the resolution controller before timing out.

data:
  default-maximum-resolution-timeout: "1m"

Results Configuration

default-sidecar-log-polling-interval

duration

default:"100ms"

Polling interval for the sidecar log results container. Controls how frequently the sidecar checks for step completion files.Lower values (e.g., 10ms) increase responsiveness but may increase CPU usage. Higher values (e.g., 1s) reduce resource usage but may delay result collection.

data:
  default-sidecar-log-polling-interval: "100ms"

Only applicable when using the sidecar-logs approach for results.

Step Reference Concurrency

default-step-ref-concurrency-limit

string

default:"5"

Maximum number of concurrent goroutines for resolving step references. Prevents overwhelming remote servers when TaskRuns contain many steps referencing StepActions.

data:
  default-step-ref-concurrency-limit: "20"

Resource Requirements

default-container-resource-requirements

string

Default resource requirements for containers created by the controller.

data:
  default-container-resource-requirements: |
    place-scripts:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
    prepare:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "256Mi"
        cpu: "500m"
    working-dir-initializer:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"
    prefix-scripts:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
    prefix-sidecar-scripts:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
    default:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "256Mi"
        cpu: "500m"

Feature Flags (feature-flags)

The feature-flags ConfigMap controls experimental and beta features.

API Fields

enable-api-fields

string

default:"beta"

Determines which gated features are enabled. Acceptable values: stable, beta, alpha.

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-api-fields: "alpha"

Affinity and Scheduling

coschedule

string

default:"workspaces"

Determines how PipelineRun pods are scheduled with Affinity Assistant.

workspaces - Schedule TaskRuns sharing PVC-based workspace to same node
pipelineruns - Schedule all TaskRuns in a PipelineRun to same node
isolate-pipelinerun - Schedule to same node, only one PipelineRun per node
disabled - No coschedule policy

data:
  coschedule: "pipelineruns"

Sidecar Configuration

await-sidecar-readiness

boolean

default:"true"

Wait for sidecar containers to be running before starting the first step.Setting to false allows immediate step execution but may cause issues with Tasks using sidecars.

data:
  await-sidecar-readiness: "false"

running-in-environment-with-injected-sidecars

boolean

default:"true"

Whether the cluster uses injected sidecars (e.g., Istio). Setting to false can decrease TaskRun startup time.

data:
  running-in-environment-with-injected-sidecars: "false"

enable-kubernetes-sidecar

boolean

default:"false"

Enable native Kubernetes sidecar support. Requires Kubernetes v1.29 or greater.

data:
  enable-kubernetes-sidecar: "true"

Credentials and Authentication

disable-creds-init

boolean

default:"false"

Disable Tekton’s built-in credential initialization. When enabled, use Workspaces to mount credentials from Secrets.

data:
  disable-creds-init: "true"

require-git-ssh-secret-known-hosts

boolean

default:"false"

Require Git SSH Secrets to include a known_hosts field for server key validation.

data:
  require-git-ssh-secret-known-hosts: "true"

OCI Bundles

enable-tekton-oci-bundles

boolean

default:"false"

Enable Tekton OCI bundle usage, allowing bundle field in taskRef and pipelineRef.

data:
  enable-tekton-oci-bundles: "true"

Results

results-from

string

default:"termination-message"

Method for extracting results from tasks.

termination-message - Use container termination message (4096 byte limit)
sidecar-logs - Use sidecar logs (configurable limit, beta feature)

data:
  results-from: "sidecar-logs"

max-result-size

string

Maximum size in bytes for each result when using sidecar-logs. Cannot exceed 1.5MB (CRD size limit).

data:
  max-result-size: "8192"

Security

set-security-context

boolean

default:"false"

Set security context for containers injected by Tekton. Required for running in namespaces with restricted pod security standards.

data:
  set-security-context: "true"

Not supported in all Kubernetes implementations (e.g., OpenShift).

set-security-context-read-only-root-filesystem

boolean

default:"false"

Enable readOnlyRootFilesystem in security context. Requires set-security-context to be enabled.

data:
  set-security-context-read-only-root-filesystem: "true"

Does not work on Windows platforms.

trusted-resources-verification-no-match-policy

string

default:"ignore"

Policy when no matching verification policies are found.

fail - Fail TaskRun/PipelineRun if no matching policies found
warn - Skip verification and log warning
ignore - Skip verification silently

data:
  trusted-resources-verification-no-match-policy: "warn"

enforce-nonfalsifiability

string

default:"none"

Configure non-falsifiable provenance support.

spire - Use SPIRE for non-falsifiable provenance (experimental)
none - No non-falsifiable provenance

data:
  enforce-nonfalsifiability: "spire"

CloudEvents

send-cloudevents-for-runs

boolean

default:"false"

Enable CloudEvents for CustomRuns and Runs when a CloudEvents sink is configured.

data:
  send-cloudevents-for-runs: "true"

Provenance

enable-provenance-in-status

boolean

default:"true"

Populate the provenance field in TaskRun and PipelineRun status with metadata about resources used.

data:
  enable-provenance-in-status: "false"

Advanced Features

keep-pod-on-cancel

boolean

default:"false"

Keep pods running when TaskRuns are cancelled, allowing log examination.

data:
  keep-pod-on-cancel: "true"

enable-cel-in-whenexpression

boolean

default:"false"

Enable CEL (Common Expression Language) evaluation in WhenExpressions.

data:
  enable-cel-in-whenexpression: "true"

enable-param-enum

boolean

default:"false"

Enable built-in parameter input validation via parameter enums.

data:
  enable-param-enum: "true"

disable-inline-spec

string

default:""

Prevent users from creating embedded spec TaskRuns or PipelineRuns. Comma-separated list of resource types.

data:
  disable-inline-spec: "pipeline,pipelinerun,taskrun"

enable-concise-resolver-syntax

boolean

default:"false"

Enable concise resolver syntax for referencing remote resources.

data:
  enable-concise-resolver-syntax: "true"

enable-step-actions

boolean

default:"true"

Enable StepActions feature (stable feature, cannot be disabled).

enable-artifacts

boolean

default:"false"

Enable the use of Artifacts in Steps (preview mode, not yet implemented).

data:
  enable-artifacts: "true"

Retry Configuration

enable-wait-exponential-backoff

boolean

default:"false"

Enable exponential backoff retry strategy for TaskRun and CustomRun creation on webhook timeouts.

data:
  enable-wait-exponential-backoff: "true"

Configure backoff parameters in the config-wait-exponential-backoff ConfigMap.

Exponential Backoff Configuration (config-wait-exponential-backoff)

When enable-wait-exponential-backoff is enabled, customize retry behavior:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-wait-exponential-backoff
  namespace: tekton-pipelines
data:
  duration: "10s"   # Initial wait time before first retry
  factor: "2.0"     # Multiplier for each subsequent retry
  jitter: "0.0"     # Random jitter (0.0-1.0)
  steps: "5"        # Maximum number of retry attempts
  cap: "60s"        # Maximum wait time between retries

duration

default:"10s"

Initial duration before the first retry.

factor

string

default:"2.0"

Factor by which duration increases after each retry.

jitter

string

default:"0.0"

Jitter factor for randomizing retry intervals (0.0 = no jitter, 0.2 = up to 20% additional wait).

steps

string

default:"5"

Number of backoff steps (retry attempts).

cap

duration

default:"60s"

Maximum duration between retries.

Remote Resolvers Configuration

Four remote resolvers are enabled by default and can be disabled in the resolvers-feature-flags ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: resolvers-feature-flags
  namespace: tekton-pipelines-resolvers
data:
  enable-bundles-resolver: "true"
  enable-git-resolver: "true"
  enable-hub-resolver: "true"
  enable-cluster-resolver: "true"

Registry Certificate Configuration

For private registries with self-signed certificates:

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-registry-cert
  namespace: tekton-pipelines
data:
  cert: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

The SSL_CERT_DIR is set to /etc/ssl/certs by default. If your cert is not in the default directory, configure it using this ConfigMap.

Complete Configuration Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-defaults
  namespace: tekton-pipelines
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"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
  namespace: tekton-pipelines
data:
  enable-api-fields: "alpha"
  coschedule: "pipelineruns"
  results-from: "sidecar-logs"
  max-result-size: "8192"
  set-security-context: "true"
  enable-tekton-oci-bundles: "true"

Get Started

Core Concepts

Guides

Advanced Features

Resolvers

Operations

Migration

ConfigMap Overview

Default Configuration (config-defaults)

Timeout Settings

Service Account

Pod Template

Workspace Configuration

Matrix Configuration

Environment Variables

Labels

Resolver Configuration

Results Configuration

Step Reference Concurrency

Resource Requirements

Feature Flags (feature-flags)

API Fields

Affinity and Scheduling

Sidecar Configuration

Credentials and Authentication

OCI Bundles

Results

Security

CloudEvents

Provenance

Advanced Features

Retry Configuration

Exponential Backoff Configuration (config-wait-exponential-backoff)

Remote Resolvers Configuration

Registry Certificate Configuration

Complete Configuration Example

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced Features

Resolvers

Operations

Migration

​ConfigMap Overview

​Default Configuration (config-defaults)

​Timeout Settings

​Service Account

​Pod Template

​Workspace Configuration

​Matrix Configuration

​Environment Variables

​Labels

​Resolver Configuration

​Results Configuration

​Step Reference Concurrency

​Resource Requirements

​Feature Flags (feature-flags)

​API Fields

​Affinity and Scheduling

​Sidecar Configuration

​Credentials and Authentication

​OCI Bundles

​Results

​Security

​CloudEvents

​Provenance

​Advanced Features

​Retry Configuration

​Exponential Backoff Configuration (config-wait-exponential-backoff)

​Remote Resolvers Configuration

​Registry Certificate Configuration

​Complete Configuration Example

Build docs developers (and LLMs) love

ConfigMap Overview

Default Configuration (config-defaults)

Timeout Settings

Service Account

Pod Template

Workspace Configuration

Matrix Configuration

Environment Variables

Labels

Resolver Configuration

Results Configuration

Step Reference Concurrency

Resource Requirements

Feature Flags (feature-flags)

API Fields

Affinity and Scheduling

Sidecar Configuration

Credentials and Authentication

OCI Bundles

Results

Security

CloudEvents

Provenance

Advanced Features

Retry Configuration

Exponential Backoff Configuration (config-wait-exponential-backoff)

Remote Resolvers Configuration

Registry Certificate Configuration

Complete Configuration Example