Tekton Catalog: reusable Tasks, and a repository that is being taken apart

A folder of Task manifests, not a distribution you install once

The unit of this project is one Kubernetes resource at a time. The README describes the repository as a catalog of Task and Pipeline resources, and also StepActions, designed to be reusable across many pipelines. Each Task lives in its own directory with a README.md and a Kubernetes manifest, and the README is explicit that you choose which Tasks to install on your cluster. There is no operator, no installer and no controller here.

That design choice has consequences. Nothing is taken on trust until you apply it, because the manifest is a plain file in a repository you can read line by line. The cost is that there is no convenient bundle of a complete workflow; you assemble the pieces yourself and you own the wiring between them. For a platform team that has to justify every Task in a build pipeline, being able to point a reviewer at a single YAML file in a known directory is worth more than a one line install.

The intended users are therefore Kubernetes and Tekton practitioners writing CI pipelines: application teams that want a familiar Task for a common step, and platform teams that copy and adapt the YAML into their own repositories once they trust it.

Directory layout is the versioning scheme

Every resource follows a fixed directory shape, and the naming rules are strict enough that a wrong path breaks the tooling. The top level directory carries the kind of the resource, so ./task/ holds Tasks. Below that sits a directory named after the resource, and inside it the version subdirectories, each of which contains the definition file whose name matches the resource name.

The README shows the pattern for an argocd resource with 0.1 and 0.2 directories, and for golang-build where the layout is slightly different, with the OWNERS file and README.md sitting alongside the 0.1 folder. The rule it spells out is that the definition file must have the same name as the resource directory, so the file for git-clone version 0.9 is git-clone.yaml in task/git-clone/0.9/.

Each version directory also carries an OWNERS file naming the people responsible for that resource, and a samples/ folder with example inputs such as a deploy-to-k8s.yaml. The samples are worth using even when you do not install the Task, because they show the shape of the params and workspaces a resource expects, which is often the only place that information is written down.

The Makefile repeats the convention when it documents a single file lint target, pointing at task/git-clone/0.9/git-clone.yaml as the example path.

Annotations are where compatibility and platform support are declared

The metadata on each resource carries more than cosmetic labels, and this is the part of the catalog most likely to be ignored and most likely to cause trouble later.

The version of the resource goes in the app.kubernetes.io/version label. Annotations record the minimum pipeline version the resource is compatible with, under tekton.dev/pipelines.minVersion, plus three optional fields: tekton.dev/categories as a comma separated list, tekton.dev/tags for free form tags such as ansible, cli, and tekton.dev/displayName for a human readable name. A further annotation, tekton.dev/platforms, takes a comma separated list of platforms such as linux/amd64,linux/s390x, and it is optional.

The minVersion annotation is the one that deserves a careful look. It tells you the oldest Pipelines release the resource was written against, which is the number to compare against the Pipelines version running in your cluster before you apply anything. The platform list matters on mixed architecture clusters, since a Task that only runs on linux/amd64 will fail elsewhere.

The categories list is inherited from an older system. The README notes that the historical list and the procedure for adding new categories are documented in the now archived tektoncd/hub repository, which is a sign that this part of the metadata has not kept pace with the rest of the project.

Applying a Task and running it through a TaskRun

The documented path from repository to running Task is short. You apply the manifest into your cluster, confirm it landed, write a TaskRun that references it with the required params and workspaces, apply that, and then read the status back.

Applying the manifest is a single kubectl call, and the expected output confirms the Task was created with its group and name.

$ kubectl apply -f golang/build.yaml
task.tekton.dev/golang-build created

The TaskRun references the Task by name and supplies the inputs it declares. In the example, the package param points at a GitHub repository and the source workspace is bound to a persistent volume claim named my-source.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: example-run
spec:
  taskRef:
    name: golang-build
  params:
  - name: package
    value: github.com/tektoncd/pipeline
  workspaces:
  - name: source
    persistentVolumeClaim:
      claimName: my-source

Applying the TaskRun produces another line of confirmation, and reading it back with kubectl get taskrun shows a status block with a completionTime and a condition of type Succeeded.

$ kubectl apply -f example-run.yaml
taskrun.tekton.dev/example-run created

Note what the example does not cover: authentication for the Git clone, image credentials, and the fact that the persistent volume claim must already exist in the namespace. The README does not document how to handle private repositories, so a team with private sources will need to work that out from the Task's own README.

Bundles remove the install step entirely

Installing a Task as a cluster resource is only one of two ways to use this catalog. Tekton Bundles store a Task as an OCI image in a container registry, and the bundle resolver then pulls it at run time. The effect is that a TaskRun can reference a catalog entry without anything ever being applied to the cluster.

The reference form changes only the taskRef block. Instead of a name, it names a resolver called bundles and passes three params: the bundle image reference, the resource name and the resource kind.

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: example-run
spec:
  taskRef:
    resolver: bundles
    params:
    - name: bundle
      value: ghcr.io/tektoncd/catalog/upstream/tasks/golang-build:0.1
    - name: name
      value: golang-build
    - name: kind
      value: task

The bundle path is versioned the same way the directory layout is, with the tag on the image carrying the version, so a pin such as golang-build:0.1 names both the Task and its version in one string.

The practical difference between the two approaches is where the trust boundary sits. A Task applied with kubectl lives in your cluster, where a cluster administrator can see and audit it, and where it can be patched. A bundle is fetched at run time from a registry, which means the pipeline depends on registry availability and on the image tag still resolving to what you expected. For reproducible pipelines, the applied manifest is easier to review; for quick experiments, the bundle reference is far less ceremony.

Artifact Hub replaced Tekton Hub, and the search index matters

Discovery is where this project has already changed once, and the README is blunt about it. The recommended way to search for Tekton resources is Artifact Hub, where the tasks in this catalog are published under the tekton-catalog-tasks repository. The previous Tekton Hub at hub.tekton.dev is marked deprecated, and the hosted service is no longer running.

That leaves a distribution model with two layers. Some Tasks live in this repository and are indexed on Artifact Hub. Others, such as git-clone, are increasingly published from their own repositories and surfaced through the same Artifact Hub index. The README frames the direction explicitly, pointing at a separate tektoncd-catalog organisation and saying individual resources are moving to be published from their own repositories and discovered through Artifact Hub rather than from one monolithic repository.

For a consumer this changes where you look and what you trust. A Task in this repository carries an OWNERS file naming its maintainers inside the project. A Task published from its own repository carries its own release history and its own versioning, which is better in one respect and worse in another, because a single directory that held several versions of everything no longer gives you a consistent view of what exists at which version.

A TEP formalising this direction and the migration path is still being prepared, and the roadmap file is being refreshed to match. Expect the versioning, maintenance and contribution model to move.

Development workflow, licence and the state of the tree

Working on the catalog itself is a make-driven flow. The README lists three targets for a new contributor: setup, lint and a single task test.

make setup  # one-command setup: installs pre-commit hooks and linters
make lint   # run all linters (yamllint + gofmt)
make test TASK=git-clone VERSION=0.9  # run e2e test for a single task

The Makefile shows what those targets do. Setup installs pre-commit, gitlint and yamllint through pip and installs the commit message hook. Lint runs yamllint over every YAML file outside vendor and checks gofmt output across the Go files. The test target calls a shell script under test/ with the task and version arguments, and a separate test-e2e target provisions a Kind cluster through a script in hack/ and pins a pipeline version of v1.9.0 for the run.

The repository is licensed Apache-2.0, with the licence file at the root. That is a permissive licence with attribution obligations, and for a catalog of manifests it is close to the default expectation for infrastructure code, though the notice requirement applies to copies you redistribute.

On maintenance, the repository is not archived and the last push was on 2026-10-01, but it has no GitHub releases at all, so there is no tag to pin. Version information lives inside the resource directories, in the version label of each manifest, and in the branch structure: the README states that the main branch has been synced with the v1beta1 branch since 2020-06-19, and that anyone wanting v1alpha1 resources must use the v1alpha1 branch.

Editorial conclusion

Adopt tektoncd/catalog when you want proven Task definitions you can apply to a cluster today and read in full before trusting, and when you are willing to vendor the YAML you depend on. Do not build a long lived automation path on the assumption that a given Task version will stay in this repository, because the project states it is moving toward a distributed catalog with resources published from their own repositories and a migration TEP still in preparation. Verify first by applying one Task from the task/ directory to a scratch cluster with kubectl apply, then checking the tekton.dev/pipelines.minVersion annotation against the Pipelines version your cluster actually runs.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. tektoncd/catalog on GitHub