#Incoming Webhooks

传入 webhook 允许您通过 HTTP POST 请求直接触发 pipeline，无需依赖 Git 事件。

#Overview

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

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

#Configure Incoming 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
     # 传入 webhook 配置
     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 参数（可选，也可通过请求头传递）：

• repository：Repository CR 名称
• namespace：Repository CR 所在命名空间
• secret：传入 webhook secret 值

带查询参数的示例：

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

带请求头的示例（推荐用于安全）：

http://pac.example.com/incoming

请求头：X-Repository、X-Namespace、X-Secret

#Trigger Pipeline via Incoming Webhook

向传入 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

传入 webhook 接受如下结构的 JSON 负载：

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

#Custom Parameters

您可以在 webhook 负载中传递自定义参数：

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

这些参数可在您的 pipeline 中通过 $(params.environment) 和 $(params.deploy) 使用。

#Security Considerations

1. 使用 secret：始终使用 webhook secret 验证请求
2. HTTPS：生产环境中使用 HTTPS 保护 webhook 端点
3. 网络策略：限制对传入 webhook 端点的访问
4. 限流：实现限流以防止滥用
5. 验证负载：处理前验证传入负载

#Troubleshooting Incoming Webhooks

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

2. 验证 secret：确保请求和 Repository CR 中的 secret 匹配

3. 查看 PAC 日志：

   kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100 | grep incoming  # 将 <pac-namespace> 替换为实际命名空间（默认：tekton-pipelines）

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

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

#Best Practices

#1. PipelineRun 管理

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

#2. 监控

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

#3. 传入 Webhook

• 保护端点：始终使用 HTTPS 和 secret
• 验证负载：验证传入 webhook 负载
• 文档记录：记录 webhook 端点和负载格式
• 充分测试：生产使用前彻底测试 webhook 触发

#Troubleshooting

#PipelineRun 未创建

1. 检查 webhook：确认 webhook 已配置且接收事件
2. 查看 Repository CR：确保 Repository CR 配置正确
3. 查看 PAC 日志：检查 PAC 控制器日志中的错误
4. 验证 pipeline 文件：确认仓库中存在 pipeline 定义文件

#PipelineRun 未运行

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

#状态未报告

1. 验证 Git 提供者 token：确保 token 具备所需权限
2. 检查 PAC Watcher：确认 PAC Watcher 正常运行
3. 查看日志：检查 PAC Watcher 日志中的错误
4. 测试连通性：确保 PAC 能访问 Git 提供者 API

#Next Steps

• Trigger Pipelines - 了解不同的触发方式
• Maintain Pipeline Code - pipeline 定义指南
• Configure Repository - 仓库配置
• Common Issues - 故障排除指南