📚 课程目录第4章事件驱动架构

4. 事件驱动架构：GitLab CI 事件类型与触发机制

事件驱动架构是 GitLab CI/CD 的核心运行模式。每一次代码变更、合并请求、标签推送或定时计划，都会产生一个事件。GitLab 通过内置的 Webhook 和 CI 触发器，将这些事件转化为流水线执行指令。理解事件类型与触发链路，是构建自动化 Runbook 联动故障定位体系的基础。

4.1 GitLab CI 事件类型全景

GitLab 支持四种主要事件类型，每种事件对应不同的业务场景和触发条件。下表从事件源、触发动作、典型用途三个维度进行对比：

事件类型	事件源	触发动作	典型用途
Push	代码仓库	向任意分支或标签推送 commit	持续集成、代码扫描、单元测试
Merge Request	合并请求	创建、更新、合并、关闭 MR	代码审查、预合并验证、合规检查
Tag	版本标签	创建或删除 Git 标签	版本发布、制品打包、生产部署
Schedule	定时器	按 cron 表达式周期性触发	夜间构建、定期安全扫描、数据备份

实战要点：在故障定位场景中，Push 和 Merge Request 事件是最常见的故障触发源。建议在流水线中为这两种事件分别配置独立的故障检测阶段，避免混合逻辑导致定位延迟。

4.2 事件触发链路与 Webhook 机制

事件从产生到驱动流水线执行，需要经过一条完整的触发链路。下图展示了 GitLab CI 事件驱动的核心架构：

  链路说明：事件源（Push/MR/Tag/Schedule）→ Webhook 接收器（GitLab 内部或外部）→ CI 触发器（基于  鉴权）→ 流水线执行。在故障定位场景中，Webhook 日志和触发器响应状态码是排查事件丢失或重复触发的关键证据。

4.3 Push 事件与分支过滤

Push 事件是最频繁的触发源。在 .gitlab-ci.yml 中，通过 only/except 或 rules 关键字实现分支级过滤：

# 仅当推送到 main 或 release/* 分支时触发
build-job:
  stage: build
  script:
    - echo "Building for production branch"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
    - if: '$CI_COMMIT_BRANCH =~ /^release\//'
    - when: never

# 排除 WIP 分支的触发
test-job:
  stage: test
  script:
    - echo "Running tests"
  except:
    - /^wip-.*/

故障定位提示：Push 事件未触发流水线时，优先检查 rules 条件是否覆盖了目标分支。使用 CI_COMMIT_BRANCH 和 CI_PIPELINE_SOURCE 变量在流水线中打印当前事件上下文，可快速定位过滤逻辑问题。

4.4 Merge Request 事件与预合并验证

Merge Request 事件支持细粒度的动作过滤：open、reopen、update、merge。在故障定位 Runbook 中，MR 事件常用于触发预合并代码审查和集成测试：

# MR 事件触发预合并流水线
mr-validation:
  stage: test
  script:
    - echo "Validating merge request"
  only:
    - merge_requests
  variables:
    CI_MERGE_REQUEST_EVENT_TYPE: "merged_result"  # 使用合并结果

MR 动作	CI 变量	典型故障场景
open	`CI_MERGE_REQUEST_ACTION=open`	新 MR 未触发流水线
update	`CI_MERGE_REQUEST_ACTION=update`	代码推送后 MR 流水线未重新运行
merge	`CI_MERGE_REQUEST_ACTION=merge`	合并后部署流水线未触发

4.5 Tag 事件与版本发布

Tag 事件通常与版本发布流水线绑定。通过 only: tags 或 rules:if: $CI_COMMIT_TAG 实现：

# Tag 事件触发生产部署
deploy-production:
  stage: deploy
  script:
    - echo "Deploying version $CI_COMMIT_TAG"
  only:
    - tags
  except:
    - branches

最佳实践：在 Tag 事件流水线中，始终使用 CI_COMMIT_TAG 变量作为版本号。故障定位时，检查 Tag 名称是否符合 v*.*.* 格式，避免因命名不规范导致触发失败。

4.6 Schedule 事件与定时任务

Schedule 事件通过 GitLab UI 配置 cron 表达式，适合执行非代码变更触发的周期性任务：

# 每天凌晨 2 点执行安全扫描
security-scan:
  stage: test
  script:
    - echo "Running scheduled security scan"
  only:
    - schedules
  variables:
    CI_PIPELINE_SOURCE: "schedule"

Schedule 事件在故障定位中的常见用途：

定期健康检查：每小时触发一次基础设施连通性测试
日志归档：每日凌晨触发日志收集与压缩流水线
基线对比：每周触发配置基线扫描，与上次结果对比生成差异报告

4.7 Webhook 与 CI 触发器的联动机制

Webhook 是 GitLab 事件向外部系统传递的桥梁。在故障定位场景中，Webhook 与 CI 触发器的联动关系如下图所示：

  联动故障定位要点：
  Webhook 发送失败时，检查 GitLab 项目设置 → Webhooks 中的 Recent events 日志，查看 HTTP 响应码和错误信息
CI 触发器未执行时，验证 Trigger  是否有效，以及 CI_JOB_ 权限范围
外部 Runbook 系统需实现 Webhook 重试机制，建议指数退避策略（1s、2s、4s、8s）

4.8 事件触发故障定位清单

当流水线未按预期触发时，按以下清单逐项排查：

确认事件类型：检查 CI_PIPELINE_SOURCE 变量值是否为 push、merge_request_event、tag 或 schedule
验证分支/标签规则：查看 rules 或 only/except 条件是否匹配当前事件
检查 Webhook 日志：在 GitLab UI → Settings → Webhooks 中查看最近事件状态
确认触发器 ：确保 CI_JOB_ 或自定义未过期且权限正确
查看流水线触发历史：在 CI/CD → Pipelines 页面按事件源过滤，确认是否有触发记录

常见陷阱：Schedule 事件不会触发 only: merge_requests 或 only: tags 的流水线。如果定时任务需要执行特定作业，必须在 rules 中显式包含 if: '$CI_PIPELINE_SOURCE == "schedule"'。