Alauda DevOps Pipelines Docs

Configure Enhancement Features via TektonConfig

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

For self-signed or private-CA Git providers, configure the CA trust for the Enhancement and PAC controllers separately from the provider-side webhook verification setting. See Configure Custom Certificates for the complete certificate mounting examples.

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.

TOC

PrerequisitesSteps1. Update TektonConfig with spec.pipeline.options.configMaps2. Parameter reference and defaults3. Verify ConfigMap update4. Restart the controller for startup-loaded settingsFAQI updated TektonConfig, but the effective config did not change. What should I check?

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. This controls Git provider -> PAC
                # webhook delivery only; it does not disable controller -> Git
                # provider API TLS verification.
                webhook-target-tls-verify: true

2. Parameter reference and defaults

ParameterMeaningDefault
template-render.details-url-templateGo 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-zoneGlobal time zone setting for template rendering."" (use container local time zone)
pac-webhook-registration.enabledEnables 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-verifyWhether GitLab or GitHub verifies the PAC webhook URL certificate when delivering events. This only affects the provider -> PAC webhook connection; it does not affect TLS verification from tektoncd-enhancement-controller or pipelines-as-code-controller to the Git provider API.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.

If the Git provider cannot validate a self-signed PAC webhook certificate, set webhook-target-tls-verify: false only for non-production environments. This setting does not resolve x509 or certificate signed by unknown authority errors in the Enhancement controller; mount the Git provider CA and set SSL_CERT_FILE/GIT_SSL_CAINFO as described in Configure Custom Certificates.

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:

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

For automatic webhook registration failures, inspect the Enhancement controller logs:

kubectl logs -n <tekton-pipelines> \
  -l app=tektoncd-enhancement-controller \
  --tail=100

x509 or certificate signed by unknown authority errors refer to the controller-to-Git-provider API connection. A failed webhook delivery test in GitLab or GitHub refers to the provider-to-PAC connection and should be investigated with pac-webhook-registration.webhook-target-tls-verify and the PAC webhook certificate.