Backstage Tekton pipelines plugin: what it shows and how it connects
Engineers usually want one thing from a Tekton view in Backstage: the status of the latest PipelineRun for their service, on the entity page they already use, without opening cluster tools. The Red Hat Tekton plugin reads PipelineRuns from Kubernetes clusters and displays them against a catalog component. It does not hold its own cluster connection. It depends on the Kubernetes plugin's cluster configuration for the API server address, authentication and the access each cluster grants, so the Kubernetes plugin has to be set up and working before the Tekton view shows anything useful.
The supported method is the Tekton plugin running alongside the Kubernetes plugin, both reading the same cluster configuration. Teams should not build a custom API that queries Tekton on the portal's behalf, because that path bypasses the access model the Kubernetes plugin already enforces and becomes another component to maintain on each Backstage upgrade. Before you install anything, confirm the exact plugin package names, the annotation keys that link a component to its pipelines, and the configuration keys for your Backstage release against the plugin's own documentation, since these change between releases and must match the Backstage version you run. Also confirm which Kubernetes namespaces and resource types the cluster service account can list, because that scope determines what engineers can see.
Plan the link between components and pipelines before the plugin is configured. Each component needs a stable identifier that the pipelines carry as a label or annotation, and the catalog descriptor should agree with the namespace and labels used by your pipeline definitions. Decide which clusters a team can see, whether one cluster serves several environments, and how credentials for each cluster are issued and rotated. Test the view with one pilot component in a non-production cluster, then check that a user with no cluster access sees only what your access model allows. Your team will run this, so record the configuration owner and the steps to reissue cluster credentials.
What must be in place before the Tekton plugin is installed
The Tekton plugin reads PipelineRuns through the Kubernetes plugin, so most setup work happens before Tekton appears on an entity page. Each item below is a prerequisite that has to be working in the Backstage instance and in the clusters that hold the pipelines.
Self-hosted Backstage on a supported release
Run a self-hosted Backstage instance on a release line the project still supports. The versioning policy describes a monthly main line and a weekly next line, and the latest release at the time of writing was v1.55.3. Confirm which line your instance is on before you add a plugin, because plugin packages are built against specific @backstage versions and mismatches surface as build or runtime errors.
Kubernetes plugin working for each cluster
The Tekton plugin does not hold its own cluster list. It depends on the Kubernetes plugin, which reads the kubernetes section of the app config to find each cluster, its API server URL and its authentication method. Before installing anything, confirm that the Kubernetes plugin already displays workloads for the target clusters on a test entity. If it does not, fix that first, because the Tekton view will fail in the same way.
Tekton installed in target clusters
Install Tekton Pipelines in every cluster where your teams run pipelines, and confirm that PipelineRuns exist on a sample component. The plugin only displays resources that the cluster serves, so an empty view can mean Tekton is missing, is in a different namespace than the one you labeled, or has not run for that component yet. Confirm the Tekton release and the plugin version pairing in the vendor documentation before you choose either.
Read-only identity for PipelineRuns
Create a dedicated service account in each cluster and bind it to a role that allows get, list and watch on PipelineRuns and the pods they create. Do not reuse an administrator token or a personal kubeconfig. Restrict the role to the namespaces that hold your pipelines, and record who owns the token so rotation is planned rather than improvised when it expires.
Network paths to each API server
The Backstage backend, not the browser, calls each Kubernetes API server. Confirm that the host running the backend can reach each API server URL on the port it listens on, through any proxy, firewall or private network path your clusters require. Test the route from the backend host itself, since a path that works from a laptop may not work from the production pod or virtual machine.
Certificate authority material for each cluster
Each connection needs the cluster's certificate authority data so the backend can verify the API server's certificate. Store that material in your configuration or secret store and keep it out of the frontend bundle. Ask the team that runs each cluster which CA chain it uses, because internal certificate authorities often differ between environments, and a missing intermediate certificate produces errors that look like authentication failures.
How to configure the Tekton plugin in order
This sequence connects a Backstage component to its Tekton PipelineRuns in the right order, so each layer is confirmed before the next one depends on it. The Tekton view only works once the Kubernetes plugin already reads the target cluster, so the checks below run from the bottom of the stack upward.
Confirm the Kubernetes plugin reads the cluster
The platform team confirms that the Backstage Kubernetes plugin is installed, that the target cluster is defined in its cluster configuration, and that the backend has the credentials it needs to authenticate to the cluster API. Open the Kubernetes view for a test component and check that the cluster appears and that its Deployments or Pods are listed. Do not continue until that view returns live workloads, because the Tekton plugin reads cluster data through the same configuration and will fail in the same way if it does not.
Create a read-only Tekton role
A cluster administrator creates a Role or ClusterRole that allows only get, list and watch on the Tekton resources the plugin displays, such as PipelineRuns and TaskRuns, and binds it to the identity Backstage uses. Scope the binding to the namespaces where your pipelines run rather than granting cluster-wide access unless your layout requires it. Check the result by authenticating as that identity and listing PipelineRuns in one allowed namespace, then confirming that a write request is refused. Ask the vendor documentation which Tekton resource names the plugin needs before you finalize the rule.
Install the Tekton frontend and backend packages
A Backstage developer adds the frontend and backend packages that the Red Hat Tekton plugin documentation names, using the install locations that documentation gives for the Backstage version you run. Register the backend module in the backend entry point and mount the frontend component where the entity page needs it. Confirm the names and locations against the plugin's own repository before you copy any command, because package names change between releases. Build the app and confirm that the backend starts without plugin load errors in its startup log.
Point the plugin at the cluster configuration
The developer sets the Tekton plugin's configuration so it reuses the cluster entry from the Kubernetes plugin and does not hold a second copy of cluster credentials. Confirm in the plugin documentation whether the plugin reads the Kubernetes cluster block directly or needs its own reference. Restart the backend and watch the log for a line showing the Tekton lookup succeeded for the configured cluster. If the log reports an authorization or not-found error, return to the role binding in the previous step before changing anything else.
Annotate the catalog component
The service owner adds the entity annotation that the plugin documentation specifies, which links the component's catalog descriptor to its PipelineRuns. The value should match the label or selector your pipelines already apply, so that PipelineRuns created for that application are matched and no others. Ask the platform team to confirm the exact annotation key and value format with the plugin maintainers. Commit the change, let the catalog refresh the entity, and check that the annotation is visible on the entity's overview page.
Verify PipelineRuns on the entity page
Open the entity page for the annotated component and open the CI/CD or Tekton tab added by the plugin. Trigger or find a recent PipelineRun for that application and confirm its name, status, start time and link to the cluster appear. Also check a component with no annotation and confirm it shows no runs rather than another team's runs. Record the backend log line and the entity page screenshot in your configuration notes, so the next upgrade or cluster change has a known-good baseline to test against.
Why the Kubernetes plugin configuration controls what Tekton shows
In most setups, the Tekton plugin does not keep its own list of clusters. It reads cluster definitions from the Kubernetes plugin's configuration in app-config.yaml, so a cluster that is missing or misconfigured in the Kubernetes plugin will also be missing from the Tekton tab. Before you configure Tekton, confirm that the Kubernetes plugin shows the target cluster's workloads for a test entity. If that view is empty, the Tekton view will be empty too, and the cause is usually the shared configuration rather than the Tekton plugin itself. Confirm the exact configuration keys and the locator method for your Backstage version in the plugin's README and the Kubernetes plugin documentation.
The same cluster entry serves both plugins, so one change affects both. The cluster name in that entry is the identifier that links a catalog entity's annotations to a cluster, and it must match exactly across the Kubernetes and Tekton plugin setups. A mismatch in spelling or case typically produces an empty Tekton panel without an obvious error, which makes it easy to misdiagnose. Authentication settings work the same way. If the Kubernetes plugin uses a service account token for the cluster, the Tekton views depend on that identity too, so changing it for workload views can silently change PipelineRun visibility. Document the cluster names and their owners in one place so both plugins are changed together.
Adding clusters or environments increases the number of places where a mistake can hide data. Each new cluster needs its own entry in the shared configuration, and the service account behind it needs read access to the Tekton resources it will display, such as PipelineRuns and TaskRuns, in the namespaces that hold your pipelines. Decide early whether development, staging and production are separate entries or share a cluster with namespace separation, because that choice determines which permissions and name mappings you maintain. For each environment, test with one component that has a known PipelineRun, and confirm that the plugin shows runs in the expected namespace before you roll the change out to all entities.
How component labels and namespaces map to PipelineRuns
This table traces how a Backstage catalog entity finds its PipelineRuns, from the annotation on the entity through the cluster name, namespace and label selector. Read each row as a link in the chain, and check the exact annotation key and selector behavior in the plugin documentation before you write any mapping, because a mismatch at any link leaves the entity page empty.
| Link in the chain | What it must match | Tekton object it selects | Failure when it is wrong |
|---|---|---|---|
| Entity annotation | The plugin's documented annotation key on the Component, set to the value your team agreed (confirm key name in plugin docs) | Selects the entity whose page shows PipelineRuns | Entity page shows no PipelineRuns or shows runs from another component |
| Cluster name | The cluster name defined in the Kubernetes plugin cluster configuration that the Red Hat plugin reads | Chooses which cluster API is queried for PipelineRuns | Runs are missing because the query targets a cluster that does not hold them, or the cluster is not found |
| Namespace | The namespace where your pipelines run, consistent with the Kubernetes plugin namespace settings | Limits the PipelineRun list to one namespace in that cluster | Runs from other teams appear, or valid runs stay hidden |
| Component label on PipelineRuns | The label key and value your Tekton triggers or pipeline templates set, matching the plugin's documented selector | Filters PipelineRuns to those belonging to the component | Empty lists, or runs from sibling components are attributed to the wrong entity |
| Service account and RBAC | Read access to PipelineRuns and related resources in the target namespace for the credential the Kubernetes plugin uses | Authorizes the list and watch calls for PipelineRuns | Forbidden errors in backend logs and no runs shown |
| Label value casing and format | Exact string match against the label value set by pipelines, following Kubernetes label syntax | Determines whether the selector matches at all | Silent empty results after a rename of the entity or the label value |
Securing cluster access for Tekton data in Backstage
The Tekton plugin reads PipelineRuns and related objects from clusters using credentials that Backstage holds on the server side. Each card below is a control that limits what that access can reveal, from the cluster identity to the Backstage sign-in that decides who sees an entity page.
Give the plugin a read-only identity
Create a dedicated service account in each cluster and bind it to a Role that allows get, list and watch on PipelineRuns, TaskRuns and the Pod and log objects the plugin displays, only in the namespaces where your pipelines run. Avoid cluster-wide bindings and never reuse an administrator token. Ask the plugin's documentation which resources it reads so the Role matches its actual calls, and confirm the list in a test cluster before rollout.
Keep cluster credentials on the backend
Cluster URLs and service account tokens belong in the backend configuration, loaded from environment variables or a secret manager at startup, and never in app-config values exposed to the browser. Check that the frontend bundle and network responses contain no bearer tokens. Kubernetes accepts several authentication methods, including client certificates, bearer tokens and OpenID Connect, so pick the one your clusters already run and document the rotation owner.
Restrict who sees entity pages
Pipeline data appears on entity pages, so anyone who can open a component can read its run history unless Backstage authorization says otherwise. Turn off guest access in production, map every sign-in provider to the same catalog identity, and decide whether pipeline views follow the entity's owning group or a broader audience. Test with a user outside the owning team before you publish the page.
Treat Kubernetes Secrets as in scope
The plugin does not need Secret objects, so its identity should have no read access to them. Review the cluster's Secrets controls anyway, because Kubernetes stores Secrets unencrypted in etcd by default. Confirm that encryption at rest is enabled, that RBAC limits list and watch on Secrets, and that any external store is used through a supported driver. A leaked Backstage token would otherwise reach these values.
Scope results and logs
PipelineRun parameters, task results and step logs can contain tokens, hostnames or customer identifiers that a developer passed in by mistake. Decide which parameters and log lines the view may show, ask the plugin maintainers whether it can filter or hide fields, and set retention on your pipeline logs. Where a value must stay private, redact it in the pipeline itself rather than relying on the portal to hide it.
Review permissions and maintenance first
Third-party plugins run inside the Backstage backend with the access you grant them, so check who maintains the Red Hat plugin, when it last released, and which permissions and credentials its documentation requires. Compare the release against your Backstage version and Node.js release. Record the review in your change log and repeat it at each Backstage upgrade, because a plugin that falls behind can block the upgrade path.
Why PipelineRuns do not appear on the entity page
This table pairs common symptoms with their likely causes and fixes when Tekton PipelineRuns fail to show on a component's entity page. Read it from the symptom column, then confirm the exact error text in your Backstage backend logs against the plugin's documentation before changing configuration. Most gaps trace back to the entity annotation, the cluster configuration shared with the Kubernetes plugin, or the identity and access path used by each viewer.
| Symptom | Likely cause | Fix |
|---|---|---|
| Tekton tab is empty with no visible error | The entity annotation or label does not match the labels on the PipelineRuns, so no runs are selected | Compare the entity's annotation with labels on the PipelineRun objects using kubectl, then correct either side so they match exactly |
| Cluster is missing from the Kubernetes view | The cluster is absent or misnamed in the Kubernetes plugin configuration that the Tekton view relies on | Check the cluster name and entry in the Kubernetes plugin config, restart the backend, and confirm the cluster appears there first |
| Forbidden or unauthorized errors from the API server | The service account lacks read access to PipelineRuns, or its role binding does not cover the component's namespace | Grant get and list on PipelineRuns in the target namespaces through a role binding, then test with kubectl auth can-i as that account |
| Connection, TLS or certificate errors in backend logs | The Backstage backend cannot reach the API server address, or it does not trust the cluster certificate authority | Verify network routes and firewall rules from the backend host, and confirm the configured CA data matches the cluster |
| Runs visible to some users but not others | Sign-in resolvers map identities inconsistently, or entity access rules hide the component from certain users | Review the sign-in resolver and catalog ownership for affected users, and confirm their group membership matches the entity's owner |
| Tekton data missing after a Backstage upgrade | Plugin packages moved to new versions without matching changes to the Kubernetes plugin wiring or the frontend extension | Align every @backstage and plugin package version, review the upgrade notes for plugin changes, and rebuild the frontend before retesting |
Questions teams ask before setting up the Tekton plugin
Does the Tekton plugin need its own cluster connection or does it reuse the Kubernetes plugin?
The Tekton plugin reads PipelineRuns through the Kubernetes plugin's cluster configuration, so you define each cluster once in the Kubernetes plugin settings and the Tekton view reuses those connections. You do not normally configure a second set of cluster credentials for Tekton. Confirm the exact configuration keys against the version of the Red Hat plugin you install, because the plugin documentation is the authority on how it resolves clusters and service account access. Plan the cluster connection as a shared piece of configuration that the Kubernetes plugin owns, since a change there affects every plugin that reads from those clusters.
What drives the effort of a Tekton plugin setup?
The main drivers are the number of clusters that run pipelines, how namespaces are laid out, the label and annotation conventions that link PipelineRuns to catalog components, the access model for the service account Backstage uses to read them, and how often you upgrade Backstage and the plugin. Each cluster adds connection and access work, and a single cluster with a clear namespace per team is much simpler than many clusters with shared namespaces. Label conventions decide whether matching is automatic or requires manual annotation on every component. No duration is given here, so ask any partner for a fixed-scope estimate tied to these drivers in writing.
Can our own team set up the Tekton plugin without outside help?
Yes, a team with Kubernetes and Backstage experience can usually do it in-house, provided it can make changes to cluster RBAC, the Kubernetes plugin configuration and the catalog. The hard parts are less about the plugin itself and more about agreeing on labels, deciding which service account reads which namespace, and keeping annotations accurate as components are added. Teams without a Tekton owner or a Kubernetes administrator often find those decisions stall. A partner can help with a written scope covering design, build, verification and handover, and you can compare that against the time your own engineers would spend on the same decisions.
What does the work require from our team?
You need cluster administrators who can create the read-only service account, role bindings and kubeconfig or token material that Backstage uses, a Tekton owner who knows which pipelines exist and how they are named, and catalog owners who maintain the annotations on each component so PipelineRuns link to the right entity. Someone also needs to own the Kubernetes plugin configuration, because the Tekton view depends on it. Without named owners for these three roles, the plugin tends to show empty or wrong data after go-live, so assign them before the build starts.
Is the Tekton plugin a license cost?
The Backstage project is open source under the Apache License 2.0 and has no paid edition from the project itself, so the framework does not carry a license fee. The Tekton plugin is a separate package, and its terms depend on who publishes it. Before installing, read the license and repository of the specific plugin version you intend to use and confirm there are no commercial terms attached to a vendor-supplied package. Your real recurring costs are infrastructure to run Backstage and the clusters it reads, plus the people who maintain configuration and upgrades.
How do Backstage and Kubernetes upgrades affect the Tekton plugin?
Backstage releases come from a monthly main line and a weekly next line, and upgrades should move all @backstage packages together using the project's version bump command, with the Backstage Upgrade Helper showing template changes. The Tekton plugin must match the Backstage version it supports, so check its compatibility before bumping. Kubernetes also changes: the project maintains the three most recent minor releases, and the version skew policy limits how far kubelets can lag behind the API server. Test PipelineRun reads against each cluster version you run, because changes in the Tekton or Kubernetes APIs can break the view even when Backstage itself upgrades cleanly.
Which access should the Backstage service account have in each cluster?
Grant read-only access to PipelineRuns, pods and related resources only in the namespaces that hold each team's pipelines, using a namespace-scoped role rather than cluster-wide read access where your layout allows it. Avoid giving the account secret read permissions, since Kubernetes stores Secrets unencrypted in etcd by default and a broad read role exposes them to the portal. Restrict list and watch permissions to what the view needs and review the binding whenever namespaces are added or renamed. Confirm the exact verbs the installed plugin requires before you narrow the role.
How DeployOpen scopes and delivers Backstage Tekton integrations
DeployOpen plans the Tekton pipelines integration as part of your Backstage portal, starting from the clusters, namespaces and entity annotations your teams already use. The work is delivered in your own infrastructure, with the Kubernetes plugin configuration, access model and handover documented so your team can operate it.
How we scope
- The written scope lists which clusters, namespaces and Tekton components the portal will display.
- Scope defines how each catalog component is linked to its PipelineRuns through annotations.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
How we build
- We configure the Kubernetes plugin cluster settings first, then add the Tekton view on top.
- Read-only service account permissions are defined per cluster and limited to the required resources.
- Each cluster connection is tested with sample components before the view is released to teams.
How we hand over
- You receive configuration, annotation conventions and a runbook for adding new components.
- Documentation covers how the Kubernetes plugin and Tekton plugin depend on each other.
- Your team walks through the setup and recovery steps so changes can be made without us.
How we support
- Ongoing support, Backstage upgrades and plugin compatibility checks are available as a retainer.
- Upgrade planning reviews plugin version changes alongside the Backstage release you run.
- Support scope, response expectations and fees are set in the written agreement, not assumed.
