<![CDATA[下游触发分支规则（FANOUT_BRANCH 单原则）]]>下游触发分支规则（FANOUT_BRANCH 单原则）

1. 背景

在多仓库、多级触发（A -> B -> C）的场景中，如果每一跳都“按当前项目的运行分支”去触发下游，很容易发生分支漂移。

本规则的目标：

  • 200+ 项目尽量不改各自的 .gitlab-ci.yml
  • 不使用 GitLab API Token
  • 触发链路稳定、可预测

2. 唯一原则：FANOUT_BRANCH 贯穿

我们定义一个变量：FANOUT_BRANCH，表示“本次触发链路从最上游开始的分支”。

生成/继承规则：

  • 若上游已传入 FANOUT_BRANCH，则下游沿用该值
  • 否则默认 FANOUT_BRANCH = CI_COMMIT_BRANCH

每次触发下游时，都必须继续传递 FANOUT_BRANCH，从而保证多级触发不会漂移。

3. 下游触发分支的决定规则

3.1 显式指定优先（最重要）

如果项目在 variables: 中显式写了 DOWNSTREAM_BRANCH，例如：

variables:
  DOWNSTREAM_PROJECT: platform/deploy/blazor-app
  DOWNSTREAM_BRANCH: master

则表现为：

  • 永远触发下游的 master 分支
  • 即使当前上游在 feature/LT-49、bugfix/* 等分支上运行，也不会触发同名分支
  • FANOUT_BRANCH 仍会被传递到下游，但仅用于链路追踪/后续再触发，不参与本次分支选择

3.2 未显式指定时的默认行为

如果未显式设置 DOWNSTREAM_BRANCH，则默认：

  • DOWNSTREAM_BRANCH = FANOUT_BRANCH

即：上游在 feature/LT-49 运行时触发下游 feature/LT-49；上游在 master 运行时触发下游 master。

4. 关于 master/main

在“不使用 Token、不调用 API”的前提下，我们无法在触发前自动判断下游默认分支是 master 还是 main。

治理建议：

  • 公司内尽量统一主干命名为 master
  • 若少数仓库历史上使用 main，建议一次性调整为 master，之后无需在 200+ 项目侧维护差异

5. 适用范围

  • NuGet / IIS / Docker 等流水线，只要通过 common-ci 的 downstream trigger 模板触发下游，本规则均适用。

6. 常见问题（FAQ）

6.1 上游是 develop（或 feature/*），下游只有 master，会怎么样？

在未显式配置 DOWNSTREAM_BRANCH 的情况下，默认行为是：

  • DOWNSTREAM_BRANCH = FANOUT_BRANCH
  • FANOUT_BRANCH 默认等于当前上游的 CI_COMMIT_BRANCH

因此：

  • 上游在 develop 跑时，会尝试触发下游的 develop
  • 若下游仓库没有 develop 分支（只有 master），则 trigger: 作业会失败
  • 因为我们使用 strategy: depend，上游流水线会在“触发下游”阶段失败

治理方式（二选一）：

  • 方式 A（推荐，稳定）
    • 对“只有主干分支”的下游仓库，在上游项目显式配置 DOWNSTREAM_BRANCH: master
    • 这样不管上游在哪个分支跑，下游都只触发 master
  • 方式 B（统一分支体系）
    • 在下游仓库创建对应分支（例如创建 develop），保证分支存在
    • 适用于需要严格“同分支联动”的仓库
]]>https://talk.loda.net/topic/43/下游触发分支规则-fanout_branch-单原则RSS for NodeFri, 17 Apr 2026 08:18:02 GMTThu, 08 Jan 2026 10:53:48 GMT60<![CDATA[Reply to 下游触发分支规则（FANOUT_BRANCH 单原则） on Fri, 09 Jan 2026 17:37:10 GMT]]>下游触发分支选择：现象、根因与最终方案（仅 develop/master）

背景与目标

我们在 NuGet 组件发布流水线中使用下游触发（trigger downstream pipeline）来联动发布/同步多个项目。

核心目标是：

  • 让下游触发分支选择可预测、可维护、可审计。
  • 避免因为 GitLab Token 权限差异导致的“误判分支不存在”“偶发失败”等不稳定行为。
  • 适配跨项目、跨实例同步（common-ci 同步到多个 GitLab 实例）的场景。

现象（问题表现）

在 trigger_downstream_pipeline 作业中出现以下典型问题：

  • 现象 A：作业过早触发

    • 流水线还未完成 push/update 等步骤，下游就被触发。

  • 现象 B：下游明明存在分支，却提示分支不存在

    • 例如下游有 develop，但 job 日志显示“分支不存在”。

  • 现象 C：HTTP 401 Unauthorized

    • 使用 CI_JOB_TOKEN 调用 GitLab API 触发下游 pipeline 时返回 401。
    • 说明默认情况下 CI_JOB_TOKEN 不具备跨项目触发的权限。

  • 现象 D：Reference not found / downstream pipeline can not be created

    • trigger 使用的 branch 变量为空或未按预期注入，导致 GitLab 认为 ref 不存在。

根因分析

1. GitLab 原生 trigger: 的能力边界

  • 原生 trigger: 只能触发一个确定的 project + branch。
  • 它不会做“分支不存在则 fallback”这种动态选择。

因此，如果要做“某项目没有分支就改触发另一个分支、后续再恢复原分支”的行为，必须：

  • 预先知道下游是否存在该分支（需要 API），或
  • 直接尝试触发并解析失败原因（需要 API），或
  • 人工/静态配置规则（每项目一个开关），或
  • 制定组织规范（所有项目都具备统一分支）。

2. 跨项目权限与 Token 复杂度

如果使用 API 触发下游（/api/v4/projects/:id/pipeline）：

  • CI_JOB_TOKEN 在多数场景下对跨项目 API 权限不足（401）。
  • 使用 GITLAB_API_TOKEN（Project/Group/Personal Access Token）可以解决，但引入：
    • Token 分发与轮换成本
    • 安全风险与合规审计成本
    • 多实例同步时的配置复杂度

3. 变量注入顺序与 artifacts 依赖

我们使用 dotenv artifacts 在 setup 阶段写入变量（如 FANOUT_BRANCH、DOWNSTREAM_BRANCH）。

如果 trigger job 没有正确 needs 对应的 setup job（且 artifacts: true），就可能拿不到变量，导致：

  • $DOWNSTREAM_BRANCH 为空
  • trigger 触发时报 Reference not found

方案对比（做过的选择）

方案 1：智能分支（API + fallback）

  • 思路：优先触发“根分支”，失败再 fallback 到 develop/master。
  • 优点：理论上能实现更复杂的链路行为。
  • 缺点：
    • 需要跨项目 API 权限，CI_JOB_TOKEN 往往不够（401）
    • Token 配置与安全治理成本高
    • 失败原因多样（401/404/网络/权限策略），可维护性差

方案 2：自建服务（分支查询/代理触发）

  • 思路：将 GitLab token 收拢到内部服务，CI 只调用内部服务。
  • 优点：可控、安全面可收敛。
  • 缺点：引入额外系统：
    • 部署与运维成本
    • 高可用/限流/审计等需求
    • 增加链路复杂度

方案 3（最终采用）：最简单方案（无 API，仅 develop/master）

结论：采用方案 3。

  • 只在 develop/master 两者之间选择分支。
  • 在 setup 阶段一次性确定“触发链根分支”，并通过 dotenv 跨项目传递。
  • trigger 使用 GitLab 原生 trigger:，不使用 API，不依赖 token。

该方案的关键前提：所有参与链路的项目必须同时存在 develop 和 master 分支。

这项前提换来的是：

  • 不需要任何额外权限与 token
  • 行为稳定、可预测
  • 维护成本最低

最终方案设计

1. 根分支归一化（setup 阶段）

在 setup_version（.version_setup）阶段：

  • 读取触发源：FANOUT_BRANCH（上游传递）或 CI_COMMIT_BRANCH（当前）
  • 归一化为：
    • master/main/hotfix/* → master
    • 其他 → develop
  • 写入 dotenv：
    • FANOUT_BRANCH=<develop|master>
    • DOWNSTREAM_BRANCH=<develop|master>（如果用户未显式指定）

2. 下游触发（trigger 阶段）

在 .trigger-downstream 中：

  • 使用 GitLab 原生：
    • trigger.project: $DOWNSTREAM_PROJECT
    • trigger.branch: $DOWNSTREAM_BRANCH
  • 同时向下游继续传递：
    • FANOUT_BRANCH
    • FANOUT_FROM
    • STOP_FANOUT

并通过 needs 确保拿到 setup 阶段的 dotenv：

  • needs: setup_global_var (artifacts: true)

代码改动点（common-ci）

  • shared/version-setup.yml

    • 在 version.env 中写入归一化后的 FANOUT_BRANCH，并默认填充 DOWNSTREAM_BRANCH。

  • nuget/7-trigger-downstream.yml

    • 恢复为原生 trigger:
    • needs 增加 setup_global_var（带 artifacts: true）以确保 DOWNSTREAM_BRANCH 可用

使用与约束

  • 组织规范（必须执行）

    • 所有参与链路的仓库必须同时存在 develop 与 master 分支。

  • 项目侧配置（可选）

    • 在 .gitlab-ci.yml 中配置：
      • DOWNSTREAM_PROJECT：下游项目路径
    • 一般无需配置 DOWNSTREAM_BRANCH，默认由上游归一化规则决定。

常见问题（FAQ）

Q1：为什么不继续做“智能分支 + fallback”？

因为需要 API 触发或分支判断，而跨项目 token 权限与安全治理成本过高，且多实例同步场景下不可控因素更多。

Q2：为什么会出现 Reference not found？

多数情况下是 trigger job 没有拿到 setup 阶段的 dotenv（变量未注入），导致 branch 为空/错误。

Q3：这个方案还能实现“某项目只有 master，但后续又想回到 develop”吗？

不能。

不使用 API 的前提下无法判断下游是否存在某分支，因此无法对“每一跳”做动态选择。

要支持这种行为，必须回到 API 方案或引入项目级配置。

]]>https://talk.loda.net/post/50https://talk.loda.net/post/50Fri, 09 Jan 2026 17:37:10 GMT