Configuration Options

Configure Tekton Pipelines installation settings

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 · 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"