Tekton Service Accounts and RBAC: Grant Pipeline Permissions (2026)

Tekton pipelines often fail because the PipelineRun can’t find the service account it’s supposed to use.

The PipelineRun needs a ServiceAccount to execute its tasks. This ServiceAccount needs specific RoleBindings to grant it permissions within the Kubernetes cluster, allowing it to create, read, and manage resources like Pods, Tasks, and Pipelines. Without these permissions, the PipelineRun will stall, often with an error indicating that the service account or its associated roles are not found or are insufficient.

Here’s a breakdown of common causes and how to fix them:

The Service Account Doesn’t Exist:
- Diagnosis: Check if the ServiceAccount specified in your PipelineRun actually exists in the namespace where the PipelineRun is being created.
```
kubectl get serviceaccount <service-account-name> -n <namespace>
```
- Fix: If it doesn’t exist, create it.
```
apiVersion: v1
kind: ServiceAccount
metadata:
  name: <service-account-name>
  namespace: <namespace>
```
  Apply this with kubectl apply -f <your-service-account-file.yaml>.
- Why it works: This ensures the fundamental identity that the PipelineRun will attempt to use is present in the cluster.
The Service Account is in the Wrong Namespace:
- Diagnosis: PipelineRuns can only use ServiceAccounts that exist in the same namespace as the PipelineRun itself. Verify the ServiceAccount’s namespace.
```
kubectl get serviceaccount <service-account-name> -n <namespace>
```
  And check your PipelineRun definition for the correct namespace.
- Fix: Either move the PipelineRun to the namespace where the ServiceAccount exists, or create a new ServiceAccount with the same name in the PipelineRun’s namespace.
```
# Example: Creating a new SA in the PipelineRun's namespace
kubectl create serviceaccount <service-account-name> -n <pipeline-run-namespace>
```
- Why it works: Kubernetes RBAC is namespace-scoped. A ServiceAccount in namespace-a cannot be directly used by a PipelineRun in namespace-b unless explicitly granted cross-namespace access (which is complex and usually not the intended pattern here).
Missing ClusterRoleBinding for Tekton Controller:
- Diagnosis: The Tekton controller (usually a tekton-pipelines-controller deployment) needs permissions to manage Tekton resources. If this controller can’t see or manage Pipelines, Tasks, etc., your runs won’t start.
```
kubectl get clusterrolebinding | grep tekton
```
  Look for a ClusterRoleBinding that grants the tekton-pipelines-controller ServiceAccount (in the tekton-pipelines namespace by default) the cluster-admin role or a specific Tekton-related ClusterRole.
- Fix: Ensure the tekton-pipelines-controller has the necessary ClusterRole or ClusterRoleBinding. If you installed Tekton using the operator or YAML, this should be present. If not, you might need to reapply the installation manifests or manually create a binding.
```
# Example of a common binding for the controller
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tekton-pipelines-aggregate-edit
subjects:
- kind: ServiceAccount
  name: tekton-pipelines-controller
  namespace: tekton-pipelines # Adjust if your Tekton is in a different namespace
roleRef:
  kind: ClusterRole
  name: tekton-pipelines-aggregate-edit # Or cluster-admin
  apiGroup: rbac.authorization.k8s.io
```
  Apply with kubectl apply -f <your-tekton-controller-binding.yaml>.
- Why it works: This grants the Tekton controller itself the cluster-wide permissions it needs to create and manage Pods and other resources on behalf of your PipelineRuns.

PipelineRun Service Account Lacks Permissions to Create Pods:

Diagnosis: The ServiceAccount used by the PipelineRun needs permission to create Pods in the namespace where the PipelineRun is executing.

# First, find the SA used by your PipelineRun
kubectl get pipelinerun <your-pipelinerun-name> -n <namespace> -o yaml
# Look for spec.serviceAccountName

# Then, check its RoleBindings in that namespace
kubectl get rolebinding -n <namespace> | grep <service-account-name>
# And check the Role it's bound to
kubectl get role <role-name-from-binding> -n <namespace> -o yaml

You’re looking for a Role that includes pods in resources and create, get, list, watch, update, patch, delete in verbs.

Fix: Create or modify a Role and RoleBinding to grant the necessary permissions.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: tekton-pod-creator
  namespace: <namespace>
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"] # pods/log is often needed for fetching logs
  verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: tekton-pod-creator-binding
  namespace: <namespace>
subjects:
- kind: ServiceAccount
  name: <service-account-name> # The SA from your PipelineRun
  namespace: <namespace>
roleRef:
  kind: Role
  name: tekton-pod-creator
  apiGroup: rbac.authorization.k8s.io

Apply with kubectl apply -f <your-tekton-permissions.yaml>.

Why it works: Each Task in a PipelineRun executes as a Pod. The ServiceAccount associated with the PipelineRun acts as the identity for creating these Task pods. Without create permission on pods, the PipelineRun cannot launch its tasks.

PipelineRun Service Account Lacks Permissions to Manage Tekton Resources:
- Diagnosis: The ServiceAccount might also need permissions to get, list, watch, update, patch, or delete Tekton-specific resources like Tasks, Pipelines, TaskRuns, and PipelineRuns themselves, especially if the PipelineRun is trying to self-update its status or if custom controllers are involved.
```
# Check the same Role/RoleBinding as above, but for Tekton resources
kubectl get rolebinding -n <namespace> | grep <service-account-name>
# Look for roles granting access to tekton.dev
kubectl get role <role-name-from-binding> -n <namespace> -o yaml
```
  You’re looking for rules covering tasks, pipelines, taskruns, pipelineruns with verbs like get, list, watch, update, patch, delete.
- Fix: Add these permissions to the Role or create a new Role and RoleBinding.
```
# Add to the existing Role or create a new one
- apiGroups: ["tekton.dev"]
  resources: ["tasks", "pipelines", "taskruns", "pipelineruns", "runs"]
  verbs: ["get", "list", "watch", "update", "patch", "delete"]
```
  Apply the updated YAML.
- Why it works: This allows the PipelineRun to interact with the Tekton control plane to report its status, fetch definitions, and manage its lifecycle.
Default Service Account Permissions (Less Common but Possible):
- Diagnosis: If your PipelineRun doesn’t explicitly specify a serviceAccountName, it defaults to default in the namespace. Check the RBAC for the default ServiceAccount.
```
kubectl get serviceaccount default -n <namespace>
kubectl get rolebinding -n <namespace> | grep default
```
- Fix: Grant the necessary permissions to the default ServiceAccount as described in points 4 and 5, or explicitly specify a dedicated ServiceAccount in your PipelineRun with its own granular permissions.
```
# In your PipelineRun
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: my-pipeline-run
  namespace: <namespace>
spec:
  pipelineRef:
    name: my-pipeline
  serviceAccountName: <dedicated-service-account-name> # <-- specify here
```
- Why it works: Explicitly defining permissions for a dedicated service account is more secure and manageable than relying on the broad permissions often (and sometimes insecurely) assigned to the default service account.

After fixing these, the next error you’ll likely encounter is a TaskRun failing because the ServiceAccount specified for the TaskRun itself (or inherited from the PipelineRun) doesn’t have permissions to pull container images or access other external resources.

More Deep Dives in Tekton