本文是《统一 CI/CD 流水线治理》系列第四篇，也是最后一篇。前三篇分别介绍了为什么要统一管理、Jenkins 如何实现、GitHub Actions 如何实现。本文的目的是帮助你做出有依据的决策：要不要迁移，以及如何迁移。本文来自一个覆盖 500+ 仓库、运行 2 年以上的生产实践——迁移决策不是纸上谈兵，而是真实发生过的权衡。

一、先说结论：Jenkins Shared Library 没有错

在讨论迁移之前，必须明确一件事：Jenkins Shared Library 是成熟的、经过验证的方案。大量组织基于它稳定运行多年，它解决了统一 CI/CD 治理的核心问题，有完整的生态支持。

迁移本身有真实的成本：

• 重写成本：Jenkins Groovy 逻辑需要翻译成 GitHub Actions YAML + shell，不是简单的格式转换
• 培训成本：团队需要重新学习 GitHub Actions 的概念和调试方式
• 验证成本：需要并行运行两套流水线对比结果，确保没有行为差异
• 历史数据：Jenkins 的 build 历史、artifact、部署记录无法迁移
• 500+ 仓库的迁移规模：500 个仓库的迁移不是一次 sprint 能完成的，需要以月到年为单位规划

不要为了迁移而迁移。 本文的目的是给出有依据的决策框架，而不是推销迁移。

二、两种方案的本质差异（深度对比）

2.1 流水线结构：动态 vs 静态

这是两种方案最本质的技术差异。

Jenkins：运行时动态结构

1
2
3
4
5
6
7
8
9
10
11
12
13

// JenkinsStageGenerator：stage 结构在运行时决定
void run(Map config, String vaultToken) {
    stage('Lint') { ... }  // 总是运行

    if (config.jobs.find { it.name == 'unit-test' }) {
        stage('Unit Test') { ... }  // 条件运行
    }

    // 业务仓库可以在 config.yaml 中声明任意数量的自定义 stage
    config.jobs.findAll { it.name.startsWith('custom-') }.each { job ->
        stage(job.name) { runCustomJob(job) }  // 动态 stage
    }
}

Jenkins UI 中，没有单元测试的仓库根本不显示 “Unit Test” stage。

GitHub Actions：编译时静态结构

1
2
3
4
5

# workflow YAML 在解析时就固定了 job 结构
jobs:
  unit-test:
    if: ${{ needs.config.outputs.has_unit_test == 'true' }}  # 只能跳过，不能"不存在"
    ...

GitHub Actions 能跳过 job，但 job 始终出现在 workflow 定义中。你无法在 YAML 中声明”如果条件满足才有这个 job”。

500+ 仓库规模下的实际影响： 对 95% 的业务场景，”可以跳过”和”不存在”没有区别。但在 500+ 仓库规模下，如果有几十个仓库需要声明任意数量的自定义 stage（数据库迁移、E2E 测试、多阶段部署），Jenkins 方案天然支持，GitHub Actions 需要用 matrix 或其他 workaround，且 UI 体验差距明显。

实际数据： 在 500+ 仓库的平台中，大约 5-10% 的仓库使用了自定义 stage，这部分是迁移最复杂的场景——不是不能迁，而是迁移后的 YAML 体积会显著膨胀，且动态性降低。

2.2 凭证安全模型：静态 vs 动态

500+ 仓库规模下的安全放大效应：

AppRole 的核心风险在于 SecretID 全局共享。当平台覆盖 500 个仓库时：

• 任意一个仓库的 Groovy Pipeline 理论上都能访问共享 SecretID
• SecretID 轮换需要协调所有 500 个仓库同时不在认证——在高频 CI 环境中，轮换窗口极难控制
• 500 个仓库并发触发 AppRole 登录时，Vault 限流导致大量认证失败（见第三节）

GitHub Actions 的 job_workflow_ref + @refs/heads/main 后缀强制要求所有 workflow 修改经过代码审查后才能访问 Vault，这个安全边界是由 Vault 的 JWT bound_claims 在认证层强制执行的，workflow 代码本身无法绕过：

1
2
3
4
5
6
7
8
9
10

攻击者修改了 .github 仓库的 feature 分支中的 workflow 文件
      │
      ▼
job_workflow_ref = "OrgA/.github/.github/workflows/platform-ci-build.yml@refs/heads/attacker-branch"
      │
      ▼
Vault 验证：bound_claims 要求 @refs/heads/main
      │
      ▼
✗ 不匹配 → 403 → 无法获取任何 secrets

500 个仓库，无一存储任何凭证——这是 JWT/OIDC 方案在 500+ 规模下的核心安全价值。

2.3 基础设施负担

500+ 仓库规模下的真实运维成本：

Jenkins 的典型运维事件（已在 500+ 仓库规模实际发生）：

• 每季度 1-2 次 Kubernetes Plugin 升级导致 Pod 调度失败，影响全量 CI（排查 2-4 小时，但全 500 仓库停摆）
• 每年 1-2 次 Jenkins 主节点 OOM（高峰期 100-200 个并发 Pipeline，JVM 堆耗尽，排查 + 恢复 4-8 小时）
• 每月 1-2 次 某个插件与新版 Jenkins 不兼容，需要降级（排查 1-2 小时）
• Vault 限流：500+ 仓库同时 push 时（早高峰），AppRole 并发认证可能触发 Vault 限流，导致数百个 Pipeline 认证失败

GitHub Actions self-hosted runner 的典型运维事件：

• 每季度 1 次 runner 软件更新（5 分钟脚本自动完成，对运行中 job 无影响）
• 偶发 runner 网络超时（重跑 job 通常即可解决）
• runner 容量：500+ 仓库需要规划充足的 runner 数量，防止高峰排队

2.4 开发者体验

这个维度的差异对工程师的日常工作影响最大，在 500+ 仓库规模下，支持成本直接受此影响：

Jenkins：

• CI 结果在 Jenkins UI 中，PR 页面只显示”succeeded/failed”
• 查看失败详情需要跳转到 Jenkins（可能需要额外登录）
• 日志在 Jenkins 的 Blue Ocean 或 Classic 界面，与代码审查流程割裂
• 失败原因经常是”某个 stage 失败”，需要逐层展开才能看到具体错误

GitHub Actions：

• CI 结果直接显示在 PR 的 Checks 标签页
• 每个 step 的日志可以直接在 PR 页面展开查看
• 与代码审查、comments、assignee 完全一体化
• 失败的 step 有直接的”Re-run”按钮
• Job Summary 页面可以展示结构化报告（配置解析结果、覆盖的模块列表等）

量化影响（500+ 仓库规模）：

平台团队的调查显示，排查一次 CI 失败的平均时间：

• Jenkins：8-12 分钟（包括切换平台、找到对应 build、定位 stage）
• GitHub Actions：3-5 分钟（直接在 PR 页面展开）

在 500+ 仓库、每天数百次 CI 运行的规模下，如果每次 CI 失败平均少花 6 分钟排查，100 人工程团队每周节省约 50-100 人时。这个数字能直接支撑迁移投入的 ROI 计算。

2.5 配置合并能力

shell 实现脆弱的场景：

1
2
3

# 当 pylint sourceSets 中包含路径含有空格时，tr '\n' ' ' 处理后的结果可能被 shell 分词
SOURCES=$(yq '.check.pylint.sourceSets[]' config.yaml | tr '\n' ' ')
# 如果某个路径是 "src/my module"，分词后会变成两个参数

500+ 仓库的边界情况放大效应： 在 500 个仓库中，任何 config.yaml 格式的边界情况都一定会出现——某个团队用了带空格的路径、某个团队用了多行 YAML 字符串、某个团队的字段值包含了 shell 特殊字符。Groovy 的类型系统在 500 个仓库的输入多样性下提供了更好的保证，而 shell + yq 方案需要更充分的测试覆盖。

综合对比表

三、迁移的真实驱动力

驱动力一：代码托管平台统一（运维简化）

维护两套系统（Jenkins + GitHub Enterprise）意味着：

• 两套权限管理（新成员入职需要申请两个平台的访问权限）
• 两套审计日志（安全审计需要关联两个系统的记录）
• 两套事故响应（Jenkins 故障和 GitHub 故障是不同的响应流程）
• 两套监控配置

在 500+ 仓库规模下，这个运维开销被进一步放大：两套系统的权限同步（离职人员需要从两个系统清除）、两套 CI 状态监控（某个仓库 CI 挂了，需要判断是 Jenkins 问题还是 GitHub 问题）。

如果代码已经全部迁移到 GitHub Enterprise，继续维护独立的 Jenkins 实例的边际价值在降低。

驱动力二：凭证安全合规要求

某些合规框架（SOC 2 Type II、ISO 27001）对静态凭证有明确要求：

• 必须定期轮换（通常 90 天）
• 必须有使用审计记录
• 必须限制访问范围

500+ 仓库规模下的 AppRole 合规挑战：

AppRole 的 SecretID 满足这些要求需要额外的运维流程（定期轮换脚本、轮换审计）。在 500+ 仓库的高频 CI 环境中，90 天轮换意味着每次轮换都需要：

1. 选择低峰窗口（避免影响太多正在运行的 Pipeline）
2. 更新 Jenkins Credential Store
3. 验证新 SecretID 对所有 Org 的 Vault role 都生效
4. 监控接下来 24 小时是否有认证失败

JWT/OIDC 的回答是”不存在可泄漏的长期凭证”——这在合规审计场景下是更简洁的答案。对 500+ 仓库的平台，这个答案可以减少每季度约 1-2 天的合规运维工作。

驱动力三：Jenkins 基础设施到达生命周期

当出现以下信号时，迁移的 ROI 开始变得合理：

• Jenkins 主节点 OOM 频率从每年 1 次增加到每月 1 次
• Kubernetes Plugin 升级在每次 Jenkins 版本更新后都需要手动回滚
• 负责维护 Jenkins 实例的工程师离职，知识传承困难
• Jenkins LTS 版本接近 EOL（End of Life）

500+ 仓库规模的特殊信号：

• 早高峰 Vault 限流成为常态（每天早晨都需要手动清理或等待）
• Jenkins 主节点需要持续的 JVM 调优（堆大小已超过 16GB 仍然 OOM）
• Pod 调度失败的排查成本超过了新功能开发的投入

这不是 Jenkins 的根本性问题，而是任何有状态基础设施在超规模使用时都会遭遇的生命周期问题。

驱动力四：开发者生产力

量化这个驱动力的方法：

• 统计过去 3 个月，工程师在排查 CI 失败上花费的时间（通过 Jira ticket 或 Slack 记录）
• 统计平台团队在维护 Jenkins 基础设施上花费的时间
• 与迁移成本对比

500+ 仓库规模的具体估算：

1
2
3
4
5
6
7
8

假设：
  500 个仓库，平均每天每仓库 5 次 CI 运行 = 2500 次/天
  CI 失败率 10%                            = 250 次失败/天
  Jenkins 排查时间：10 分钟/次
  GitHub Actions 排查时间：4 分钟/次
  节省时间：6 分钟/次 × 250 次/天           = 25 小时/天

年化节省（工作日 250 天）                    = 6250 小时/年

即便实际数字只有估算的 1/10，每年节省 625 小时也足以支持迁移投入。

四、不值得迁移的场景（重要）

场景一：动态 Stage 生成是核心需求，且覆盖大量仓库

如果你的平台允许业务团队在 config.yaml 中声明任意的自定义 stage，且这个能力被 超过 10% 的仓库 广泛使用，GitHub Actions 无法原生复制这个功能。

具体例子：某个业务仓库声明了 10 个数据库迁移 stage，每个对应一个目标环境，stage 名称和数量在运行时从配置文件生成。Jenkins 的 StageGenerator 一行代码搞定，GitHub Actions 需要复杂的 matrix 配置，且在 UI 展示上差距明显。

500+ 仓库下的评估方法：

1
2
3
4
5
6
7
8
9

# 检查有多少仓库使用了 custom- 开头的 stage（即动态 stage）
gh repo list OrgA --limit 1000 --json name \
  | jq -r '.[].name' \
  | while read repo; do
      if gh api "repos/OrgA/${repo}/contents/.ci-config/config.yaml" --silent 2>/dev/null \
           | jq -r '.content' | base64 -d | grep -q 'custom-'; then
        echo "${repo}: 使用了自定义 stage"
      fi
    done | wc -l

如果输出超过 50 个仓库，动态 stage 迁移的工作量可能超过其他所有迁移工作之和。

场景二：流水线配置合并逻辑极其复杂

如果你的 ConfigMerger 已经积累了大量处理特殊场景的 Groovy 逻辑（递归合并、引用解析、条件覆盖），这些逻辑翻译成 shell + yq 不只是工作量大，还会降低可维护性和可测试性。

Groovy 的类型系统和 Jenkins 的测试工具链（JenkinsPipelineUnit）在这个场景下有不可替代的价值。在 500+ 仓库的输入多样性下，未经充分测试的 shell 配置解析可能引发大量偶发性问题。

场景三：深度依赖 Jenkins 特定插件

以下插件目前没有成熟的 GitHub Actions 替代：

• Build Failure Analyzer：自动分析失败原因并分类
• Performance Plugin：CI 性能趋势分析
• Warnings Next Generation：多工具警告汇聚和趋势分析
• Configuration as Code（JCasC）：Jenkins 配置版本化管理

如果这些插件提供的功能是你的工作流核心，迁移会有明显的功能缺失。

场景四：Jenkins 运行稳定，团队熟悉，没有明显痛点

这是最重要的场景——如果现状运转良好，不要迁移。

评估”是否有痛点”的具体问题（针对 500+ 仓库规模）：

1. 过去 6 个月，Jenkins 基础设施故障导致多少次全量 CI 中断（影响 500 个仓库）？
2. 过去一年，Vault 限流导致多少次 Pipeline 批量失败？
3. 工程师是否在抱怨 CI 排查困难、需要切换平台？
4. 凭证轮换是否按时完成，还是一再推迟？
5. Jenkins 主节点 JVM 堆是否持续满负荷运行？

如果这五个问题的答案都是”没有”或”很少”，迁移的 ROI 很可能是负的。

ROI 计算框架（500+ 仓库版）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

迁移成本（一次性）：
  - 平台工程师重写流水线代码：8-12 人周
  - 500 个仓库迁移：
    * 无自定义 stage 仓库（约 90%）：每仓库 30 分钟 = 225 人时
    * 有自定义 stage 仓库（约 10%）：每仓库 4 小时 = 200 人时
    * 合计：约 425 人时（约 53 人天）
  - 并行验证周期：4-8 周（双轨运行成本）
  - 培训（500 仓库的工程师）：1小时/人 × N 人

持续收益（年化）：
  - 减少 Jenkins 维护事件：6-10 次/年 × 4 小时/次 = 24-40 小时/年
  - 减少 CI 故障排查时间：见第三节驱动力四估算
  - 减少 Vault 限流影响：季度轮换 × 2 天/次 = 8 天/年
  - 消除 Jenkins 主节点 OOM 风险

迁移 ROI = 持续收益 / 迁移成本（以年计）

五、如果决定迁移，如何降低风险（500+ 仓库策略）

策略一：分波次迁移，而非大爆炸

在 500+ 仓库规模下，”一次性迁移所有仓库”不是一个可执行的方案。分波次策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

第 0 阶段（1-2 个月）：搭建 GitHub Actions 平台框架
  - 实现 platform-ci-core.yml 及所有 sub-workflow
  - 确保与 .ci-config/config.yaml 接口完全兼容
  - 针对 5-10 个内部测试仓库验证

第 1 波（2-3 个月）：新仓库 + 低风险存量仓库（约 100 个）
  - 所有新创建仓库默认 GitHub Actions
  - 迁移活跃度低、业务影响小的存量仓库
  - 目标：积累 6+ 个月的运行数据，发现并修复边界情况

第 2 波（3-6 个月）：中等重要性仓库（约 250 个）
  - 无自定义 stage 的标准仓库
  - 并行运行 2 周后切断 Jenkins

第 3 波（6-12 个月）：核心仓库 + 复杂仓库（约 150 个）
  - 有自定义 stage 的仓库（需要单独评估）
  - 高可见性的核心业务仓库（需要最充分的验证）
  - 部分仓库可能永久保留 Jenkins（见共存方案）

策略二：并行运行期验证

在正式切换前，让 Jenkins 和 GitHub Actions 同时运行，对比每次 build 的结果：

1
2
3
4
5
6
7
8

# 业务仓库的 ci.yml 临时配置
jobs:
  # 新流水线（GitHub Actions）
  platform-gha:
    uses: OrgA/.github/.github/workflows/platform-ci-core.yml@main

  # 旧流水线仍在 Jenkins 运行（通过 Jenkins GitHub Plugin 触发）
  # 两者结果在 PR 的 Checks 中并排显示

只有当 GitHub Actions 结果稳定等于 Jenkins 结果至少 2 周、10 次以上 CI 运行后，才切断 Jenkins。

500+ 仓库的注意事项： 不要在整个 500 个仓库上同时启动并行运行——双倍的 CI 负载会对 runner 容量和 Vault 造成额外压力。按波次启动并行运行，每波完成后再切断 Jenkins 连接，释放资源。

策略三：保留 .ci-config/config.yaml 接口不变（关键）

这是降低业务团队迁移成本的最重要决策。如果 .ci-config/config.yaml 的结构保持兼容，业务团队的迁移工作只是：

1. 创建一个新的 .github/workflows/ci.yml（15 行）
2. 删除旧的 Jenkinsfile
3. .ci-config/config.yaml 完全不动

业务团队的感知： CI 结果显示在不同的地方了，流水线快了，Jenkinsfile 不见了。其余一切不变。

在 500 个仓库中，这种无感迁移意味着每个仓库的迁移不需要专门的协调会议——平台团队准备好后，由业务团队在自己的节奏内完成两步操作。

策略四：通过 Org Variable 控制切换

利用 GitHub Enterprise 的 Org Variable 机制，实现不修改业务仓库代码的路由控制：

1
2
3
4

# 不同 Org 代表不同迁移阶段
# OrgA-Dev：新仓库优先接入 GitHub Actions（Dev 环境）
# OrgA-Stg：存量仓库逐步迁移（Staging 环境）
# OrgA：最后切换核心 prod 仓库（生产环境）

Org Variable（VAULT_ENV、VAULT_URL 等）在不同 Org 中配置不同值，业务仓库的 ci.yml 代码完全相同，平台行为根据 Org 上下文自动路由。这是 500+ 仓库分阶段迁移的基础设施保证——你可以在不同 Org 处于不同迁移阶段时，平台仍然统一维护一套代码。

策略五：批量检查迁移进度

在 500 个仓库的迁移过程中，需要工具化监控迁移状态：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

#!/bin/bash
# 检查各仓库的迁移状态：Jenkins only / GitHub Actions only / Both（并行）/ Neither
ORG="OrgA"
echo "=== 迁移状态报告 ==="

gh repo list "${ORG}" --limit 1000 --json name \
  | jq -r '.[].name' \
  | while read repo; do
      HAS_JENKINSFILE=$(gh api "repos/${ORG}/${repo}/contents/Jenkinsfile" --silent 2>/dev/null && echo "yes" || echo "no")
      HAS_GHA=$(gh api "repos/${ORG}/${repo}/contents/.github/workflows/ci.yml" --silent 2>/dev/null && echo "yes" || echo "no")
      HAS_CONFIG=$(gh api "repos/${ORG}/${repo}/contents/.ci-config/config.yaml" --silent 2>/dev/null && echo "yes" || echo "no")

      if [ "${HAS_JENKINSFILE}" = "yes" ] && [ "${HAS_GHA}" = "no" ]; then
        echo "[Jenkins only]    ${repo}"
      elif [ "${HAS_JENKINSFILE}" = "no" ] && [ "${HAS_GHA}" = "yes" ]; then
        echo "[GHA only]        ${repo}"
      elif [ "${HAS_JENKINSFILE}" = "yes" ] && [ "${HAS_GHA}" = "yes" ]; then
        echo "[Parallel run]    ${repo}"
      elif [ "${HAS_CONFIG}" = "yes" ]; then
        echo "[No CI!]          ${repo}"
      fi
    done | sort | tee migration_status.txt

echo ""
echo "统计："
grep -c "\[Jenkins only\]" migration_status.txt | xargs echo "  Jenkins only:"
grep -c "\[GHA only\]" migration_status.txt     | xargs echo "  GitHub Actions only:"
grep -c "\[Parallel run\]" migration_status.txt | xargs echo "  并行运行中:"
grep -c "\[No CI!\]" migration_status.txt       | xargs echo "  无 CI（需要接入）:"

这个脚本在 500 个仓库的迁移过程中，是平台团队每周例会的标准输入。

策略六：保留回滚方案（30 天窗口）

在切换后的 30 天内，保留 Jenkins Job 但暂停触发：

1
2

// 旧 Jenkinsfile 重命名为 .jenkinsfile.bak 保留在仓库中
// 如果 GitHub Actions 出现严重问题，可以临时恢复文件名并在 Jenkins 手动触发

500+ 仓库的回滚策略： 不要在整个 500 个仓库上同时删除 Jenkins 配置。按批次删除，每批次等待 30 天观察期。一旦出现平台级问题（比如 runner 容量不足导致排队严重），可以将该批次已迁移的仓库先回滚，同时扩容 runner，再重新迁移。

六、决策树（500+ 仓库版）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Q1: 你的仓库数量是否超过 50 个？
│
├─ 否 → 统一管理的收益可能低于成本，参考小规模建议
│
└─ 是 → Q2: Jenkins 是否运行稳定（过去一年全量 CI 中断 ≤ 2 次）？
          │
          ├─ 是 → Q3: 是否有明确的凭证安全合规要求（SOC 2 / ISO 27001）？
          │         │
          │         ├─ 否 → Q4: 工程师排查 CI 失败是否需要频繁切换平台，
          │         │            且团队规模 > 50 人？
          │         │         │
          │         │         ├─ 否 → 继续使用 Jenkins，每年评估一次
          │         │         └─ 是 → 计算年化节省时间（见第三节驱动力四）
          │         │                  若 > 500 小时/年，评估迁移 ROI
          │         │
          │         └─ 是 → Q5: 超过 10% 的仓库依赖动态 Stage 生成？
          │                   │
          │                   ├─ 是 → 维持 Jenkins，加固 AppRole 轮换流程
          │                   │        （动态 stage 迁移成本过高）
          │                   └─ 否 → 推荐迁移，优先从 Dev/Stg 环境 Org 开始
          │
          └─ 否（Jenkins 不稳定）→ Q6: 不稳定原因是否是规模性问题？
                    │              （OOM、Vault 限流、插件兼容）
                    │
                    ├─ 否（随机故障）→ 先解决根本原因，再评估迁移
                    │
                    └─ 是（规模性问题）→ Q7: 超过 10% 的仓库依赖动态 Stage？
                                          │
                                          ├─ 是 → 迁移部分仓库（无自定义 stage），
                                          │        保留复杂仓库在 Jenkins
                                          └─ 否 → 强烈推荐迁移
                                                   Jenkins 维护成本已超过迁移成本

七、两种方案能否共存？（500+ 仓库的现实选择）

可以，且在 500+ 仓库规模下，这往往是比”完全迁移”更现实的长期策略。

永久共存的合理场景

• 动态 Stage 仓库永留 Jenkins：约 5-10% 的仓库因为大量自定义 stage，迁移成本远超收益，接受永久双系统
• 新项目全走 GitHub Actions，存量仓库按节奏迁移：不设硬性截止日期，随仓库的正常维护周期自然迁移
• 不同 CI 复杂度分流：Jenkins 处理复杂的多环境部署流水线，GitHub Actions 处理标准构建 + 测试

.ci-config/config.yaml 的战略价值

这个接口文件是两套系统可以共存的关键：

1
2
3
4
5
6
7
8
9

# .ci-config/config.yaml 的结构对两套系统都有效
containers:
  - name: project-runtime
    image: platform-registry.example.com/python:3.12
jobs:
  - name: lint
    steps:
      - pyLint:
          sourceSets: [src/]

• Jenkins 的 ConfigMerger.groovy 读取它
• GitHub Actions 的 config job 的 shell 脚本读取它

业务团队不需要知道底层是哪套系统——这是接口设计的价值所在。当平台团队决定在某个仓库上切换底层 CI 引擎时，业务团队唯一的感知是”CI 结果显示的位置变了”。

长期策略建议（更新的规模阈值）

在 500+ 仓库规模下，追求 100% 迁移不是目标——目标是让业务团队有统一的 CI 接入体验，同时让平台团队的维护工作收敛。即使 10% 的仓库永远留在 Jenkins，只要接口统一，这 10% 的维护成本是可接受的。

可观测性：双系统监控

在混合架构运行期间，平台团队需要统一的 CI 健康视图，跨越两套系统：

1
2
3
4
5

需要回答的问题：
  - 今天 Jenkins CI 失败了多少次？GitHub Actions 失败了多少次？
  - 两套系统的平均耗时对比？
  - 哪些仓库的 Jenkins CI 超过 30 天没有运行（可以加速迁移）？
  - 当前双轨运行的仓库数量（并行验证进度）？

这需要 Jenkins 的 build 数据和 GitHub Actions 的 workflow 数据汇聚到同一个 dashboard（如 Grafana），以避免平台团队在两个系统之间手动关联信息。

结语

本系列四篇文章从”为什么”出发，经过 Jenkins 和 GitHub Actions 的技术实现，到今天的迁移决策框架，试图回答一个完整的问题：如何在 500+ 仓库的工程组织中治理 CI/CD 流水线，以及在不同阶段应该选择什么工具。

核心结论：

1. 统一管理的价值是真实的——分离关注点让平台团队和业务团队各自专注，这个价值在 500+ 仓库时乘以 500 倍的规模效应
2. Jenkins Shared Library 是成熟可靠的方案，不是”旧技术”；在 500+ 规模下它的挑战是运维复杂度，而非功能缺失
3. GitHub Actions 的 JWT/OIDC + Reusable Workflow 在凭证安全和开发者体验上有实质性优势，且在 500+ 规模下这些优势被进一步放大
4. 迁移的决策应该基于 ROI，而不是技术时髦性——500 个仓库的迁移是一个以年为单位的工程项目
5. .ci-config/config.yaml 这样的接口设计让平台迁移对业务团队透明——这是 500+ 仓库规模下迁移可行性的关键设计决策
6. 混合架构可能是 500+ 仓库规模下的长期现实——以接口统一代替技术统一，是更务实的目标

无论你今天的选择是什么，最重要的原则是：让业务团队只需要声明意图，不需要理解实现。这个原则在 Jenkins 和 GitHub Actions 中都适用，在 5 个仓库和 500 个仓库时都成立。

本文是《统一 CI/CD 流水线治理》系列第二篇。上一篇讲了为什么要统一管理，这篇深入 Jenkins Shared Library 的技术实现细节。本文来自一个覆盖 500+ 仓库、运行 2 年以上的生产实践。

一、Shared Library 是什么

Jenkins Shared Library 是 Jenkins 提供的代码复用机制：将 Groovy 代码放在独立 Git 仓库中，在 Jenkins 全局配置中注册后，所有 Jenkinsfile 都可以 @Library 引入并调用其中的函数。

对业务团队来说，效果是这样的：

1
2
3
4

// 业务仓库的 Jenkinsfile（完整文件）
@Library('platform-ci-library') _

platformCi()

两行代码，完整的 CI/CD 流水线。平台团队在 platform-ci-library 仓库中维护所有逻辑，500+ 个业务仓库都是这两行。

二、Shared Library 目录结构

1
2
3
4
5
6
7
8
9
10
11
12

platform-ci-library/
├── vars/
│   └── platformCi.groovy          # 业务仓库调用的入口函数
├── src/
│   └── com/platform/ci/
│       ├── ConfigMerger.groovy    # 配置合并逻辑
│       ├── PodGenerator.groovy    # Kubernetes Pod YAML 生成
│       ├── StageGenerator.groovy  # 动态 Stage 生成
│       └── VaultClient.groovy     # Vault AppRole 认证
└── resources/
    └── config/
        └── default.yaml           # 平台默认配置

三个目录的职责：

• vars/：存放全局变量和顶层函数，文件名即函数名（platformCi.groovy → platformCi()）
• src/：存放辅助类，遵循 Java 包路径约定，可以使用完整的 Groovy/Java 语法
• resources/：存放静态资源文件，通过 libraryResource() 加载

三、入口函数的完整执行流程

vars/platformCi.groovy 是整个流水线的编排入口：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// vars/platformCi.groovy（伪代码，已脱敏）
def call(Map params = [:]) {
    // Step 1: 加载平台默认配置
    def defaultConfigYaml = libraryResource('config/default.yaml')
    def defaultConfig = readYaml(text: defaultConfigYaml)

    // Step 2: 加载业务仓库的 .ci-config/config.yaml
    def repoConfig = readYaml(file: '.ci-config/config.yaml')

    // Step 3: 合并配置（平台默认 + 业务覆盖）
    def mergedConfig = new ConfigMerger().run(defaultConfig, repoConfig)

    // Step 4: 自动提取仓库名（从 Git 远端 URL，无需业务团队传入）
    def repoName = sh(
        script: "git remote get-url origin | sed 's|.*[:/]||' | sed 's|\\.git$||'",
        returnStdout: true
    ).trim()
    mergedConfig.repoName = repoName

    // Step 5: 生成 Kubernetes Pod YAML
    def podYaml = new PodGenerator().run(mergedConfig.containers)

    // Step 6: Vault AppRole 认证，换取临时 token
    def vaultToken = new VaultClient().getToken(mergedConfig.vault)

    // Step 7: 动态生成并运行 stage
    podTemplate(yaml: podYaml) {
        node(POD_LABEL) {
            checkout scm
            new StageGenerator().run(mergedConfig, vaultToken)
        }
    }

    // Step 8: post 阶段（状态上报、健康检查数据推送）
    // 注：Jenkins post 块在 StageGenerator 外部处理
}

为什么要自动提取仓库名？

要求 500 个业务团队在 platformCi() 调用时传入仓库名，100% 会有人拼写错误或大小写不一致。从 Git remote URL 提取是无歧义的：https://github.example.com/OrgA/my-app.git → my-app。

四、配置合并机制

4.1 default.yaml 的结构设计

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# resources/config/default.yaml
containers:
  - name: jnlp
    image: platform-registry.example.com/jenkins-inbound-agent:latest
    allowOverride: false       # 业务团队不能覆盖这个容器

  - name: project-runtime
    image: platform-registry.example.com/python:3.x
    allowOverride: true        # 业务团队可以指定 Python 版本

  - name: build-tools
    image: platform-registry.example.com/build-tools:latest
    allowOverride: false

jobs:
  - name: security-scan
    allowOverride: false       # 安全扫描不允许关闭（合规基线）
    steps:
      - semgrep:
          rulesets: ["p/python", "p/security-audit"]

  - name: lint
    allowOverride: true
    steps:
      - pyLint:
          sourceSets: []       # 默认空，业务仓库必须声明
          rcFile: ""           # 默认空，使用平台 rcFile

vault:
  address: https://vault.example.com
  namespace: platform/projects/myteam
  roleIds:
    OrgA-Dev: "role-id-dev-placeholder"
    OrgA-Stg: "role-id-stg-placeholder"
    OrgA:     "role-id-prod-placeholder"

4.2 合并规则

配置合并需要处理两类数据结构：

标量字段（字符串、数字、布尔）：业务值直接覆盖默认值（如果 allowOverride: true）

列表字段（如 containers）：按 name 字段匹配合并，而非简单追加或替换

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// src/com/platform/ci/ConfigMerger.groovy（核心逻辑，已简化）
class ConfigMerger {
    Map run(Map defaultConfig, Map repoConfig) {
        def merged = deepCopy(defaultConfig)

        // 合并 containers：按 name 匹配
        repoConfig.containers?.each { repoContainer ->
            def defaultContainer = merged.containers.find {
                it.name == repoContainer.name
            }

            if (defaultContainer) {
                if (defaultContainer.allowOverride == false) {
                    // 平台强制容器，忽略业务覆盖，打印警告
                    echo "Warning: container '${repoContainer.name}' has allowOverride=false, ignoring override"
                } else {
                    // 合并字段（不允许覆盖 allowOverride 字段本身）
                    repoContainer.each { key, value ->
                        if (key != 'allowOverride') {
                            defaultContainer[key] = value
                        }
                    }
                }
            } else {
                // 业务仓库声明了新容器，追加
                merged.containers << repoContainer
            }
        }

        // 合并 jobs：按 name 匹配，逻辑类似
        repoConfig.jobs?.each { repoJob ->
            def defaultJob = merged.jobs.find { it.name == repoJob.name }
            if (defaultJob && defaultJob.allowOverride == false) {
                return
            }
            mergeJob(merged.jobs, repoJob)
        }

        return merged
    }
}

4.3 Python 版本提取

业务团队声明的是镜像 tag，不是 Python 版本号：

1
2
3

containers:
  - name: project-runtime
    image: platform-registry.example.com/python:3.14

平台从镜像 tag 中提取版本：

1
2
3
4

def pythonVersion = repoContainer.image
    .tokenize(':')
    .last()               // "3.14"
    .find(/\d+\.\d+(\.\d+)?/)  // 正则提取语义化版本

3.14 → 用于 pip install、python --version 验证、lint 配置中的 python-version。

在 500+ 仓库中，Python 版本跨度通常从 3.8 到 3.13，平台需要兼容所有版本，而不是要求业务团队主动传入版本号。

五、动态 Stage 生成

这是 Jenkins 方案最独特的能力，也是 GitHub Actions 最难复制的部分。

5.1 什么是”运行时动态 Stage”

在 Jenkins Pipeline 中，stage 可以在 Groovy 代码执行时动态创建：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// StageGenerator 根据配置决定运行哪些 stage
class StageGenerator {
    void run(Map config, String vaultToken) {
        stage('Checkout') {
            checkout scm
        }

        // 有 pylint 配置时才运行
        if (config.jobs.find { it.name == 'lint' }?.steps?.pyLint?.sourceSets) {
            stage('Lint') {
                runPylint(config, vaultToken)
            }
        }

        // 有 unit-test job 时才运行
        if (config.jobs.find { it.name == 'unit-test' }) {
            stage('Unit Test') {
                runUnitTest(config, vaultToken)
            }
        }

        // 总是运行，allowOverride=false
        stage('Security Scan') {
            runSecurityScan(config, vaultToken)
        }

        // 有 Dockerfile 时才运行
        if (config.containerBuild?.path) {
            stage('Build') {
                runContainerBuild(config, vaultToken)
            }
        }

        // 业务仓库在 config.yaml 中声明的额外任务（500+ 仓库中有几十种自定义 stage）
        config.jobs.findAll { it.name.startsWith('custom-') }.each { customJob ->
            stage(customJob.name) {
                runCustomJob(customJob, vaultToken)
            }
        }
    }
}

在 500+ 仓库规模下，这个能力尤为重要：不同仓库的 stage 结构差异很大，有的仓库有 3 个 stage，有的有 12 个（含多个自定义 stage）。Jenkins 天然支持这种动态结构，业务仓库只需在 config.yaml 中声明，无需修改平台代码。

5.2 并行 Stage

1
2
3
4
5
6
7
8
9
10
11
12
13

stage('Parallel Checks') {
    parallel(
        'Lint': {
            runPylint(config, vaultToken)
        },
        'Security Scan': {
            runSecurityScan(config, vaultToken)
        },
        'Unit Tests': {
            runUnitTest(config, vaultToken)
        }
    )
}

并行度在运行时动态决定——没有单元测试的仓库，parallel 块中就不会有 Unit Tests 分支。

5.3 GitHub Actions 的对比局限

1
2
3
4
5

# GitHub Actions：无法做到"有 Dockerfile 才显示 Build job"
jobs:
  build:
    if: ${{ needs.config.outputs.dockerfile != '' }}  # 可以跳过，但 job 始终出现在 UI 中
    uses: ./.github/workflows/platform-ci-build.yml

GitHub Actions 能跳过 job，但 job 的定义是静态的。对 95% 的场景，”跳过”和”不存在”没有区别；但对于需要动态声明任意数量自定义 stage 的业务仓库，Jenkins 方案更自然。

六、Vault AppRole 凭证管理

6.1 AppRole 认证流程

1
2
3
4
5
6
7
8
9
10
11
12
13

Jenkins Credential Store
├── RoleID（低敏感性，可以在配置文件中硬编码）
└── SecretID（高敏感性，保存在 Jenkins Credential Store，定期轮换）
           │
           ▼
POST /v1/auth/approle/login
{ "role_id": "...", "secret_id": "..." }
           │
           ▼
临时 Vault Token（TTL: 1小时）
           │
           ▼
读取 KV secrets（Registry 凭证、代码签名证书等）

6.2 多环境路由

不同 GitHub Org 对应不同环境，RoleID 不同：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// src/com/platform/ci/VaultClient.groovy
class VaultClient {
    String getToken(Map vaultConfig) {
        def remoteUrl = sh(
            script: 'git remote get-url origin',
            returnStdout: true
        ).trim()

        def roleId = resolveRoleId(remoteUrl, vaultConfig.roleIds)
        def secretId = getSecretId()  // 从 Jenkins Credential Store 读取

        def response = httpRequest(
            url: "${vaultConfig.address}/v1/auth/approle/login",
            httpMode: 'POST',
            contentType: 'APPLICATION_JSON',
            requestBody: """{"role_id":"${roleId}","secret_id":"${secretId}"}"""
        )

        return readJSON(text: response.content).auth.client_token
    }

    private String resolveRoleId(String remoteUrl, Map roleIds) {
        if (remoteUrl.contains('OrgA-Dev')) return roleIds['OrgA-Dev']
        if (remoteUrl.contains('OrgA-Stg')) return roleIds['OrgA-Stg']
        return roleIds['OrgA']  // 默认 prod
    }

    private String getSecretId() {
        withCredentials([string(credentialsId: 'vault-approle-secret-id', variable: 'SECRET_ID')]) {
            return env.SECRET_ID
        }
    }
}

6.3 凭证注入到 Stage 环境变量

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

def registryCreds = readVaultSecret(vaultToken, 'secret/data/platform/dev/registry')

container('build-tools') {
    withEnv([
        "REGISTRY_USER=${registryCreds.username}",
        "REGISTRY_PASS=${registryCreds.password}"
    ]) {
        sh """
            echo "\${REGISTRY_PASS}" | docker login platform-registry.example.com \\
              -u "\${REGISTRY_USER}" --password-stdin
            docker build -t my-app:latest .
            docker push my-app:latest
        """
    }
}

6.4 AppRole 在 500+ 规模下的安全隐患

AppRole 方案的已知局限，在 500+ 仓库规模下被放大：

1. SecretID 全局共享：所有 500 个仓库的 CI 共享同一个 SecretID，任何一个仓库的 Groovy 代码理论上都能通过 sh 'printenv | grep VAULT' 读取注入的凭证
2. 轮换协调成本高：SecretID 轮换时需要暂停全部 CI 或容忍短暂认证失败，在 500+ 仓库的高频 CI 环境中，轮换窗口的影响面很大
3. Token 全 Pipeline 共享：单次 Pipeline 运行的所有 stage 共享同一个 1 小时 TTL 的 Vault token

这些不是 Jenkins 的根本性缺陷，但在 500+ 规模下，维持同等安全水平所需的运维投入明显高于 GitHub Actions 的 JWT/OIDC 方案（无静态凭证、每个 sub-workflow 独立 5 分钟 batch token）。

七、500+ 规模下的运维挑战

7.1 Jenkins 主节点 OOM

500+ 仓库并发提交时（如早上 9 点开工高峰），同时运行的 Pipeline 数量可能达到 100-200 个。每个运行中的 Pipeline 都在 Jenkins 主节点 JVM 中占用内存（用于存储 Pipeline 状态）。

典型症状：Jenkins UI 响应变慢 → 新 Pipeline 无法启动 → 已有 Pipeline 被强制终止 → JVM 崩溃重启。

在 500+ 规模下，这不是偶发问题，而是一个需要持续运维的系统压力。

缓解措施：

• 配置 Pipeline Durability 为 PERFORMANCE_OPTIMIZED（减少状态保存频率）
• 增大 Jenkins 主节点 JVM 堆（-Xmx），通常需要 16GB+
• 限制最大并发 Pipeline 数量（Throttle Concurrent Builds 插件）
• 将 Pipeline 日志存储外置（不存在主节点磁盘上）
• 使用 @NonCPS 减少序列化对象数量

7.2 @NonCPS 注解陷阱

Jenkins Pipeline 的 Groovy 代码需要支持序列化（将执行状态保存到磁盘以便恢复）。普通 Groovy 对象大多不可序列化，这导致常见错误：

1

NotSerializableException: java.util.LinkedHashMap

解决方案是用 @NonCPS 标注不需要序列化的方法，但 @NonCPS 方法中不能使用 Pipeline DSL：

1
2
3
4
5
6
7
8
9
10
11
12

// 错误：普通方法中使用了不可序列化的对象
def processConfig(Map config) {
    config.entrySet().each { entry ->  // entrySet() 返回不可序列化的视图
        // ...
    }
}

// 正确：用 @NonCPS 标注，方法中不使用 Pipeline DSL
@NonCPS
List processConfigKeys(Map config) {
    return config.keySet().toList()  // 返回可序列化的 List
}

在维护大型 Shared Library 时，这个问题会在每次功能迭代中反复出现。处理策略：所有纯数据处理方法加 @NonCPS，所有 Pipeline DSL 调用（sh、stage、echo）不加。

7.3 Kubernetes Plugin 升级破坏性变更

Jenkins Kubernetes Plugin 在某些版本升级后，Pod YAML 的字段格式会变化，导致 Pod 调度失败——在 500+ 仓库环境中，这意味着全量 CI 中断。

1
2
3
4
5
6
7
8
9

# 新版本要求 containers 有明确的 resources 字段，否则 Pod 调度失败
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:latest
    resources:
      requests:
        memory: "256Mi"
        cpu: "100m"

排查思路：

1. 检查 Jenkins Pod Events（kubectl describe pod <jenkins-agent-pod>）
2. 查看 Jenkins Plugin 的 GitHub Issues / Changelog
3. 在非生产 Jenkins 实例先升级验证（500+ 规模的中断代价很高，升级必须有预演）

7.4 allowOverride: false 的边界情况

在 500 个仓库中，总会有团队尝试覆盖平台强制容器：

1
2
3

containers:
  - name: jnlp
    image: my-custom-jenkins-agent:latest  # 试图替换 jnlp 容器

如果 ConfigMerger 实现不当（先覆盖再检查 allowOverride），这类问题会导致 CI 行为不一致且难以复现。

正确实现：先检查 allowOverride，再决定是否合并：

1
2
3
4

if (defaultContainer.allowOverride == false) {
    echo "Skipping override for protected container: ${repoContainer.name}"
    return  // 直接跳过，不做任何合并
}

同时输出明确的警告信息——在 500 个仓库中，平台团队无法逐一沟通，日志必须自解释。

7.5 大规模并发时的 Vault 限流

500+ 仓库同时触发 CI 时，AppRole 的 /v1/auth/approle/login 请求并发量可能达到每分钟数百次。Vault 有请求限流配置，超限后返回 429 错误，导致大量 Pipeline 的 Vault 认证步骤失败。

缓解措施：

• 在 Vault 配置中提高 max_request_duration 和并发限制
• 在 VaultClient.getToken() 中加入指数退避重试逻辑
• 考虑缓存同一仓库短时间内的重复认证请求

八、运行效果

一个典型的业务仓库 CI 运行后，Jenkins UI 中显示的流水线结构：

1
2
3
4
5
6
7
8
9
10
11
12

✅ Checkout
✅ Config Parse
✅ Lint (parallel)
   ✅ PyLint
   ✅ ShellCheck
✅ Security Scan (parallel)
   ✅ Semgrep
   ✅ Dependency Audit
✅ Unit Test
✅ Build (仅 trunk/releases/latest 分支)
✅ Deploy (仅 trunk 分支)
⏭ Prepare Release (仅针对 release PR，此次跳过)

业务团队看到的是：CI 通过了。他们不需要知道 Vault 在哪里、Registry 是哪个、Semgrep 规则集版本是什么。这种体验在第 1 个仓库和第 500 个仓库上完全相同——这正是统一平台的价值。

小结

Jenkins Shared Library 在 500+ 仓库规模下的核心工程价值：

1. default.yaml + allowOverride：明确区分”平台强制”和”业务可配置”，500 个仓库的合规基线通过数据驱动保证
2. ConfigMerger：类型安全的配置合并，Groovy 的类型系统在复杂合并场景下比 shell + yq 更可靠
3. StageGenerator：运行时动态决定流水线结构，天然支持 500 个仓库的差异化 stage 需求
4. 规模化运维挑战：主节点 OOM、Vault 限流、插件升级——这些在小规模时不显著的问题在 500+ 规模下需要系统性应对

下一篇将介绍如何在 GitHub Actions 中实现等价能力，以及在 500+ 规模下 GitHub Actions 方案特有的工程优势。

当你的组织有 500 个仓库各自维护一套 CI/CD 配置时，问题不是”要不要统一”，而是”分散的代价你能承受多久”。本文来自一个已在 500+ 仓库生产环境运行 2 年以上的统一 CI/CD 平台的实践总结。

一、一个真实的场景

平台团队在某个周五下午收到安全团队通知：代码扫描工具需要升级，旧版本存在已知漏洞，要求在 2 周内全部迁移。

如果是统一流水线，平台团队修改一个文件，提一个 PR，合并后所有仓库在下次 CI 运行时自动使用新版本。2 小时内完成，500 个仓库同步更新。

如果是 500 个仓库各自维护，则需要：

1. 找出所有仓库的 CI 配置文件——格式各异，有 Jenkinsfile、ci.yaml、build.groovy、.travis.yml
2. 评估每个仓库的版本和升级影响（其中约 80 个已无活跃维护者）
3. 为每个仓库提 PR，等待各自团队 review 和合并
4. 协调 500 个团队，追踪哪些完成、哪些在等待、哪些无人响应
5. 两周后复查，发现仍有 130+ 个仓库未完成
6. 向安全团队解释”部分合规”的原因

在 500+ 仓库规模下，这不是一个可执行的方案——这是一个系统性失控。

二、分散管理在 500+ 规模下的四类代价

2.1 安全策略变更传播的指数级成本

安全相关的 CI 步骤包括：依赖漏洞扫描、静态代码分析（SAST）、容器镜像扫描、代码签名。这些工具会定期更新，扫描规则会调整，认证凭证会轮换。

在小规模（20 个仓库）时，人工协调勉强可行。到 500+ 仓库时，”广播问题”演变成一个不可解的协调问题：

1
2
3
4
5
6
7
8
9
10

平台团队发出通知（第0天）
    │
    ├─► 仓库 001-100（核心团队，约2周内完成）
    ├─► 仓库 101-250（普通团队，推迟到下个 Sprint，约4周）
    ├─► 仓库 251-380（低活跃仓库，原维护者离职，无人响应）
    ├─► 仓库 381-450（使用不同 CI 工具，通知没触达）
    └─► 仓库 451-500（外包团队，响应周期不定）

第 60 天：仍有约 200 个仓库未完成
第 90 天：审计截止日，组织处于"部分合规"状态

“部分合规”在审计中比”明确不合规”更棘手——你无法简洁地说明状态，只能提供一份不断变化的进度列表。

统一管理的改变： 平台团队提交 1 个 PR → 合并 → 500 个仓库在 24 小时内完成更新（随各仓库下次 CI 运行）。安全团队得到一个确定的答案。

2.2 凭证泄漏面积：从 1 个入口到 500 个风险点

Vault token、Registry 密码、代码签名证书——这些凭证在 CI 中使用。分散管理时：

• 500 个仓库的 Jenkinsfile 或 CI YAML 都可能错误引用凭证
• 凭证轮换时，需要确认 500 个地方都已更新（通常做不到）
• 某个开发者在调试时把临时 Registry 密码提交到 CI 配置里——在 500 个仓库中这每年至少发生数次

真实案例（已脱敏）： 平台团队在安全扫描中发现，有 23 个仓库的 CI 配置文件中存在凭证引用问题——有的是硬编码测试密码，有的是已失效但仍存在的 token 字符串。清理这 23 个问题耗时 3 周，因为每个仓库都需要单独联系负责人、确认影响、提 PR、合并。

在统一管理架构中，这不可能发生——业务仓库的 CI 文件没有任何凭证，凭证只存在于平台的 Vault 中，通过 JWT/OIDC 运行时动态获取。

2.3 合规审计：从”一句话”到”500 份文档的汇总”

SOC 2、ISO 27001 等合规框架要求证明所有代码在合并前经过了安全扫描。

分散管理（500 个仓库）时，审计对话：

• 审计员：”你们所有仓库都启用了 SAST 扫描吗？”
• 平台团队：”应该都有，但我们需要逐一检查才能确认”
• 审计员（三周后）：”我们抽查了 30 个仓库，其中 8 个 SAST 配置不一致或版本过旧”
• 结果：审计发现，需要整改

统一管理时，审计对话：

• 审计员：”你们所有仓库都启用了 SAST 扫描吗？”
• 平台团队：”是的。所有 500+ 个仓库调用同一个 platform-ci-core.yml 入口，该入口强制执行安全扫描步骤（allowOverride: false），业务团队无法绕过。这是 Vault 审计日志，这是过去 30 天的 CI 运行记录。”
• 结果：审计通过，5 分钟内给出完整证据

在 500+ 规模下，合规审计的答案质量直接影响审计结论。统一管理让”所有仓库的安全基线一致”从一个努力方向变成一个可证明的事实。

2.4 最佳实践漂移：500 个仓库，500 个不同时间点的”最佳实践”

CI/CD 最佳实践持续演进：缓存策略从无到有、并行度从单线程到并行、构建缓存从本地到分布式、artifact 管理从临时存储到带保留策略的管理。

分散管理时，每个仓库的 CI 配置质量取决于它最后一次被认真维护的时间点。在 500 个仓库中：

• 约 100 个仓库有积极维护，CI 质量较好
• 约 200 个仓库是 2-3 年前写的配置，用着当年的”最佳实践”
• 约 150 个仓库是从其他仓库 copy-paste 来的，连原始的注释都没有改
• 约 50 个仓库几乎无人知道 CI 是怎么跑起来的

结果： 组织的 CI 速度和质量呈现严重的长尾分布。某些仓库的 CI 需要 45 分钟，另一些只需要 8 分钟——不是因为业务复杂度不同，而是因为 CI 配置质量天壤之别。

统一管理后，平台团队对所有仓库做一次构建速度优化，500 个仓库同步受益。这是规模效应的直接体现。

三、统一管理的核心价值：分离关注点

统一管理的本质不是”控制”，而是明确划定谁负责什么：

1
2
3
4
5
6
7
8
9
10
11
12
13

平台团队负责（一次实现，500+ 仓库受益）：
├─ CI/CD 流水线逻辑（如何 build、如何 test、如何 deploy）
├─ 安全工具的版本和配置
├─ 凭证管理和轮换（Vault JWT/OIDC）
├─ 合规规则的执行（allowOverride: false 强制步骤）
├─ 流水线可观测性（日志、通知、状态上报）
└─ 性能优化（构建缓存、并行度调整）

业务团队负责（只需维护这一件事）：
├─ 业务代码
├─ 测试代码
├─ .ci-config/config.yaml（声明业务意图）
└─ 接受流水线运行结果

在 500+ 规模下，这个分离的价值是线性叠加的：平台团队的每一次改进，都乘以 500 这个系数。

业务团队的 .ci-config/config.yaml 是意图声明，不是实现细节：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 业务团队的 .ci-config/config.yaml
# 我需要 Python 3.12 环境
containers:
  - name: project-runtime
    image: platform-registry.example.com/python:3.12

# 我需要对这几个模块做 lint
jobs:
  - name: lint
    steps:
      - pyLint:
          sourceSets:
            - src/my_module
            - src/another_module
          rcFile: .pylintrc

# 我有单元测试
  - name: unit-test
    steps:
      - script:
          workspace: tests/run_tests.sh

# 我需要构建容器镜像（公网发布）
containerBuild:
  path: Dockerfile
  registryType: internet

业务团队不需要知道：

• 扫描工具的版本（Semgrep 的规则集版本由平台统一管理）
• 镜像 Registry 的地址（随环境自动路由）
• Vault 凭证的路径（JWT/OIDC 运行时获取）
• 如何打镜像 tag、如何签名、如何上报状态

这些由平台团队在流水线代码中处理，一次修改，500 个仓库同步受益。

四、业务团队的接入体验

理想状态下，一个新业务仓库接入统一 CI 的完整工作是：

1. 创建 .ci-config/config.yaml，声明运行环境和所需任务（约 20 行 YAML）
2. 在 .github/workflows/ci.yml 中调用平台流水线（约 15 行 YAML）
3. 提交代码，流水线自动运行

没有 Vault 配置，没有 Registry 凭证，没有 工具版本选择。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 业务仓库的 .github/workflows/ci.yml（完整文件）
name: CI

on:
  push:
    branches: [trunk, releases/latest]
  pull_request:
    branches: [trunk, releases/latest]
  pull_request_target:
    branches: [trunk, releases/latest]

jobs:
  pipeline:
    if: >-
      github.event_name != 'pull_request_target' ||
      github.event.pull_request.head.repo.full_name != github.repository
    uses: OrgA/.github/.github/workflows/platform-ci-core.yml@main
    # 无 with: 块 —— 所有配置从 .ci-config/config.yaml 读取
    # 无 secrets: 块 —— 凭证由平台流水线内部处理

这 15 行是业务团队需要维护的全部 CI 代码。在 500+ 仓库规模下，接入流程的简洁程度直接决定了新团队的上手速度和存量仓库的迁移成本。

五、500+ 规模特有的挑战

在小规模（20-50 个仓库）时不显著的问题，在 500+ 规模时会成为系统性痛点：

5.1 Onboarding 自动化

手动接入 20 个仓库是可行的，接入 500 个需要工具化：

1
2
3
4
5
6
7
8

# 批量检查哪些仓库还没有 .ci-config/config.yaml
gh repo list OrgA --limit 1000 --json name,defaultBranchRef \
  | jq -r '.[].name' \
  | while read repo; do
      if ! gh api "repos/OrgA/${repo}/contents/.ci-config/config.yaml" &>/dev/null; then
        echo "${repo}: 缺少 .ci-config/config.yaml"
      fi
    done

平台团队需要提供脚手架工具，让新仓库可以用一条命令生成标准的 config.yaml 模板。

5.2 配置漂移检测

500 个仓库接入后，随着时间推移，部分仓库的 config.yaml 可能变得不合规（字段格式变更、废弃字段未清理、新增必填字段缺失）。需要定期的合规性扫描：

1
2
3
4
5
6

# 定期扫描所有仓库的 .ci-config/config.yaml 合规性
# 检查必填字段、检查废弃字段、检查版本兼容性
for repo in $(get_all_repos); do
  validate_config "${repo}/.ci-config/config.yaml" || \
    echo "${repo}: 配置不合规" >> violation_report.txt
done

5.3 可观测性：500 个流水线同时运行

在 500+ 规模下，平台团队需要知道：

• 今天有多少个 CI 运行失败？失败原因分布？
• 平均 CI 耗时趋势？哪些仓库是异常慢的尾部？
• 安全扫描覆盖率？哪些仓库超过 30 天没有 CI 运行？

这需要在流水线中内置 metrics 上报，以及统一的 dashboard。

5.4 Runner 容量规划

500+ 仓库同时触发 CI（如 trunk push 后）会产生并发 job 峰值。需要根据历史数据规划 runner 数量和自动扩缩容策略。

六、”统一”不等于”强制相同”

统一管理容易被误解为”所有仓库必须用完全相同的 CI”。好的统一管理架构支持受控的差异化：

• 有些仓库有单元测试，有些没有 → config.yaml 声明是否有 unit-test job
• 有些仓库需要构建容器镜像，有些是纯 Python 库 → config.yaml 声明是否有 containerBuild
• 有些仓库镜像需要公网发布 → registryType: internet
• lint 的 rcFile 可以是仓库自己的 → rcFile: .pylintrc

平台团队通过 allowOverride 机制明确哪些是可定制的，哪些是平台强制的：

1
2
3
4
5
6
7
8
9
10
11
12
13

# platform-defaults.yaml（平台团队维护）
jobs:
  - name: security-scan
    allowOverride: false  # 安全扫描不允许业务团队关闭
    steps:
      - semgrep:
          rulesets: ["p/python"]

  - name: lint
    allowOverride: true   # lint 配置允许业务团队覆盖
    steps:
      - pyLint:
          sourceSets: []

即使某个业务团队在 .ci-config/config.yaml 中写了 security-scan: disabled，流水线也会忽略并强制运行安全扫描。这是 500+ 仓库合规基线的技术保证。

七、投入与回报的规模效应

统一管理的初始投入是固定的（平台团队设计和实现流水线框架），但收益随仓库数量线性增长：

这个数字在 20 个仓库时看起来”够用”，在 500 个仓库时变成了战略差距。

八、小结

分散 CI 管理在 500+ 规模下的代价是系统性的：

• 安全更新传播：从”2 小时”变成”3 个月且仍未完成”
• 凭证泄漏面积：从”1 个入口”变成”500 个潜在风险点”
• 合规审计：从”5 分钟给出证据”变成”数周整改”
• 最佳实践漂移：500 个仓库，500 个不同时代的 CI 配置

统一管理的核心价值是分离关注点，结合规模效应：平台团队掌控流水线实现，业务团队只需声明意图，每一次平台改进都乘以 500 的系数。.ci-config/config.yaml 是这个边界的物理载体。

本系列后续三篇将分别介绍：

• Jenkins Shared Library 的完整工程实现
• GitHub Actions Reusable Workflow 的零配置架构
• 从 Jenkins 迁移到 GitHub Actions 的决策框架