Configure Enhancement Features via TektonConfig

This guide shows how to manage enhancement feature configuration through TektonConfig using spec.pipeline.options.configMaps.

Namespace Note: Throughout this guide, <tekton-pipelines> is used as a placeholder for your Tekton namespace. Replace it with your actual namespace name. The default installation uses tekton-pipelines namespace.

Prerequisites

Tekton Operator is installed.
TektonConfig resource exists (usually named config).
You can edit TektonConfig in your cluster.

Steps

1. Update TektonConfig with `spec.pipeline.options.configMaps`

The options structure follows the same pattern as described in Adjusting Optional Configuration Items of Subcomponents.

Use a TektonConfig patch like this:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: <tekton-pipelines>
  pipeline:
    options:
      configMaps:
        tektoncd-enhancement-config:
          data:
            config: |
              # Shared configuration for enhancement features.
              template-render:
                # Template to build the details URL.
                details-url-template: "{{- if .isPipelineRun -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/pipelineRuns/detail/{{ .pipelineRunName }}{{- else -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/taskRuns/detail/{{ .taskRunName }}{{- end -}}"
                # Empty value means using the container local time zone.
                time-zone: ""
              pac-webhook-registration:
                # Register GitLab/GitHub webhooks for PAC Repository resources.
                # The default is true. Setting this to false deletes webhooks
                # previously managed by tektoncd-enhancement.
                enabled: true
                # Keep enabled in production.
                webhook-target-tls-verify: true

2. Parameter reference and defaults

Parameter	Meaning	Default
`template-render.details-url-template`	Go template used to render `detailsURL` for mail/template rendering context.	`{{- if .isPipelineRun -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/pipelineRuns/detail/{{ .pipelineRunName }}{{- else -}}{{ .platformURL }}/console-acp/workspace/{{ .project }}~{{ .cluster }}~{{ .namespace }}/pipeline/taskRuns/detail/{{ .taskRunName }}{{- end -}}`
`template-render.time-zone`	Global time zone setting for template rendering.	`""` (use container local time zone)
`pac-webhook-registration.enabled`	Enables automatic GitLab/GitHub webhook registration for PAC `Repository` resources. When set to `false`, the controller deletes provider webhooks it previously managed and marks the Repository as `Disabled`.	`true`
`pac-webhook-registration.webhook-target-tls-verify`	Whether Git providers verify the PAC webhook URL certificate when delivering events.	`true`

PAC webhook registration reads the public webhook URL from pipelines-as-code-info.data.controller-url. Configure that value through the PAC component options; see Get the PAC Webhook URL.

To use automatic webhook registration, set each PAC Repository spec.git_provider.type to github or gitlab. Repositories without a supported type are skipped, with the reason recorded as a Repository Event and status annotations.

WARNING

Setting pac-webhook-registration.enabled to false is not only a pause for future registrations. It also removes Git provider webhooks that were previously created or updated by the enhancement controller. Set it back to true to let the controller reconcile eligible PAC Repository resources again and recreate or update their webhooks.

For active Repository resources, cleanup must complete before the controller removes the managed webhook annotations and finalizer. If credentials are missing or the provider API is temporarily unreachable, fix the credential or provider access and the controller retries. Deleting a Repository is different: provider cleanup is best-effort so the Kubernetes finalizer can be removed after the cleanup warning is recorded.

3. Verify ConfigMap update

After updating TektonConfig, check whether the managed ConfigMap has been reconciled:

kubectl get configmap tektoncd-enhancement-config -n <tekton-pipelines> -o yaml

The Tekton Operator applies the configuration from TektonConfig. Do not update the managed Deployment or ConfigMap directly because those changes can be overwritten by the next reconciliation.

4. Restart the controller for startup-loaded settings

pac-webhook-registration.* settings are hot-reloaded after the ConfigMap is updated. template-render.* settings are loaded when the enhancement controller starts, so restart tektoncd-enhancement-controller after changing template-render.details-url-template or template-render.time-zone:

kubectl rollout restart deployment tektoncd-enhancement-controller -n <tekton-pipelines>
kubectl rollout status deployment tektoncd-enhancement-controller -n <tekton-pipelines>

FAQ

I updated `TektonConfig`, but the effective config did not change. What should I check?

Check in this order:

TektonConfig was updated successfully.
tektoncd-enhancement-config in namespace <tekton-pipelines> has the expected data.config.
The Tekton Operator has reconciled the latest TektonConfig.
If you changed any template-render.* setting, tektoncd-enhancement-controller was restarted after the ConfigMap update.

#Configure Enhancement Features via TektonConfig

#TOC

#Prerequisites

#Steps

#1. Update TektonConfig with spec.pipeline.options.configMaps

#2. Parameter reference and defaults

#3. Verify ConfigMap update

#4. Restart the controller for startup-loaded settings

#FAQ

#I updated TektonConfig, but the effective config did not change. What should I check?