Skip to main content

​
Installing on Kubernetes

This guide covers installing Pipelines as Code on standard Kubernetes clusters, including Minikube, Kind, GKE, EKS, AKS, and other Kubernetes distributions.

​
Prerequisites

Before installing Pipelines as Code on Kubernetes, ensure you have:
  • Kubernetes cluster: Version 1.27 or higher
  • kubectl: Configured to access your cluster
  • Cluster admin access: Required for creating CRDs and cluster roles

​
Step 1: Install Tekton Pipelines

Pipelines as Code requires Tekton Pipelines version 0.50.0 or higher.
1

Check if Tekton Pipelines is installed

kubectl get deployment -n tekton-pipelines tekton-pipelines-controller
If this command returns a deployment, Tekton Pipelines is already installed. You can skip to Step 2.
2

Install Tekton Pipelines

If Tekton Pipelines is not installed, install the latest version:
kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml
3

Verify Tekton Pipelines installation

Wait for all Tekton components to be ready:
kubectl get pods -n tekton-pipelines
Expected output:
NAME                                           READY   STATUS    RESTARTS   AGE
tekton-pipelines-controller-xxxxxxxxxx-xxxxx   1/1     Running   0          2m
tekton-pipelines-webhook-xxxxxxxxxx-xxxxx      1/1     Running   0          2m
If you’re not installing the latest version, ensure you have Tekton Pipelines at version v0.50.0 or higher.

​
Step 2: Install Pipelines as Code

1

Apply the Pipelines as Code release manifest

Install the stable release:
kubectl apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/stable/release.k8s.yaml
This will create:
  • The pipelines-as-code namespace
  • Custom Resource Definitions (CRDs)
  • RBAC roles and bindings
  • Controller, webhook, and watcher deployments
  • Required ConfigMaps and Secrets
2

Verify the installation

Check that all Pipelines as Code components are running:
kubectl get deployment -n pipelines-as-code
Expected output:
NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
pipelines-as-code-controller   1/1     1            1           1m
pipelines-as-code-watcher      1/1     1            1           1m
pipelines-as-code-webhook      1/1     1            1           1m
All three deployments should show 1/1 in the READY column.
3

Check pod status

Verify all pods are running:
kubectl get pods -n pipelines-as-code
All pods should be in Running status.
For the latest development version, use the nightly release:
kubectl apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/nightly/release.k8s.yaml

​
Step 3: Configure Ingress

Pipelines as Code requires an externally accessible URL to receive webhooks from Git providers. You need to set up an Ingress to expose the controller service.

​
Option 1: Production Ingress Setup

The ingress configuration depends on your Kubernetes provider and ingress controller.

​
Google Kubernetes Engine (GKE)

Create an ingress using the GKE ingress controller: 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  labels:
    pipelines-as-code/route: controller
  name: pipelines-as-code
  namespace: pipelines-as-code
  annotations:
    kubernetes.io/ingress.class: gce
spec:
  defaultBackend:
    service:
      name: pipelines-as-code-controller
      port:
        number: 8080
Apply the ingress: 
kubectl apply -f ingress.yaml

​
Nginx Ingress Controller

If you’re using the Nginx ingress controller: 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  labels:
    pipelines-as-code/route: controller
  name: pipelines-as-code
  namespace: pipelines-as-code
spec:
  ingressClassName: nginx
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix
Replace pac.example.com with your actual hostname. Apply the ingress: 
kubectl apply -f ingress.yaml

​
Get the Ingress URL

After creating the ingress, get its external address: 
kubectl get ingress pipelines-as-code -n pipelines-as-code
You’ll use this URL when configuring your Git provider webhooks.
Either the ingress hostname or its IP address can be used as the webhook URL.

​
Option 2: Development/Testing with Webhook Forwarder

For local development with Minikube, Kind, or when you cannot set up an ingress, you can use a webhook forwarder service.
The webhook forwarder is useful for testing and development but is NOT recommended for production use. The gosmee platform at hook.pipelinesascode.com has no support or security guarantees.
1

Generate a webhook forwarder URL

Go to hook.pipelinesascode.com/new to generate a unique URL.Copy the generated Webhook Proxy URL (e.g., https://hook.pipelinesascode.com/oLHu7IjUV4wGm2tJ).
2

Deploy the gosmee forwarder

Create a deployment with your webhook URL:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gosmee-client
  namespace: pipelines-as-code
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gosmee-client
  template:
    metadata:
      labels:
        app: gosmee-client
    spec:
      containers:
      - name: gosmee-client
        image: ghcr.io/chmouel/gosmee:main
        args:
        - 'https://hook.pipelinesascode.com/YOUR_UNIQUE_ID'
        - $(SVC)
        env:
        - name: SVC
          value: http://pipelines-as-code-controller.pipelines-as-code.svc.cluster.local:8080
Replace YOUR_UNIQUE_ID with your actual webhook proxy URL.
3

Apply the deployment

kubectl apply -f gosmee-deployment.yaml
4

Use the webhook URL

Use your Webhook Proxy URL when configuring webhooks in GitHub, GitLab, or Bitbucket.

​
Option 3: Using tkn pac bootstrap

The tkn pac bootstrap command provides an interactive way to set up Pipelines as Code, including automatic webhook forwarder configuration: 
tkn pac bootstrap
The CLI will:
  • Detect if Pipelines as Code is installed
  • Offer to install it if not present
  • Optionally set up a gosmee webhook forwarder
  • Help you configure a GitHub Application

​
Step 4: Configure RBAC for Users

Non-admin users need explicit permission to create Repository CRDs in their namespaces.

​
Grant Repository CR Creation Rights

To allow a user to create Repository CRDs in a namespace: 
kubectl create rolebinding pac-repo-admin \
  --clusterrole=openshift-pipeline-as-code-clusterrole \
  --user=username \
  --namespace=my-namespace
Or apply this YAML: 
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: pac-repo-admin
  namespace: my-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: openshift-pipeline-as-code-clusterrole
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: username

​
Step 5: Optional Configurations

​
Configure TLS for the Controller

By default, the controller runs on HTTP. To enable HTTPS:
1

Create a TLS secret

kubectl create secret generic pipelines-as-code-tls-secret \
  -n pipelines-as-code \
  --from-file=cert=/path/to/tls.crt \
  --from-file=key=/path/to/tls.key
2

Restart the controller

kubectl rollout restart deployment/pipelines-as-code-controller -n pipelines-as-code
The controller will automatically detect and use the TLS secret.
If your secret uses different key names than cert and key, update the controller environment variables:
kubectl set env deployment/pipelines-as-code-controller \
  -n pipelines-as-code \
  TLS_KEY=your-key-name \
  TLS_CERT=your-cert-name

​
Integrate with Tekton Dashboard

If you have Tekton Dashboard installed, you can configure Pipelines as Code to link to it: 
kubectl patch configmap pipelines-as-code \
  -n pipelines-as-code \
  --type merge \
  -p '{"data":{"tekton-dashboard-url":"https://dashboard.example.com"}}'
Replace https://dashboard.example.com with your Tekton Dashboard URL.

​
Verification

Verify your installation is complete:
1

Check all components are running

kubectl get all -n pipelines-as-code
2

Verify CRDs are installed

kubectl get crd repositories.pipelinesascode.tekton.dev
3

Check the controller logs

kubectl logs -n pipelines-as-code -l app.kubernetes.io/component=controller
Look for any errors in the logs.

​
Next Steps

After successfully installing Pipelines as Code:
  1. Configure a Git Provider: Set up integration with GitHub, GitLab, or another Git provider
  2. Create a Repository CR: Connect your Git repository to Pipelines as Code
  3. Define Pipelines: Add .tekton/ directory with pipeline definitions to your repository
  4. Test the Setup: Create a pull request to trigger your first pipeline

​
Troubleshooting

​
Pods Not Starting

If pods are not starting, check the pod events: 
kubectl describe pod -n pipelines-as-code -l app.kubernetes.io/part-of=pipelines-as-code

​
Ingress Not Working

Check ingress status and events: 
kubectl describe ingress pipelines-as-code -n pipelines-as-code

​
Controller Not Receiving Webhooks

Verify the controller service is accessible: 
kubectl get svc pipelines-as-code-controller -n pipelines-as-code
Test internal connectivity: 
kubectl run test-curl --image=curlimages/curl -it --rm -- \
  curl http://pipelines-as-code-controller.pipelines-as-code.svc.cluster.local:8080

​
Upgrading

To upgrade to a newer version: 
kubectl apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/stable/release.k8s.yaml
The installation manifest will update all components to the latest stable version.

​
Uninstalling

To uninstall Pipelines as Code: 
kubectl delete -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/stable/release.k8s.yaml
This will delete all Repository CRs and associated resources. Make sure to back up any important configurations before uninstalling.

Build docs developers (and LLMs) love

Get started for freeTalk to us