Incoming Webhooks

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

概述配置 Incoming Webhook 通过 Incoming Webhook 触发 Pipeline Incoming Webhook Payload 自定义参数安全注意事项排查 Incoming Webhooks 问题最佳实践 1. PipelineRun 管理 2. 监控 3. Incoming Webhooks 故障排查 PipelineRun 未创建 PipelineRun 未运行未报告状态下一步

概述

Incoming webhooks 提供了一种方式来：

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

Incoming 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 webhook 的主要区别：

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

配置 Incoming Webhook

在 Repository CR 中启用：向你的 Repository CR 添加 incoming 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

创建 incoming webhook secret：

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

获取 incoming webhook URL：

Incoming webhook 端点为：

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

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

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

带 query 参数的示例：

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 参数，以避免在 URL 和日志中暴露 secret。

通过 Incoming Webhook 触发 Pipeline

向 incoming 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"
}
  }'

Incoming Webhook Payload

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

自定义参数

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

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

这些参数可在你的 pipeline 中通过 $(params.environment) 和 $(params.deploy) 访问。

安全注意事项

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

排查 Incoming 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：确保 incoming webhook 配置正确
使用 curl 测试：使用 curl 测试 webhook 端点

最佳实践

1. PipelineRun 管理

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

2. 监控

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

3. Incoming Webhooks

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

故障排查

PipelineRun 未创建

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

PipelineRun 未运行

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

未报告状态

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

下一步

触发 Pipeline - 了解不同的触发方式
在 Git 中定义 PipelineRun - PipelineRun 文件和触发注解
指南 - Repository 设置教程
常见问题 - 故障排查指南

#Incoming Webhooks

#目录

#概述

#配置 Incoming Webhook

#通过 Incoming Webhook 触发 Pipeline

#Incoming Webhook Payload

#自定义参数

#安全注意事项

#排查 Incoming Webhooks 问题

#最佳实践

#1. PipelineRun 管理

#2. 监控

#3. Incoming Webhooks

#故障排查

#PipelineRun 未创建

#PipelineRun 未运行

#未报告状态

#下一步