多分支流水线

单分支 Pipeline Job 每次都要手动维护分支列表，团队协作时分支一多就失控。**多分支流水线（Multibranch Pipeline）**自动发现仓库中的分支和合并请求，为每个分支/PR 独立维护一条流水线。

本篇目标：能创建 Multibranch Pipeline 并配置分支发现策略，用 when 实现按分支差异化的流水线。

---

1. 为什么用多分支流水线

单分支 Job	多分支流水线
手工配置每个分支	自动发现全部分支
分支列表靠人维护	新分支 / 删除分支自动同步
无法直接校验 MR/PR	对每个 MR/PR 跑构建
所有分支同一套逻辑难区分	用 when { branch } 轻松差异化

多分支下，Jenkins 为每个分支创建一个"子 Job"，命名如 my-repo/feature/login、my-repo/main，各自维护独立的构建历史和记录。

2. 创建 Multibranch Pipeline

New Item → 输入名称 → 选择 Multibranch Pipeline

配置要点：

Branch Sources:
  Git → Project Repository: https://gitlab.company.com/team/app.git
        Credentials: gitlab-token（见第 4 篇）

Build Configuration:
  Mode: by Jenkinsfile
  Script Path: Jenkinsfile        # 仓库根目录的流水线文件

Branch Discovery:
  Filter by name: main, release-*, feature-*
  Discover branches: ✅
  Discover pull requests / merge requests: ✅（选 "Merging the pull request with the current target branch version"）
  Discover tags: 可选

2.1 分支发现策略

选项	作用
Filter by name	只索引匹配的分支（如 main、release-*）
Discover branches	普通分支变更触发
Discover PR/MR	合并请求自动构建，用于门禁
Discover tags	Tag 触发构建（如打版本号）
Suppress automatic SCM triggering	关闭自动触发，只手动

分支过多会撑爆 Master

每个分支 = 一个子 Job。几十上百个分支会生成海量子 Job 和构建记录。用 Filter by name 限制只构建需要的分支（main + release-* + 活跃 feature）。

3. 按分支差异化流水线

多分支下用 when 控制不同分支的行为：

pipeline {
    agent any
    stages {
        // 所有分支都执行
        stage('编译') {
            steps { sh 'mvn compile' }
        }
        // 只在 main 分支跑完整测试
        stage('全量测试') {
            when { branch 'main' }
            steps { sh 'mvn test' }
        }
        // 只在 main 分支构建并推送镜像
        stage('构建镜像') {
            when { branch 'main' }
            steps { sh 'docker build -t $IMAGE . && docker push $IMAGE' }
        }
        // release 分支打 tag 后才部署生产
        stage('部署生产') {
            when { branch 'release-*' }
            steps { sh 'kubectl apply -f deploy/prod/' }
        }
    }
}

3.1 分支变量

多分支流水线提供 env.BRANCH_NAME：

stage('显示分支') {
    steps {
        echo "当前分支: ${env.BRANCH_NAME}"
    }
}

4. MR/PR 门禁

用 MR 门禁保证合并前质量：

pipeline {
    agent any
    stages {
        stage('测试') {
            steps { sh 'mvn test' }
        }
        stage('代码质量') {
            steps { sh 'mvn sonar:sonar -Dsonar.qualitygate.wait=true' }
        }
    }
    post {
        failure {
            // 在 MR 上评论失败结果（GitLab/GitHub 插件）
            echo 'MR 门禁未通过'
        }
    }
}

配合代码仓库的 Pipeline status / Merge checks 把 Jenkins 构建状态作为合并条件：MR 构建失败则不能合并。

结果通知到 MR 讨论

安装 GitLab / GitHub 插件后，配置 publishBuildStatus 或在流水线用插件步骤把构建结果回写到 MR 页面，让开发在 MR 上直接看到门禁结果，不用跳转 Jenkins。

5. 与共享库配合

多分支 + 共享库（第 8 篇）是生产标配：流水线文件极简，逻辑抽到共享库统一维护：

// Jenkinsfile（仓库内）
@Library('my-shared-lib') _

pipeline {
    agent any
    stages {
        stage('Build') { steps { buildJavaApp() } }
        stage('Test')  { steps { runUnitTests() } }
        stage('Deploy') { when { branch 'main' } steps { deployK8s() } }
    }
}

6. 常见问题

现象	原因与处理
分支没有被发现	Branch Discovery 未勾选、Filter by name 把分支过滤掉了
子 Job 一直显示"No Jenkinsfile"	Script Path 配错，或 Jenkinsfile 不在该分支
分支删了子 Job 还在	开启"自动清理过时分支"（Orphaned Item Strategy）
MR 构建失败但能合并	MR 门禁未接入 Jenkins 状态，需在仓库端配置检查项

---

7. 练习与验收

练习 A

1. 建一个 Multibranch Pipeline 指向你的 GitLab/Gitea 仓库
2. 创建 feature/login 分支并提交 Jenkinsfile，观察自动生成子 Job
3. 用 Filter by name 只保留 main 和 feature-*

练习 B

1. 在流水线中用 when { branch 'main' } 区分 main 与其他分支的步骤
2. 提交一个 MR，观察 MR 构建是否触发，并把构建状态发布到 MR
3. 设置 Orphaned Item Strategy 自动清理已删除分支的子 Job

验收清单

• 能创建 Multibranch Pipeline 并配置分支 / MR 发现
• 会用 Filter by name 控制分支范围，避免子 Job 爆炸
• 会用 when { branch } 做分支差异化流水线
• 知道如何把 Jenkins 构建接入 MR/PR 合并门禁
• 知道分支删除后如何自动清理子 Job

下一篇：共享库。