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 name 和 namespace 查找 Repository CR
Pipeline 触发：PAC 处理 payload 并触发匹配的 pipeline，类似于 Git webhook 事件
PipelineRun 创建：PAC 根据 payload 和 pipeline definitions 创建 PipelineRun

与 Git webhooks 的主要区别：

不涉及 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 name
namespace：Repository CR 所在的 namespace
secret：Incoming webhook secret value

使用 query parameters 的示例：

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 parameters，以避免在 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