#Incoming Webhooks

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

#概述

Incoming webhooks 提供了一种方式来：

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

#配置 Incoming Webhook

1. 在 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

2. 创建 incoming webhook secret：

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

3. 获取 incoming webhook URL：

Incoming webhook endpoint 为：

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

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

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

带 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

#通过 Incoming Webhook 触发 Pipeline

向 incoming webhook endpoint 发送 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) 访问。

#安全注意事项

1. 使用 secret：始终使用 webhook secret 来验证请求
2. HTTPS：在生产环境中为 webhook endpoint 使用 HTTPS
3. 网络策略：限制对 incoming webhook endpoint 的访问
4. 限流：实现限流以防止滥用
5. 验证 payload：在处理前验证 incoming payload

#排查 Incoming Webhooks 问题

1. 检查 webhook URL：确认 URL 正确且可访问

2. 验证 secret：确保请求中的 secret 与 Repository CR 中的 secret 一致

3. 检查 PAC logs：

   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)

4. 验证 Repository CR：确保 incoming webhook 配置正确

5. 使用 curl 测试：使用 curl 测试 webhook endpoint

#最佳实践

#1. PipelineRun 管理

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

#2. 监控

• 使用 labels：为 PipelineRuns 添加 label，便于筛选
• 设置告警：为失败的 PipelineRuns 配置告警
• 定期审查：定期检查 PipelineRun 状态和 logs

#3. Incoming Webhooks

• 保护 endpoint：始终使用 HTTPS 和 secret
• 验证 payload：验证 incoming webhook payload
• 记录用法：记录 webhook endpoint 和 payload 格式
• 充分测试：在生产使用前充分测试 webhook 触发

#故障排查

#未创建 PipelineRun

1. 检查 webhook：确认 webhook 已配置并正在接收 events
2. 查看 Repository CR：确保 Repository CR 配置正确
3. 检查 PAC logs：查看 PAC controller logs 中的错误
4. 验证 pipeline 文件：确保 repository 中存在 pipeline 定义文件

#PipelineRun 未运行

1. 检查状态：查看 PipelineRun 状态和 conditions
2. 查看 logs：检查 PipelineRun 和 TaskRun logs
3. 验证资源：确保集群资源充足
4. 检查权限：验证 ServiceAccount 具有所需权限

#未报告状态

1. 验证 Git provider token：确保 token 具有所需 scopes
2. 检查 PAC Watcher：验证 PAC Watcher 正在运行
3. 查看 logs：检查 PAC Watcher logs 中的错误
4. 测试连通性：确保 PAC 能够访问 Git provider API

#下一步

• Trigger PAC Pipelines - 自动 events 和 comment commands
• Define PipelineRuns in Git - PipelineRun 文件和 trigger annotations
• Guides - Repository 设置指南
• Common Issues - 故障排查指南