常见问题

面向所有用户

本故障排除指南涵盖 管理员(组件部署、配置)和 普通用户(仓库设置、流水线执行)遇到的问题。

重要:本文档中使用了两个不同的命名空间:

  • <pac-namespace>:部署 PAC 组件(controller、watcher、webhook)的命名空间。默认为 tekton-pipelines,但可以通过 targetNamespace 在 TektonConfig CR 中自定义。
  • <namespace>:创建 PipelineRuns 的命名空间。创建 Repository CR 时指定此命名空间,并且可以是集群中的任意命名空间。

请将这些占位符替换为实际的命名空间名称。

本文档提供了使用 Pipelines-as-Code (PAC) 时常见问题的故障排除步骤。

开始之前

在排查具体问题之前,请先验证以下基础信息:

1. 检查 PAC 组件是否正在运行

验证所有 PAC Pod 是否正在运行(将 <pac-namespace> 替换为 PAC 命名空间,默认为 tekton-pipelines):

kubectl get pods -n <pac-namespace> | grep pipelines-as-code

示例输出(所有 Pod 的状态都应为 Running):

NAME                                          READY   STATUS    RESTARTS   AGE
pipelines-as-code-controller-769bf5c88c-xxxxx  1/1     Running   0          113d
pipelines-as-code-watcher-546d6cd86d-xxxxx     1/1     Running   15         113d
pipelines-as-code-webhook-5fcd94db5b-xxxxx     1/1     Running   0          113d

2. 确定命名空间

获取 PAC 命名空间(PAC 组件部署所在的命名空间):

kubectl get tektonconfig config -o jsonpath='{.spec.targetNamespace}'

如果命令失败或返回空值,请使用默认值:tekton-pipelines

获取 Pipeline 命名空间(创建 PipelineRuns 的命名空间):

kubectl get repository -A

此命令会显示所有 Repository CR 及其命名空间。命名空间列显示将创建 PipelineRuns 的位置。

3. 获取资源名称

获取 Pod 名称:

kubectl get pods -n <pac-namespace> | grep pipelines-as-code

获取 Repository CR 名称:

kubectl get repository -n <namespace>

获取 PipelineRun 名称:

kubectl get pipelinerun -n <namespace>

4. 本文档中使用的常见占位符

  • <pac-namespace>:PAC 部署命名空间(默认:tekton-pipelines)
  • <namespace>:PipelineRun 命名空间(因仓库而异)
  • <repo-name>:Repository CR 名称(使用 kubectl get repository -n <namespace> 列出)
  • <pod-name>:Pod 名称(使用 kubectl get pods -n <pac-namespace> 列出)
  • <name>:PipelineRun 名称(使用 kubectl get pipelinerun -n <namespace> 列出)
  • <gitlab-secret>:GitLab 令牌 Secret 名称(检查 Repository CR spec)

PAC 组件未部署

症状

OpenShiftPipelinesAsCode CR 显示为 Ready: False,Pod 未启动,或者该 CR 根本不存在。

故障排查步骤

  1. 检查 TektonConfig 是否请求 PAC。operator 根据 TektonConfig 派生 OpenShiftPipelinesAsCode CR,且仅当 profile 为 all 并且已启用 PAC 时才会执行。如果 CR 完全缺失,请从这里开始:

    kubectl get tektonconfig config \
      -o jsonpath='profile={.spec.profile} enable={.spec.platforms.kubernetes.pipelinesAsCode.enable}{"\n"}'

    预期输出:

    profile=all enable=true

    profile 为 basic 或 lite,表示 operator 根本不会进入 PAC 逻辑——既不会创建 CR,也不会删除 CR。

    enable 为空表示 spec.platforms.kubernetes.pipelinesAsCode 完全不存在。默认值 webhook 会使用 enable: true 填充该区块,但仅当某些操作写入 TektonConfig 时才会执行,因此在 operator 升级后尚未写入 TektonConfig 的集群上,该区块会保持缺失。在 profile: all 上——这是唯一会进入 PAC 逻辑的 profile——reconciler 会将该缺失区块视为已禁用 PAC,并删除派生的 CR。如部署 PAC 组件中所示显式写入该区块,既能立即解决问题,也能让意图在 CR 中清晰可见。

  2. 检查 CR 状态:

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

示例输出(已省略部分内容):

apiVersion: operator.tekton.dev/v1alpha1
kind: OpenShiftPipelinesAsCode
metadata:
  name: pipelines-as-code
status:
  conditions:
  - status: "False"
    type: Ready
    reason: DeploymentFailed
  1. 检查 CR 事件:

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

示例输出(已省略部分内容):

Name:         pipelines-as-code
Status:       False
Events:
Type     Reason           Age   From              Message
----     ------           ----  ----              -------
Warning  DeploymentFailed 5m    tekton-operator   Failed to deploy PAC component
  1. 检查 TektonInstallerSet:

    kubectl get tektoninstallersets | grep openshiftpipelinesascode
    kubectl describe tektoninstallerset <name>

    注意:TektonInstallerSet 是集群范围的资源。这是用于故障排查的只读检查。请勿直接修改或删除它。如果问题仍然存在,请通过 TektonConfig 和派生的 OpenShiftPipelinesAsCode CR 进行排查。

示例输出:

NAME                                             AGE
openshiftpipelinesascode-main-deployment-4bzwx   153d
openshiftpipelinesascode-main-static-s7qn2       153d
openshiftpipelinesascode-post-cdwjw              153d
  1. 检查 operator 日志:

    kubectl logs -n <pac-namespace> -l app=tekton-operator --tail=100

示例输出(示例日志条目):

{"level":"error","ts":"2024-01-01T12:00:00Z","logger":"operator","msg":"Failed to deploy PAC","error":"..."}

常见原因

  • TektonConfig 中未请求 PAC:profile 不是 all,或者 profile 是 all,但 spec.platforms.kubernetes.pipelinesAsCode 缺失或为 enable: false。这是 CR 缺失而不是未就绪的通常原因。这两种情况有所不同:在 basic 或 lite 上,operator 不会创建 CR,也不会触碰已存在的 CR;而在 all 上,缺失区块或 enable: false 会导致 operator 删除 CR。就地升级后很容易遇到区块缺失的情况,因为只有在某些操作写入 TektonConfig 时才会填充该区块
  • operator 未运行:检查 Tekton Operator 状态
  • 命名空间问题:确认 targetNamespace 存在
  • 资源冲突:检查是否存在同名资源

解决方案

  1. 在 TektonConfig 中设置 spec.profile: all 和 spec.platforms.kubernetes.pipelinesAsCode.enable: true
  2. 确保 Tekton Operator 正在运行
  3. 检查命名空间是否存在(将 <pac-namespace> 替换为实际的 PAC 命名空间):kubectl get namespace <pac-namespace>
  4. 如果派生的 CR 是卡住而不是缺失,请将其删除——在 profile: all 上,只要 TektonConfig 中仍启用了 PAC,operator 就会在下一次 reconcile 时重新创建该 CR。请勿在 basic 或 lite 上执行此操作:在那里没有任何机制会重新创建 CR,因此删除它会永久移除 PAC

PAC Pod 未启动

症状

PAC Pod 处于 Pending 或 CrashLoopBackOff 状态。

故障排查步骤

  1. 检查 Pod 状态(将 <pac-namespace> 替换为 PAC 命名空间):

    kubectl get pods -n <pac-namespace> | grep pipelines-as-code

示例输出:

NAME                                          READY   STATUS             RESTARTS   AGE
pipelines-as-code-controller-769bf5c88c-xxxxx  0/1     CrashLoopBackOff   5          113d
pipelines-as-code-watcher-546d6cd86d-xxxxx    0/1     Pending            0          113d
  1. 检查 Pod 日志:

    首先获取 Pod 名称(将 <pac-namespace> 替换为 PAC 命名空间):

    kubectl get pods -n <pac-namespace> | grep pipelines-as-code

    然后检查日志(将 <pod-name> 替换为实际的 Pod 名称):

    kubectl logs -n <pac-namespace> <pod-name>

示例输出(示例错误):

Error: failed to start controller: cannot connect to database
  1. 检查 Pod 事件:

    先获取 Pod 名称,然后描述该 Pod(将 <pod-name> 替换为实际的 Pod 名称):

    kubectl describe pod <pod-name> -n <pac-namespace>

示例输出(缩略):

Name:         pipelines-as-code-controller-xxxxx
Status:       CrashLoopBackOff
Events:
Type     Reason     Age   From               Message
----     ------     ----  ----               -------
Warning  Failed     5m    kubelet            Error: ImagePullBackOff
  1. 检查资源限制:

    kubectl get pod <pod-name> -n <pac-namespace> -o yaml | grep -A 5 resources

示例输出:

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 100m
    memory: 128Mi

自动注册 Webhook 失败

症状

应用 Repository 后未创建 GitLab/GitHub Webhook,或者 Repository 具有:

metadata:
  annotations:
    pac.tekton.alauda.io/webhook-registration-status: Failed

故障排查步骤

  1. 检查 Repository 注解和事件:

    kubectl describe repository <repo-name> -n <namespace>
    kubectl get repository <repo-name> -n <namespace> \
      -o jsonpath='{.metadata.annotations.pac\.tekton\.alauda\.io/webhook-registration-reason}{"\n"}'
    kubectl get repository <repo-name> -n <namespace> \
      -o jsonpath='{.metadata.annotations.pac\.tekton\.alauda\.io/webhook-registration-message}{"\n"}'
  2. 检查 Webhook 注册控制器日志:

    kubectl logs -n <pac-namespace> \
      -l app=tektoncd-enhancement-controller \
      --tail=100
  3. 验证 PAC Webhook URL 来源:

    kubectl get configmap pipelines-as-code-info -n <pac-namespace> \
      -o jsonpath='{.data.controller-url}{"\n"}'

    如果为空,请配置 PAC 公共 URL,并将其记录在 pipelines-as-code-info.data.controller-url 中。请参阅获取 PAC Webhook URL。

  4. 验证令牌和 Webhook Secret 引用:

    kubectl get repository <repo-name> -n <namespace> -o yaml
    kubectl get secret <secret-name> -n <namespace> -o json | jq '.data | keys'
  5. 使用共享 Webhook 管理令牌时,检查集中式凭证 Secret 标签:

    kubectl get secret -n <controller-namespace> \
      -l pac.tekton.alauda.io/provider-credential=true \
      --show-labels

常见原因

原因注解含义修复
WebhookURLUnavailable控制器找不到 PAC 公共 Webhook URL。通过 pipelines-as-code-info.data.controller-url 填充 TektonConfig。
MissingWebhookSecret有效的 spec.git_provider.webhook_secret 缺失,或指向缺失/空的键。在 Repository 命名空间中添加 webhook_secret.name 和键 webhook.secret,或从 PAC 全局 Repository 继承。继承的 Secret 从全局 Repository 命名空间读取。
MissingCredential未找到可用的 provider 令牌。在 Repository 命名空间中添加 spec.git_provider.secret,从 PAC 全局 Repository 继承,或在 Webhook 注册控制器命名空间中添加一个匹配的集中式 Secret。继承的 Secret 从全局 Repository 命名空间读取。
AmbiguousCredential有多个集中式 Secret 与相同的 provider 类型和 URL 匹配。仅保留一个匹配的 Secret,或调整 pac.tekton.alauda.io/provider-url。
ProviderAPIErrorGitLab/GitHub API 返回错误。检查令牌权限、git_provider.url、provider 可达性和 CA 信任。对于集中式 Webhook 注册,GitHub 需要 admin:repo_hook 或 Webhooks 写入权限,GitLab 需要具有管理员或 Maintainer/Owner 项目访问权限的 api 作用域。
NoGitProviderRepository 没有本地 spec.git_provider,或者有效的 provider 类型为空且无法推断。为 Webhook 模式添加本地 spec.git_provider 区块。将 type 设置为 github 或 gitlab,从 PAC 全局 Repository 继承,或者提供明确的公共 GitHub/GitLab URL、/api/v3 或 /api/v4 API URL。GitHub App 模式不使用自动 Webhook 注册。
UnsupportedProvider控制器仅支持 GitLab 和 GitHub Webhook 模式。使用手动注册或其他受支持的集成模式。

TLS 错误取决于发起连接的组件:

  • x509、certificate signed by unknown authority,或 tektoncd-enhancement-controller 日志中出现的类似错误,表示控制器不信任 Git provider API 证书。挂载 CA bundle 并设置 SSL_CERT_FILE/GIT_SSL_CAINFO;请参阅配置自定义证书。
  • 如果 GitLab/GitHub Webhook 传送测试因无法验证 PAC 端点证书而失败,这是 provider 到 PAC 的问题。检查通过 TektonConfig 配置增强功能中的 pac-webhook-registration.webhook-target-tls-verify,或者安装 Git provider 信任的 CA。
  • 获取 Repository 内容或报告状态时出现的 pipelines-as-code-controller 错误,是独立的 PAC controller 到 provider 的信任问题,需要按照配置自定义证书配置 PAC controller CA。

注意事项

  • 首先尝试 Repository 本地令牌。如果返回 401 或 403,控制器会使用匹配的集中式 Secret 重试。
  • 集中式凭证 Secret 从 Webhook 注册控制器命名空间读取;控制器不会在每个 Repository 命名空间中搜索集中式凭证。
  • 直接使用的 Repository Secret 不需要标签。控制器仅监视有效 Repository spec 所引用的 Secret 命名空间/名称对,并在这些 Secret 发生变化时 reconcile 相关 Repository。
  • 将 Repository 本地令牌限制在 PAC 的正常访问范围内。启用自动 Webhook 注册后,将 Webhook 管理权限存储在集中式凭证中。
  • PAC 全局 Repository git_provider 设置仅适用于具有本地 spec.git_provider 区块的 Repository。仅包含 spec.url 的 Repository 会被自动 Webhook 注册跳过。
  • 注解 pac.tekton.alauda.io/webhook-managed-ref 存储 provider hook ID。当 PAC Webhook URL 发生变化但 provider 和 Repository 标识保持不变时,控制器会按 ID 更新记录的 hook,而不是创建重复的 hook。
  • 更新 spec.url 会为新 Repository 注册 Webhook,但不会删除旧 Repository 中的 Webhook。如果不再需要,请手动删除旧 provider Webhook。
  • 删除 Repository 时会尽力清理记录的受管 Webhook。清理失败会记录日志并作为事件发出,但不会阻止移除 Repository finalizer。如果凭证已被删除或 provider API 无法访问,请手动检查 provider 侧的 Webhook。
  • 全局禁用自动注册,或向 Repository 添加 pac.tekton.alauda.io/webhook-registration-disabled: "true",会在控制器将 Repository 标记为非活动状态之前移除记录的受管 Webhook。如果因凭证缺失或 provider 访问不可用而导致清理失败,控制器会保留受管注解和 finalizer,并在凭证或 provider 访问恢复后重试。
  • 向 Repository 添加标签 pac.tekton.alauda.io/webhook-registration-disabled: "true",可跳过该 Repository 的自动 Webhook 注册。

对于控制器日志,请使用:

kubectl logs -n <pac-namespace> \
  -l app=tektoncd-enhancement-controller \
  --tail=100 | grep -Ei 'x509|certificate|tls|webhook|ProviderAPIError'

Webhook 未接收事件

症状

GitLab Webhook 事件未到达 PAC,Pipeline 未触发。

故障排除步骤

  1. 检查 GitLab 中的 Webhook 配置:

    • 转到 GitLab 项目 → Settings → Webhooks
    • 确认 Webhook URL 正确
    • 检查 Webhook Secret 是否与 Repository CR 匹配
  2. 检查 PAC controller 日志(将 <pac-namespace> 替换为 PAC 命名空间):

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100

示例输出(示例日志条目):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Received webhook event"}
{"level":"error","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Webhook validation failed","error":"invalid signature"}
  1. 从 GitLab 测试 Webhook:

    • 转到 GitLab 项目 → Settings → Webhooks
    • 单击“Test” → “Push events”
    • 检查 Webhook 响应
  2. 验证 controller URL 是否可访问:

    # If using Gateway API
    curl -i http://pac.example.com/
    # If DNS is not ready yet, resolve the host to the Envoy Gateway external IP:
    # curl -i --resolve "pac.example.com:80:<gateway-external-ip>" http://pac.example.com/

示例输出:

HTTP/1.1 200 OK
Content-Type: text/plain
# If using Ingress
curl -i http://pac.example.com/

示例输出:

HTTP/1.1 200 OK
Content-Type: text/plain
# If using NodePort
curl -i http://<node-ip>:<node-port>/

示例输出:

HTTP/1.1 200 OK
Content-Type: text/plain
  1. 检查 Repository CR:

    首先列出所有 Repository CR 以查找名称(将 <namespace> 替换为 Pipeline 命名空间):

    kubectl get repository -n <namespace>

    然后检查特定的 Repository CR(将 <repo-name> 替换为实际的 Repository 名称):

    kubectl get repository <repo-name> -n <namespace> -o yaml

示例输出(已缩略):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  git_provider:
    type: gitlab
    webhook_secret:
      name: webhook-secret
      key: secret

常见原因

  • Controller URL 不可访问:防火墙或网络问题
  • Webhook Secret 不匹配:GitLab 中的 Secret 与 Repository CR 中的不匹配
  • Webhook URL 不正确:配置了错误的 controller URL
  • Gateway/Ingress/Service 未配置:Controller 未暴露

解决方案

  1. 验证 GitLab 服务器是否可以访问 controller URL
  2. 确保 GitLab 和 Repository CR 中的 Webhook Secret 一致
  3. 检查 Gateway/Ingress/Service 配置
  4. 使用 curl 手动测试 Webhook

验证

应用解决方案后,验证修复结果:

  1. 从 GitLab 测试 Webhook:

    • 转到 GitLab 项目 → Settings → Webhooks
    • 单击“Test” → “Push events”
    • 检查 Webhook 是否返回 200 OK 响应
  2. 检查 PAC controller 日志中的 Webhook 事件:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i webhook

    您应该会看到表明 Webhook 事件已接收的日志条目。

Pipeline 未触发

症状

发生 Git 事件时未创建 Pipeline。

故障排查步骤

  1. 检查 Pipeline 注解:

    cat .tekton/pipelinerun.yaml | grep pipelinesascode.tekton.dev

示例输出:

pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]"
pipelinesascode.tekton.dev/on-event: "[push]"
  1. 验证分支名称是否匹配:

    git branch --show-current
    git log --oneline -1

示例输出:

main
abc1234 Test commit
  1. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i trigger

示例输出(日志条目示例):

{"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing trigger","branch":"main","event":"push"}
{"level":"warn","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Branch mismatch","expected":"main","actual":"develop"}
  1. 检查 Repository CR 状态:

    首先列出 Repository CR,以查找名称:

    kubectl get repository -n <namespace>

    然后检查 Repository CR(将 <repo-name> 替换为实际的 repository 名称):

    kubectl get repository <repo-name> -n <namespace> -o yaml
    kubectl describe repository <repo-name> -n <namespace>

示例输出(已省略部分内容):

Name:         my-repo
Namespace:    project-pipelines
Status:       Ready
Events:
Type    Reason   Age   From     Message
----    ------   ----  ----     -------
Normal  Ready    5m    pac      Repository validated
  1. 验证 Pipeline 文件是否存在:

    git ls-files .tekton/

示例输出:

.tekton/pipelinerun.yaml

常见原因

  • 注解语法错误:注解格式不正确
  • 分支名称不匹配:分支模式与实际分支不匹配
  • 找不到 Pipeline 文件:文件不在预期位置
  • 路径过滤:已更改的文件与路径过滤器不匹配
  • 找不到 Repository CR:没有与该 repository 匹配的 Repository CR

解决方案

  1. 验证注解语法:使用 pipelinesascode.tekton.dev/on-target-branch: "[refs/heads/main]" 和 pipelinesascode.tekton.dev/on-event: "[push]",而不是已弃用的 on-push 注解
  2. 检查分支名称是否完全匹配(区分大小写)
  3. 确保 repository 中存在 .tekton/pipelinerun.yaml
  4. 如果配置了路径过滤,请检查路径过滤设置
  5. 验证 Repository CR 是否存在,并且是否与 repository URL 匹配

验证

应用解决方案后,验证修复结果:

  1. 触发测试事件:

    • 向 Pipeline 注解中指定的分支推送提交
    • 或者在测试 MR 触发器时创建 Merge Request
  2. 检查是否创建了 PipelineRun:

    kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -5

    Git 事件发生后,您应该会看到新创建的 PipelineRun。

  3. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i trigger

    查找表明事件已处理的日志条目。

未创建 PipelineRun

症状

已接收到 Webhook 事件,但未创建 PipelineRun。

故障排查步骤

  1. 检查 PAC Controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=200

示例输出(示例错误):

{"level":"error","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Failed to create PipelineRun","error":"namespaces \"project-pipelines\" not found"}
  1. 检查 Repository CR:

    首先,列出 Repository CR 以查找名称:

    kubectl get repository -n <namespace>

    然后检查 Repository CR(将 <repo-name> 替换为实际的 repository 名称):

    kubectl get repository <repo-name> -n <namespace> -o yaml
    kubectl describe repository <repo-name> -n <namespace>

示例输出(已省略部分内容):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  git_provider:
    type: gitlab
  # ......
  1. 验证命名空间是否存在:

    kubectl get namespace <namespace>

示例输出:

NAME                STATUS   AGE
project-pipelines   Active   10m

如果命名空间不存在,您将看到:

Error from server (NotFound): namespaces "project-pipelines" not found
  1. 检查 RBAC 权限:

    kubectl auth can-i create pipelineruns --namespace <namespace>

示例输出:

yes
  1. 检查 GitLab 令牌:

    首先,从 Repository CR 中查找 secret 名称:

    kubectl get repository <repo-name> -n <namespace> -o jsonpath='{.spec.git_provider.secret.name}'

    然后检查 secret(将 <gitlab-secret> 替换为实际的 secret 名称):

    kubectl get secret <gitlab-secret> -n <namespace> -o yaml

示例输出(已省略部分内容,令牌经过 base64 编码):

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
data:
  token: Z2xwYXQt...

常见原因

  • 命名空间不存在:未创建目标命名空间
  • RBAC 权限:PAC ServiceAccount 缺少权限
  • GitLab 令牌无效:令牌已过期或不正确
  • Pipeline 定义错误:YAML 或 Tekton 语法无效
  • Repository 访问:无法访问 Git repository

解决方案

  1. 如果命名空间缺失,则创建命名空间:

    kubectl create namespace <namespace>

示例输出:

namespace/project-pipelines created
  1. 验证 RBAC:检查 ServiceAccount 和 RoleBindings

    检查 PAC 使用的 ServiceAccount:

    kubectl get pod -n <pac-namespace> -l app=pipelines-as-code-controller -o jsonpath='{.items[0].spec.serviceAccountName}'

    检查 ServiceAccount 是否具有所需权限:

    kubectl auth can-i create pipelineruns --namespace <namespace> --as=system:serviceaccount:<pac-namespace>:<service-account-name>
  2. 如果 GitLab 令牌已过期,则更新令牌

  3. 验证 Pipeline YAML 语法

  4. 测试 GitLab 令牌:

    curl --header "PRIVATE-TOKEN: <token>" "https://gitlab.com/api/v4/user"

示例输出(令牌有效时):

{
  "id": 1,
  "username": "user",
  "email": "user@example.com"
}

如果令牌无效:

{"message":"401 Unauthorized"}

验证

应用解决方案后,验证修复结果:

  1. 触发 Git 事件(推送或创建 MR),并检查是否创建了 PipelineRun:

    kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -1
  2. 检查 PipelineRun 状态:

    kubectl describe pipelinerun <name> -n <namespace>

    此时应已创建 PipelineRun 并开始执行。

找不到 Task

症状

PipelineRun 失败,并显示“找不到 task”错误。

故障排查步骤

  1. 检查 PipelineRun 状态:

    首先,列出 PipelineRun 以查找其名称:

    kubectl get pipelinerun -n <namespace>

    然后检查该 PipelineRun(将 <name> 替换为实际的 PipelineRun 名称):

    kubectl get pipelinerun <name> -n <namespace> -o yaml
    kubectl describe pipelinerun <name> -n <namespace>

示例输出(已缩略,显示错误):

status:
  conditions:
  - status: "False"
    type: Succeeded
    reason: TaskNotFound
  taskRuns:
    task-run-name:
      status:
        conditions:
        - message: 'Task "my-task" not found'
  1. 检查 Task 引用:

    cat .tekton/pipelinerun.yaml | grep -A 5 taskRef

示例输出:

taskRef:
  name: my-task
  kind: Task
  1. 验证 Task 是否存在:

    # For local tasks
    kubectl get task <task-name> -n <namespace>

示例输出(Task 存在时):

NAME       AGE
my-task    10m

Task 不存在时:

Error from server (NotFound): tasks.tekton.dev "my-task" not found
# For DevOps Hub catalog tasks
curl http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local/api/v1/packages/tekton-task/catalog/<task-name>

示例输出(Task 存在时):

{
  "id": 1,
  "name": "git-clone",
  "kind": "Task",
  "catalog": {
    "id": 1,
    "name": "Tekton"
  }
}
  1. 检查网络连接:

    # Test artifacthub-shim access
    curl http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local/api/v1/packages/tekton-task/catalog/git-clone

示例输出(可访问时):

{"id":1,"name":"git-clone",...}
# Test remote URL access
curl <remote-task-url>

示例输出(可访问时):

apiVersion: tekton.dev/v1
kind: Task
...

常见原因

  • Task 名称不正确:Task 名称中存在拼写错误
  • Task 不在该命名空间中:Task 定义在其他命名空间中
  • DevOps Hub 不可用:访问 artifacthub-shim 时存在网络问题
  • 远程 URL 无法访问:无法从远程 URL 获取 Task
  • Task resolver 错误:resolver 配置不正确

解决方案

  1. 验证 Task 名称的拼写
  2. 检查正确的命名空间中是否存在该 Task
  3. 测试与 artifacthub-shim 的连接
  4. 验证远程 URL 是否可访问
  5. 检查 Task resolver 配置

变量无法解析

症状

Pipeline 变量(如 {{revision}})未被替换。

故障排查步骤

  1. 检查变量语法:

    cat .tekton/pipelinerun.yaml | grep -E "\{\{|\}\}"

示例输出:

revision: {{revision}}
repo_url: {{repo_url}}
  1. 使用 Dry-Run 验证 YAML 语法:

    使用 kubectl apply --dry-run=client 验证 PipelineRun YAML 语法并及早发现错误:

    kubectl apply --dry-run=client -f .tekton/pipelinerun.yaml -n <namespace>

示例输出(语法有效时):

pipelinerun.tekton.dev/my-pipeline created (dry run)

示例输出(存在语法错误时):

error: error validating ".tekton/pipelinerun.yaml": error validating data: [ValidationError(PipelineRun.spec): unknown field "invalid-field" in tekton.dev.v1.PipelineRun.spec, ...]

注意:此 Dry-Run 检查会验证 YAML 语法和 Tekton schema,但不会验证变量解析(变量如 {{revision}} 在 Dry-Run 中仍会作为字面字符串保留)。对于变量解析问题,请检查 PAC controller 日志。

  1. 检查 PAC controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i variable

示例输出(示例日志条目):

{"level":"warn","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Unknown variable","variable":"{{Revision}}"}
  1. 验证变量名称:

    • {{revision}} - 正确
    • {{Revision}} 或 {{REVISION}} - 错误(区分大小写)
    • 使用双花括号:{{variable_name}}
  2. 检查 PipelineRun 参数:

    首先,获取 PipelineRun 名称:

    kubectl get pipelinerun -n <namespace>

    然后检查参数(将 <name> 替换为实际的 PipelineRun 名称):

    kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.params}'

示例输出:

[
  {
    "name": "revision",
    "value": "abc1234"
  },
  {
    "name": "repo_url",
    "value": "https://gitlab.com/user/repo"
  }
]

常见原因

  • 语法错误:缺少花括号或格式不正确
  • 大小写敏感:变量名称区分大小写
  • 变量不可用:当前事件类型不提供该变量(例如,{{pull_request_number}} 仅适用于 pull_request 事件)
  • PAC 版本:较旧的 PAC 版本可能不支持某些变量

解决方案

  1. 验证变量语法:使用 {{variable_name}} 格式,例如 {{revision}} 或 {{repo_url}}
  2. 检查变量名称是否正确(区分大小写):{{repo_owner}}、{{source_branch}}、{{pull_request_number}}
  3. 确保变量适用于相应的事件类型:某些变量(如 {{pull_request_number}})仅适用于 pull_request 事件
  4. 如有需要,将 PAC 更新到最新版本

有关可用变量的完整列表,请参阅参数化提交和 URL。

验证

应用解决方案后,验证修复结果:

  1. 检查已创建的 PipelineRun 中的变量是否已解析:

    kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.spec.params}' | jq .

    变量应已替换为实际值(例如,{{revision}} 应替换为 commit SHA)。

  2. 检查 PAC controller 日志中的变量解析情况:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=50 | grep -i variable

    不应存在关于未知变量的警告。

向 GitLab 报告状态失败

症状

Pipeline 成功运行,但状态未显示在 GitLab 中。

故障排查步骤

  1. 检查 PAC Watcher 日志:

    kubectl logs -n <pac-namespace> -l app.kubernetes.io/name=watcher --tail=100

示例输出(示例日志条目):

{"level":"error","ts":"2024-01-01T12:00:00Z","logger":"watcher","msg":"Failed to update status","error":"401 Unauthorized"}
  1. 检查 GitLab 令牌:

    首先,从 Repository CR 中查找 secret 名称:

    kubectl get repository <repo-name> -n <namespace> -o jsonpath='{.spec.git_provider.secret.name}'

    然后检查 secret(将 <gitlab-secret> 替换为实际的 secret 名称):

    kubectl get secret <gitlab-secret> -n <namespace> -o yaml

示例输出(已截断,令牌采用 base64 编码):

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-secret
data:
  token: Z2xwYXQt...
  1. 测试 GitLab API 访问:

    TOKEN=$(kubectl get secret <gitlab-secret> -n <namespace> -o jsonpath='{.data.token}' | base64 -d)
    curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab.com/api/v4/user"

示例输出(令牌有效时):

{
  "id": 1,
  "username": "user",
  "email": "user@example.com"
}

如果令牌无效或已过期:

{
  "message": "401 Unauthorized"
}
  1. 检查 Repository CR:

    kubectl get repository <repo-name> -n <namespace> -o yaml

示例输出(已截断):

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  git_provider:
    type: gitlab
    secret:
      name: gitlab-secret
      key: token
  1. 验证 PipelineRun 状态:

    列出 PipelineRun 以查找其名称:

    kubectl get pipelinerun -n <namespace>

    然后检查状态(将 <name> 替换为实际的 PipelineRun 名称):

    kubectl get pipelinerun <name> -n <namespace>

示例输出:

NAME                    STARTED        DURATION   STATUS
simple-pipeline-xxxxx   5 minutes ago  30s        Succeeded

常见原因

  • GitLab 令牌无效:令牌已过期或不正确
  • 令牌权限:令牌缺少所需的作用域
  • 网络问题:无法访问 GitLab API
  • PAC Watcher 未运行:Watcher Pod 未运行
  • Repository CR 配置错误:GitLab 配置不正确

解决方案

  1. 验证 GitLab 令牌有效且未过期
  2. 确保令牌具有 api 作用域
  3. 测试 GitLab API 连通性
  4. 检查 PAC Watcher Pod 是否正在运行
  5. 验证 Repository CR 中的 GitLab 配置

验证

应用解决方案后,验证修复结果:

  1. 检查 PAC Watcher 日志,确认状态更新成功:

    kubectl logs -n <pac-namespace> -l app.kubernetes.io/name=watcher --tail=50 | grep -i status

    应看到表明状态更新已成功发送的日志条目。

  2. 检查 GitLab UI:

    • 转到 GitLab 项目
    • 检查 Merge Request 或 commit
    • 验证是否显示 Pipeline 状态(例如,“passed”、“failed”、“running”)
  3. 验证 PipelineRun 已完成:

    kubectl get pipelinerun -n <namespace> --sort-by=.metadata.creationTimestamp | tail -1

    PipelineRun 应显示 Succeeded 或 Failed 状态,并且该状态应反映在 GitLab 中。

注释命令不起作用

症状

/retest 等注释命令不会触发 Pipeline。

排查步骤

  1. 检查注解配置:

    cat .tekton/pipelinerun.yaml | grep on-comment

    示例输出:

    pipelinesascode.tekton.dev/on-comment: "retest"
  2. 验证注释格式:

    • 命令必须单独占一行或位于行首
    • /retest - 正确
    • Please /retest - 不正确(命令不在行首)
  3. 检查 PAC Controller 日志:

    kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep -i comment

    示例输出(示例日志条目):

    {"level":"info","ts":"2024-01-01T12:00:00Z","logger":"controller","msg":"Processing comment command","command":"/retest"}
    {"level":"warn","ts":"2024-01-01T12:00:01Z","logger":"controller","msg":"Comment command not at start of line","comment":"Please /retest"}
  4. 验证 Merge Request 是否存在:

    • 注释命令仅在 Merge Request 中有效
    • 普通 commit 不支持
  5. 检查 Webhook 配置:

    # In GitLab, verify webhook includes "Comments" trigger

常见原因

  • 缺少注解:未配置 on-comment 注解
  • 命令格式错误:命令不在行首
  • 不在 Merge Request 中:注释命令仅在 Merge Request 中有效
  • 未配置 Webhook:Webhook 中未启用 Comments 事件
  • 命令名称不匹配:注释中的命令与注解不匹配

解决方案

  1. 添加 on-comment 注解:pipelinesascode.tekton.dev/on-comment: "retest"
  2. 确保命令位于行首
  3. 仅在 Merge Request 中使用命令
  4. 在 GitLab Webhook 配置中启用“Comments”
  5. 确保命令名称完全匹配(区分大小写)

PAC 设置不起作用

症状

已将设置添加到 TektonConfig.spec.platforms.kubernetes.pipelinesAsCode.settings 并成功应用,但 PAC 仍然表现得像该设置保持默认值一样。TektonConfig 和派生的 OpenShiftPipelinesAsCode CR 均报告 ready,未记录任何事件或错误,而读取 TektonConfig 时发现该键已从 settings 中消失。

这只影响 Alauda 扩展设置:custom-console-url-namespace-vars、replace-empty-template-vars-with-empty 和 enable-pull-request-number-on-push-events。

请注意,这里的症状是“默认值生效”,而不是“功能缺失”。当该键不在其 ConfigMap 中时,PAC 会回退到该设置的内置默认值,因此,关闭默认启用的设置和启用默认关闭的设置同样会受到影响。

排查步骤

以下命令使用两个占位符。请先在同一 shell 中设置它们,这样其余内容就可以直接粘贴执行:

SETTING=custom-console-url-namespace-vars   # the setting you configured
PAC_NS=tekton-pipelines                     # spec.targetNamespace of TektonConfig
  1. 检查该键是否保留在 TektonConfig 中:

    kubectl get tektonconfig config \
      -o jsonpath="{.spec.platforms.kubernetes.pipelinesAsCode.settings.$SETTING}"

    只有当你将该键写入 settings 时,此步骤才有意义;此时空输出表示 operator 丢弃了该键。如果你已将该键移至 options.configMaps,则此处为空是预期结果,请直接执行第 3 步。

  2. 检查派生 CR。在 profile: all 上,由于 PAC 正在运行,这正是此症状所表明的情况,operator 会将 settings 从 TektonConfig 复制到其中,因此该键在此处也会消失——此步骤只能确认副本保持同步,并非权威检查:

    kubectl get openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code \
      -o jsonpath="{.spec.settings.$SETTING}"
  3. 检查 PAC 实际读取的 ConfigMap。这是权威检查——settings 只能说明配置意图:

    kubectl get configmap pipelines-as-code -n "$PAC_NS" \
      -o jsonpath="{.data.$SETTING}"

    将输出与预期值进行比较。任何其他结果都表示 PAC 未使用你的配置。请注意,如果你有意将该键设置为空字符串(例如清除不再需要的映射),则空输出是正确结果。

常见原因

  • 将键写入 settings:operator 的默认值 Webhook 会根据上游 Pipelines as Code 设置结构体重建该映射。Alauda 扩展设置在该结构体中没有对应字段,因此保存时会被静默丢弃,不会产生错误或事件。这会在 TektonConfig 本身上发生,因此该键甚至不会到达派生 CR。
  • 将键写入派生的 OpenShiftPipelinesAsCode CR:在 profile: all 上,operator 会在下一次 reconcile 时将 settings 和 options 从 TektonConfig 复制回来,因此即使对于其他情况下会接受的键,该修改也会丢失。
  • 直接将键写入 ConfigMap:手动修改会在普通 reconcile 中保留,因为 operator 会将渲染后的 manifest 与哈希注解进行比较,而你的修改不会改变该注解。比较按资源进行,因此不会改变渲染后 ConfigMap 的 PAC 修改(例如 spec.config 或 Deployment 选项)会保留该修改。当渲染后的 ConfigMap 本身发生变化时,手动修改会被静默覆盖:对 settings 或 options.configMaps 的任何修改、operator 升级,或 installer set 重建都会触发这种情况。因此,手动编辑 ConfigMap 看似生效,但随后会在不可预测的时刻停止生效。

解决方案

将该键移至 TektonConfig 中的 options.configMaps。operator 会按键将其合并到 ConfigMap 中,并且不会重写这些内容:

spec:
  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"

然后重复第 3 步,确认该值已写入 ConfigMap。详细信息和完整键列表请参阅每个设置的放置位置。

获取帮助

如果你仍然遇到问题:

  1. 查看日志:检查所有组件日志中的错误
  2. 验证配置:仔细检查所有配置文件
  3. 查看文档:查看本指南中的 PAC 文档
  4. 查看故障排除:查看本文档中的其他故障排除部分

后续步骤