Parameters

Parameters concept for Tekton Pipelines

Parameters allow you to supply values at runtime to customize the execution of Tasks and Pipelines. Parameters provide flexibility and reusability for your Tekton resources.

Overview

Parameters enable you to:

• Pass configuration values to Tasks and Pipelines
• Customize execution without modifying resource definitions
• Reuse Tasks and Pipelines with different inputs
• Share data between Tasks in a Pipeline

Parameter Types

Tekton supports three parameter types:

String Parameters

The most common parameter type. If no type is specified, it defaults to string.

params:
  - name: image-name
    type: string
    description: The name of the image to build
    default: "my-app:latest"

Array Parameters

Useful when the number of values varies, such as compilation flags or file lists.

params:
  - name: flags
    type: array
    description: Build flags to pass to the compiler
    default:
      - "--verbose"
      - "--optimize"

Object Parameters

Useful for grouping related parameters together.

params:
  - name: gitrepo
    type: object
    description: Git repository information
    properties:
      url:
        type: string
      commit:
        type: string
      branch:
        type: string
    default:
      url: "https://github.com/tektoncd/pipeline"
      branch: "main"

Object parameters must specify the properties section to define their schema.

Parameter Names

Parameter names must follow these rules:

• Must only contain alphanumeric characters, hyphens (-), underscores (_), and dots (.)
• Must begin with a letter or an underscore (_)
• Are case insensitive (e.g., APPLE and apple are treated as the same)

Object parameter names and their key names cannot contain dots (.).

Using Parameter Names with Dots

If a parameter name contains dots, use bracket notation with quotes:

params:
  - name: foo.bar
    type: string
    default: "test"
steps:
  - name: echo-param
    image: bash
    args:
      - "echo"
      - "$(params['foo.bar'])"

Parameters in Tasks

Defining Parameters in Tasks

apiVersion: tekton.dev/v1
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
  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[*])"
        - "url=$(params.someURL)"

Providing Parameters in TaskRuns

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-with-parameters
spec:
  taskRef:
    name: task-with-parameters
  params:
    - name: gitrepo
      value:
        url: "https://github.com/tektoncd/pipeline"
        commit: "c12b72"
    - name: flags
      value:
        - "--set"
        - "arg1=foo"
        - "--randomflag"
    - name: someURL
      value: "http://google.com"

Parameters in Pipelines

Defining Parameters in Pipelines

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

Providing Parameters in PipelineRuns

apiVersion: tekton.dev/v1
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"

Parameter Variable Substitution

Parameters can be referenced using variable substitution syntax:

String Parameters

# Reference a string parameter
$(params.image-name)

Array Parameters

# Reference entire array (expands to all elements)
$(params.flags[*])

# Reference specific element
$(params.flags[0])

Object Parameters

# Reference object properties
$(params.gitrepo.url)
$(params.gitrepo.commit)
$(params.gitrepo.branch)

You can only reference individual properties of object parameters, not the entire object (except when passing to another object parameter).

Default Values

Parameters can have default values that are used when no value is provided at runtime:

params:
  - name: image-name
    type: string
    default: "nginx:latest"
  - name: flags
    type: array
    default:
      - "--verbose"
  - name: gitrepo
    type: object
    properties:
      url:
        type: string
      branch:
        type: string
    default:
      url: "https://github.com/example/repo"
      branch: "main"

If a parameter does not have a default value, you must explicitly provide its value when creating a TaskRun or PipelineRun.

Parameter Propagation

When using embedded specs (taskSpec or pipelineSpec), parameters from the parent resource are automatically propagated to child resources:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: pr-echo-
spec:
  params:
    - name: HELLO
      value: "Hello World!"
  pipelineSpec:
    tasks:
      - name: echo-hello
        taskSpec:
          steps:
            - name: echo
              image: ubuntu
              script: |
                #!/usr/bin/env bash
                echo "$(params.HELLO)"

Propagation Rules

• Parameters are propagated only to embedded specs (taskSpec/pipelineSpec)
• Parameters are not propagated to referenced resources (taskRef/pipelineRef)
• Inner scopes take precedence over outer scopes when parameter names conflict
• Runtime values take precedence over default values

Best Practices

1. Use Descriptive Names

   Choose parameter names that clearly indicate their purpose:

   - name: image-tag        # Good
   - name: it               # Avoid
   
2. Provide Descriptions

   Always include descriptions to help users understand parameter usage:

   - name: timeout
     type: string
     description: "Maximum time to wait for the build to complete (e.g., 1h, 30m)"
   
3. Use Default Values

   Provide sensible defaults when possible to make your resources easier to use:

   - name: log-level
     type: string
     default: "info"
   
4. Group Related Parameters

   Use object parameters to group related configuration:

   - name: database
     type: object
     properties:
       host:
         type: string
       port:
         type: string
       name:
         type: string
   

Complete Example

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: build-and-push
spec:
  params:
    - name: image
      type: object
      description: Container image information
      properties:
        registry:
          type: string
        repository:
          type: string
        tag:
          type: string
      default:
        registry: "docker.io"
        tag: "latest"
    - name: build-args
      type: array
      description: Build arguments for docker build
      default: []
    - name: push
      type: string
      description: Whether to push the image after building
      default: "true"
  steps:
    - name: build
      image: gcr.io/kaniko-project/executor:latest
      args:
        - "--dockerfile=Dockerfile"
        - "--context=."
        - "--destination=$(params.image.registry)/$(params.image.repository):$(params.image.tag)"
        - "$(params.build-args[*])"
        - "--no-push=$(params.push)"
---
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-and-push-run
spec:
  taskRef:
    name: build-and-push
  params:
    - name: image
      value:
        registry: "gcr.io"
        repository: "my-project/my-app"
        tag: "v1.0.0"
    - name: build-args
      value:
        - "--build-arg=VERSION=1.0.0"
        - "--build-arg=ENV=production"
    - name: push
      value: "true"