#入站 Webhook

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

#概述

入站 Webhook 提供了一种方式来：

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

#配置入站 Webhook

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

2. 创建入站 webhook secret：

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

3. 获取入站 webhook URL：

入站 webhook 端点为：

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

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

• 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

使用 header 的示例（推荐，更安全）：

http://pac.example.com/incoming

使用的 headers：X-Repository、X-Namespace、X-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"
    }
  }
}

#自定义参数

你可以在 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 端点使用 HTTPS
3. 网络策略：限制对入站 webhook 端点的访问
4. 速率限制：实现速率限制以防止滥用
5. 验证 payload：在处理之前验证入站 payload

#入站 Webhook 故障排查

1. 检查 webhook URL：验证 URL 是否正确且可访问

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

3. 检查 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)

4. 验证 Repository CR：确保入站 webhook 已正确配置

5. 使用 curl 测试：使用 curl 测试 webhook 端点

#最佳实践

#1. PipelineRun 管理

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

#2. 监控

• 使用 labels：为 PipelineRun 添加 labels 以便更轻松地筛选
• 设置告警：为失败的 PipelineRun 配置告警
• 定期审查：定期检查 PipelineRun 状态和日志

#3. 入站 Webhook

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

#故障排查

#PipelineRun 未创建

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

#PipelineRun 未运行

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

#未报告状态

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

#后续步骤

• 触发 Pipelines - 了解不同的触发方式
• 维护 Pipeline Code - Pipeline 定义指南
• 配置 Repository - Repository 设置
• 常见问题 - 故障排查指南