管理 PAC 组件

仅供管理员

本指南仅适用于集群管理员。它涵盖 PAC 组件的部署、配置和维护任务，这些任务需要集群管理员权限。

普通用户请参阅：

指南 - 设置 Git provider 集成

本指南说明如何在 Kubernetes 平台上部署、更新和卸载 Pipelines-as-Code (PAC) 组件。

先决条件

在管理 PAC 之前，请确保具备以下条件：

Kubernetes 集群（版本 1.24 或更高）
已安装并正在运行的 Tekton Operator
集群管理员权限
已安装并配置好 kubectl，可访问你的集群

部署 PAC 组件

PAC 由 Tekton Operator 通过集群作用域的名为 config 的 TektonConfig CR 部署。在默认的 spec.profile: all 下，operator 会基于它派生出一个 OpenShiftPipelinesAsCode CR，并保持该 CR 同步，因此你只需要编辑 TektonConfig。本指南假定使用该 profile；在 basic 或 lite 下，operator 根本不会协调 PAC，因此集群中已有的任何 OpenShiftPipelinesAsCode CR 都需要你直接管理——请参阅 operator 如何管理 PAC。示例使用默认的 PAC namespace tekton-pipelines；如果你的 TektonConfig.spec.targetNamespace 不同，请在命令和 manifest 中替换它。

在 spec.platforms.kubernetes.pipelinesAsCode 下启用 PAC 并设置其配置：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all
  targetNamespace: tekton-pipelines  # Default namespace, you can customize this
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        settings:
          application-name: Pipelines as Code CI
          hub-url: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
          hub-catalog-type: artifacthub
          hub-catalog-name: catalog
          remote-tasks: "true"
          secret-auto-create: "true"

应用更改：

kubectl edit tektonconfig config

使用

platforms.kubernetes，不要使用 platforms.openshift

operator 会拒绝 spec.platforms.openshift 下的任何内容——包括 pipelinesAsCode 和 scc——并返回校验错误。如果较旧的配置中仍包含该子树，请在应用之前将其移除。

检查派生的 OpenShiftPipelinesAsCode CR 状态：

kubectl get openshiftpipelinesascodes.operator.tekton.dev

输出应显示 READY=True；VERSION 会随版本变化，而 REASON 通常为空。

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

验证 PAC pod 是否正在运行：

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

示例输出（controller、watcher 和 webhook pod 必须处于 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

三个 pod（controller、watcher、webhook）必须处于 Running 状态。

operator 如何管理 PAC

由于 TektonConfig 拥有 PAC 部署，因此会产生三个后果。它们解释了本指南其余部分中的大多数“意外”现象：

spec.profile 必须为 all。 operator 为你创建的 TektonConfig 使用的是 all，因此通常满足这一点。在 profile: basic——也就是手写的 TektonConfig 将该字段留空时应用的值——或 profile: lite 下，reconciler 会在到达 PAC 部分之前返回。pipelinesAsCode 下的内容不会被处理：PAC 既不会安装也不会移除，而已存在的 OpenShiftPipelinesAsCode CR 也会保持不变。
OpenShiftPipelinesAsCode CR 是派生的，不是直接编写的。 在启用 PAC 的 profile: all 下，operator 会创建该 CR，设置指向 TektonConfig 的 owner reference，并在每次 reconcile 时将 targetNamespace、config、settings、options 和 additionalPACControllers 从 TektonConfig 复制过去。在派生 CR 上编辑这些字段不会报错，但下一次 reconcile 会覆盖更改。排查问题时读取该 CR；写入则应修改 TektonConfig。
删除派生 CR 不会卸载 PAC。 只要 profile 为 all 且 PAC 仍处于启用状态，下一次 reconcile 就会重新创建它。将 enable: false 才会让 operator 将其移除并保持移除状态——请参阅卸载 PAC 组件。

启用 Repository UI 功能

如果用户需要从 UI 中创建或管理 PAC Repository 资源，请在 tektoncd-enhancement-feature-flags ConfigMap 中启用 Repository UI 功能开关。即使不启用该开关，PAC 仍可正常运行，但当未设置 "true" 的 enable-pac-repository 时，UI 会隐藏 Repository 工作流。

该 ConfigMap 由 TektonConfig 通过 spec.pipeline.options.configMaps 管理。请应用以下配置；如果你的 TektonConfig.spec.targetNamespace 使用的是其他 namespace，请替换 tekton-pipelines：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  targetNamespace: tekton-pipelines
  pipeline:
    options:
      disabled: false
      configMaps:
        tektoncd-enhancement-feature-flags:
          data:
            enable-pac-repository: "true"

验证 operator 已协调该 ConfigMap：

kubectl get configmap tektoncd-enhancement-feature-flags \
  -n tekton-pipelines \
  -o jsonpath='{.data.enable-pac-repository}'

预期输出：

true

配置访问

重要

PAC controller 必须能够被将向其发送 webhook 事件的 Git provider 访问。在配置任何 repository 之前，请先通过以下任一方法将其暴露出来。

使用 Gateway API

使用此方法可通过 ACP Gateway API 使用域名暴露 PAC controller。

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

此示例使用：

默认 PAC namespace：tekton-pipelines
GatewayClass：envoy-gateway-operator-cpaas-default
域名：pac.example.com

步骤 1：准备 Envoy Gateway。 安装 Alauda build of Envoy Gateway，并确保默认 GatewayClass 已被接受。参考：Envoy Gateway Operator。

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

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

步骤 2：准备 LoadBalancer 地址。 Envoy Gateway Service 将创建为 type: LoadBalancer，因此 LoadBalancer Service 必须能够获取外部 IP。在 ACP 裸金属集群上，请安装并配置 Alauda Container Platform Load Balancer for MetalLB。参考：Configure MetalLB。

kubectl get ipaddresspool,l2advertisement -A

预期结果：

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

步骤 3：创建 Gateway API 资源。 创建 gateway-api.yaml。按需替换 tekton-pipelines、envoy-gateway-operator-cpaas-default 和 pac.example.com。参考：Configure GatewayAPI Gateway 和 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

应用该文件：

kubectl apply -f gateway-api.yaml

预期结果：

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

步骤 4：获取外部地址。 检查生成的 Envoy Service：

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

预期结果：

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

步骤 5：验证并获取 webhook URL。 确保 Git provider 可以解析并访问 PAC 域名。常见做法是创建 DNS A 记录。例如，如果 Service 的 EXTERNAL-IP 是 192.168.1.100，则创建：

类型: A
名称: pac.example.com
值: 192.168.1.100

如果 DNS 还未准备好，或者你只想从当前机器测试该路由，请使用 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/

预期结果：

Service 具有 EXTERNAL-IP。
Gateway 显示 PROGRAMMED=True。
HTTPRoute 已被接受。
curl 返回 PAC controller 响应。

在该域名可从 Git provider 网络访问之后，输出 URL：

WEBHOOK_URL=http://pac.example.com

WEBHOOK_URL 即 PAC webhook URL。通过 TektonConfig 将此值记录到 pipelines-as-code-info.data.controller-url 中；请参阅获取 PAC Webhook URL。在手动配置 Git provider webhook，或 tkn pac create repo 提示输入 webhook URL 时，请使用相同的值。

如果你改为通过 ACP ALB 或其他 Ingress Controller 暴露 PAC，请使用使用 Ingress。

注意：

HTTPRoute 会将流量转发到现有的 pipelines-as-code-controller Service 的 8080 端口；不要将其指向名为 pipelines-as-code-webhook 的 admission webhook Service。
如果生成的 Envoy Service 仍为 EXTERNAL-IP=<pending>，请检查集群的 LoadBalancer 提供程序。对于 MetalLB，请参阅 Configure MetalLB。
关于 Gateway API 选项（例如预留 VIP、无主机路由或 HTTPS listener），请参阅 Configure GatewayAPI Gateway 和 Configure GatewayAPI Route。

使用 Ingress

当集群已经有 Ingress Controller，并且你希望通过 Ingress 域名暴露 PAC controller 时，请使用此方法。

此示例使用：

默认 PAC namespace：tekton-pipelines
域名：pac.example.com

步骤 1：准备 Ingress Controller。 确保 Ingress Controller 已安装并就绪。参考：Configure Ingress。

步骤 2：创建 Ingress 资源。 创建 ingress.yaml。按需替换 tekton-pipelines 和 pac.example.com。

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

应用该文件：

kubectl apply -f ingress.yaml

预期结果：

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

步骤 3：验证 Ingress 地址。 检查 Ingress 是否具有地址：

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

预期结果：

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

步骤 4：获取 webhook URL。 确保 Git provider 可以通过 Ingress 地址解析并访问 pac.example.com。然后输出 URL：

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

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

如果你没有 DNS 名称，请移除 host 字段，并改用可访问的 Ingress IP URL。

可选：启用 HTTPS。 在 tekton-pipelines 中创建 TLS Secret，并在同一个 Ingress 中添加 tls 部分。证书必须匹配 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

配置 TLS 后，请使用 HTTPS webhook URL：

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

使用 NodePort

创建一个 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

重要：

targetPort 必须为 8082，这是 PAC controller pod 监听 webhook 事件的端口
port（8080）是 Service 端口（用于集群内部通信）
nodePort（30080）是集群外可访问的外部端口
对于 Ingress，Service 端口是 8080，它会在内部路由到 controller 的 8082 端口

从一个可访问的节点 IP 和生成的 NodePort 输出 URL：

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}"

配置设置

PAC 配置位于 spec.platforms.kubernetes.pipelinesAsCode 下的两个不同位置：settings 和 options.configMaps。具体应使用哪一个取决于键名。编辑之前请先阅读每个设置应放在哪里，因为写入错误位置的键会被直接丢弃且不会报错。

标准设置

这些键应放在 pipelinesAsCode.settings 下：

设置	描述	默认值
`application-name`	在 Git provider UI 中显示的名称	`Pipelines as Code CI`
`hub-url`	PAC 用于远程 task 和 pipeline 注解的 Hub API URL	`http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local`
`hub-catalog-type`	Hub provider 类型	`artifacthub`
`hub-catalog-name`	PAC 远程注解使用的默认 Artifact Hub repository 名称	`catalog`
`remote-tasks`	启用远程 task 解析	`true`
`secret-auto-create`	自动创建 secret	`true`
`error-detection-from-container-logs`	从容器日志中检测错误。仅适用于 GitHub Apps	`true`
`error-log-snippet`	显示错误日志片段	`true`
`custom-console-name`	Git provider UI 中自定义 console 链接的显示名称	``（空）
`custom-console-url`	Console 基础 URL。按原样使用；此键中的模板变量不会展开	``（空）
`custom-console-url-pr-details`	PipelineRun 详情页的 URL 模板。支持 `{{ namespace }}`、`{{ pr }}`	``（空）
`custom-console-url-pr-tasklog`	task 日志页的 URL 模板。支持 `{{ namespace }}`、`{{ pr }}`、`{{ task }}`	``（空）
`custom-console-url-namespace`	namespace 页面的 URL 模板。支持 `{{ namespace }}`	``（空）

hub-url 指向 PAC controller 在解析远程 task 时查询的 Hub 后端。ACP DevOps 默认将其指向集群内的 artifacthub-shim Service。对于 Artifact Hub provider，请不要附加 /api/v1；PAC 会在内部添加该路径。

custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接，使其指向平台 console 而不是 OpenShift Console。操作流程见配置自定义 Console 链接。

Alauda 扩展设置

这些键是在上游 Pipelines as Code 基础上的 Alauda 扩展。它们必须放在 pipelinesAsCode.options.configMaps 下，而不是 pipelinesAsCode.settings 下：

设置	描述	默认值
`custom-console-url-namespace-vars`	`custom-console-url-*` 模板的额外模板变量，取自该 run 所属 namespace 的 label 或 annotation，例如 `{{ project }}` 和 `{{ cluster }}`	``（空）
`replace-empty-template-vars-with-empty`	将没有值的模板变量（例如 push 事件中的 `{{ pull_request_number }}`）替换为空字符串，而不是在 PipelineRun 中保留字面量 `{{ ... }}`	`false`
`enable-pull-request-number-on-push-events`	当推送的 commit 属于某个 pull request 时，在 push 事件中填充 `{{ pull_request_number }}`。仅适用于 GitHub	`true`

操作流程：配置自定义 Console 链接 适用于 custom-console-url-namespace-vars，在 Push 事件中配置 Pull Request Number 适用于另外两个设置。

每个设置应放在哪里

这两个位置在 operator 中由完全不同的代码路径处理：

settings 并不会按你写入的方式存储。operator 的默认值 webhook 会将你的 map 解析为上游 Pipelines as Code settings 结构体，然后再从该结构体重新生成 map。凡是没有与结构体字段匹配的键——上面列出的每个 Alauda 扩展设置都属于这种情况——都会被静默丢弃：TektonConfig 会丢失该键，派生的 OpenShiftPipelinesAsCode CR 永远看不到该键，生成的 pipelines-as-code ConfigMap 也不会接收该键，并且不会报告任何错误或事件。
options.configMaps 由 additional-options transformer 应用；这是最后执行的 transformer，它会将你的条目按键逐个合并到渲染后的 ConfigMap 中。之后没有任何东西会重写该 map，因此任何键都会保留下来——包括 operator 不认识的键。

有三点值得记住：

将上游键放在 settings 中，将 Alauda 扩展键放在 options.configMaps 中。不要无故把上游键移到 options 中：settings 才是它们有文档支持且经过校验的位置。
如果同一个键在两个位置都设置了，则 options.configMaps 的值优先生效，因为该 transformer 运行于 settings 派生的 ConfigMap 渲染之后。
设置 options.disabled: true 会完全关闭整个 transformer。此时 options 下的所有内容都会被忽略，包括这些设置，行为会回到“静默丢弃”。请保持其未设置或设为 false。

options.configMaps 是以 ConfigMap 名称为键的 map——它可以针对组件 manifest 中的任意 ConfigMap，如果名称不存在还会创建一个。PAC 从名为 pipelines-as-code 的 ConfigMap 读取其设置，因此这里应使用该键：

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  profile: all
  targetNamespace: tekton-pipelines
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        options:
          disabled: false
          configMaps:
            pipelines-as-code:
              data:
                custom-console-url-namespace-vars: "project=label:cpaas.io/project,cluster=label:cpaas.io/cluster"

验证该键已写入 ConfigMap。这是唯一可靠的检查方式——从 settings 中读回并不能说明 PAC 是否已接收到该值：

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

更新 PAC 组件

更新配置

编辑 TektonConfig CR：
kubectl edit tektonconfig config

按需更新 settings 字段：

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        settings:
          application-name: "My Custom PAC"
          hub-url: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
          hub-catalog-type: artifacthub
          hub-catalog-name: catalog
          remote-tasks: "true"
          error-detection-from-container-logs: "true"

要更改某个 Alauda 扩展设置，请改为编辑 pipelinesAsCode.options.configMaps——这些键在保存时会从 settings 中移除。

保存并退出。operator 会更新派生的 OpenShiftPipelinesAsCode CR，然后更新 TektonInstallerSet，并应用更改。

不要改为编辑派生的 OpenShiftPipelinesAsCode CR：在 profile: all 下，operator 会在下一次 reconcile 时将 settings 和 options 从 TektonConfig 重新复制回来，因此更改会丢失。请参阅 operator 如何管理 PAC。

常见配置更新

本节中的示例会更新名为 config 的 TektonConfig 中的 spec.platforms.kubernetes.pipelinesAsCode。每个示例都显示其所属字段——大多数使用 settings，而 Alauda 扩展设置使用 options.configMaps。如果你不确定应该使用哪一个，请参阅每个设置应放在哪里。

kubectl edit tektonconfig config

配置自定义 Console 链接

custom-console-* 设置会重写 PAC 回传给 Git provider 的集群侧链接，使其指向平台 console。下面的示例从 namespace label 中解析 {{ project }} 和 {{ cluster }}，因此 URL 不需要硬编码 cluster 标识符。

注意，这三个模板化键位于 settings 下，而 custom-console-url-namespace-vars 必须位于 options.configMaps 下——请参阅每个设置应放在哪里：

spec:
  targetNamespace: tekton-pipelines
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        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"

效果：Git provider 状态链接将打开平台 console 中的 PipelineRun 和 task 页面，而不是默认的 OpenShift 风格占位 URL。

Warning

custom-console-url 不是模板

只有 custom-console-url-pr-details、custom-console-url-pr-tasklog 和 custom-console-url-namespace 会进行模板展开。PAC 会原样返回 custom-console-url，因此在其中写入 {{ ... }} 会生成损坏的链接。请保持其为普通 URL：它既是 console 入口点，也是模板化 URL 构建失败时 PAC 回退使用的值。

PAC 在发布状态链接时会展开这些变量：

变量	解析为
`{{ namespace }}`	`PipelineRun` 运行所在的 namespace
`{{ pr }}`	`PipelineRun` 名称
`{{ task }}`	Pipeline task 名称——即 `spec.pipelineSpec.tasks` 下条目的 `name`，不是生成的 `TaskRun` 资源名称
`{{ pod }}` 和 `{{ firstFailedStep }}`	Pod 名称和第一个失败 step 的名称。仅在 `custom-console-url-pr-tasklog` 中使用它们——这是 PAC 唯一填充它们的地方，而且由于之后从不清除它们，另外两个模板会得到空值，或者拿到上一个 task-log 链接残留的旧值
`{{ project }}` 和 `{{ cluster }}`	在 `custom-console-url-namespace-vars` 中声明的 namespace label

标准事件变量（{{ revision }}、{{ repo_url }} 等）也可在这些模板中使用，Repository 的 spec.params 中为该事件解析出的条目也同样可用——没有名称的条目，或 CEL filter 未匹配的条目，不会被传递。上面提到的五个内置名称始终优先：重用其中任一名称的 namespace 变量或 Repository 参数会被忽略，而不会覆盖它。

custom-console-url-namespace-vars 是一个逗号分隔列表。每一项使用 name=label:<key> 或 name=annotation:<key>，并可带一个可选的 |<default> 回退值，用于 label 或 annotation 缺失或为空时。没有默认值时，该变量会解析为空字符串，而不是保留为字面量 {{ name }}。

要实现这一点，必须满足两个条件。PAC 必须能够读取该 namespace——如果 Namespace GET 失败，例如因为 PAC controller 没有该 namespace 的权限，那么该 run 就不会注入任何 namespace 派生变量。并且，它读取的是创建 run 时的 Repository namespace，以及报告最终状态时的 PipelineRun namespace；只有当 PipelineRun 通过 target-namespace annotation 被路由到其他位置时，这两个 namespace 才会不同。每当某个变量最终未被替换时，generateURL 会丢弃整个 URL，并回退到 custom-console-url，这正是“链接正确但从不展开”的典型症状。

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        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 的 label 和 annotation 最多缓存 30 分钟，因此 label 变更可能需要几分钟才会出现在生成的链接中。

对于名为 my-app-build-abc123、位于 namespace my-app 的 PipelineRun，并且其 label 为 cpaas.io/project=team-a 和 cpaas.io/cluster=prod，PAC 会生成如下链接：

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

这些 URL 会出现在 commit status、GitHub Checks 面板和 merge request 注释中。

在 Push 事件中配置 Pull Request Number

{{ pull_request_number }} 是一个你可以在 repository 中的 PipelineRun 里引用的动态变量。在 pull request 事件中，它的值显而易见；但在 push 事件中则不然。两个 Alauda 扩展设置用于控制此时的行为。二者都位于 options.configMaps 下，而不是 settings 下：

spec:
  targetNamespace: tekton-pipelines
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: true
        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（默认 "true"）：当 push 事件携带的 commit 属于某个 pull request 时，PAC 会将 {{ pull_request_number }} 设置为该 pull request 的编号。如果你希望 push 事件永远不继承 pull request number，请将其设为 "false"——例如当 pipeline 使用该变量来判断自己是否正在为 pull request 运行时。

NOTE

此设置仅影响 GitHub。其他 provider 从不会在 push 事件中填充 {{ pull_request_number }}，因此在 GitLab 及其他平台上，push 事件的行为相当于该设置为 "false"。

它也仅在 PAC 仍会处理的 push 事件中生效。上游的 skip-push-event-for-pr-commits 设置默认值为 "true"，它会在推送的 commit 属于一个打开的 pull request 时，直接让 PAC 丢弃 GitHub push 事件——根本不会创建 PipelineRun，因此也不会展开任何变量。其他情况仍会到达该设置：例如 tag push，因为跳过规则从不适用；例如 commit 只关联已关闭或已合并的 pull request 的 push，这通常是 merge 产生的 push 情况；以及当将 skip-push-event-for-pr-commits 设为 "false" 后的每一个 push 事件。

replace-empty-template-vars-with-empty（默认 "false"）：控制 PAC 对无法解析的模板变量的处理方式。默认情况下，未解析的 {{ pull_request_number }} 会以字面字符串 {{ pull_request_number }} 的形式保留在 PipelineRun 中，这通常会表现为一个毫无意义的参数值或校验失败。将其设为 "true" 可将未解析的变量替换为空字符串。名称以 body、headers 或 files 开头的变量会被刻意保留，因为它们由不同机制解析。

对于 PAC 实际处理的 GitHub push 事件，这两个设置的组合效果如下：

`enable-pull-request-number-on-push-events`	`replace-empty-template-vars-with-empty`	`{{ pull_request_number }}` 解析为
`"true"`（默认）	`"false"`（默认）	如果该 commit 关联了某个 pull request，则为该 pull request 编号；否则为字面量 `{{ pull_request_number }}`
`"true"`（默认）	`"true"`	如果该 commit 关联了某个 pull request，则为该 pull request 编号；否则为空字符串
`"false"`	`"true"`	始终为空字符串，即使该 commit 关联了 pull request 也是如此

上表假定没有其他内容提供该名称。名为 pull_request_number 的 Repository spec.params 条目会像其他参数一样被传递，而当 PAC 没有从事件本身获取该值时，模板就会解析为它。

效果：当 replace-empty-template-vars-with-empty: "true" 时，引用 {{ pull_request_number }} 的 pipeline 在 pull request 和 push 事件中都能保持不变地运行，而不会在 push 事件中失败。

NOTE

replace-empty-template-vars-with-empty 适用于从 repository 解析出的 PipelineRun 定义。它不影响 custom-console-url-* 模板，这些模板具有各自的回退行为，见配置自定义 Console 链接。

更改应用名称

使用此设置可更改 PAC 在 Git provider 状态消息中使用的显示名称：

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          application-name: "New Application Name"

效果：Git provider 的 checks、statuses 和 comments 会显示新的 application 名称。此操作不会更改派生的 OpenShiftPipelinesAsCode 资源名称。

启用错误检测

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

效果：PAC 会扫描失败的 task 日志，并将一段简短的错误片段添加到 Git provider 反馈中。

更新 Hub URL

默认值已经指向集群内的 artifacthub-shim Service，因此只有在 artifacthub-shim 部署在其他 namespace 中，或者你想使用外部 Hub 时，才需要设置此项：

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          # The address artifacthub-shim is installed at by default. Change only the
          # namespace if it was deployed somewhere other than artifacthub-shim-system.
          hub-url: "http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local"
          hub-catalog-type: "artifacthub"
          hub-catalog-name: "catalog"

          # Or for a Tekton Hub instance - the catalog type has to change with it,
          # otherwise PAC queries it with the Artifact Hub API
          # hub-url: "https://api.hub.tekton.dev/v1"
          # hub-catalog-type: "tekton"

效果：PAC 会从指定的 Hub API 解析远程 task，而不是默认的集群内 shim Service。

查找你的 artifacthub-shim service：

kubectl get svc -A | grep artifacthub-shim-api

示例输出：

artifacthub-shim-system   artifacthub-shim-api   ClusterIP   10.96.123.45   <none>   80/TCP   10m

禁用远程 Task

使用 remote-tasks 控制 PAC 是否获取并嵌入由 PAC 注解引用的远程资源。

NOTE

remote-tasks: "true" 是默认值。PAC 可以获取由 pipelinesascode.tekton.dev/task 和 pipelinesascode.tekton.dev/pipeline 注解引用的远程资源，然后将解析后的 Task 或 Pipeline 嵌入生成的 PipelineRun 中。

remote-tasks: "false" 会禁用 PAC 基于注解的远程资源解析。Pipeline 代码必须在 repository 中定义所需的 Pipeline 和 Task，或将其内联，或者依赖集群资源。

此设置不会禁用 Tekton Pipelines 的远程 resolver 语法，例如 taskRef.resolver 或 pipelineRef.resolver；这些由 Tekton Pipelines controller 处理。

spec:
  platforms:
    kubernetes:
      pipelinesAsCode:
        settings:
          remote-tasks: "false"

效果：当你想阻止 PAC 从注解引用中获取远程 Task 或 Pipeline 时，请将其设为 "false"。

卸载 PAC 组件

本节描述的是 profile: all 集群，此时 operator 拥有 PAC 部署。在 profile: basic 或 lite 下，operator 根本不会协调 PAC：enable: false 不会移除任何内容，而删除 OpenShiftPipelinesAsCode CR 本身就是卸载——不会有任何东西将其重新创建。

在 `TektonConfig` 中禁用 PAC

设置 enable: false。operator 会删除派生的 OpenShiftPipelinesAsCode CR，随后会拆除 TektonInstallerSet 以及 operator 创建的所有 PAC Deployment、Service、ConfigMap 和 RBAC 对象。

spec:
  profile: all
  platforms:
    kubernetes:
      pipelinesAsCode:
        enable: false

不要手动删除派生 CR

在 profile: all 下，当 TektonConfig 仍启用 PAC 时，kubectl delete openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code 并不会卸载 PAC——下一次 reconcile 会重新创建该 CR，PAC 也会恢复。应改为在 TektonConfig 中将其禁用。

确认 CR、installer set 和 pod 都已消失：

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

第一条命令应输出 No resources found。两个 grep 命令都不应输出任何内容——你要找的是空结果，而不是错误消息。TektonInstallerSet 是集群作用域的，这就是第二条命令不需要 namespace 的原因。

清理 operator 不拥有的资源

operator 会移除其创建的所有内容。你自己添加的资源会保留，需要手动删除。

用户 namespace 中的 Repository CR：

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

用户 namespace 中按 repository 创建的 Secret。这些是用户在配置 repository 时创建的 Git provider 访问令牌（provider.token）和 webhook secret（webhook.secret）。由 PAC 拥有的集群 Secret（带有 app.kubernetes.io/part-of=pipelines-as-code 标签）会由 operator 删除；这些按 repository 创建的 Secret 不会。删除前请验证每个 Secret 未被其他资源使用：

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

PAC controller 的 Gateway API 资源，如果你在配置访问中创建了它们：

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

PAC controller 的 Ingress / NodePort Service，如果你在配置访问中创建了它们：

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

故障排查

PAC Pod 未启动

检查 pod 日志：

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

示例输出（示例日志条目）：

{"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 未就绪

检查派生 CR 的状态和事件。这是只读检查——请在 TektonConfig 中修复配置，而不是在这里修复：

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

示例输出（节选）：

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 问题

当 TektonInstallerSet 未处于 Ready 状态时，请查看其 conditions 以及 operator 对底层 OpenShiftPipelinesAsCode CR 的视图。这两项都是只读检查；切勿自行删除 installer set。

kubectl get tektoninstallersets -o yaml
kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -o yaml

TektonInstallerSet 是集群作用域的，因此第一条命令不需要 namespace，并会列出集群中的所有 installer set；PAC 相关的 installer set 名称中包含 pipelinesascode。

如果错误仍然存在，让 operator 重建该 CR：在 profile: all 下，当 TektonConfig 仍为 enable: true 时删除派生的 OpenShiftPipelinesAsCode CR，下一次 reconcile 会连同一个新的 installer set 一起重新创建它。请先检查 profile——在 basic 或 lite 下，不会有任何东西重新创建该 CR，删除它会永久移除 PAC。

CR 无法删除

卡住的删除通常是被 operator finalizer 挂住了。列出 finalizer：

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

tekton.dev/operator finalizer 表示 operator 仍在清理；请等待后重试。空输出表示该 CR 已可安全删除。

资源未移除

当删除后 pod 或 Service 仍然存在时：

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

管理 PAC 组件

目录

先决条件

部署 PAC 组件

operator 如何管理 PAC

启用 Repository UI 功能

配置访问

使用 Gateway API

使用 Ingress

使用 NodePort

配置设置

标准设置

Alauda 扩展设置

每个设置应放在哪里

更新 PAC 组件

更新配置

常见配置更新

配置自定义 Console 链接

在 Push 事件中配置 Pull Request Number

更改应用名称

启用错误检测

更新 Hub URL

禁用远程 Task

卸载 PAC 组件

在 `TektonConfig` 中禁用 PAC

清理 operator 不拥有的资源

故障排查

PAC Pod 未启动

`OpenShiftPipelinesAsCode` CR 未就绪

TektonInstallerSet 问题

CR 无法删除

资源未移除

下一步

#管理 PAC 组件

#目录

#先决条件

#部署 PAC 组件

#operator 如何管理 PAC

#启用 Repository UI 功能

#配置访问

#使用 Gateway API

#使用 Ingress

#使用 NodePort

#配置设置

#标准设置

#Alauda 扩展设置

#每个设置应放在哪里

#更新 PAC 组件

#更新配置

#常见配置更新

#配置自定义 Console 链接

#在 Push 事件中配置 Pull Request Number

#更改应用名称

#启用错误检测

#更新 Hub URL

#禁用远程 Task

#卸载 PAC 组件

#在 TektonConfig 中禁用 PAC

#清理 operator 不拥有的资源

#故障排查

#PAC Pod 未启动

#OpenShiftPipelinesAsCode CR 未就绪

#TektonInstallerSet 问题

#CR 无法删除

#资源未移除

#下一步

管理 PAC 组件

目录

先决条件

部署 PAC 组件

operator 如何管理 PAC

启用 Repository UI 功能

配置访问

使用 Gateway API

使用 Ingress

使用 NodePort

配置设置

标准设置

Alauda 扩展设置

每个设置应放在哪里

更新 PAC 组件

更新配置

常见配置更新

配置自定义 Console 链接

在 Push 事件中配置 Pull Request Number

更改应用名称

启用错误检测

更新 Hub URL

禁用远程 Task

卸载 PAC 组件

在 `TektonConfig` 中禁用 PAC

清理 operator 不拥有的资源

故障排查

PAC Pod 未启动

`OpenShiftPipelinesAsCode` CR 未就绪

TektonInstallerSet 问题

CR 无法删除

资源未移除

下一步