3. CI触发器异常：Push/MR/Tag事件未触发Pipeline、定时任务未执行、手动触发权限不足

触发器是CI/CD流水线的“起跑线”。当代码推送、合并请求、标签创建等事件未能正确触发Pipeline，或定时任务“失约”、手动触发按钮灰化时，整个交付流程将陷入停滞。本章聚焦三类触发器异常的根因定位与修复方法。

3.1 触发器异常全景分类

根据触发方式与事件源，CI触发器异常可分为以下三类，每类对应不同的排查路径：

3.2 Push/MR/Tag事件未触发Pipeline

这是最频繁的触发器故障。当开发者执行 git push 或创建MR后，预期中的Pipeline没有出现。以下按排查链路逐一分析。

3.2.1 CI文件缺失或路径错误

平台引擎默认在仓库根目录查找 .gitlab-ci.yml（GitLab）或 Jenkinsfile（Jenkins）。若文件位于子目录或命名不符，触发器将静默跳过。

# 错误示例：CI文件放在 .ci/ 目录下，但未在平台配置中指定路径
# GitLab 需在 Settings → CI/CD → General pipelines 中设置：
#   Custom CI config path: .ci/.gitlab-ci.yml

# GitHub Actions 需在 .github/workflows/ 目录下放置 .yml 文件
# 若文件名拼写错误（如 ci.yml 而非 ci.yaml），也会被忽略

3.2.2 分支/标签过滤规则不匹配

CI配置中的 only/except 或 rules 关键字定义了触发条件。若推送的分支不在允许列表中，Pipeline不会启动。

# 以下配置仅允许 main 和 develop 分支触发
# 若推送到 feature/xxx 分支，Pipeline 不会运行
rules:
  - if: '$CI_COMMIT_BRANCH == "main"'
    when: always
  - if: '$CI_COMMIT_BRANCH == "develop"'
    when: always
  - when: never

# 排查方法：在CI/CD日志中查看 "Rules evaluation" 部分
# 确认当前分支是否匹配任何规则

3.2.3 Webhook配置失效（外部集成场景）

当平台使用Webhook连接外部代码源（如GitHub触发Jenkins）时，Webhook的URL、Secret 或SSL证书问题会导致事件丢失。

3.3 定时任务未执行

定时任务（Scheduled Pipeline）用于夜间构建、定期测试或数据备份。当任务“失约”时，需从时间配置与平台状态两方面排查。

3.3.1 Cron表达式与时区偏差

平台默认使用UTC时间，而开发者常按本地时区（如UTC+8）配置。例如，期望每天上午10:00（北京时间）执行，但cron写为 0 10 * * *，实际会在UTC 10:00（北京时间18:00）触发。

# 正确做法：将本地时间转换为UTC
# 期望北京时间 10:00 → UTC 02:00
# cron 表达式应为：0 2 * * *

# 排查命令：在平台调度器容器内查看当前时区
date
# 若输出 UTC，则所有定时配置均需按UTC计算

3.3.2 定时器被禁用或冲突

部分平台允许手动启用/禁用定时任务。若任务被禁用，即使cron正确也不会触发。此外，同一项目下多个定时任务若cron表达式相同，可能产生资源竞争或触发失败。

3.4 手动触发权限不足

当用户点击“Run Pipeline”或通过API手动触发时，返回403或按钮灰化，通常与角色权限、令牌作用域或分支保护有关。

3.4.1 角色与权限模型

不同平台对“手动触发”的权限要求不同。下表列出主流平台的最小权限要求：

3.4.2 受保护分支与Tag限制

若手动触发时选择的分支或Tag被标记为“受保护”，且用户不在允许列表中，触发将被拒绝。

# GitLab 受保护分支设置路径：
# Settings → Repository → Protected branches
# 确认当前用户是否在 "Allowed to merge" 或 "Allowed to push" 列表中

# Jenkins 中类似限制通过 "Branch Specifier" 和 "Git Parameter" 插件实现
# 若分支名包含通配符（如 release/*），需确保用户有对应权限

3.4.3 API令牌作用域不足

通过API手动触发时，使用的Personal Access 或Project Access 必须包含 api 或 write_repository 作用域。

# 错误示例：使用只读令牌触发Pipeline
curl --header "PRIVATE-: <read_only_>" \
  "https://gitlab.example.com/api/v4/projects/1/trigger/pipeline"
# 返回 403 Forbidden

# 正确做法：生成令牌时勾选 "api" 作用域
# 或使用CI/CD专用触发器令牌（Settings → CI/CD → Pipeline triggers）

3.5 触发器异常排查流程图

以下SVG图总结了从事件发生到Pipeline启动的完整链路，以及各环节的故障点与排查动作。

3.6 典型故障案例与修复

以下三个案例覆盖了本章三类异常，每个案例均包含现象、根因与修复步骤。

案例一：Push事件未触发，CI文件在子目录

• 现象： 开发者推送代码到 feature/xxx 分支，GitLab Pipeline列表为空。
• 根因： CI文件位于 .gitlab/ci-templates/main.yml，但项目未设置自定义CI路径。
• 修复： 进入 Settings → CI/CD → General pipelines，在“Custom CI config path”中输入 .gitlab/ci-templates/main.yml，保存后重新推送。

案例二：定时任务未执行，时区偏差

• 现象： 配置了 0 9 * * * 期望每天北京时间9:00执行，但实际从未触发。
• 根因： GitLab调度器使用UTC时间，0 9 * * * 对应UTC 9:00（北京时间17:00），且该时间点无代码变更。
• 修复： 将cron改为 0 1 * * *（UTC 1:00 = 北京时间9:00），并确认时区设置。

案例三：手动触发按钮灰化，受保护分支限制

• 现象： 项目管理员尝试手动触发 release/1.0 分支的Pipeline，按钮不可点击。
• 根因： release/1.0 被设置为受保护分支，且当前用户不在“Allowed to push”列表中。
• 修复： 进入 Settings → Repository → Protected branches，将用户添加到允许列表，或临时取消分支保护。