传入 Webhooks

传入 webhooks 允许你通过 HTTP POST 请求直接触发 pipeline，而无需 Git 事件。

概述

传入 webhooks 提供了一种方式来：

从外部系统触发 pipeline
与不使用 Git 的 CI/CD 工具集成
手动或通过 API 调用触发 pipeline
支持自定义 payload 和 parameter

传入 Webhooks 的工作原理

HTTP POST 请求：向 PAC controller 的 /incoming 端点发送 POST 请求
身份验证：PAC 使用 secret（来自 header 或 query parameter）验证请求
Repository 查询：PAC 根据 repository 名称和 namespace 查找 Repository CR
Pipeline 触发：PAC 处理 payload 并触发匹配的 pipeline，类似于 Git webhook 事件
PipelineRun 创建：PAC 根据 payload 和 pipeline 定义创建 PipelineRun

与 Git webhooks 的主要区别：

不涉及 Git provider —— 直接 HTTP 请求
自定义 payload 格式 —— 由你控制结构
无需实际 Git commit 也可触发 pipeline
适用于外部集成和手动触发

配置传入 Webhook

在 Repository CR 中启用：向你的 Repository CR 添加传入 webhook 配置：

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: "https://gitlab.com/user/repo"
  git_provider:
    type: gitlab
    url: "https://gitlab.com"
    secret:
      name: gitlab-secret
      key: token
    webhook_secret:
      name: webhook-secret
      key: secret
  # Incoming webhook configuration
  incoming:
  - type: webhook-url
    secret:
      name: incoming-webhook-secret
      key: secret

创建传入 webhook secret：

kubectl create secret generic incoming-webhook-secret \
  --from-literal=secret=your-incoming-webhook-secret \
  -n project-pipelines

获取传入 webhook URL：

传入 webhook 端点为：

http://<pac-controller-url>/incoming

URL 参数（可选，也可以通过 headers 传递）：

repository：Repository CR 名称
namespace：Repository CR 所在的 namespace
secret：传入 webhook secret 值

使用 query parameter 的示例：

http://pac.example.com/incoming?repository=my-repo&namespace=project-pipelines&secret=your-secret

使用 headers 的示例（推荐用于安全性）：

http://pac.example.com/incoming

使用 headers：X-Repository、X-Namespace、X-Secret

安全最佳实践

使用 headers（X-Repository、X-Namespace、X-Secret）而不是 query parameter，以避免在 URL 和日志中暴露 secret。

通过传入 Webhook 触发 Pipeline

向传入 webhook 端点发送 POST 请求：

curl -X POST \
  http://pac.example.com/incoming \
  -H "Content-Type: application/json" \
  -H "X-Repository: my-repo" \
  -H "X-Namespace: project-pipelines" \
  -H "X-Secret: your-incoming-webhook-secret" \
  -d '{
"ref": "refs/heads/main",
"sha": "abc123def456...",
"repository": {
  "url": "https://gitlab.com/user/repo"
}
  }'

传入 Webhook Payload

传入 webhook 接受具有以下结构的 JSON payload：

{
  "ref": "refs/heads/main",
  "sha": "commit-sha",
  "repository": {
    "url": "https://gitlab.com/user/repo",
    "name": "repo-name",
    "full_name": "user/repo"
  },
  "sender": {
    "login": "username"
  },
  "head_commit": {
    "message": "Commit message",
    "author": {
      "name": "Author Name",
      "email": "author@example.com"
    }
  }
}

自定义 Parameter

你可以在 webhook payload 中传递自定义 parameter：

{
  "ref": "refs/heads/main",
  "sha": "abc123...",
  "repository": {
    "url": "https://gitlab.com/user/repo"
  },
  "params": {
    "environment": "production",
    "deploy": "true"
  }
}

这些 parameter 可在 pipeline 中通过 $(params.environment) 和 $(params.deploy) 使用。

安全注意事项

使用 secret：始终使用 webhook secret 来验证请求
HTTPS：在生产环境中为 webhook 端点使用 HTTPS
网络策略：限制对传入 webhook 端点的访问
速率限制：实施速率限制以防止滥用
验证 payload：在处理之前验证传入的 payload

传入 Webhooks 故障排查

检查 webhook URL：确认 URL 正确且可访问
验证 secret：确保请求中的 secret 与 Repository CR 中的 secret 匹配

检查 PAC 日志：

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep incoming  # Replace <pac-namespace> with your actual namespace (default: tekton-pipelines)

验证 Repository CR：确保传入 webhook 配置正确
使用 curl 测试：使用 curl 测试 webhook 端点

最佳实践

1. PipelineRun 管理

设置清理限制：使用 max-keep-runs 防止积压
监控资源：关注 PipelineRun 带来的资源使用情况
归档重要运行：在清理之前导出重要的 PipelineRun

2. 监控

使用标签：为 PipelineRun 添加标签，便于筛选
设置告警：为失败的 PipelineRun 配置告警
定期审查：定期检查 PipelineRun 状态和日志

3. 传入 Webhooks

保护端点：始终使用 HTTPS 和 secret
验证 payload：验证传入的 webhook payload
记录用法：记录 webhook 端点和 payload 格式
充分测试：在生产使用前充分测试 webhook 触发

故障排查

未创建 PipelineRun

检查 webhook：验证 webhook 已正确配置并正在接收事件
检查 Repository CR：确保 Repository CR 配置正确
检查 PAC 日志：查看 PAC controller 日志中的错误
验证 pipeline 文件：确保仓库中存在 pipeline 定义文件

PipelineRun 未运行

检查状态：查看 PipelineRun 状态和条件
检查日志：检查 PipelineRun 和 TaskRun 日志
验证资源：确保集群资源充足
检查权限：验证 ServiceAccount 是否具有所需权限

状态未报告

验证 Git provider 令牌：确保令牌具有所需的 scope
检查 PAC Watcher：验证 PAC Watcher 正在运行
检查日志：查看 PAC Watcher 日志中的错误
测试连通性：确保 PAC 能够访问 Git provider API

下一步

触发 PAC Pipelines - 自动事件和注释命令
在 Git 中定义 PipelineRun - PipelineRun 文件和触发注解
指南 - Repository 设置流程
常见问题 - 故障排查指南

#传入 Webhooks

#目录

#概述

#配置传入 Webhook

#通过传入 Webhook 触发 Pipeline

#传入 Webhook Payload

#自定义 Parameter

#安全注意事项

#传入 Webhooks 故障排查

#最佳实践

#1. PipelineRun 管理

#2. 监控

#3. 传入 Webhooks

#故障排查

#未创建 PipelineRun

#PipelineRun 未运行

#状态未报告

#下一步