OpenShift Pipelines (Tekton): From a Monolithic Jenkinsfile to Reusable Tasks

Most teams that adopt OpenShift arrive with luggage: a Jenkinsfile that started at 60 lines and now weighs 800, with nested script {} blocks, a shared library nobody dares to touch, and three agents whose Docker images were last rebuilt in 2021. It works — until a new service needs the same build logic, and the only migration path is copy-paste.

OpenShift Pipelines (the supported downstream of Tekton) changes the unit of reuse. Instead of one file describing the whole flow, you get Task objects: versioned, namespaced (or clusterwide), testable in isolation, and composed into Pipeline objects. This article is a pragmatic migration guide: how to cut a monolithic Jenkinsfile into Tasks, how to handle workspaces, dependency resolution and build cache, and how to trigger everything from Git with an EventListener.

Context: why the monolith hurts on Kubernetes

A Jenkinsfile is executable Groovy. That is its strength and its curse. Logic, orchestration, and infrastructure assumptions all live in the same file:

pipeline { agent { label 'maven-jdk17' } stages { stage('Checkout') { steps { checkout scm } } stage('Build') { steps { sh 'mvn -B -s settings.xml clean package' } } stage('Test') { steps { sh 'mvn -B verify' } } stage('Image') { steps { sh 'podman build -t $REG/$APP:$TAG . && podman push ...' } } stage('Deploy') { steps { sh 'oc apply -f k8s/ && oc rollout status deploy/$APP' } } } } 

Three problems surface once you run this at scale on OpenShift:

1. No reuse boundary. stage('Image') is identical in 40 repositories, but each repo owns its own copy. One CVE in the build tooling means 40 pull requests.
2. Implicit state. Jenkins gives you a persistent workspace directory on the agent, so .m2 cache, node_modules and the Git checkout "just exist". On Kubernetes, every step is a container in a Pod; nothing persists unless you declare it.
3. Agent drift. The maven-jdk17 label points to a VM or image maintained outside Git. Tekton forces each step to name its own image, which is both more verbose and far more auditable.

The goal of migration is not a 1:1 translation. It is to extract the five or six genuinely reusable Tasks your organisation needs, version them, and leave the per-application glue in a thin Pipeline.

Concept mapping

Getting the platform ready

OpenShift Pipelines ships as an operator. Verify it and install the CLI:

# Operator and version oc get csv -n openshift-operators | grep pipelines # Cluster-wide Tasks shipped by Red Hat (git-clone, buildah, s2i, ...) oc get clustertasks 2>/dev/null | head oc get tasks -n openshift-pipelines | head # tkn CLI, matched to the cluster tkn version 

Create a dedicated namespace and service account for the pipeline — do not reuse pipeline SA defaults blindly across teams:

oc new-project payments-ci oc create sa pipeline-runner -n payments-ci 

Step 1 — Cut the Jenkinsfile into Tasks

Apply one rule: a Task is reusable only if it takes everything it needs as params and workspaces, and exposes everything downstream needs as results. No hardcoded registry, no hardcoded namespace.

Here is the Maven build extracted as a Task, with an explicit cache workspace:

apiVersion: tekton.dev/v1 kind: Task metadata: name: maven-build namespace: payments-ci labels: app.kubernetes.io/version: "0.4" spec: description: Build a Maven project, reusing a persistent ~/.m2 cache. params: - name: GOALS type: array default: ["-B", "clean", "package"] - name: MAVEN_IMAGE type: string default: registry.access.redhat.com/ubi9/openjdk-17:1.20 - name: CONTEXT_DIR type: string default: "." workspaces: - name: source description: Checked-out sources. - name: maven-cache description: Persistent local repository. optional: true - name: maven-settings description: ConfigMap or Secret holding settings.xml. optional: true results: - name: ARTIFACT_VERSION description: Project version read from the POM. steps: - name: build image: $(params.MAVEN_IMAGE) workingDir: $(workspaces.source.path)/$(params.CONTEXT_DIR) args: ["$(params.GOALS[*])"] env: - name: MAVEN_OPTS value: -Dmaven.repo.local=$(workspaces.maven-cache.path)/repository script: | #!/usr/bin/env bash set -euo pipefail SETTINGS="" if [ -f "$(workspaces.maven-settings.path)/settings.xml" ]; then SETTINGS="-s $(workspaces.maven-settings.path)/settings.xml" fi mvn ${SETTINGS} "$@" mvn -q help:evaluate -Dexpression=project.version -DforceStdout \ | tee $(results.ARTIFACT_VERSION.path) 

Two details matter here:

• optional: true workspaces let the same Task run with or without a cache. Local developers can start a PipelineRun with an emptyDir; CI mounts a PVC.
• Results are files, not environment variables. Write to $(results.<name>.path) with no trailing newline issues (tee is fine, Tekton trims trailing whitespace).

Versioning Tasks

Treat Tasks like libraries. Two viable strategies:

1. Git + resolver. Keep Tasks in a platform-tekton-catalog repo and reference them by tag with the Git resolver. No cluster-side copy to keep in sync.
2. OCI bundles. Push Tasks to your registry with tkn bundle push and reference them by digest. Best for air-gapped clusters and for signing.

# OCI bundle, immutable reference tkn bundle push quay.io/acme/tekton-catalog/maven-build:0.4 -f task-maven-build.yaml 

In a Pipeline, pin the version:

- name: build taskRef: resolver: bundles params: - name: bundle value: quay.io/acme/tekton-catalog/maven-build@sha256:3f1d... # digest, not tag - name: name value: maven-build - name: kind value: task 

Never reference a mutable tag in production pipelines. A digest is the Tekton equivalent of a pinned shared-library version.

Step 2 — Workspaces, dependency resolution and cache

This is where most migrations fail. Jenkins gave you a sticky filesystem; Tekton gives you declarative volumes.

Source workspace

Use a volumeClaimTemplate so each PipelineRun gets a fresh, automatically deleted PVC:

workspaces: - name: source volumeClaimTemplate: spec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 2Gi 

With RWO storage, every Task sharing that PVC must be scheduled on the same node. Tekton's affinity assistant handles this automatically (it creates a placeholder StatefulSet that pins the Pods). Check the feature flag before you fight phantom scheduling issues:

oc get cm feature-flags -n openshift-pipelines -o jsonpath='{.data.coschedule}{"\n"}' # expected: workspaces (default) — pins Pods sharing a workspace to one node 

Cache workspace

The source workspace dies with the run; the cache must not. Create a long-lived PVC per team and language runtime:

apiVersion: v1 kind: PersistentVolumeClaim metadata: name: maven-cache namespace: payments-ci spec: accessModes: ["ReadWriteMany"] # RWX: concurrent PipelineRuns resources: requests: storage: 20Gi storageClassName: ocs-storagecluster-cephfs 

If you only have RWO storage (common on bare metal with LVM or on some cloud CSI drivers), you have two options:

• One cache PVC per pipeline, ReadWriteOnce, and accept serialised runs (PipelineRun concurrency 1 via a mutex Task or an admission policy).
• Externalise the cache: a cache-fetch / cache-upload Task pair that pulls a tarball from S3/ODF object storage keyed by the hash of pom.xml or package-lock.json. Slower cold start, but fully parallel and node-independent.

The key-based approach is worth the extra two Tasks once you exceed ~10 concurrent builds:

- name: cache-key image: registry.access.redhat.com/ubi9/ubi-minimal:9.4 script: | #!/bin/sh set -e sha256sum $(workspaces.source.path)/pom.xml | cut -c1-16 \ > $(results.CACHE_KEY.path) 

Step 3 — Compose the Pipeline

The Pipeline is now thin: ordering, parameter plumbing, and workspace binding.

apiVersion: tekton.dev/v1 kind: Pipeline metadata: name: payments-api namespace: payments-ci spec: params: - name: git-url - name: git-revision default: main - name: image default: image-registry.openshift-image-registry.svc:5000/payments-ci/payments-api workspaces: - name: source - name: maven-cache - name: maven-settings - name: dockerconfig results: - name: image-digest value: $(tasks.build-image.results.IMAGE_DIGEST) tasks: - name: clone taskRef: { name: git-clone, kind: Task } params: - name: url value: $(params.git-url) - name: revision value: $(params.git-revision) workspaces: - name: output workspace: source - name: build runAfter: ["clone"] taskRef: { name: maven-build, kind: Task } params: - name: GOALS value: ["-B", "clean", "verify"] workspaces: - name: source workspace: source - name: maven-cache workspace: maven-cache - name: maven-settings workspace: maven-settings - name: build-image runAfter: ["build"] taskRef: { name: buildah, kind: Task } params: - name: IMAGE value: $(params.image):$(tasks.build.results.ARTIFACT_VERSION) - name: TLSVERIFY value: "true" workspaces: - name: source workspace: source - name: dockerconfig workspace: dockerconfig finally: - name: report taskRef: { name: slack-notify, kind: Task } params: - name: status value: $(tasks.status) 

finally replaces the Jenkins post { always { ... } } block, and $(tasks.status) gives you Succeeded, Failed or Completed.

Run and watch it with the CLI:

tkn pipeline start payments-api \ -p git-url=https://github.com/acme/payments-api.git \ -p git-revision=main \ -w name=source,volumeClaimTemplateFile=./wsp-source.yaml \ -w name=maven-cache,claimName=maven-cache \ -w name=maven-settings,config=maven-settings \ -w name=dockerconfig,secret=registry-push \ --serviceaccount pipeline-runner \ --use-param-defaults --showlog tkn pr list tkn pr logs -f --last tkn pr describe --last tkn taskrun logs payments-api-run-abc123-build -f 

tkn pr logs -f --last is the command you will type a thousand times; make an alias.

Step 4 — Trigger from Git with an EventListener

Triggers replace the Jenkins multibranch webhook. Three objects: a TriggerBinding (extract fields from the payload), a TriggerTemplate (render a PipelineRun), an EventListener (HTTP endpoint + interceptors).

apiVersion: triggers.tekton.dev/v1beta1 kind: TriggerBinding metadata: name: github-push namespace: payments-ci spec: params: - name: git-url value: $(body.repository.clone_url) - name: git-revision value: $(body.after) --- apiVersion: triggers.tekton.dev/v1beta1 kind: TriggerTemplate metadata: name: payments-api-template namespace: payments-ci spec: params: - name: git-url - name: git-revision resourcetemplates: - apiVersion: tekton.dev/v1 kind: PipelineRun metadata: generateName: payments-api- spec: taskRunTemplate: serviceAccountName: pipeline-runner pipelineRef: name: payments-api params: - name: git-url value: $(tt.params.git-url) - name: git-revision value: $(tt.params.git-revision) timeouts: pipeline: "1h0m0s" workspaces: - name: source volumeClaimTemplate: spec: accessModes: ["ReadWriteOnce"] resources: requests: storage: 2Gi - name: maven-cache persistentVolumeClaim: claimName: maven-cache - name: maven-settings configMap: name: maven-settings - name: dockerconfig secret: secretName: registry-push --- apiVersion: triggers.tekton.dev/v1beta1 kind: EventListener metadata: name: payments-el namespace: payments-ci spec: serviceAccountName: tekton-triggers-sa triggers: - name: github-push-main interceptors: - ref: name: github params: - name: secretRef value: secretName: github-webhook-secret secretKey: secretToken - name: eventTypes value: ["push"] - ref: name: cel params: - name: filter value: "body.ref == 'refs/heads/main'" bindings: - ref: github-push template: ref: payments-api-template 

Expose it with a TLS-terminated route (never plain HTTP for a webhook):

oc create secret generic github-webhook-secret \ --from-literal=secretToken="$(openssl rand -hex 20)" -n payments-ci oc create route edge payments-el --service=el-payments-el \ --port=8080 --insecure-policy=Redirect -n payments-ci oc get route payments-el -o jsonpath='{.spec.host}{"\n"}' tkn eventlistener logs payments-el -f 

Point the GitHub/GitLab webhook at https://<route-host> with the same secret. The github interceptor validates the HMAC signature; the CEL interceptor filters branches so you do not start a build for every tag push.

Security best practices

CI is the most privileged system in most organisations: it can read all source code and push to production registries. Treat it accordingly.

• One ServiceAccount per pipeline, not a shared one. Give pipeline-runner only the RBAC it needs (push to its own ImageStream, deploy to its own namespace). The Triggers SA needs create on pipelineruns and nothing else — bind the shipped tekton-triggers-eventlistener-roles ClusterRole, not edit.
• Avoid privileged builds. The Red Hat buildah Task runs rootless with the pipelines-scc SCC. Do not grant privileged to work around a storage driver error; set STORAGE_DRIVER=vfs or use fuse-overlayfs instead.
• Never pass secrets as params. Params end up in the PipelineRun spec, visible to anyone with get pipelineruns. Mount secrets as workspaces (secret: secretName: ...) or bind them to the ServiceAccount.
• Scope registry credentials. Prefer the internal registry with a ServiceAccount token over a long-lived dockerconfigjson for quay.io. If you need an external registry, use a robot account restricted to one repository.
• Validate webhook payloads. The github/gitlab interceptors verify the HMAC signature — always configure secretRef. An unauthenticated EventListener is remote code execution with extra steps.
• Pin Task references by digest (OCI bundles) or by Git tag with commit verification. A mutable :latest catalog Task is a supply-chain backdoor.
• Enable Tekton Chains for SLSA provenance and image signing; it is bundled with OpenShift Pipelines and signs TaskRun outputs automatically.
• Apply a NetworkPolicy on the CI namespace: allow egress to the registry, Git and artifact proxy; deny lateral traffic to application namespaces.
• Set timeouts and resource limits. A Pipeline without a timeout is a PVC leak and a node-pressure incident waiting to happen. Also configure the operator's pruner to delete old PipelineRun objects.

Conclusion

Migrating from Jenkins to Tekton is not a file conversion, it is a refactoring exercise. The mental shift is straightforward once you accept it: a Task is a function with typed inputs (params, workspaces) and typed outputs (results), and a Pipeline is the call graph.

Key takeaways:

• Start by extracting 5–6 Tasks, not 30. Build, test, image, deploy, notify. Everything else stays inline until a second consumer appears.
• Declare your state. The source workspace is ephemeral (volumeClaimTemplate), the dependency cache is persistent (RWX PVC or object storage keyed by lockfile hash). Getting this wrong is the main cause of "Tekton is slower than Jenkins" complaints.
• Version Tasks as artifacts, referenced by digest through the bundles or git resolver. That is what finally kills the copy-paste problem.
• Triggers replace the multibranch job: EventListener + interceptors give you signature validation and CEL filtering in a declarative, reviewable form.
• Live in tkn. tkn pr logs -f --last, tkn pr describe, tkn eventlistener logs will cover 90% of your debugging.

Run both systems in parallel for a few sprints: let Jenkins keep deploying while Tekton builds and publishes images. When the Tekton PipelineRun has been green for two weeks, flip the webhook and delete the Jenkinsfile. The diff will be the best part of the migration.