Remote Resolution

Reference Tasks and Pipelines from remote sources like Git, OCI bundles, and Artifact Hub

Remote resolution allows you to reference Tasks and Pipelines stored outside your cluster, enabling sharing and reuse across teams and organizations.

Overview

Tekton supports multiple remote resolvers:

• Git resolver: Fetch from Git repositories
• Hub resolver: Fetch from Tekton Hub or Artifact Hub
• Cluster resolver: Reference resources in other namespaces
• Bundles resolver: Fetch from OCI registries
• HTTP resolver: Fetch from HTTP(S) URLs

Remote resolution promotes:

• Task and Pipeline reusability
• Version control for pipeline definitions
• Centralized catalog management
• Separation of pipeline definitions from runs

Prerequisites

Starting with v0.41.0, remote resolvers are enabled by default. Verify they’re enabled:

kubectl get configmap resolvers-feature-flags -n tekton-pipelines-resolvers -o yaml

Each resolver has a feature flag:

• enable-git-resolver: Git resolver
• enable-hub-resolver: Hub resolver
• enable-cluster-resolver: Cluster resolver
• enable-bundles-resolver: Bundles resolver
• enable-http-resolver: HTTP resolver

Git Resolver

Reference Tasks and Pipelines from Git repositories:

Basic Git Resolution

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: git-resolver-
spec:
  pipelineRef:
    resolver: git
    params:
      - name: url
        value: https://github.com/tektoncd/catalog.git
      - name: revision
        value: main
      - name: pathInRepo
        value: task/git-clone/0.10/git-clone.yaml
  params:
    - name: url
      value: https://github.com/my-org/my-repo
  workspaces:
    - name: output
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi

Git Resolver Parameters

Parameter	Description	Required	Default
url	Repository URL	Yes	-
revision	Git revision (branch, tag, commit)	No	main
pathInRepo	Path to YAML file in repo	Yes	-
token	Secret name for authentication	No	-
tokenKey	Key in secret containing token	No	token
serverURL	Custom Git server API URL	No	-
scmType	SCM type (github, gitlab, gitea, bitbucket)	No	Auto-detect

Using Private Repositories

1. Create authentication secret

   apiVersion: v1
   kind: Secret
   metadata:
     name: git-credentials
   type: Opaque
   stringData:
     token: ghp_your_github_token_here
   
2. Reference in PipelineRun

   apiVersion: tekton.dev/v1
   kind: PipelineRun
   metadata:
     generateName: private-git-
   spec:
     pipelineRef:
       resolver: git
       params:
         - name: url
           value: https://github.com/my-org/private-repo.git
         - name: revision
           value: main
         - name: pathInRepo
           value: pipelines/build.yaml
         - name: token
           value: git-credentials
         - name: tokenKey
           value: token
   

Custom Git Server

For self-hosted Git servers:

pipelineRef:
  resolver: git
  params:
    - name: url
      value: https://gitlab.example.com/my-group/my-repo.git
    - name: revision
      value: v1.0.0
    - name: pathInRepo
      value: tekton/pipeline.yaml
    - name: serverURL
      value: https://gitlab.example.com
    - name: scmType
      value: gitlab
    - name: token
      value: gitlab-token-secret

Hub Resolver

Fetch Tasks and Pipelines from Tekton Hub or Artifact Hub:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: hub-resolver-
spec:
  pipelineRef:
    resolver: hub
    params:
      - name: catalog
        value: Tekton
      - name: kind
        value: pipeline
      - name: name
        value: buildpacks
      - name: version
        value: "0.2"
  params:
    - name: BUILDER_IMAGE
      value: docker.io/cnbs/sample-builder:bionic
    - name: APP_IMAGE
      value: my-registry/my-app
    - name: SOURCE_URL
      value: https://github.com/buildpacks/samples
  workspaces:
    - name: source-ws
      volumeClaimTemplate:
        spec:
          accessModes:
            - ReadWriteOnce
          resources:
            requests:
              storage: 1Gi

Hub Resolver Parameters

Parameter	Description	Required	Default
name	Resource name	Yes	-
kind	Resource kind (task or pipeline)	Yes	task
version	Resource version	No	Latest
catalog	Catalog name (Tekton, Tekton-nightly)	No	Tekton
type	Hub type (artifact or tekton)	No	artifact

Using TaskRuns with Hub Resolver

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  generateName: hub-task-
spec:
  taskRef:
    resolver: hub
    params:
      - name: catalog
        value: Tekton
      - name: kind
        value: task
      - name: name
        value: git-clone
      - name: version
        value: "0.10"
  params:
    - name: url
      value: https://github.com/tektoncd/pipeline
  workspaces:
    - name: output
      emptyDir: {}

Cluster Resolver

Reference Tasks and Pipelines in other namespaces within the same cluster:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: cluster-resolver-example
  namespace: my-namespace
spec:
  pipelineRef:
    resolver: cluster
    params:
      - name: kind
        value: pipeline
      - name: name
        value: shared-pipeline
      - name: namespace
        value: tekton-resources

Cluster Resolver Parameters

Parameter	Description	Required	Default
kind	Resource kind (task or pipeline)	Yes	-
name	Resource name	Yes	-
namespace	Namespace containing the resource	Yes	-

The ServiceAccount running the PipelineRun needs RBAC permissions to read the referenced resource in the target namespace.

RBAC for Cluster Resolver

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: tekton-resource-reader
  namespace: tekton-resources
rules:
  - apiGroups: ["tekton.dev"]
    resources: ["tasks", "pipelines"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tekton-resource-reader-binding
  namespace: tekton-resources
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: tekton-resource-reader
subjects:
  - kind: ServiceAccount
    name: default
    namespace: my-namespace

HTTP Resolver

Fetch Tasks and Pipelines from HTTP(S) URLs:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: http-resolver-
spec:
  pipelineRef:
    resolver: http
    params:
      - name: url
        value: https://raw.githubusercontent.com/tektoncd/catalog/main/task/git-clone/0.10/git-clone.yaml

HTTP Resolver with Authentication

apiVersion: v1
kind: Secret
metadata:
  name: http-credentials
type: Opaque
stringData:
  token: bearer-token-value
---
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  generateName: http-auth-
spec:
  pipelineRef:
    resolver: http
    params:
      - name: url
        value: https://api.example.com/pipelines/build.yaml
      - name: secret-name
        value: http-credentials
      - name: secret-key
        value: token

Getting Started Example

1. Create a Pipeline in Git

   Create pipeline.yaml in your repository:

   kind: Pipeline
   apiVersion: tekton.dev/v1
   metadata:
     name: a-simple-pipeline
   spec:
     params:
       - name: username
     tasks:
       - name: task-1
         params:
           - name: username
             value: $(params.username)
         taskSpec:
           params:
             - name: username
           steps:
             - image: alpine:3.15
               script: |
                 echo "hello $(params.username)"
   
2. Commit and push

   git add pipeline.yaml
   git commit -m "Add a basic pipeline"
   git push origin main
   
3. Create a PipelineRun

   kind: PipelineRun
   apiVersion: tekton.dev/v1
   metadata:
     name: run-basic-pipeline-from-git
   spec:
     pipelineRef:
       resolver: git
       params:
         - name: url
           value: https://github.com/your-org/your-repo
         - name: revision
           value: main
         - name: pathInRepo
           value: pipeline.yaml
     params:
       - name: username
         value: tekton-user
   
4. Apply and monitor

   kubectl apply -f pipelinerun.yaml
   kubectl get pipelineruns -w
   

Best Practices

Version Control

Always specify explicit revisions (tags or commit SHAs) in production to ensure reproducibility.

# Good: Explicit version
params:
  - name: revision
    value: v1.2.3

# Also good: Commit SHA
params:
  - name: revision
    value: abc123def456

# Avoid in production: Branch name
params:
  - name: revision
    value: main

Organize Remote Resources

my-repo/
├── tekton/
│   ├── tasks/
│   │   ├── build.yaml
│   │   ├── test.yaml
│   │   └── deploy.yaml
│   └── pipelines/
│       ├── ci.yaml
│       └── cd.yaml

Cache Considerations

Tekton caches resolved resources. Cache TTL can be configured in the resolver configuration.

Security

# Use secrets for authentication
params:
  - name: token
    value: git-token-secret

# Don't embed credentials in URLs
# Bad:
value: https://username:[e-mail]/repo

# Good:
value: https://github.com/repo
# With separate token parameter

Troubleshooting

Resolution failed: repository not found

Check:

1. Repository URL is correct
2. Repository is public, or authentication is configured
3. Token has appropriate permissions
4. Branch/tag/revision exists

View resolver logs:

kubectl logs -n tekton-pipelines-resolvers deployment/tekton-pipelines-remote-resolvers

Resolution failed: file not found

Verify:

1. pathInRepo is correct (case-sensitive)
2. File exists at the specified revision
3. File contains valid Tekton YAML

Test manually:

git clone <repo-url>
git checkout <revision>
cat <pathInRepo>

RBAC errors with cluster resolver

Ensure ServiceAccount has permissions:

# Check ServiceAccount
kubectl get sa -n <namespace>

# Check RoleBindings
kubectl get rolebinding -n <target-namespace>

# Describe PipelineRun for details
kubectl describe pipelinerun <name>

Comparison of Resolvers

Resolver	Use Case	Pros	Cons
Git	Versioned pipelines in repos	Version control, collaboration	Requires Git access
Hub	Curated, community tasks	Verified tasks, easy discovery	Limited to Hub catalog
Cluster	Cross-namespace sharing	No external dependencies	Cluster-scoped only
HTTP	Generic URL-based	Flexible, simple	No versioning
Bundles	OCI registry storage	Immutable, cached	Requires OCI registry

Use Git resolver for your organization’s custom Tasks and Pipelines, and Hub resolver for community-maintained resources.