forked from Gitlink/gitlink-cli
278 lines
6.9 KiB
Markdown
278 lines
6.9 KiB
Markdown
# gitlink-cli webhook +update
|
||
|
||
更新现有 Webhook 的配置。
|
||
|
||
## 命令格式
|
||
|
||
```bash
|
||
gitlink-cli webhook +update \
|
||
--owner OWNER \
|
||
--repo REPO \
|
||
--id WEBHOOK_ID \
|
||
[--url URL] \
|
||
[--events EVENTS] \
|
||
[--active ACTIVE] \
|
||
[--content_type CONTENT_TYPE] \
|
||
[--secret SECRET] \
|
||
[--description DESCRIPTION]
|
||
```
|
||
|
||
## 参数说明
|
||
|
||
| 参数 | 短参数 | 说明 | 是否必须 | 默认值 |
|
||
|------|--------|------|----------|--------|
|
||
| `--owner` | `-o` | 仓库所有者 | 否 | 自动从 git remote 解析 |
|
||
| `--repo` | `-r` | 仓库名称 | 否 | 自动从 git remote 解析 |
|
||
| `--id` | `-i` | Webhook ID | **是** | - |
|
||
| `--url` | `-u` | 新的 Webhook URL | 否 | 不修改 |
|
||
| `--events` | `-e` | 新的触发事件 | 否 | 不修改 |
|
||
| `--active` | - | 是否激活 | 否 | 不修改 |
|
||
| `--content_type` | - | 内容类型 | 否 | 不修改 |
|
||
| `--secret` | - | 新的密钥 | 否 | 不修改 |
|
||
| `--description` | `-d` | 新的描述 | 否 | 不修改 |
|
||
|
||
## 返回值
|
||
|
||
### 成功返回
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"id": "456",
|
||
"hook_url": "https://new-url.example.com/webhook",
|
||
"events": ["push", "pull_request", "issue"],
|
||
"is_active": false,
|
||
"content_type": "json",
|
||
"description": "Updated webhook description",
|
||
"created_at": "2024-01-01T00:00:00Z",
|
||
"updated_at": "2024-01-02T12:00:00Z"
|
||
},
|
||
"meta": {
|
||
"identity": "user:myuser"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误返回
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": 404,
|
||
"message": "Webhook not found",
|
||
"suggestion": "Please check the webhook ID"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 更新 URL
|
||
```bash
|
||
# 修改 Webhook 回调地址
|
||
gitlink-cli webhook +update --owner myuser --repo myrepo --id 456 --url https://new-url.example.com/webhook
|
||
|
||
# 在 git 仓库目录中更新
|
||
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook
|
||
```
|
||
|
||
### 更新事件
|
||
```bash
|
||
# 添加更多事件类型
|
||
gitlink-cli webhook +update --id 456 --events push,pull_request,issue,issue_comment
|
||
|
||
# 减少事件类型（只监听 push）
|
||
gitlink-cli webhook +update --id 456 --events push
|
||
```
|
||
|
||
### 激活/停用 Webhook
|
||
```bash
|
||
# 停用 Webhook
|
||
gitlink-cli webhook +update --id 456 --active false
|
||
|
||
# 重新激活 Webhook
|
||
gitlink-cli webhook +update --id 456 --active true
|
||
```
|
||
|
||
### 更新密钥
|
||
```bash
|
||
# 更新 Webhook 密钥（推荐定期轮换）
|
||
gitlink-cli webhook +update --id 456 --secret new-secret-key-2024
|
||
```
|
||
|
||
### 更新描述
|
||
```bash
|
||
# 更新 Webhook 描述
|
||
gitlink-cli webhook +update --id 456 --description "Updated for new CI/CD pipeline"
|
||
```
|
||
|
||
### 批量更新多个属性
|
||
```bash
|
||
# 同时更新多个属性
|
||
gitlink-cli webhook +update \
|
||
--id 456 \
|
||
--url https://new-url.example.com/webhook \
|
||
--events push,pull_request,issue \
|
||
--secret new-secret \
|
||
--description "Comprehensive webhook update"
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误
|
||
|
||
#### 1. Webhook 不存在
|
||
```bash
|
||
Error: [404] Webhook not found
|
||
```
|
||
**原因**: 指定的 Webhook ID 不存在
|
||
**解决方案**:
|
||
```bash
|
||
# 先列出所有 Webhook 找到正确 ID
|
||
gitlink-cli webhook +list
|
||
```
|
||
|
||
#### 2. 无效的事件类型
|
||
```bash
|
||
Error: no valid events specified
|
||
```
|
||
**原因**: 指定了不支持的事件类型
|
||
**解决方案**:
|
||
```bash
|
||
# 查看支持的事件
|
||
gitlink-cli webhook +events
|
||
```
|
||
|
||
#### 3. 权限不足
|
||
```bash
|
||
Error: [403] You don't have permission to update webhooks
|
||
```
|
||
**原因**: 用户不是仓库管理员
|
||
**解决方案**: 确认您有仓库管理员权限
|
||
|
||
#### 4. 没有指定更新字段
|
||
```bash
|
||
Error: no fields specified for update
|
||
```
|
||
**原因**: 没有提供任何要更新的字段
|
||
**解决方案**: 至少指定一个要更新的字段
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 密钥轮换
|
||
```bash
|
||
# 定期更新密钥（建议每3个月）
|
||
gitlink-cli webhook +update --id 456 --secret $(openssl rand -hex 32)
|
||
```
|
||
|
||
### 2. 临时停用
|
||
```bash
|
||
# 临时停用 Webhook 进行维护
|
||
gitlink-cli webhook +update --id 456 --active false
|
||
|
||
# 维护完成后重新激活
|
||
gitlink-cli webhook +update --id 456 --active true
|
||
```
|
||
|
||
### 3. 渐进式更新
|
||
```bash
|
||
# 先测试新配置
|
||
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook --active false
|
||
gitlink-cli webhook +test --id 456
|
||
|
||
# 确认无误后激活
|
||
gitlink-cli webhook +update --id 456 --active true
|
||
```
|
||
|
||
## AI Agent 使用建议
|
||
|
||
### 批量更新 Webhook
|
||
```bash
|
||
# 为所有 Webhook 添加新事件
|
||
for id in $(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[].id'); do
|
||
# 获取当前事件
|
||
current_events=$(gitlink-cli webhook +info --id $id --format json | jq -r '.data.events | join(",")')
|
||
# 添加新事件
|
||
gitlink-cli webhook +update --id $id --events "$current_events,issue_comment"
|
||
done
|
||
```
|
||
|
||
### 验证更新
|
||
```bash
|
||
# 更新后立即验证
|
||
WEBHOOK_ID=456
|
||
gitlink-cli webhook +update --id $WEBHOOK_ID --url $NEW_URL
|
||
gitlink-cli webhook +info --id $WEBHOOK_ID
|
||
gitlink-cli webhook +test --id $WEBHOOK_ID
|
||
```
|
||
|
||
### 检查更新前后差异
|
||
```bash
|
||
# 查看更新前后配置差异
|
||
BEFORE=$(gitlink-cli webhook +info --id 456 --format json)
|
||
gitlink-cli webhook +update --id 456 --url $NEW_URL
|
||
AFTER=$(gitlink-cli webhook +info --id 456 --format json)
|
||
|
||
# 对比差异（需要 jq 工具）
|
||
echo "Before:" && echo "$BEFORE" | jq '.data'
|
||
echo "After:" && echo "$AFTER" | jq '.data'
|
||
```
|
||
|
||
## 安全建议
|
||
|
||
1. **密钥轮换**: 定期更新 Webhook 密钥，建议每3个月一次
|
||
2. **测试新配置**: 更新重要配置前先停用，测试后再激活
|
||
3. **备份配置**: 更新前记录原配置，便于回滚
|
||
4. **权限验证**: 确保只有授权用户能修改 Webhook
|
||
5. **审计日志**: 记录所有 Webhook 配置变更
|
||
|
||
## 注意事项
|
||
|
||
1. **部分更新**: 只更新指定的字段，未指定的字段保持不变
|
||
2. **ID 不变**: 更新不会改变 Webhook ID
|
||
3. **立即生效**: 更新后立即生效，除非停用 Webhook
|
||
4. **测试验证**: 建议更新后测试 Webhook 是否正常工作
|
||
5. **权限要求**: 需要仓库管理员权限
|
||
|
||
## 常见使用场景
|
||
|
||
### 场景1: 迁移 Webhook 到新服务器
|
||
```bash
|
||
# 更新 Webhook URL 到新服务器
|
||
gitlink-cli webhook +update --id 456 --url https://new-server.example.com/webhook
|
||
# 测试新地址
|
||
gitlink-cli webhook +test --id 456
|
||
```
|
||
|
||
### 场景2: 调整事件监听
|
||
```bash
|
||
# 原来只监听 push，现在增加 PR 监听
|
||
gitlink-cli webhook +update --id 456 --events push,pull_request
|
||
```
|
||
|
||
### 场景3: 安全密钥轮换
|
||
```bash
|
||
# 定期更新密钥提高安全性
|
||
NEW_SECRET=$(openssl rand -hex 32)
|
||
gitlink-cli webhook +update --id 456 --secret "$NEW_SECRET"
|
||
# 更新接收服务器的密钥配置
|
||
# 然后测试
|
||
gitlink-cli webhook +test --id 456
|
||
```
|
||
|
||
### 场景4: 临时维护
|
||
```bash
|
||
# 临时停用 Webhook
|
||
gitlink-cli webhook +update --id 456 --active false --description "Maintenance in progress"
|
||
|
||
# 维护完成后重新激活
|
||
gitlink-cli webhook +update --id 456 --active true --description "Production webhook"
|
||
```
|
||
|
||
## 相关命令
|
||
|
||
- `webhook +list` - 列出所有 Webhook
|
||
- `webhook +create` - 创建新 Webhook
|
||
- `webhook +info` - 查看 Webhook 详情
|
||
- `webhook +test` - 测试 Webhook
|