📚 课程目录第3章 GitLab CI/CD基础

3. GitLab 仓库配置：创建项目、配置 Webhook、管理分支策略

GitLab 仓库是流水线的起点，也是代码、CI/CD 配置、环境变量和分支策略的载体。本章将完成从项目创建到 Webhook 触发、再到分支保护的全链路配置，确保蓝绿发布流水线在正确的仓库结构上安全运行。

3.1 创建 GitLab 项目

在 GitLab 中，每个微服务或应用对应一个独立项目。推荐使用 Group 组织多个服务，便于权限继承和跨项目 CI/CD 变量共享。

配置项	推荐值	说明
Project name	`blue-green-demo`	与流水线名称一致，便于识别
Visibility Level	Private	生产级项目必须私有，防止泄露 Secrets
Initialize repository with a README	勾选	快速获得默认分支（main）
Default branch	`main`	作为生产发布基线

最佳实践： 在 Group 级别创建 CI/CD 变量（如 KUBECONFIG、REGISTRY_PASSWORD），子项目自动继承，避免重复配置。

3.2 配置 Webhook：连接 GitLab 与 CI/CD 触发器

Webhook 是 GitLab 事件（如 push、merge request）向外部系统发送 HTTP 通知的机制。在蓝绿发布场景中，Webhook 用于触发 Jenkins、ArgoCD 或自研流水线引擎。

3.2.1 Webhook 配置步骤

进入项目 Settings → Webhooks。
填写 URL：指向 CI/CD 系统的接收端点（如 Jenkins Generic Webhook Trigger）。
选择 Trigger：至少勾选 Push events 和 Merge request events。
设置 Secret ：用于验证请求来源，防止伪造。
点击 Add webhook，并执行 Test 验证连通性。

  安全要点： Secret  必须使用强随机字符串（至少 32 位），并存储在 CI/CD 系统的凭据管理中。不要在代码或日志中明文记录。

3.2.2 Webhook 事件与蓝绿发布映射

GitLab 事件	触发时机	蓝绿发布动作
Push to main	代码合并到生产分支	触发构建 → 部署到 Green 环境 → 健康检查 → 切换流量
Push to feature/*	功能分支推送	触发单元测试 + 镜像构建（不部署）
Merge request opened	创建 MR	触发预发布环境部署（Blue 或临时环境）
Tag push	打版本标签	触发生产级蓝绿发布（带版本回滚能力）

常见陷阱： 不要对 Push to main 和 Tag push 同时配置相同的 Webhook URL，否则会导致重复触发。建议 Tag push 使用独立的流水线路径。

3.3 分支策略管理

蓝绿发布要求分支模型清晰、权限严格。推荐采用 Trunk-Based Development 配合 GitFlow 简化版，确保 main 分支始终可发布。

3.3.1 分支命名规范

main：生产就绪分支，只允许通过 Merge Request 合并。
release/x.y.z：发布候选分支，用于蓝绿部署前的最终验证。
feature/<issue-id>-<description>：功能开发分支，短生命周期。
hotfix/<issue-id>-<description>：紧急修复分支，直接基于 main 创建。

3.3.2 分支保护规则

在 Settings → Repository → Protected Branches 中配置：

分支	允许合并	允许推送	允许强制推送	代码所有者审核
`main`	Maintainer + Owner	不允许	不允许	必需（至少 1 人）
`release/*`	Maintainer + Owner	Maintainer + Owner	不允许	可选
`feature/*`	Developer + Maintainer	Developer + Maintainer	不允许	不强制

蓝绿发布专用规则： 在 main 分支上启用 Pipeline must succeed 和 Deployments must succeed 作为合并条件，确保只有通过蓝绿验证的代码才能进入生产。

3.4 分支策略与蓝绿发布流程 SVG

下图展示了从功能分支到蓝绿发布的完整分支流转与 Webhook 触发关系：

3.5 分支策略与 Secrets 环境映射

不同分支对应不同的部署环境，Secrets 的加载策略必须与分支绑定：

分支	目标环境	Secrets 来源	CI/CD 变量作用域
`feature/*`	开发环境 (Dev)	项目级 CI/CD 变量	仅当前流水线
`release/*`	预发布环境 (Staging)	Group 级 CI/CD 变量 + 环境变量覆盖	Group 内所有 release 流水线
`main`	生产环境 (Production)	Group 级 + 外部 Secrets Manager (Vault/AWS Secrets Manager)	仅 main 分支触发时加载
`hotfix/*`	生产环境 (紧急)	与 main 相同，但增加紧急审批标记	临时提升权限

  配置建议： 在 GitLab CI/CD 变量中，使用 Environment scopes 将敏感变量（如数据库密码、API ）限定到特定环境。例如：DB_PASSWORD 在 production 环境中使用 Vault 动态凭据，在 dev 环境中使用固定测试密码。

3.6 分支策略自动化检查

在 .gitlab-ci.yml 中增加分支合规性检查阶段，防止不符合策略的代码进入关键分支：

stages:
  - validate-branch
  - build
  - deploy

validate-branch:
  stage: validate-branch
  script:
    - |
      if [[ "$CI_COMMIT_BRANCH" =~ ^feature/ ]]; then
        echo "Feature branch detected. Running unit tests only."
      elif [[ "$CI_COMMIT_BRANCH" =~ ^release/ ]]; then
        echo "Release branch detected. Running full pre-deployment checks."
      elif [[ "$CI_COMMIT_BRANCH" == "main" ]]; then
        echo "Main branch detected. Triggering blue-green deployment."
      else
        echo "Branch name does not follow convention: $CI_COMMIT_BRANCH"
        exit 1
      fi
  only:
    - branches
  except:
    - tags

注意： 分支命名检查脚本应作为流水线的第一个阶段，失败则立即终止流水线，避免浪费构建资源。同时，该脚本不应包含任何 Secrets 或敏感逻辑。

3.7 本章小结

完成 GitLab 仓库配置后，团队将获得：

一个私有、受保护的项目仓库，main 分支不可直接推送。
Webhook 自动将代码事件转发到 CI/CD 系统，触发蓝绿发布流水线。
分支策略与 Secrets 环境映射清晰，生产环境凭据不会泄露到开发分支。
分支合规性检查作为流水线第一道门，确保代码质量与安全。

下一阶段将基于此仓库结构编写 .gitlab-ci.yml 流水线定义，实现从代码提交到蓝绿部署的完整自动化。