Skip to main content
The Bundle Resolver fetches Tekton resources from OCI bundles stored in container registries, enabling secure and versioned distribution of Tasks and Pipelines.

​
Resolver Type

This resolver responds to type bundles.

​
Parameters

​
bundle
string
required
The bundle URL pointing at the OCI image to fetch.Example: gcr.io/tekton-releases/catalog/upstream/golang-build:0.1Example with digest: docker.io/myuser/task@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828
​
name
string
required
The name of the resource to pull out of the bundle.Example: golang-build, hello-world
​
kind
string
required
The resource kind to pull out of the bundle.Options: task, pipeline
​
secret
string
The name of the secret to use when constructing registry credentials.Example: registry-credentials
​
cache
string
default:"auto"
Controls caching behavior for the resolved resource.Options: always, never, auto

​
Requirements

  • A cluster running Tekton Pipeline v0.41.0 or later
  • Built-in remote resolvers installed
  • The enable-bundles-resolver feature flag set to true in the resolvers-feature-flags ConfigMap
  • Beta features enabled

​
Configuration

The Bundle Resolver uses the bundleresolver-config ConfigMap in the tekton-pipelines-resolvers namespace.

​
Configuration Options

backoff-duration

Initial duration for a backoff (e.g., 500ms, 2s)

backoff-factor

Factor by which sleep duration increases (e.g., 2.5, 4.0)

backoff-jitter

Random sleep addition between 0 and duration × jitter (e.g., 0.1, 0.5)

backoff-steps

Number of backoff attempts (e.g., 3, 7)

backoff-cap

Maximum backoff duration (e.g., 10s, 20s)

default-kind

Default layer kind in bundle image (e.g., task, pipeline)

​
Caching Options

The bundle resolver supports caching to improve performance:
Cache ValueDescription
alwaysAlways cache resolved resources
neverNever cache resolved resources
autoCache only bundles pulled by digest (default)
Configure default cache mode in the bundleresolver-config ConfigMap: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: bundleresolver-config
  namespace: tekton-pipelines-resolvers
data:
  default-cache-mode: "auto"

​
Global Cache Configuration

Configure cache size and TTL using the resolver-cache-config ConfigMap: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: resolver-cache-config
  namespace: tekton-pipelines-resolvers
data:
  max-size: "1000"  # Maximum cache entries
  ttl: "5m"         # Time-to-live for entries

​
Usage Examples

​
Task Resolution by Digest

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: bundle-task-digest
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: docker.io/ptasci67/example-oci@sha256:053a6cb9f3711d4527dd0d37ac610e8727ec0288a898d5dfbd79b25bcaa29828
    - name: name
      value: hello-world
    - name: kind
      value: task

​
Task Resolution by Tag

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: bundle-task-tag
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: gcr.io/tekton-releases/catalog/upstream/git-clone:0.7
    - name: name
      value: git-clone
    - name: kind
      value: task
  params:
  - name: url
    value: https://github.com/tektoncd/catalog
  workspaces:
  - name: output
    volumeClaimTemplate:
      spec:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 500Mi

​
Task Resolution with Private Registry

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: bundle-private-registry
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: myregistry.io/myorg/private-task:latest
    - name: name
      value: my-task
    - name: kind
      value: task
    - name: secret
      value: registry-credentials

​
Pipeline Resolution

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: bundle-pipeline
spec:
  pipelineRef:
    resolver: bundles
    params:
    - name: bundle
      value: 10.96.190.208:5000/simple/pipeline:latest
    - name: name
      value: hello-pipeline
    - name: kind
      value: pipeline
  params:
  - name: username
    value: "tekton pipelines"

​
Task Resolution with Always Cache

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: bundle-always-cache
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: gcr.io/tekton-releases/catalog/upstream/golang-build:0.1
    - name: name
      value: golang-build
    - name: kind
      value: task
    - name: cache
      value: always

​
Task Resolution with Never Cache

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: bundle-never-cache
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: gcr.io/tekton-releases/catalog/upstream/golang-build:latest
    - name: name
      value: golang-build
    - name: kind
      value: task
    - name: cache
      value: never

​
Creating Registry Credentials

For private registries, create a secret with registry credentials: 
kubectl create secret docker-registry registry-credentials \
  --docker-server=myregistry.io \
  --docker-username=myuser \
  --docker-password=mypassword \
  [email protected]

​
ResolutionRequest Status

The ResolutionRequest.Status.RefSource field captures source metadata: 
status:
  refSource:
    uri: gcr.io/tekton-releases/catalog/upstream/git-clone
    digest:
      sha256: f51ca50f1c065acba8290ef14adec8461915ecc5f70a8eb26190c6e8e0ededaf
    entryPoint: git-clone
  data: YXBpVmVyc2lvbjog...

uri

Image repository URI without tag or digest

digest

Map of algorithm to hex-encoded image digest

entryPoint

Resource name in the OCI bundle

​
Best Practices

Use Digests

Reference bundles by digest for immutable, reproducible builds

Enable Caching

Use cache: auto or cache: always for frequently used bundles

Secure Credentials

Store registry credentials in Kubernetes secrets

Version Bundles

Tag bundle images with semantic versions
When using cache: auto (default), only bundles pulled by digest are cached. This ensures cached content is immutable.
The Tekton Catalog does not currently publish pipelines as OCI bundles. Use the Hub or Git resolvers for pipelines.

Build docs developers (and LLMs) love

Get started for freeTalk to us