#Consume Resources with the Hub Resolver

#Feature Overview

Tekton hub resolver can fetch remote Task, Pipeline, and StepAction manifests from artifacthub-shim when TektonConfig points the Artifact Hub endpoint to the shim API.

The resolver catalog parameter must match a repository.yaml gitRepositories[].repositories[].name value for ConfigMap-backed repositories, or one of the built-in catalog names:

The built-in StepAction catalog is registered only when the packaged catalog contains a stepaction/ directory.

#Prerequisites

• artifacthub-shim is installed and ready.
• Tekton hub resolver is enabled.
• TektonConfig.spec.pipeline.hub-resolver-config.default-type is set to artifact, or each reference explicitly passes type: artifact.
• default-tekton-hub-catalog remains set to catalog; current resolver versions still read it even when Artifact Hub mode is the default.

#Reference a Task

Use a remote Task in taskRef.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-remote-task
spec:
  taskRef:
    resolver: hub
    params:
      - name: type
        value: artifact
      - name: catalog
        value: catalog
      - name: kind
        value: task
      - name: name
        value: run-script
      - name: version
        value: "0.1.0"
  params:
    - name: script
      value: echo docs-verify

#Reference a Pipeline

Use a remote Pipeline in pipelineRef.

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: run-remote-pipeline
spec:
  pipelineRef:
    resolver: hub
    params:
      - name: type
        value: artifact
      - name: catalog
        value: catalog-pipelines
      - name: kind
        value: pipeline
      - name: name
        value: build-deploy
      - name: version
        value: "0.2.0"

#Reference a StepAction

Use a remote StepAction in a step ref.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: run-remote-stepaction
spec:
  taskSpec:
    steps:
      - name: echo
        ref:
          resolver: hub
          params:
            - name: type
              value: artifact
            - name: catalog
              value: catalog-stepactions
            - name: kind
              value: stepaction
            - name: name
              value: echo-message
            - name: version
              value: "0.1.0"

StepAction references should pass catalog explicitly. Current hub resolver defaults only include Artifact Hub task and pipeline catalog settings.

#Historical Pipeline Catalog Compatibility

Older Pipeline references may use catalog: catalog. New references should use catalog-pipelines, but shim keeps a built-in catalog alias from pipeline/catalog to pipeline/catalog-pipelines for compatibility. See Historical Pipeline Catalog References for the exact behavior and recommended cleanup.

#Parameter Reference

#Verification

If a resource does not resolve, first check the TaskRun or PipelineRun status:

kubectl get taskrun run-remote-task -o yaml

Resolver failures usually appear before the workload Pod is created. If the failure mentions a missing catalog, package, or version, inspect the repository ConfigMap Events:

kubectl describe configmap <repository-configmap-name> \
  -n artifacthub-shim-system

Look for RepositorySourceReady, RepositorySourceInvalid, or RepositorySourceDegraded. Use the resolver logs only after the run status and repository Events do not explain the failure.

#Learn More

• Quick Start
• Configure Tekton Integration
• Troubleshoot hub resolver failures
• Tekton Hub Resolver