Tekton Pipelines — API Surface#

API types#

Kubernetes CRD API (primary surface) + Go Library API (clientset) + Resolver Plugin Interface + Admission Webhook API + Metrics/Events (Prometheus/CloudEvents)

Tekton’s user-facing API is not HTTP REST or gRPC in the traditional application sense. Its primary API is the Kubernetes Custom Resource API — users submit YAML manifests for Tekton CRD types and interact with them through kubectl or the generated Go clientset. The system also exposes a plugin extension point via the Resolver interface, and internal HTTP health endpoints.

Kubernetes CRD API (primary)#

Tekton’s entire surface is modeled as Kubernetes CRDs registered under the tekton.dev API group. Each CRD is versioned and managed through Kubernetes’ own API server machinery.

Stable API — tekton.dev/v1#

Beta API — tekton.dev/v1beta1#

Alpha API — tekton.dev/v1alpha1#

Resolution API — resolution.tekton.dev#

All CRD definitions live in config/300-crds/. Version conversion between v1alpha1 ↔ v1beta1 ↔ v1 is handled by the webhook’s CRD hub conversion, implemented in pkg/apis/pipeline/v1/ (e.g., pipelinerun_conversion.go).

REST/HTTP API (internal only)#

All binaries expose minimal health-check HTTP endpoints. These are not user-facing APIs but are used by Kubernetes liveness/readiness probes.

• Router: stdlib net/http.ServeMux
• Port: 8080 (configurable via PROBES_PORT env var)
• Endpoints:

Present in: cmd/controller, cmd/webhook, cmd/events, and implicitly in cmd/resolvers.

Admission Webhook API#

The cmd/webhook binary registers three Kubernetes admission webhooks via Knative’s webhook infrastructure, all served on port 8443 (TLS):

Covered types (defaulting + validation):

v1alpha1: VerificationPolicy, StepAction
v1beta1:  Pipeline, Task, TaskRun, PipelineRun, CustomRun, StepAction
v1:       Task, Pipeline, TaskRun, PipelineRun
resolution/v1alpha1: ResolutionRequest
resolution/v1beta1:  ResolutionRequest

Each CRD Go type implements Knative webhook interfaces — SetDefaults(ctx) for defaulting and Validate(ctx) *apis.FieldError for validation — defined in pkg/apis/pipeline/{v1,v1beta1,v1alpha1}/. The webhook does not perform any application logic; it enforces API contracts.

Go Library API (clientset)#

Tekton ships a fully generated Kubernetes-style Go clientset at pkg/client/clientset/versioned/. This is the programmatic API for Go tools (Tekton CLI, CI systems, operators) to interact with Tekton resources.

Top-level interface#

// pkg/client/clientset/versioned/clientset.go
type Interface interface {
    Discovery() discovery.DiscoveryInterface
    TektonV1alpha1() TektonV1alpha1Interface
    TektonV1beta1() TektonV1beta1Interface
    TektonV1() TektonV1Interface
}

Per-version interfaces#

TektonV1Interface (pkg/client/clientset/versioned/typed/pipeline/v1/)

type TektonV1Interface interface {
    RESTClient() rest.Interface
    PipelinesGetter          // → PipelineInterface (namespaced)
    PipelineRunsGetter       // → PipelineRunInterface (namespaced)
    TasksGetter              // → TaskInterface (namespaced)
    TaskRunsGetter           // → TaskRunInterface (namespaced)
}

TektonV1beta1Interface (pkg/client/clientset/versioned/typed/pipeline/v1beta1/)

type TektonV1beta1Interface interface {
    RESTClient() rest.Interface
    CustomRunsGetter         // → CustomRunInterface (namespaced)
    PipelinesGetter
    PipelineRunsGetter
    StepActionsGetter        // → StepActionInterface (namespaced)
    TasksGetter
    TaskRunsGetter
}

TektonV1alpha1Interface (pkg/client/clientset/versioned/typed/pipeline/v1alpha1/)

type TektonV1alpha1Interface interface {
    RESTClient() rest.Interface
    RunsGetter               // → RunInterface (namespaced)
    StepActionsGetter
    VerificationPoliciesGetter // → VerificationPolicyInterface (namespaced)
}

Each resource interface (e.g., TaskRunInterface) provides the standard Kubernetes CRUD surface:

type TaskRunInterface interface {
    Create(ctx, *v1.TaskRun, metav1.CreateOptions) (*v1.TaskRun, error)
    Update(ctx, *v1.TaskRun, metav1.UpdateOptions) (*v1.TaskRun, error)
    UpdateStatus(ctx, *v1.TaskRun, metav1.UpdateOptions) (*v1.TaskRun, error)
    Delete(ctx, name string, metav1.DeleteOptions) error
    DeleteCollection(ctx, metav1.DeleteOptions, metav1.ListOptions) error
    Get(ctx, name string, metav1.GetOptions) (*v1.TaskRun, error)
    List(ctx, metav1.ListOptions) (*v1.TaskRunList, error)
    Watch(ctx, metav1.ListOptions) (watch.Interface, error)
    Patch(ctx, name string, pt types.PatchType, data []byte, ...) (*v1.TaskRun, error)
}

All client code is generated by client-gen (code generation, not manually written). Also generated: informers (pkg/client/informers/), listers (pkg/client/listers/), and injection helpers (pkg/client/injection/).

API style: Standard Kubernetes client-go pattern — CRUD with Watch for event streaming. No fluent builder or functional options; config is passed via rest.Config.

Backward compatibility: Three API versions co-exist; v1 is stable. ConvertTo/ConvertFrom methods on each type handle cross-version conversion through the webhook’s hub pattern.

Plugin / Extension System: Resolver Interface#

The most significant extension point is the Resolver interface, which allows new remote resource sources to be plugged into Tekton’s resolution framework:

// pkg/remoteresolution/resolver/framework/interface.go
type Resolver interface {
    Initialize(ctx context.Context) error
    GetName(ctx context.Context) string
    GetSelector(ctx context.Context) map[string]string
    Validate(ctx context.Context, req *v1beta1.ResolutionRequestSpec) error
    Resolve(ctx context.Context, req *v1beta1.ResolutionRequestSpec) (ResolvedResource, error)
}

Mechanism: Interface-based plugin, compiled in — not dynamic loading. Each resolver is a Go struct implementing Resolver, wrapped by framework.NewController(ctx, resolver) and registered into the cmd/resolvers binary.

Built-in resolvers (all in pkg/remoteresolution/resolver/):

Extension points for third-party resolvers: Implement Resolver, compile into a new binary alongside framework.NewController. The GetSelector method returns labels used to route ResolutionRequest objects to the correct resolver controller.

ResolvedResource return type:

type ResolvedResource interface {
    Data() []byte
    Annotations() map[string]string
    RefSource() *pipelinev1.RefSource
}

Internal Binary CLIs (operator management, not user-facing)#

All Tekton binaries use stdlib flag — no Cobra or urfave/cli. These are operator-configured, not user-invoked.

cmd/controller flags#

Also accepts THREADS_PER_CONTROLLER env var.

cmd/resolvers flags#

Also accepts TEKTON_HUB_API and ARTIFACT_HUB_API env vars for Hub resolver URLs.

cmd/entrypoint flags (injected into step containers)#

Internal CLI used by the pod builder to wrap each step. Users never invoke this directly.

Metrics API#

Tekton exposes observability data through two mechanisms:

OpenTelemetry / Prometheus (pkg/taskrunmetrics, pkg/pipelinerunmetrics):

• TaskRun and PipelineRun metrics are published via the OpenTelemetry SDK
• Metrics include: count by state, duration histograms, running counts
• Prometheus scraping is configured via OpenTelemetry Prometheus exporter
• Metrics are registered lazily at controller startup when the ConfigMap (config-observability) is read

CloudEvents (pkg/reconciler/notifications/):

• Optional feature (toggled by send-cloudevents-for-runs feature flag)
• Emitted by the cmd/events binary, a separate controller that watches CustomRuns
• CloudEvents are sent to a sink configured in the TaskRun/PipelineRun object
• Event schema follows CloudEvents 1.0 spec with Tekton-specific types

API versioning strategy#

Tekton follows Kubernetes API versioning conventions:

• v1 = stable, production-ready; long deprecation period
• v1beta1 = beta; breaking changes possible with deprecation notice
• v1alpha1 = alpha; unstable, may change without notice

Cross-version conversion is handled by the webhook’s hub conversion pattern — each type has ConvertTo(*v1.Type, ...) and ConvertFrom(*v1.Type, ...) methods. The config/300-crds/ YAML files declare all stored versions and their schemas (OpenAPI v3 via openapi_generated.go).

There is no explicit semantic versioning of the Go module itself for Tekton’s library API — the module is github.com/tektoncd/pipeline without a /v2 suffix, and breaking changes are governed by the CRD API deprecation policy rather than Go module versioning.