novalon-website/TROUBLESHOOTING_AUTO_TRIGGER.md

Woodpecker CI 自动触发问题完整排查指南

📋 问题现象

• ✅ 手动触发 CI 可以正常工作
• ❌ 推送代码后 CI 不会自动触发

---

🔍 排查步骤（按优先级）

步骤 1: 检查 Git Webhook 配置 ⭐⭐⭐⭐⭐

这是最可能的原因！

操作步骤

1. 访问 Git 仓库设置页面：

   https://git.f.novalon.cn/novalon/novalon-website/settings/hooks
   

2. 检查是否存在 Woodpecker CI 的 Webhook：

   • ✅ 如果存在 → 继续步骤 3
   • ❌ 如果不存在 → 执行步骤 2

3. 查看 Webhook 详情：

   • URL: 应该是 http://woodpecker-server/hook 或类似格式
   • Secret: 如果配置了，确保与 Woodpecker CI 一致
   • Trigger events: 必须包含 Push events

4. 查看 "Recent Deliveries"：

   • ✅ 如果有记录 → 查看响应状态码（应该是 200）
   • ❌ 如果没有记录 → Webhook 未触发，检查触发事件配置

如何添加 Webhook

如果 Webhook 不存在，需要添加：

# Webhook URL 格式
http://your-woodpecker-server/hook

# 或使用 Secret
http://your-woodpecker-server/hook?secret=your-secret

# 触发事件
✅ Push events
✅ Pull request events
✅ Tag push events（可选）

---

步骤 2: 检查 Woodpecker CI 仓库设置 ⭐⭐⭐⭐

操作步骤

1. 访问 Woodpecker CI Web 界面
2. 选择 novalon/novalon-website 仓库
3. 点击仓库设置（Settings）

检查项

• Active: ✅ 必须启用
• Trusted: ✅ 建议启用（允许使用 volumes 等特权操作）
• Protected: ❌ 如果启用，会限制自动触发
• Configuration: 确认配置文件路径正确（.woodpecker.yml）

---

步骤 3: 检查 Woodpecker CI 全局配置 ⭐⭐⭐

如果可以访问 Woodpecker CI 服务器：

检查环境变量

# 查看 Woodpecker CI 容器环境变量
docker exec woodpecker-server env | grep WOODPECKER

# 关键环境变量
WOODPECKER_OPEN=true                    # 允许公开访问
WOODPECKER_HOST=http://your-server      # 服务器地址
WOODPECKER_WEBHOOK_HOST=http://your-server  # Webhook 地址

检查日志

# 查看 Woodpecker CI 日志
docker logs woodpecker-server --tail 100

# 查找 webhook 相关日志
docker logs woodpecker-server 2>&1 | grep -i webhook

---

步骤 4: 检查配置文件语法 ⭐⭐

使用 YAML 验证器

# 安装 yamllint
pip install yamllint

# 验证配置文件
yamllint .woodpecker.yml

在线验证

访问 https://www.yamllint.com/ 粘贴配置文件内容验证。

---

步骤 5: 检查提交信息 ⭐

确认提交信息不包含跳过 CI 的关键词：

# 查看最近的提交信息
git log --oneline -5

# 跳过 CI 的关键词（避免使用）
[skip ci]
[ci skip]
[no ci]
***NO_CI***

---

🛠️ 快速测试方案

方案 1: 使用简化的配置文件

创建 .woodpecker-test.yml：

steps:
  test:
    image: alpine
    commands:
      - echo "CI is working!"

然后在 Woodpecker CI 设置中将配置文件改为 .woodpecker-test.yml。

方案 2: 手动触发测试

1. 在 Woodpecker CI 界面手动触发 Pipeline
2. 观察是否能正常执行
3. 如果手动触发正常，说明配置文件没问题，问题在 Webhook

方案 3: 检查 Webhook 发送记录

在 Git 仓库的 Webhook 设置中：

1. 找到 "Recent Deliveries"
2. 查看最近的发送记录
3. 点击查看详情：
   • Request: 查看发送的数据
   • Response: 查看服务器响应
   • Status code: 应该是 200

---

📊 常见问题及解决方案

问题 1: Webhook 发送失败（404 Not Found）

原因: Woodpecker CI 仓库未激活

解决:

1. 访问 Woodpecker CI Web 界面
2. 找到并激活 novalon/novalon-website 仓库

---

问题 2: Webhook 发送失败（401 Unauthorized）

原因: Webhook Secret 不匹配

解决:

1. 检查 Woodpecker CI 的 WOODPECKER_WEBHOOK_SECRET 配置
2. 在 Git Webhook 设置中配置相同的 Secret

---

问题 3: Webhook 发送成功但 CI 未触发

原因: 配置文件中的 when 条件限制

解决:

1. 检查配置文件中的 when 条件
2. 确保包含正确的分支和事件
3. 临时移除 when 条件测试

---

问题 4: Woodpecker CI 日志显示 "repo not found"

原因: 仓库权限问题

解决:

1. 在 Woodpecker CI 中重新授权访问仓库
2. 检查 OAuth token 是否过期

---

🎯 推荐操作流程

立即执行（5分钟）

1. 检查 Git Webhook 配置

   • 访问仓库设置 → Webhooks
   • 确认有 Woodpecker CI 的 Webhook
   • 查看 "Recent Deliveries"

2. 手动触发测试

   • 在 Woodpecker CI 中手动触发 Pipeline
   • 确认配置文件正确

短期执行（30分钟）

1. 重新配置 Webhook（如果需要）

   • 删除旧的 Webhook
   • 添加新的 Webhook
   • 测试发送

2. 检查 Woodpecker CI 设置

   • 确认仓库已激活
   • 启用 "Trusted" 选项
   • 取消分支保护

中期执行（如果问题持续）

1. 查看 Woodpecker CI 日志

   • 检查服务器日志
   • 查找错误信息

2. 联系管理员

   • 如果没有服务器访问权限
   • 提供详细的错误信息

---

📝 诊断信息收集

如果以上步骤都无法解决，请收集以下信息：

# 1. Git Webhook 配置截图
# 2. Webhook "Recent Deliveries" 截图
# 3. Woodpecker CI 仓库设置截图
# 4. 手动触发的 Pipeline 日志
# 5. 配置文件内容

---

✅ 成功标志

当以下条件满足时，CI 应该能够自动触发：

• ✅ Git Webhook 配置正确且有发送记录
• ✅ Woodpecker CI 仓库已激活
• ✅ 配置文件语法正确
• ✅ when 条件包含当前分支
• ✅ 提交信息不包含跳过关键词

---

最后更新: 2026-03-28