Skip to main content
CustomRuns allow you to instantiate and execute Custom Tasks, which are implemented by custom task controllers running on-cluster. Custom Tasks provide behavior that’s independent of the standard Tekton Task implementation.

​
Overview

A CustomRun requires a custom task controller to be running on the cluster. This controller watches CustomRuns that reference its task type and updates their status. Without a controller, CustomRuns will have no status and no action will be taken.
v1beta1.CustomRun has replaced v1alpha1.Run for executing Custom Tasks. See the migration documentation for details on updating from v1alpha1.Run.

​
Configuring a CustomRun

​
Required Fields

  • apiVersion - Currently only tekton.dev/v1beta1 is supported
  • kind - Must be CustomRun
  • metadata - Uniquely identifies the CustomRun (e.g., name)
  • spec - Configuration for the CustomRun
    • Either customRef OR customSpec (not both)

​
Optional Fields

  • timeout - Maximum duration for a single execution
  • retries - Number of retries upon failure
  • params - Execution parameters for the custom task
  • serviceAccountName - ServiceAccount for executing the CustomRun
  • workspaces - Physical volumes for workspace requirements

​
Specifying the Target Custom Task

You can reference a custom task in two ways:

​
Referencing an Existing Custom Task

Use customRef to reference a custom task type by API group and kind:
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 MyCustomKind in the example.dev/v1beta1 API group will execute it.

​
Referencing by Name

You can also specify a named custom task resource:
apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1beta1
    kind: Example
    name: an-existing-example-task
The custom task controller will look up the Example resource with that name and use it to configure execution.

​
Unnamed Tasks

If no name is specified, the custom task controller may provide default behavior:
apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1beta1
    kind: Example

​
Parameters

Pass parameters to custom tasks using the params field: 
spec:
  params:
    - name: my-param
      value: chicken
The custom task controller interprets these values and may enforce required parameters or reject unknown ones.

​
Workspaces

If supported by the custom task, provide workspaces to share data: 
spec:
  workspaces:
    - name: my-workspace
      emptyDir: {}
Consult the custom task’s documentation to determine workspace support and naming requirements.

​
Service Account

Execute with specific credentials by specifying a ServiceAccount: 
spec:
  serviceAccountName: my-account
If not specified, the CustomRun uses the service account from configmap-defaults, or the namespace’s default service account.

​
Timeout

Specify a maximum duration for the custom task: 
apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  generateName: simpleexample
spec:
  timeout: 10s
  params:
    - name: searching
      value: the purpose of my existence
  customRef:
    apiVersion: custom.tekton.dev/v1alpha1
    kind: Example
    name: exampleName
Timeout support is optional but recommended. The custom task controller must implement timeout behavior. Tekton controllers never directly update CustomRun status.

​
Timeout Implementation Guide for Controllers

  1. Tekton controllers never directly update CustomRun status - the custom task controller must handle timeouts
  2. When CustomRun.Spec.Status is set to RunCancelled, the controller MUST cancel the CustomRun for pipeline-level timeout and cancellation to work
  3. Controllers should watch for CustomRun.Spec.Status == RunCancelled or CustomRun.HasTimedOut() and take cleanup actions
  4. Set conditions on the CustomRun’s status to Succeeded/False with optional reason CustomRunTimedOut
  5. Timeout is specified for each retry attempt, not all retries combined

​
Retries

Specify the number of retry attempts: 
apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  generateName: simpleexample
spec:
  retries: 3
  params:
    - name: searching
      value: the purpose of my existence
  customRef:
    apiVersion: custom.tekton.dev/v1alpha1
    kind: Example
    name: exampleName

​
Retry Implementation Guide for Controllers

  1. Tekton only checks ConditionSucceeded to determine termination - controllers MUST NOT set ConditionSucceeded to False until all retries are exhausted
  2. Controllers that don’t support retry can simply ignore the field
  3. Update the RetriesStatus field on each retry attempt
  4. Tekton does not validate that RetriesStatus entries match the retry count

​
Cancellation

Custom tasks must implement cancellation to support pipeline-level timeouts and cancellation. Pipeline Controller signals cancellation by setting spec.Status and spec.StatusMessage. The CustomRun controller updates status.conditions: 
status
  conditions:
  - type: Succeeded
    status: False
    reason: CustomRunCancelled
If the custom task does not support cancellation via .spec.status, the Pipeline cannot timeout or be cancelled as expected.

​
Monitoring Execution Status

The CustomRun’s status field tracks execution state, start and completion times, and output results.

​
Status Conditions

Custom task controllers update the status.conditions field to report progress: Ongoing Execution: 
status
  conditions:
  - type: Succeeded
    status: Unknown
Successful Completion: 
status
  conditions:
  - type: Succeeded
    status: True
    reason: ExampleComplete
    message: Yay, good times
Failed Completion: 
status
  conditions:
  - type: Succeeded
    status: False
    reason: ExampleFailed
    message: Oh no bad times
Cancelled: 
status
  conditions:
  - type: Succeeded
    status: False
    reason: CustomRunCancelled
    message: Oh it's cancelled

​
Status Values

StatusDescription
(unset)The custom task controller has not taken any action
UnknownExecution has started and is ongoing
TrueCompleted successfully
FalseCompleted unsuccessfully, all retries exhausted

​
Complete Status Example

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

​
Results

Custom task controllers can report output values in the results field after completion: 
results:
- name: my-result
  value: chicken

​
Complete Examples

​
Example with Referenced Task

apiVersion: tekton.dev/v1beta1
kind: CustomRun
metadata:
  name: my-example-run
spec:
  customRef:
    apiVersion: example.dev/v1alpha1
    kind: Example
    name: my-example-task
The controller looks up the Example resource named my-example-task and uses it to configure execution.

​
Example with Parameters

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
The controller validates and interprets these parameters to configure execution.

Build docs developers (and LLMs) love

Get started for freeTalk to us