Manage PAC Component

For Administrators Only

This guide is for cluster administrators only. It covers PAC component deployment, configuration, and maintenance tasks that require cluster administrator permissions.

Regular users should refer to:

Guides - Set up Git provider integration

This guide explains how to deploy, update, and uninstall the Pipelines-as-Code (PAC) component on Kubernetes platforms.

Prerequisites

Before managing PAC, ensure you have:

Kubernetes cluster (version 1.24 or higher)
Tekton Operator installed and running
Cluster administrator permissions
kubectl installed and configured to access your cluster

Deploy PAC Component

Create the OpenShiftPipelinesAsCode CR to deploy PAC. The examples use the default PAC namespace tekton-pipelines; replace it in the commands and manifests if you set a different targetNamespace.

Create a YAML file named pac.yaml:

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  settings:
    application-name: Pipelines as Code CI
    remote-tasks: "true"
    secret-auto-create: "true"
  targetNamespace: tekton-pipelines  # Default namespace, you can customize this

hub-url is intentionally omitted: the operator already ships a working value in the pipelines-as-code ConfigMap. Set it only to point at a different Hub — see Standard Settings.

Apply the CR to your cluster:

kubectl apply -f pac.yaml

Check the OpenShiftPipelinesAsCode CR status:

kubectl get openshiftpipelinesascodes.operator.tekton.dev

The output should show READY=True; VERSION varies by release and REASON is usually empty.

NAME                  VERSION     READY   REASON
pipelines-as-code    <version>   True

Verify the PAC pods are running:

kubectl get pods -n tekton-pipelines | grep pipelines-as-code

Example output (the controller, watcher, and webhook pods must be Running):

NAME                                      READY   STATUS    RESTARTS   AGE
pipelines-as-code-controller-xxxxx        1/1     Running   0          5m
pipelines-as-code-watcher-xxxxx           1/1     Running   0          5m
pipelines-as-code-webhook-xxxxx           1/1     Running   0          5m

Configure Access

Important

The PAC controller must be reachable from the Git providers that will send webhook events to it. Expose it through one of the methods below before configuring any repository.

Using Gateway API

Use this method to expose the PAC controller with a domain name through ACP Gateway API.

Git provider -> PAC domain -> Envoy Gateway Service -> Gateway/HTTPRoute -> pipelines-as-code-controller

This example uses:

Default PAC namespace: tekton-pipelines
GatewayClass: envoy-gateway-operator-cpaas-default
Domain: pac.example.com

Step 1: Prepare Envoy Gateway. Install Alauda build of Envoy Gateway and ensure the default GatewayClass is accepted. Reference: Envoy Gateway Operator.

kubectl get gatewayclass envoy-gateway-operator-cpaas-default

NAME                                   ACCEPTED
envoy-gateway-operator-cpaas-default   True

Step 2: Prepare LoadBalancer addresses. The Envoy Gateway Service will be created as type: LoadBalancer, so LoadBalancer Services must be able to get an external IP. On ACP bare-metal clusters, install and configure Alauda Container Platform Load Balancer for MetalLB. Reference: Configure MetalLB.

kubectl get ipaddresspool,l2advertisement -A

Expected result:

NAMESPACE        NAME                                    ADDRESSES
metallb-system   ipaddresspool.metallb.io/default-pool   ["192.168.1.100-192.168.1.110"]

Step 3: Create Gateway API resources. Create gateway-api.yaml. Replace tekton-pipelines, envoy-gateway-operator-cpaas-default, and pac.example.com as needed. References: Configure GatewayAPI Gateway and Configure GatewayAPI Route.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: pipelines-as-code
  gatewayClassName: envoy-gateway-operator-cpaas-default
  listeners:
    - name: http
      port: 80
      hostname: pac.example.com
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  provider:
    kubernetes:
      envoyService:
        type: LoadBalancer
      envoyDeployment:
        replicas: 1
        container:
          imageRepository: registry.alauda.cn:60080/acp/envoyproxy/envoy
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: 100m
              memory: 256Mi
    type: Kubernetes
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  hostnames:
    - pac.example.com
  parentRefs:
    - name: pipelines-as-code
      sectionName: http
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: pipelines-as-code-controller
          port: 8080

Apply the file:

kubectl apply -f gateway-api.yaml

Expected result:

gateway.gateway.networking.k8s.io/pipelines-as-code created
envoyproxy.gateway.envoyproxy.io/pipelines-as-code created
httproute.gateway.networking.k8s.io/pipelines-as-code created

Step 4: Get the external address. Check the generated Envoy Service:

kubectl get svc -A \
  -l gateway.envoyproxy.io/owning-gateway-name=pipelines-as-code,gateway.envoyproxy.io/owning-gateway-namespace=tekton-pipelines

Expected result:

NAMESPACE                  NAME                                                 TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)
envoy-gateway-operator    envoy-tekton-pipelines-pipelines-as-code-3f8c88ad    LoadBalancer   10.96.10.20     192.168.1.100   80:32176/TCP

Step 5: Verify and get the webhook URL. Make sure the Git provider can resolve and access the PAC domain. A common way is to create a DNS A record. For example, if the Service EXTERNAL-IP is 192.168.1.100, create:

Type: A
Name: pac.example.com
Value: 192.168.1.100

If DNS is not ready yet, or you only want to test the route from your current machine, use curl --resolve:

EXTERNAL_IP=$(kubectl get svc -A \
  -l gateway.envoyproxy.io/owning-gateway-name=pipelines-as-code,gateway.envoyproxy.io/owning-gateway-namespace=tekton-pipelines \
  -o jsonpath='{.items[0].status.loadBalancer.ingress[0].ip}')

kubectl get gateway pipelines-as-code -n tekton-pipelines
kubectl get httproute pipelines-as-code -n tekton-pipelines -o yaml
curl -i --resolve "pac.example.com:80:${EXTERNAL_IP}" http://pac.example.com/

Expected result:

The Service has an EXTERNAL-IP.
The Gateway shows PROGRAMMED=True.
The HTTPRoute is accepted.
curl returns the PAC controller response.

After the domain is reachable from the Git provider network, print the URL:

WEBHOOK_URL=http://pac.example.com

WEBHOOK_URL is the PAC webhook URL. Register this value in the Git provider or enter it when tkn pac create repo prompts for a webhook URL.

If you expose PAC through ACP ALB or another Ingress Controller instead, use Using Ingress.

Notes:

HTTPRoute forwards to the existing pipelines-as-code-controller Service on port 8080; do not point it at the admission webhook Service named pipelines-as-code-webhook.
If the generated Envoy Service remains EXTERNAL-IP=<pending>, check the cluster LoadBalancer provider. For MetalLB, see Configure MetalLB.
For Gateway API options such as a reserved VIP, hostless routes, or HTTPS listeners, see Configure GatewayAPI Gateway and Configure GatewayAPI Route.

Using Ingress

Use this method when the cluster already has an Ingress Controller and you want to expose the PAC controller with an Ingress domain.

This example uses:

Default PAC namespace: tekton-pipelines
Domain: pac.example.com

Step 1: Prepare an Ingress Controller. Ensure an Ingress Controller is installed and ready. Reference: Configure Ingress.

Step 2: Create the Ingress resource. Create ingress.yaml. Replace tekton-pipelines and pac.example.com as needed.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix

Apply the file:

kubectl apply -f ingress.yaml

Expected result:

ingress.networking.k8s.io/pipelines-as-code created

Step 3: Verify the Ingress address. Check that the Ingress has an address:

kubectl get ingress pipelines-as-code -n tekton-pipelines

Expected result:

NAME                CLASS   HOSTS             ADDRESS         PORTS
pipelines-as-code   nginx   pac.example.com   192.168.1.100   80

Step 4: Get the webhook URL. Make sure the Git provider can resolve and access pac.example.com through the Ingress address. Then print the URL:

HOST=$(kubectl get ingress pipelines-as-code -n tekton-pipelines \
  -o jsonpath='{.spec.rules[0].host}')

echo "WEBHOOK_URL=http://${HOST}"

WEBHOOK_URL is the PAC webhook URL. Register this value in the Git provider or enter it when tkn pac create repo prompts for a webhook URL.

If you do not have a DNS name, remove the host field and use the reachable Ingress IP URL instead.

Optional: Enable HTTPS. Create a TLS Secret in tekton-pipelines and add a tls section to the same Ingress. The certificate must match pac.example.com.

kubectl create secret tls pipelines-as-code-tls \
  -n tekton-pipelines \
  --cert=tls.crt \
  --key=tls.key

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pipelines-as-code
  namespace: tekton-pipelines
spec:
  rules:
  - host: pac.example.com
    http:
      paths:
      - backend:
          service:
            name: pipelines-as-code-controller
            port:
              number: 8080
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - pac.example.com
    secretName: pipelines-as-code-tls

When TLS is configured, use the HTTPS webhook URL:

echo "WEBHOOK_URL=https://${HOST}"

Using NodePort

Create a NodePort Service:

apiVersion: v1
kind: Service
metadata:
  name: pipelines-as-code-controller-nodeport
  namespace: tekton-pipelines
spec:
  ports:
    - name: http-listener
      port: 8080
      protocol: TCP
      targetPort: 8082  # PAC controller listens on port 8082
      nodePort: 30080  # Optional: specify a fixed NodePort
  selector:
    app.kubernetes.io/part-of: pipelines-as-code
    app.kubernetes.io/component: controller
  type: NodePort

Important:

The targetPort must be 8082, which is the port the PAC controller pod listens on for webhook events
The port (8080) is the Service port (used for internal cluster communication)
The nodePort (30080) is the external port accessible from outside the cluster
For Ingress, the Service port is 8080, which routes to the controller's port 8082 internally

Print the URL from a reachable node IP and the generated NodePort:

NODEPORT=$(kubectl get service pipelines-as-code-controller-nodeport -n tekton-pipelines \
  -o jsonpath='{.spec.ports[?(@.name=="http-listener")].nodePort}')

NODE_IP=$(kubectl get nodes \
  -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}')

echo "WEBHOOK_URL=http://${NODE_IP}:${NODEPORT}"

WEBHOOK_URL is the PAC webhook URL. Register this value in the Git provider or enter it when tkn pac create repo prompts for a webhook URL.

Configuration Settings

PAC configuration lives in two different places on the OpenShiftPipelinesAsCode CR: spec.settings and spec.options.configMaps. Which one you must use depends on the key. Read Where to Put Each Setting before editing, because a key written in the wrong place is dropped without any error.

Standard Settings

These keys go under spec.settings:

Setting	Description	Default
`application-name`	Name displayed in Git provider UI	`Pipelines as Code CI`
`hub-url`	Hub API URL used to resolve remote tasks	`http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local` (the in-cluster ArtifactHub Shim)
`hub-catalog-type`	Hub API flavor: `artifacthub` or `tekton`	`artifacthub`
`hub-catalog-name`	Catalog to resolve from	`catalog`
`remote-tasks`	Enable remote task resolution	`true`
`secret-auto-create`	Automatically create secrets	`true`
`error-detection-from-container-logs`	Detect errors from container logs. GitHub Apps only	`true`
`error-log-snippet`	Show error log snippets	`true`
`custom-console-name`	Display name for custom console links in Git provider UI	`` (empty)
`custom-console-url`	Console base URL. Used verbatim; template variables are not expanded in this key	`` (empty)
`custom-console-url-pr-details`	URL template for the PipelineRun details page. Supports `{{ namespace }}`, `{{ pr }}`	`` (empty)
`custom-console-url-pr-tasklog`	URL template for the task log page. Supports `{{ namespace }}`, `{{ pr }}`, `{{ task }}`	`` (empty)
`custom-console-url-namespace`	URL template for the namespace page. Supports `{{ namespace }}`	`` (empty)

hub-url addresses the Hub the PAC controller queries when resolving remote tasks. The operator ships a working value, so leave all three hub settings unset unless you are pointing PAC at a different Hub. To see what your cluster actually uses:

kubectl -n tekton-pipelines get configmap pipelines-as-code \
  -o jsonpath='{.data.hub-url}{"\n"}{.data.hub-catalog-type}{"\n"}'

If you point hub-url at a Tekton Hub instance, you must also set hub-catalog-type: tekton. The shipped default is artifacthub, and setting hub-url alone leaves it in place, so PAC would talk to a Tekton Hub using the ArtifactHub API and fail to resolve tasks.

custom-console-* settings rewrite the cluster-side links PAC posts back to the Git provider so they point at the platform console rather than at the OpenShift Console. The walkthrough is in Configure Custom Console Links.

Alauda Extension Settings

These keys are Alauda additions on top of upstream Pipelines as Code. They must go under spec.options.configMaps, not under spec.settings:

Setting	Description	Default
`custom-console-url-namespace-vars`	Extra template variables for the `custom-console-url-*` templates, resolved from the labels or annotations of the namespace the run belongs to, for example `{{ project }}` and `{{ cluster }}`	`` (empty)
`replace-empty-template-vars-with-empty`	Replace template variables that have no value (such as `{{ pull_request_number }}` on a push event) with an empty string instead of leaving the literal `{{ ... }}` in the PipelineRun	`false`
`enable-pull-request-number-on-push-events`	Populate `{{ pull_request_number }}` on push events when the pushed commit belongs to a pull request. GitHub only	`true`

Walkthroughs: Configure Custom Console Links for custom-console-url-namespace-vars, and Configure Pull Request Number on Push Events for the other two.

Where to Put Each Setting

The two locations are handled by completely different code paths in the operator:

spec.settings is not stored as you write it. The operator's defaulting webhook parses your map into the upstream Pipelines as Code settings struct and then regenerates the map from that struct. Any key that has no matching field in the struct — which is the case for every Alauda extension setting listed above — is silently discarded: the CR loses the key, the generated pipelines-as-code ConfigMap never receives it, and no error or event is reported.
spec.options.configMaps is applied by the additional-options transformer, which is the last transformer to run and merges your entries into the rendered ConfigMap key by key. Nothing rewrites this map afterwards, so any key survives — including keys the operator does not know about.

Three consequences worth remembering:

Put upstream keys under spec.settings and Alauda extension keys under spec.options.configMaps. Do not move upstream keys into options without reason: settings is the documented, validated location for them.
If the same key is set in both places, the spec.options.configMaps value wins, because that transformer runs after the settings-derived ConfigMap has been rendered.
Setting spec.options.disabled: true turns the whole transformer off. Everything under spec.options is then ignored, including these settings, and you are back to the silent-drop behavior. Leave it unset or false.

spec.options.configMaps is a map keyed by ConfigMap name — it can target any ConfigMap in the component's manifest, and creates one if the name does not exist there. PAC reads its settings from the ConfigMap named pipelines-as-code, so that is the key to use here:

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
spec:
  targetNamespace: tekton-pipelines
  options:
    disabled: false
    configMaps:
      pipelines-as-code:
        data:
          custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"

Verify that the key reached the ConfigMap. This is the only reliable check — reading it back from spec.settings does not tell you whether PAC received it:

kubectl get configmap pipelines-as-code -n tekton-pipelines \
  -o jsonpath='{.data.custom-console-url-namespace-vars}'

Update PAC Component

Update Configuration

Edit the OpenShiftPipelinesAsCode CR:

kubectl edit openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

Update the settings field as needed:
spec: settings: application-name: "My Custom PAC" remote-tasks: "true" error-detection-from-container-logs: "true"
To change one of the Alauda extension settings, edit spec.options.configMaps instead — those keys are removed from spec.settings on save.
Save and exit. The operator will automatically update the TektonInstallerSet and apply the changes.

Common Configuration Updates

The examples in this section update the OpenShiftPipelinesAsCode CR named pipelines-as-code. Each example shows the field it belongs in — most use spec.settings, and the Alauda extension settings use spec.options.configMaps. See Where to Put Each Setting if you are unsure which applies.

kubectl edit openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

Configure Custom Console Links

The custom-console-* settings rewrite the cluster-side links PAC posts back to the Git provider so they point at the platform console. The example below resolves {{ project }} and {{ cluster }} from namespace labels, so the URLs do not hard-code a cluster identifier.

Note that the three templated keys live under spec.settings, while custom-console-url-namespace-vars must live under spec.options.configMaps — see Where to Put Each Setting:

spec:
  targetNamespace: tekton-pipelines
  settings:
    custom-console-name: "My Console"
    custom-console-url: "https://console.example.com/console-acp/"
    custom-console-url-pr-details: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}"
    custom-console-url-pr-tasklog: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns/detail/{{ pr }}?tab=task_overview&id={{ task }}"
    custom-console-url-namespace: "https://console.example.com/console-acp/workspace/{{ project }}~{{ cluster }}~{{ namespace }}/pipeline/pipelineRuns"
  options:
    disabled: false
    configMaps:
      pipelines-as-code:
        data:
          custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"

Effect: Git provider status links open the platform console PipelineRun and task pages instead of the default OpenShift-style placeholder URLs.

Warning

custom-console-url is not a template

Only custom-console-url-pr-details, custom-console-url-pr-tasklog and custom-console-url-namespace go through template expansion. PAC returns custom-console-url verbatim, so writing {{ ... }} in it produces a broken link. Keep it a plain URL: it is the console entry point and also the value PAC falls back to whenever a templated URL fails to build.

PAC expands these variables when it posts status links:

Variable	Resolved to
`{{ namespace }}`	Namespace where the `PipelineRun` runs
`{{ pr }}`	`PipelineRun` name
`{{ task }}`	`TaskRun` name within the `PipelineRun`
`{{ pod }}` and `{{ firstFailedStep }}`	Pod name and the name of the first failed step. Use them only in `custom-console-url-pr-tasklog` — that is the only place PAC fills them in, and since they are never cleared afterwards, the other two templates get either an empty value or a stale one left over from an earlier task-log link
`{{ project }}` and `{{ cluster }}`	Namespace labels declared in `custom-console-url-namespace-vars`

The standard event variables ({{ revision }}, {{ repo_url }} and the rest) are also available in these templates, as are the Repository spec.params entries that resolved for this event — an entry with no name, or with a CEL filter that did not match, is not passed through. The five builtin names above always win: a namespace variable or a Repository parameter that reuses one of them is ignored rather than overriding it.

custom-console-url-namespace-vars is a comma-separated list. Each item uses name=label:<key> or name=annotation:<key>, with an optional |<default> fallback used when the label or annotation is missing or empty. Without a default the variable resolves to an empty string rather than being left as a literal {{ name }}.

Two things have to hold for that to happen. PAC must be able to read the namespace — if the Namespace GET fails, for example because the PAC controller has no permission on it, no namespace-derived variable is injected for that run. And the namespace it reads is the Repository namespace while the run is being created, and the PipelineRun namespace when the final status is reported; the two differ only if a PipelineRun is routed elsewhere through the target-namespace annotation. Whenever a variable ends up unsubstituted, generateURL discards the whole URL and falls back to custom-console-url, which is exactly the "the link is right but never expands" symptom.

spec:
  options:
    disabled: false
    configMaps:
      pipelines-as-code:
        data:
          custom-console-url-namespace-vars: "project=label:cpaas.io/project|unknown,cluster=label:cpaas.io/cluster"

INFO

Namespace labels and annotations are cached for up to 30 minutes, so label changes may take a few minutes to appear in generated links.

For a PipelineRun named my-app-build-abc123 in namespace my-app with labels cpaas.io/project=team-a and cpaas.io/cluster=prod, PAC generates links like:

https://console.example.com/console-acp/workspace/team-a~prod~my-app/pipeline/pipelineRuns/detail/my-app-build-abc123
https://console.example.com/console-acp/workspace/team-a~prod~my-app/pipeline/pipelineRuns/detail/my-app-build-abc123?tab=task_overview&id=build-task
https://console.example.com/console-acp/workspace/team-a~prod~my-app/pipeline/pipelineRuns

These URLs appear in commit statuses, GitHub Checks panels and merge request comments.

Configure Pull Request Number on Push Events

{{ pull_request_number }} is a dynamic variable you can reference from a PipelineRun in your repository. It has an obvious value on a pull request event, but not on a push event. Two Alauda extension settings control what happens then. Both live under spec.options.configMaps, not under spec.settings:

spec:
  targetNamespace: tekton-pipelines
  options:
    disabled: false
    configMaps:
      pipelines-as-code:
        data:
          enable-pull-request-number-on-push-events: "true"
          replace-empty-template-vars-with-empty: "true"

enable-pull-request-number-on-push-events (default "true"): when a push event carries a commit that belongs to a pull request, PAC sets {{ pull_request_number }} to that pull request number. Set it to "false" if you want push events to never inherit a pull request number — for example when a pipeline uses the variable to decide whether it is running for a pull request.

NOTE

This setting only affects GitHub. The other providers never populate {{ pull_request_number }} from a push event, so on GitLab and the rest a push event behaves as if the setting were "false".

It also only comes into play for push events that PAC still processes. The upstream skip-push-event-for-pr-commits setting defaults to "true", and it makes PAC drop a GitHub push event outright when the pushed commit belongs to an open pull request — no PipelineRun is created at all, so no variable is expanded. Everything else still reaches this setting: tag pushes, which the skip rule never applies to; pushes whose commit is associated only with closed or merged pull requests, which is the usual case for the push that results from a merge; and every push event once skip-push-event-for-pr-commits is set to "false".

replace-empty-template-vars-with-empty (default "false"): controls what PAC does with template variables it could not resolve. By default an unresolved {{ pull_request_number }} is left in the PipelineRun as the literal string {{ pull_request_number }}, which usually shows up as a nonsensical parameter value or a validation failure. Set it to "true" to replace unresolved variables with an empty string instead. Variables whose name starts with body, headers or files are deliberately left alone, because they are resolved by a different mechanism.

For a GitHub push event that PAC does process, the two combine as follows:

`enable-pull-request-number-on-push-events`	`replace-empty-template-vars-with-empty`	`{{ pull_request_number }}` resolves to
`"true"` (default)	`"false"` (default)	The pull request number if the commit is associated with one, otherwise the literal `{{ pull_request_number }}`
`"true"` (default)	`"true"`	The pull request number if the commit is associated with one, otherwise an empty string
`"false"`	`"true"`	Always an empty string, even when the commit is associated with a pull request

The table assumes nothing else provides that name. A Repository spec.params entry called pull_request_number is passed through like any other parameter, and it is what the template resolves to whenever PAC did not take the value from the event itself.

Effect: with replace-empty-template-vars-with-empty: "true", pipelines that reference {{ pull_request_number }} run unchanged on both pull request and push events instead of failing on push.

NOTE

replace-empty-template-vars-with-empty applies to PipelineRun definitions resolved from the repository. It does not affect the custom-console-url-* templates, which have their own fallback behavior described in Configure Custom Console Links.

Change Application Name

Use this setting to change the display name that PAC uses in Git provider status messages:

spec:
  settings:
    application-name: "New Application Name"

Effect: Git provider checks, statuses, and comments show the new application name. This does not change the OpenShiftPipelinesAsCode resource name.

Enable Error Detection

Error detection is already on by default. Set it explicitly only when you want to change how many log lines are scanned, or to turn the feature off:

spec:
  settings:
    error-detection-from-container-logs: "true"
    error-detection-max-number-of-lines: "100"

Effect: PAC scans failed task logs and adds a short error snippet to the Git provider feedback. This is a GitHub App feature; the other providers ignore it.

Update Hub URL

By default PAC resolves remote tasks from the in-cluster ArtifactHub Shim, and nothing needs to be configured. Override it only to point PAC at a different Hub — and always set hub-catalog-type together with hub-url, because the shipped artifacthub value stays in place otherwise:

spec:
  settings:
    # An ArtifactHub-compatible API (public artifacthub.io, or your own mirror)
    hub-url: "https://artifacthub.io"
    hub-catalog-type: "artifacthub"

    # Or a Tekton Hub instance — note the different catalog type
    # hub-url: "http://tekton-hub-api.devops-system:8000/v1"
    # hub-catalog-type: "tekton"

Effect: PAC resolves remote tasks from the Hub you specify instead of the in-cluster shim.

To check the value currently in effect:

kubectl -n tekton-pipelines get configmap pipelines-as-code \
  -o jsonpath='{.data.hub-url}{"\n"}{.data.hub-catalog-type}{"\n"}{.data.hub-catalog-name}{"\n"}'

Example output:

http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
artifacthub
catalog

Disable Remote Tasks

Use remote-tasks to control whether PAC fetches and embeds remote resources referenced by PAC annotations.

NOTE

remote-tasks: "true" is the default. PAC can fetch remote resources referenced by pipelinesascode.tekton.dev/task and pipelinesascode.tekton.dev/pipeline annotations, then embed the resolved Task or Pipeline into the generated PipelineRun.

remote-tasks: "false" disables PAC annotation-based remote resource resolution. Pipeline code must define the required Pipeline and Tasks in the repository, inline them, or rely on cluster resources.

This setting does not disable Tekton Pipelines remote resolver syntax such as taskRef.resolver or pipelineRef.resolver; those are handled by the Tekton Pipelines controller.

spec:
  settings:
    remote-tasks: "false"

Effect: Use "false" when you want to prevent PAC from fetching remote Tasks or Pipelines from annotation references.

Uninstall PAC Component

Delete the `OpenShiftPipelinesAsCode` CR

Removing the CR makes the operator tear down the TektonInstallerSet and every PAC Deployment, Service, ConfigMap and RBAC object the operator created.

kubectl delete openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

Confirm the CR, the installer set and the pods are gone:

kubectl get openshiftpipelinesascodes.operator.tekton.dev
kubectl get tektoninstallersets -n tekton-pipelines | grep pipelinesascode
kubectl get pods -n tekton-pipelines | grep pipelines-as-code

Each of these should return No resources found.

Clean up resources the operator does not own

The operator removes everything it created. Resources you added yourself stay behind and must be removed manually.

Repository CRs in user namespaces:

kubectl get repositories -A
kubectl delete repositories --all -n <namespace>

Per-repository Secrets in user namespaces. These are the Git provider access tokens (provider.token) and webhook secrets (webhook.secret) created by users when configuring repositories. The PAC-owned cluster secrets (carrying the app.kubernetes.io/part-of=pipelines-as-code label) are removed by the operator; these per-repository ones are not. Verify each Secret is not used by any other resource before deleting:

kubectl delete secret <secret-name> -n <namespace>

Gateway API resources for the PAC controller, if you created them in Configure Access:

kubectl delete httproute pipelines-as-code -n tekton-pipelines
kubectl delete gateway pipelines-as-code -n tekton-pipelines
kubectl delete envoyproxy pipelines-as-code -n tekton-pipelines

Ingress / NodePort Service for the PAC controller, if you created them in Configure Access:

kubectl delete ingress pipelines-as-code -n tekton-pipelines
kubectl delete service pipelines-as-code-controller-nodeport -n tekton-pipelines

Troubleshooting

PAC Pods Not Starting

Check pod logs:

kubectl logs -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code

Example output (example log entries):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Starting PAC controller"}
{"level":"info","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"PAC controller ready"}

`OpenShiftPipelinesAsCode` CR Not Ready

Check the CR status and events:

kubectl describe openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code

Example output (abbreviated):

Name:         pipelines-as-code
Namespace:
Status:       Ready
Version:      0.x.x
Events:
  Type    Reason   Age   From              Message
  ----    ------   ----  ----              -------
  Normal  Ready    5m    tekton-operator   PAC component deployed successfully

TektonInstallerSet Issues

When the TektonInstallerSet is not Ready, read its conditions and the operator's view of the underlying OpenShiftPipelinesAsCode CR. Both are read-only checks; never delete the installer set yourself.

kubectl get tektoninstallersets -n tekton-pipelines -o yaml

If errors persist, recreate the OpenShiftPipelinesAsCode CR — the operator rebuilds the installer set from scratch.

CR Not Deleting

A deletion that hangs is usually held by the operator finalizer. List the finalizers:

kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o yaml | grep finalizers

A tekton.dev/operator finalizer means the operator is still cleaning up; wait and retry. An empty output means the CR is free to delete.

Resources Not Removed

When pods or Services linger after deletion:

kubectl delete deployment -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code
kubectl delete service -n tekton-pipelines -l app.kubernetes.io/part-of=pipelines-as-code

Manage PAC Component

TOC

Prerequisites

Deploy PAC Component

Configure Access

Using Gateway API

Using Ingress

Using NodePort

Configuration Settings

Standard Settings

Alauda Extension Settings

Where to Put Each Setting

Update PAC Component

Update Configuration

Common Configuration Updates

Configure Custom Console Links

Configure Pull Request Number on Push Events

Change Application Name

Enable Error Detection

Update Hub URL

Disable Remote Tasks

Uninstall PAC Component

Delete the `OpenShiftPipelinesAsCode` CR

Clean up resources the operator does not own

Troubleshooting

PAC Pods Not Starting

`OpenShiftPipelinesAsCode` CR Not Ready

TektonInstallerSet Issues

CR Not Deleting

Resources Not Removed

Next Steps

#Manage PAC Component

#TOC

#Prerequisites

#Deploy PAC Component

#Configure Access

#Using Gateway API

#Using Ingress

#Using NodePort

#Configuration Settings

#Standard Settings

#Alauda Extension Settings

#Where to Put Each Setting

#Update PAC Component

#Update Configuration

#Common Configuration Updates

#Configure Custom Console Links

#Configure Pull Request Number on Push Events

#Change Application Name

#Enable Error Detection

#Update Hub URL

#Disable Remote Tasks

#Uninstall PAC Component

#Delete the OpenShiftPipelinesAsCode CR

#Clean up resources the operator does not own

#Troubleshooting

#PAC Pods Not Starting

#OpenShiftPipelinesAsCode CR Not Ready

#TektonInstallerSet Issues

#CR Not Deleting

#Resources Not Removed

#Next Steps

Manage PAC Component

TOC

Prerequisites

Deploy PAC Component

Configure Access

Using Gateway API

Using Ingress

Using NodePort

Configuration Settings

Standard Settings

Alauda Extension Settings

Where to Put Each Setting

Update PAC Component

Update Configuration

Common Configuration Updates

Configure Custom Console Links

Configure Pull Request Number on Push Events

Change Application Name

Enable Error Detection

Update Hub URL

Disable Remote Tasks

Uninstall PAC Component

Delete the `OpenShiftPipelinesAsCode` CR

Clean up resources the operator does not own

Troubleshooting

PAC Pods Not Starting

`OpenShiftPipelinesAsCode` CR Not Ready

TektonInstallerSet Issues

CR Not Deleting

Resources Not Removed

Next Steps