常见问题

适用于所有用户

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

重要:在本文档中,我们使用两个不同的命名空间:

  • <pac-namespace>:PAC 组件(controller、watcher、webhook)部署所在的命名空间。默认值为 tekton-pipelines,但可以通过 OpenShiftPipelinesAsCode CR 中的 targetNamespace 进行自定义。
  • <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 openshiftpipelinesascodes.operator.tekton.dev pipelines-as-code -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 token secret 名称(检查 Repository CR spec)

PAC 组件未部署

现象

OpenShiftPipelinesAsCode CR 显示 Ready: False,或者 pod 未启动。

故障排查步骤

  1. 检查 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 是集群作用域资源。此处仅进行只读检查以便排查问题。请勿直接修改或删除它。如果问题仍然存在,请通过 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":"..."}

常见原因

  • CR 名称不正确:必须严格为 pipelines-as-code
  • Operator 未运行:检查 Tekton Operator 状态
  • 命名空间问题:确认 targetNamespace 存在
  • 资源冲突:检查是否存在已有资源

解决方案

  1. 确认 CR 名称为 pipelines-as-code
  2. 确保 Tekton Operator 正在运行
  3. 检查命名空间是否存在(将 <pac-namespace> 替换为你的实际 PAC 命名空间):kubectl get namespace <pac-namespace>
  4. 如有需要,删除并重新创建 CR

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 注册 controller 日志:

    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. 验证 token 和 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 管理 token 时检查集中式 credential Secret 标签:

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

自动 Webhook 注册失败的常见原因

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

说明

  • 先尝试 Repository 本地 token。如果返回 401 或 403,controller 会使用匹配的集中式 Secret 重新尝试。
  • 集中式 credential Secrets 从 webhook 注册 controller 命名空间读取;controller 不会在每个 Repository 命名空间中搜索集中式凭证。
  • 直接的 Repository Secrets 不需要标签。controller 只监视有效 Repository spec 所引用的 Secret 命名空间/名称对,并在这些 Secrets 变化时协调相关 Repositories。
  • 请将 Repository 本地 token 的作用域限制为正常 PAC 访问。启用自动 webhook 注册时,将 webhook 管理权限存储在集中式 credential 中。
  • PAC 全局 Repository 的 git_provider 设置仅适用于具有本地 spec.git_provider block 的 Repositories。仅有 spec.url 的 Repository 会被自动 webhook 注册跳过。
  • 注解 pac.tekton.alauda.io/webhook-managed-ref 存储 provider hook ID。当 PAC webhook URL 变更但 provider 和仓库身份保持不变时,controller 会按 ID 更新已记录的 hook,而不是创建重复项。
  • 更新 spec.url 会为新仓库注册 webhook,但不会删除旧仓库上的 webhook。如果不再需要,请手动删除旧的 provider webhook。
  • 删除 Repository 时会尽力清理已记录的 managed webhook。清理失败会被记录到日志并产生事件,但不会阻止移除 Repository finalizer。如果凭证已被移除或 provider API 不可达,请手动检查 provider 侧的 webhook。
  • 全局禁用自动注册,或为 Repository 添加 pac.tekton.alauda.io/webhook-registration-disabled: "true",会在 controller 将 Repository 标记为 inactive 之前移除已记录的 managed webhooks。如果由于缺少凭证或 provider 访问不可用导致清理失败,controller 会保留 managed 注解和 finalizer,并在凭证或 provider 访问恢复后重试。
  • 为 Repository 添加标签 pac.tekton.alauda.io/webhook-registration-disabled: "true",可跳过该 Repository 的自动 webhook 注册。

Webhook 未接收事件

现象

GitLab webhook 事件未到达 PAC,流水线未触发。

故障排查步骤

  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 可访问:

    # 如果使用 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> 替换为实际仓库名称):

    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
  • Ingress/Service 未配置:controller 未暴露

解决方案

  1. 验证 GitLab 服务器可以访问 controller URL
  2. 确保 GitLab 和 Repository CR 中的 webhook secret 一致
  3. 检查 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 事件时没有创建流水线。

故障排查步骤

  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> 替换为实际仓库名称):

    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 CR

解决方案

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

验证

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

  1. 触发测试事件:

    • 向 pipeline 注解中指定的分支推送 commit
    • 或在测试 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

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

未创建 PipelineRuns

现象

已接收到 webhook 事件,但没有创建 PipelineRuns。

故障排查步骤

  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> 替换为实际仓库名称):

    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 token:

    首先,从 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

示例输出(已截断,token 经过 base64 编码):

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

常见原因

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

解决方案

  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 token 过期,请更新 token

  3. 验证 pipeline YAML 语法

  4. 测试 GitLab token:

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

示例输出(如果 token 有效):

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

如果 token 无效:

{"message":"401 Unauthorized"}

验证

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

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

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

    kubectl describe pipelinerun <name> -n <namespace>

    PipelineRun 应该已创建并开始执行。

未找到任务

现象

PipelineRun 失败,并报出 “task not found” 错误。

故障排查步骤

  1. 检查 PipelineRun 状态:

    先列出 PipelineRuns 以找到名称:

    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 Tekton Hub tasks
curl https://api.hub.tekton.dev/v1/resource/task/<task-name>

示例输出(如果 task 存在):

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

    # Test Tekton Hub access
    curl https://api.hub.tekton.dev/v1/resource/task/git-clone

示例输出(如果可访问):

{"id":1,"name":"git-clone",...}
# 测试远程 URL 访问
curl <remote-task-url>

示例输出(如果可访问):

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

常见原因

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

解决方案

  1. 检查 task 名称拼写
  2. 检查 task 是否存在于正确的命名空间中
  3. 测试 Tekton Hub 连通性
  4. 验证远程 URL 可访问
  5. 检查 task resolver 配置

变量未解析

现象

像 {{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 更新到最新版本

有关可用变量的完整列表,请参见 参数化 Commits 和 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

现象

流水线运行成功,但状态未显示在 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 token:

    首先,从 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

示例输出(已截断,token 经过 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"

示例输出(如果 token 有效):

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

如果 token 无效或已过期:

{
  "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 状态:

    列出 PipelineRuns 以找到名称:

    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 token 无效:token 过期或不正确
  • token 权限不足:token 缺少所需 scope
  • 网络问题:无法访问 GitLab API
  • PAC Watcher 未运行:watcher pod 未运行
  • Repository CR 配置错误:GitLab 配置不正确

解决方案

  1. 验证 GitLab token 有效且未过期
  2. 确保 token 具有 api scope
  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
    • 确认显示了流水线状态(例如,“passed”、“failed”、“running”)
  3. 验证 PipelineRun 已完成:

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

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

评论命令不生效

现象

像 /retest 这样的评论命令没有触发流水线。

故障排查步骤

  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 Requests
    • 不适用于普通 commit
  5. 检查 Webhook 配置:

    # In GitLab, verify webhook includes "Comments" trigger

常见原因

  • 缺少注解:未配置 on-comment 注解
  • 命令格式问题:命令不在行首
  • 不在 Merge Request 中:评论命令仅适用于 Merge Requests
  • Webhook 未配置:webhook 中未启用 Comments 事件
  • 命令名称不匹配:评论中的命令与注解不一致

解决方案

  1. 添加 on-comment 注解:pipelinesascode.tekton.dev/on-comment: "retest"
  2. 确保命令位于一行的开头
  3. 仅在 Merge Requests 中使用命令
  4. 在 GitLab webhook 配置中启用 “Comments”
  5. 严格匹配命令名称(区分大小写)

获取帮助

如果你仍然遇到问题:

  1. 查看日志:检查所有组件日志中的错误
  2. 验证配置:再次检查所有配置文件
  3. 查看文档:阅读本指南中的 PAC 文档
  4. 回顾故障排查:检查本文档中的其他故障排查章节

后续步骤