forked from Gitlink/gitlink-cli
379 lines
9.5 KiB
Markdown
379 lines
9.5 KiB
Markdown
# gitlink-cli webhook +test
|
||
|
||
测试 Webhook 连接性，发送测试事件验证 Webhook 是否正常工作。
|
||
|
||
## 命令格式
|
||
|
||
```bash
|
||
gitlink-cli webhook +test \
|
||
[--owner OWNER] \
|
||
[--repo REPO] \
|
||
--id WEBHOOK_ID \
|
||
[--event EVENT_TYPE]
|
||
```
|
||
|
||
## 参数说明
|
||
|
||
| 参数 | 短参数 | 说明 | 是否必须 | 默认值 |
|
||
|------|--------|------|----------|--------|
|
||
| `--owner` | `-o` | 仓库所有者 | 否 | 自动从 git remote 解析 |
|
||
| `--repo` | `-r` | 仓库名称 | 否 | 自动从 git remote 解析 |
|
||
| `--id` | `-i` | Webhook ID | **是** | - |
|
||
| `--event` | `-e` | 测试的事件类型 | 否 | `push` |
|
||
|
||
### 支持的测试事件
|
||
- `push` - 推送事件（默认）
|
||
- `pull_request` - Pull 请求事件
|
||
- `issue` - Issue 事件
|
||
- 其他支持的事件类型
|
||
|
||
## 返回值
|
||
|
||
### 成功返回
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"message": "Webhook test triggered successfully",
|
||
"webhook_id": "456",
|
||
"event_type": "push",
|
||
"delivered": true,
|
||
"response_status": 200,
|
||
"response_body": "Webhook received"
|
||
},
|
||
"meta": {
|
||
"identity": "user:myuser"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Webhook 不可达
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"message": "Webhook test completed with warnings",
|
||
"webhook_id": "456",
|
||
"event_type": "push",
|
||
"delivered": false,
|
||
"error": "Connection timeout",
|
||
"suggestion": "Please check if the webhook URL is accessible"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误返回
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": 404,
|
||
"message": "Webhook not found",
|
||
"suggestion": "Please check the webhook ID"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 基本测试
|
||
```bash
|
||
# 测试 Webhook（默认使用 push 事件）
|
||
gitlink-cli webhook +test --owner myuser --repo myrepo --id 456
|
||
|
||
# 在 git 仓库目录中测试
|
||
gitlink-cli webhook +test --id 456
|
||
|
||
# 使用短参数
|
||
gitlink-cli webhook +test -i 456
|
||
```
|
||
|
||
### 测试特定事件类型
|
||
```bash
|
||
# 测试 pull_request 事件
|
||
gitlink-cli webhook +test --id 456 --event pull_request
|
||
|
||
# 测试 issue 事件
|
||
gitlink-cli webhook +test --id 456 --event issue
|
||
|
||
# 测试多种事件类型
|
||
for event in push pull_request issue; do
|
||
echo "Testing event: $event"
|
||
gitlink-cli webhook +test --id 456 --event $event
|
||
done
|
||
```
|
||
|
||
### 批量测试所有 Webhook
|
||
```bash
|
||
# 测试仓库的所有 Webhook
|
||
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
|
||
echo "Testing webhook: $id"
|
||
gitlink-cli webhook +test --id $id
|
||
done
|
||
```
|
||
|
||
### 测试新创建的 Webhook
|
||
```bash
|
||
# 创建后立即测试
|
||
WEBHOOK_ID=$(gitlink-cli webhook +create --url https://example.com/webhook --events push --format json | jq -r '.data.id')
|
||
echo "Testing new webhook: $WEBHOOK_ID"
|
||
gitlink-cli webhook +test --id $WEBHOOK_ID
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误
|
||
|
||
#### 1. Webhook 不存在
|
||
```bash
|
||
Error: [404] Webhook not found
|
||
```
|
||
**原因**: 指定的 Webhook ID 不存在
|
||
**解决方案**:
|
||
```bash
|
||
# 先列出所有 Webhook 找到正确 ID
|
||
gitlink-cli webhook +list
|
||
```
|
||
|
||
#### 2. 无效的事件类型
|
||
```bash
|
||
Error: unsupported event type: custom_event
|
||
```
|
||
**原因**: 指定了不支持的事件类型
|
||
**解决方案**:
|
||
```bash
|
||
# 查看支持的事件类型
|
||
gitlink-cli webhook +events
|
||
|
||
# 使用支持的事件类型
|
||
gitlink-cli webhook +test --id 456 --event push
|
||
```
|
||
|
||
#### 3. Webhook URL 不可达
|
||
```bash
|
||
Warning: Webhook delivery failed - Connection timeout
|
||
```
|
||
**原因**: Webhook URL 无法访问或服务器无响应
|
||
**解决方案**:
|
||
```bash
|
||
# 1. 检查 URL 是否正确
|
||
gitlink-cli webhook +info --id 456
|
||
|
||
# 2. 手动测试 URL
|
||
curl -X POST https://your-webhook-url.com/test
|
||
|
||
# 3. 检查服务器防火墙和网络设置
|
||
```
|
||
|
||
#### 4. SSL 证书问题
|
||
```bash
|
||
Warning: Webhook delivery failed - SSL certificate verify failed
|
||
```
|
||
**原因**: Webhook 服务器的 SSL 证书有问题
|
||
**解决方案**:
|
||
```bash
|
||
# 检查 SSL 证书
|
||
curl -v https://your-webhook-url.com/test
|
||
|
||
# 更新服务器的 SSL 证书
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 创建后测试
|
||
```bash
|
||
# 创建 Webhook 后立即测试
|
||
WEBHOOK_ID=$(gitlink-cli webhook +create --url $URL --events $EVENTS --format json | jq -r '.data.id')
|
||
if gitlink-cli webhook +test --id $WEBHOOK_ID; then
|
||
echo "Webhook created and tested successfully"
|
||
else
|
||
echo "Webhook test failed, please check configuration"
|
||
gitlink-cli webhook +delete --id $WEBHOOK_ID
|
||
fi
|
||
```
|
||
|
||
### 2. 更新后测试
|
||
```bash
|
||
# 更新 Webhook 后测试
|
||
gitlink-cli webhook +update --id 456 --url $NEW_URL
|
||
gitlink-cli webhook +test --id 456
|
||
```
|
||
|
||
### 3. 定期测试
|
||
```bash
|
||
# 定期测试所有 Webhook 确保正常工作
|
||
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
|
||
if ! gitlink-cli webhook +test --id $id; then
|
||
echo "WARNING: Webhook $id test failed"
|
||
fi
|
||
done
|
||
```
|
||
|
||
## AI Agent 使用建议
|
||
|
||
### 自动化测试流程
|
||
```bash
|
||
# AI Agent 测试 Webhook 的完整流程
|
||
test_and_fix_webhook() {
|
||
WEBHOOK_ID=$1
|
||
MAX_RETRIES=3
|
||
RETRY_COUNT=0
|
||
|
||
while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
|
||
echo "Testing webhook $WEBHOOK_ID (attempt $((RETRY_COUNT + 1))/$MAX_RETRIES)"
|
||
|
||
# 测试 Webhook
|
||
if gitlink-cli webhook +test --id $WEBHOOK_ID; then
|
||
echo "✓ Webhook test successful"
|
||
return 0
|
||
fi
|
||
|
||
# 测试失败，等待后重试
|
||
RETRY_COUNT=$((RETRY_COUNT + 1))
|
||
if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
|
||
echo "Test failed, waiting 5 seconds before retry..."
|
||
sleep 5
|
||
fi
|
||
done
|
||
|
||
echo "✗ Webhook test failed after $MAX_RETRIES attempts"
|
||
return 1
|
||
}
|
||
```
|
||
|
||
### 监控 Webhook 健康
|
||
```bash
|
||
# 定期检查所有 Webhook 的健康状态
|
||
check_all_webhooks_health() {
|
||
REPORT_FILE="webhook_health_report_$(date +%Y%m%d_%H%M%S).txt"
|
||
|
||
echo "Webhook Health Check Report - $(date)" > $REPORT_FILE
|
||
echo "=================================" >> $REPORT_FILE
|
||
|
||
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
|
||
webhook_info=$(gitlink-cli webhook +info --id $id --format json)
|
||
webhook_url=$(echo $webhook_info | jq -r '.data.hook_url')
|
||
webhook_status=$(echo $webhook_info | jq -r '.data.is_active')
|
||
|
||
echo -e "\nWebhook ID: $id" >> $REPORT_FILE
|
||
echo "URL: $webhook_url" >> $REPORT_FILE
|
||
echo "Active: $webhook_status" >> $REPORT_FILE
|
||
echo "Test Result:" >> $REPORT_FILE
|
||
|
||
if gitlink-cli webhook +test --id $id >> $REPORT_FILE 2>&1; then
|
||
echo "Status: HEALTHY ✓" >> $REPORT_FILE
|
||
else
|
||
echo "Status: UNHEALTHY ✗" >> $REPORT_FILE
|
||
fi
|
||
done
|
||
|
||
cat $REPORT_FILE
|
||
}
|
||
```
|
||
|
||
### 故障诊断
|
||
```bash
|
||
# 诊断 Webhook 问题
|
||
diagnose_webhook() {
|
||
WEBHOOK_ID=$1
|
||
|
||
echo "=== Webhook Diagnosis ==="
|
||
echo "Webhook ID: $WEBHOOK_ID"
|
||
echo
|
||
|
||
# 1. 检查 Webhook 是否存在
|
||
echo "1. Checking webhook existence..."
|
||
if ! gitlink-cli webhook +info --id $WEBHOOK_ID >/dev/null 2>&1; then
|
||
echo " ✗ Webhook not found"
|
||
return 1
|
||
fi
|
||
echo " ✓ Webhook exists"
|
||
|
||
# 2. 获取 Webhook 配置
|
||
echo "2. Webhook configuration:"
|
||
gitlink-cli webhook +info --id $WEBHOOK_ID
|
||
|
||
# 3. 测试网络连通性
|
||
echo "3. Testing network connectivity..."
|
||
WEBHOOK_URL=$(gitlink-cli webhook +info --id $WEBHOOK_ID --format json | jq -r '.data.hook_url')
|
||
if curl -s -o /dev/null -w "%{http_code}" "$WEBHOOK_URL" | grep -q "200\|301\|302"; then
|
||
echo " ✓ URL is accessible"
|
||
else
|
||
echo " ✗ URL is not accessible"
|
||
fi
|
||
|
||
# 4. 测试 Webhook
|
||
echo "4. Testing webhook delivery..."
|
||
if gitlink-cli webhook +test --id $WEBHOOK_ID; then
|
||
echo " ✓ Webhook test successful"
|
||
else
|
||
echo " ✗ Webhook test failed"
|
||
fi
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **测试限制**: 测试事件不会触发实际的业务逻辑，仅验证连通性
|
||
2. **请求格式**: 测试请求的格式与真实事件略有不同
|
||
3. **响应时间**: Webhook 应在 10 秒内响应，否则超时
|
||
4. **重试机制**: 测试失败不会触发 GitLink 的重试机制
|
||
5. **权限要求**: 需要仓库管理员权限
|
||
|
||
## 常见使用场景
|
||
|
||
### 场景1: 验证新 Webhook
|
||
```bash
|
||
# 创建 Webhook 后验证配置
|
||
WEBHOOK_ID=$(gitlink-cli webhook +create \
|
||
--url https://ci.example.com/webhook \
|
||
--events push,pull_request \
|
||
--format json | jq -r '.data.id')
|
||
|
||
# 测试各种事件类型
|
||
for event in push pull_request; do
|
||
echo "Testing $event event..."
|
||
gitlink-cli webhook +test --id $WEBHOOK_ID --event $event
|
||
done
|
||
```
|
||
|
||
### 场景2: 故障排查
|
||
```bash
|
||
# Webhook 未触发时进行测试
|
||
# 1. 检查 Webhook 是否激活
|
||
gitlink-cli webhook +info --id 456
|
||
|
||
# 2. 测试 Webhook 连通性
|
||
gitlink-cli webhook +test --id 456
|
||
|
||
# 3. 查看详细错误信息
|
||
gitlink-cli webhook +test --id 456 --debug
|
||
```
|
||
|
||
### 场景3: 批量验证
|
||
```bash
|
||
# 验证所有 Webhook 在服务器迁移后是否正常
|
||
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
|
||
echo "Testing webhook $id..."
|
||
if ! gitlink-cli webhook +test --id $id; then
|
||
echo "WARNING: Webhook $id needs attention"
|
||
# 可以在这里添加自动修复逻辑
|
||
fi
|
||
done
|
||
```
|
||
|
||
## 安全建议
|
||
|
||
1. **避免敏感数据**: 测试事件可能包含真实数据，注意隐私保护
|
||
2. **测试频率**: 不要过于频繁测试，避免对服务器造成压力
|
||
3. **错误信息**: 测试失败时的错误信息可能暴露系统细节
|
||
4. **访问控制**: 确保测试 URL 只暴露必要的信息
|
||
|
||
## 相关命令
|
||
|
||
- `webhook +list` - 列出所有 Webhook
|
||
- `webhook +info` - 查看 Webhook 详情
|
||
- `webhook +create` - 创建新 Webhook
|
||
- `webhook +update` - 更新 Webhook 配置
|
||
- `webhook +events` - 查看支持的事件类型
|