Renovate 配置总览从 Default 到 Repository 的完整配置层级、加载顺序与合并机制【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovateRenovate本仓库即 Renovate CLI 的完整源码实现每次在仓库上运行时都会按固定顺序读取多种来源的配置并合并成一份最终配置final config这份最终配置决定了本次运行的一切行为。本文以 Renovate 官方配置总览文档为骨架结合仓库源码lib/config与lib/workers/global/config/parse等逐层拆解默认配置、全局配置文件 / 附加文件 / 环境变量 / CLI、继承配置、预设解析与仓库配置的加载顺序、优先级与合并规则并给出可直接落地的配置示例与 GitLab CI 下的 Onboarding 配置实战。配置的读取顺序与优先级核心规则每当 Renovate 处理一个仓库时它会按照下面这个从上到下的顺序读取配置最终生成一份完整的运行期配置Default config默认配置Global config全局配置内部再细分为File config配置文件Additional file config附加配置文件Environment config环境变量配置CLI config命令行参数配置Inherited config继承配置Resolved presets referenced in config配置中引用并解析后的预设Repository config仓库配置优先级规则非常简单编号越大的配置项覆盖编号越小的配置项。也就是说 Repository config 优先级最高Default config 优先级最低在同一层内部CLI 参数又优先于环境变量、环境变量优先于文件。唯一例外是如果某个配置项带有mergeable可合并属性那么它不会被覆盖而是与低层级的同名配置执行合并merge操作。关于合并语义可以从源码 lib/config/utils.ts 的mergeChildConfig函数看到具体实现对于标为mergeable的选项如果父子配置同时存在数组类型会执行concat拼接对象类型会递归调用mergeChildConfig继续合并此外constraints这种对象类型采用浅展开合并。最后还会执行{ ...config, ...config.force }把force块中的设置强制覆盖到结果上——这正是文档中Force config边缘案例的底层来源。需要注意最终配置是 Renovate内部运行期概念它不会被保存或缓存以供下次运行使用但你随时可以在 Renovate 的日志中找到这份最终配置通常以 debug 级别输出排查为什么 Renovate 的行为和我配置的不一样时这是最直接的依据。若你使用 Mend 托管的 Renovate App请在读完本文后继续阅读 Mend 托管应用配置该页面与本文互补。五类配置详解默认配置Default config每一个 Renovate 配置项都有默认值/默认设置默认值甚至可以是null。默认配置最先被加载后续所有类型的配置都可以覆盖它。例如onboarding的默认值为true即默认会为没有配置文件的仓库创建 Onboarding PRlabels选项没有默认值意味着默认情况下 Renovate 创建的 PR 不会自动打任何标签。各选项的默认值、类型、适用阶段stage与是否仅限全局globalOnly都集中定义在 lib/config/options/index.ts 的选项注册表中。例如requireConfig的默认值为required、inheritConfig的默认值为false、onboardingConfig的默认值为{ $schema: https://docs.renovatebot.com/renovate-schema.json }这些默认值都直接写在该文件的default字段中是文档所述默认行为的代码级证据。全局配置Global config全局配置由负责部署和运行 Renovate 的个人或团队定义它既可以包含仅全局可用的配置也可以包含任何在继承配置或仓库配置中合法的普通配置项。历史上它被称为 bot config如今官方已弃用 bot 术语改称 global self-hosted configuration全局自托管配置。如果你是 Renovate 的终端用户例如使用 Mend Renovate App则通常无需关心全局配置——有些设置是全局独有的终端用户无法修改此时可以直接跳到后面的继承配置小节。但要注意全局配置至少要配置一种来源文件、环境变量或 CLI 参数否则 Renovate 缺少运行所需的信息例如平台凭据 token将无法运行。全局配置有三类来源下面依次说明。文件配置File configRenovate 首先尝试从文件中读取全局配置默认在当前工作目录查找config.js文件可以通过环境变量RENOVATE_CONFIG_FILE覆盖默认路径例如RENOVATE_CONFIG_FILE/tmp/my-renovate-config.js。文件存在性处理规则很明确默认情况下允许配置文件缺失找不到也不会报错但一旦你显式设置了RENOVATE_CONFIG_FILE而指定路径不存在Renovate 会判定这是配置错误并报错退出。如果文件存在但无法解析同样会报错退出。从源码 lib/workers/global/config/parse/file.ts 可以看到getConfig首先取env.RENOVATE_CONFIG_FILE ?? config.js用fs.pathExists检查存在性当RENOVATE_CONFIG_FILE已设置但文件缺失时直接logger.fatal并以process.exit(1)退出。解析失败时SyntaxError/TypeError/ReferenceError等同样致命退出只有在未显式指定配置文件的场景下读取或解析错误才会被降级为 debug 日志并跳过。全局配置文件可以是.js或.json文件。.js文件内可以使用同步或异步方法甚至可以远程获取配置信息。文件解析的具体逻辑在 lib/config/parse.ts.json5扩展名走JSON5.parse其余情况先通过json-dup-key-validator做严格的重复键检查并先剥离注释与尾逗号再用宽松的 JSONC 解析器解析因此 JSON 配置天然支持注释与尾逗号。附加文件配置Additional file config仅当设置了环境变量RENOVATE_ADDITIONAL_CONFIG_FILE时Renovate 才会尝试读取第二个全局配置文件例如RENOVATE_ADDITIONAL_CONFIG_FILE/tmp/my-additional-renovate-config.js存在性与解析错误的行为和 File config 完全一致未设置时不读取设置了但找不到文件、或文件无法解析时都报错退出。支持.js或.json.js内同样允许同步/异步方法。实现位于 lib/workers/global/config/parse/additional-config-file.ts。警告不要把附加配置文件命名为config.js该名称已被 File config 保留占用。附加文件配置的引入使得基础全局配置 运行环境专用覆盖成为可能例如同一套配置库在开发与生产环境通过附加文件注入不同的 token 或开关。环境变量配置Environment config全局配置可以通过环境变量定义所有可用作环境变量的配置项都带有RENOVATE_前缀。例如RENOVATE_PLATFORMgitlab等价于在 File config 中设置platform: gitlab。环境变量名与配置项名通常存在清晰的映射源码 lib/config/options/env.ts 的getEnvName展示了自动推导规则——默认把配置名中的大写字母转成_大写并整体大写即onboardingConfig→RENOVATE_ONBOARDING_CONFIG若选项显式声明了env字段则优先使用若选项设置了env: false则没有对应的环境变量。因此在为某个选项设置环境变量前仍建议查阅该选项文档中的env字段确认若某配置项没有env字段或env: false它就没有对应的环境变量名无法通过环境变量设置。环境变量配置有一个特殊元选项RENOVATE_CONFIG它接受一段字符串化的完整配置例如RENOVATE_CONFIG{platform:gitlab,onboarding:false}RENOVATE_CONFIG等价于把整份配置以 JSON 字符串形式传入其余单独的环境变量配置优先级高于RENOVATE_CONFIG中的同名值。在 lib/workers/global/config/parse/env.ts 的getConfig中可以看到先解析RENOVATE_CONFIG随后遍历所有选项把各自对应的RENOVATE_*环境变量逐一覆盖到配置上从而实现了单独环境变量覆盖元配置的语义。环境变量示例注意转义警告请务必转义标点符号尤其是传入字符串化值时更要小心。布尔值RENOVATE_ONBOARDINGtrue字符串RENOVATE_BASE_DIR/tmp/something、RENOVATE_BASE_DIR/tmp/some thing数字RENOVATE_PR_HOURLY_LIMIT1字符串/数字列表RENOVATE_LABELSabc,def,label with space对象或对象列表RENOVATE_CONFIG{platform\:\gitlab\,\onboarding\:false}、RENOVATE_PACKAGE_RULES[{matchHost:\gitlab\,token:\$SOME_TOKEN\}]提示字符串和对象建议先用在线 JSON stringify 工具序列化后再赋值避免手写转义出错。实验性环境变量Renovate 提供以RENOVATE_X_开头的实验性环境变量。它们随时可能变更且不作为常规配置的一部分被解析。需要特别注意的是一部分实验变量已经转正为常规配置项在 lib/workers/global/config/parse/env.ts 的convertedExperimentalEnvVars映射表中可以看到RENOVATE_X_AUTODISCOVER_REPO_SORT→autodiscoverRepoSort、RENOVATE_X_AUTODISCOVER_REPO_ORDER→autodiscoverRepoOrder、RENOVATE_X_DOCKER_MAX_PAGES→dockerMaxPages、RENOVATE_X_S3_ENDPOINT→s3Endpoint等自动转换逻辑。更完整的说明请阅读自托管实验性环境变量文档。日志相关变量还有一组特殊的日志环境变量它们在配置解析之前就被加载因为日志系统初始化需要它们LOG_CONTEXT每条日志消息中用于追踪上下文的唯一标识符LOG_FILE启用文件日志并指定日志文件路径LOG_FILE_FORMAT默认为json可改为pretty人可读输出LOG_FILE_LEVEL文件日志级别默认为debugLOG_FORMAT默认为pretty人可读输出可改为jsonLOG_LEVEL最常用默认info排查问题时通常调到debug。CLI 配置CLI config全局配置的最后一种来源是 CLI 参数。例如--platformgitlab等价于 File config 中的platform: gitlab或环境变量RENOVATE_PLATFORMgitlab。CLI 配置最后读取优先级高于环境变量与文件配置。例如同一值在环境变量、File config 与 CLI 中互相冲突时CLI 配置最后合并并胜出。使用 CLI 配置时有两个硬性要求布尔值也必须显式传值例如--onboardingtrue不能只写--onboarding优先使用号而非空格例如--onboardingtrue而不是--onboarding true。从源码 lib/workers/global/config/parse/cli.ts 可以看到 CLI 解析基于 commander 实现遍历全部选项注册表把每个选项名的大写字母转成-小写生成--xxx参数getCliName并按选项类型做强制类型转换coersions。仓库自带的 CLI 示例包括$ renovate --token 123test singapore/lint-condo $ LOG_LEVELdebug renovate --labelsrenovate,dependency --ignore-unstablefalse singapore/lint-condo $ renovate singapore/lint-condo singapore/package-test $ renovate singapore/lint-condo --onboarding-config{extends:[config:recommended]}此外migrateArgs会对已废弃/裸标志做自动迁移例如--dry-run→--dry-runtrue、--include-forks→--fork-processingenabled、--endpoints→--host-rules等保证旧脚本仍可运行。继承配置Inherited config使用场景继承配置Inherited config的核心目的是为组织/群组提供默认设置两大典型场景是控制组织内的 Onboarding 行为例如禁用 onboarding、将配置设为可选为组织内各仓库定义默认配置。官方建议组织优先使用共享预设shared presets而非继承配置但以下场景继承配置依然有价值你不想在每个仓库里都手写 Repository config你在拥有统一组织配置之前就已经 onboarding 了大量仓库不想事后逐个回改每个仓库的配置。如何被找到当全局配置中inheritConfig为true时Renovate 会在处理每个仓库之前查找继承配置。查找的仓库名与文件名可由全局配置中的其他inheritConfig*选项配置默认值分别是仓库名inheritConfigRepoName{{parentOrg}}/renovate-config支持模板占位符文件名inheritConfigFileNameorg-inherited-config.json。注意在 Azure DevOps 中{{parentOrg}}指仓库所属的 Project在 Bitbucket 中指仓库所属的 Workspace。各平台实际位置如下表平台继承配置文件位置GitHub{parentOrg} / renovate-config / org-inherited-config.jsonBitbucket{parentWorkspace} / renovate-config / org-inherited-config.jsonAzure DevOps{parentProject} / renovate-config / org-inherited-config.json上述默认值都定义在 lib/config/options/index.ts 的选项注册表中inheritConfig默认false、inheritConfigRepoName默认{{parentOrg}}/renovate-config、inheritConfigFileName默认org-inherited-config.json、另有inheritConfigStrict与实验性的inheritConfigTrusted选项。查找与合并逻辑实现在 lib/workers/repository/init/inherited.tsmergeInheritedConfig在config.repository与config.inheritConfig均存在时解析模板化的仓库名从平台拉取继承配置文件并解析、解密、校验后合并到全局配置之上。如果找到了继承配置它会合并覆盖到全局配置之上。需要注意不要在继承配置中放置任何全局独有的设置否则会报错。继承配置可以使用全部 Repository config 设置以及文档中标注了supportsInheritConfig源码中对应inheritConfigSupport属性属性的全局配置项——例如configFileNames、onboardingConfig、requireConfig等。另外若全局设置了inheritConfigTrustedtrue继承配置中的hostRules才被允许授予内部主机访问权限allowInternal否则相关规则会被拒绝这是组织管理员控制继承配置权限边界的手段见 lib/workers/repository/init/inherited.ts 中inheritedHostRuleOptions的实现注释。预设Presets处理如果继承配置中包含extends预设Renovate 会解析这些预设把解析后的预设配置添加到继承配置的开头把预设合并到全局配置之上。无法忽略继承配置中的预设你不能在仓库配置中使用ignorePresets来忽略继承配置内部的预设——因为继承配置在仓库配置之前就已解析完成。仓库配置Repository config仓库配置是从仓库内的配置文件中加载的配置。默认文件名为renovate.json也支持其他文件名通过全局配置项configFileNames自定义文件名列表见 lib/config/options/index.ts 中configFileNames的定义其为仅全局且支持继承的数组选项。如果在同一仓库中发现多个配置文件Renovate 使用第一个找到的配置文件并忽略其余文件。配置优先级Config precedence仓库配置加载完成后会合并到之前已加载的全局与继承配置之上因此仓库配置的优先级最高。配置中通过extends引用的预设会先被解析且优先级低于同一文件或同一配置对象中的普通/原始配置——也就是说你在仓库配置里直接书写的字段可以覆盖extends预设带来的同名设置。Onboarding 流程与配置处理仓库时Renovate 最先做的决策之一就是这个仓库需要 onboarding 吗 默认情况下如果仓库的默认分支上没有提交任何 Repository config 文件Renovate 会创建一个带默认配置的Onboarding PR。Onboarding 配置创建 Onboarding PR 时Renovate 会提议一个待合并的 Repository config 文件。默认情况下它本质上是一份空配置——只引用 Renovate 的 JSON schema即源码中onboardingConfig的默认值{ $schema: https://docs.renovatebot.com/renovate-schema.json }——但你可以按需改变这一行为。如果在全局配置或继承配置中设置了onboardingConfigRenovate 会直接使用该配置代替默认值例如配置onboardingConfig为自定义的 manager 文件匹配规则module.exports { // ... onboardingConfig: { argocd: { managerFilePatterns: [application\\.yaml$], }, }, };GitLab 自托管场景renovate-runner在 GitLab 上使用renovate-runner自托管时其 CI 模板会默认注入一个RENOVATE_ONBOARDING_CONFIG变量会与你的配置合并默认内容大致为RENOVATE_ONBOARDING_CONFIG: {$$schema: https://docs.renovatebot.com/renovate-schema.json, extends: [config:recommended] }如果你想修改其中的extends需要在自己的.gitlab-ci.yml中覆盖该变量variables: RENOVATE_ONBOARDING_CONFIG: {$$schema:https://docs.renovatebot.com/renovate-schema.json,extends:[platformorganization/repo:renovate-config]}注意你运行 Renovate 的renovate.js中不能包含任何extends定义extends会取自RENOVATE_ONBOARDING_CONFIG变量。例如上述renovate.js与变量组合后最终生成的 onboarding 配置为{ $schema: https://docs.renovatebot.com/renovate-schema.json, argocd: { managerFilePatterns: [/application\\.yaml$/] }, extends: [platformorganization/repo:renovate-config], }GitLab CI 下环境变量与文件配置合并的实现原理可参考 lib/workers/global/config/parse/env.ts 与 lib/workers/global/config/parse/file.ts 的解析与migrateAndValidate处理链。按约定自动发现组织默认预设如果你遵循 Renovate 的共享预设命名约定它还能自动检测这些预设。若仓库{{parentOrg}}/renovate-config中存在default.json该文件会被视为组织的默认预设并包含进 Onboarding 配置对于支持嵌套 Organization/Group 层级的平台Renovate 会沿着层级向上寻找带默认配置的renovate-config仓库命中第一个即停止。注意如果预设仓库中找不到default.jsonRenovate 也会检查是否存在renovate.json文件但该做法已废弃、不推荐使用。此外如果在组织内的renovate-config仓库中未找到默认配置Renovate 还会检查与当前仓库平行的.{{platform}}仓库中是否存在renovate-config.json文件。例如被 onboarding 的仓库是 GitHub 平台上的abc/defRenovate 会检查abc/.github仓库中是否存在renovate-config.json。改变默认行为组织的默认 onboarding 行为可以在全局配置或继承配置中修改设置onboardingfalseRenovate 将不对仓库进行 onboarding并跳过任何没有 Repository config 的仓库。换句话说用户必须手动提交一份有效的 Repository config 文件才能激活 Renovate设置onboardingfalse同时requireConfigoptionalRenovate 会跳过 onboarding并且即使找不到任何 Repository config 也会继续在仓库上运行。从源码看requireConfig的合法取值为required、optional、ignored默认required且为仅全局、支持继承的选项见 lib/config/options/index.ts。另外在全局解析阶段 lib/workers/global/config/parse/index.ts 还有一处贴心处理非 autodiscover 模式下会把onboardingNoDeps从auto强制为enabled确保显式指定单个仓库时即使没有发现依赖也会完成 onboarding。共享预设Shared Presets概述共享配置shared configuration / presets的完整概念在预设Presets文档中有详细讲解请先阅读该文档再继续本节。本节聚焦预设如何在配置层级中发挥作用。全局配置中的预设使用在全局配置中使用预设需要格外谨慎因为它们经常引发误解。关键区别在于globalExtends与extends两个选项。globalExtends有时你不想把所有设置都写进全局配置本身而是希望提交到一个仓库中、再从全局配置引用它。此时应使用globalExtends而不是extends——globalExtends会在全局配置处理期间被立即解析并作为全局配置的一部分生效。从源码看globalExtends是仅全局globalOnly: true的字符串数组选项定义在 lib/config/options/index.ts 中。extends如果在全局配置中使用extends请务必注意这些预设不会在全局配置处理期间被解析/展开而是会原样透传到 Repository config 中作为其一部分。将extends透传至 Repository config 会带来两个重要后果仓库用户可以借助ignorePresets忽略extends预设的全部或部分内容全局配置extends中定义的预设其优先级高于普通全局配置——因为它是在更晚的阶段才被解析的。使用集中式配置Centralized config通过 Renovate 预设实现集中式配置的意义在于节省时间不必在每个仓库中重复同样的配置一处修改全局生效可以在一个位置改变整个组织或一组仓库的设置。创建好集中式预设后有多种方式将其传递给各仓库按对终端用户可见性从低到高排列在全局配置中定义使用globalExtends或extends将其作为继承配置使用或通过继承配置的extends引用它确保它被引用进 Onboarding 配置从而随 Repository config 一并提交到仓库。可见性差异值得关注全局配置对开发者可能是不可见的没有日志访问权限就看不到因此你在全局配置中通过预设或直接设置的任何行为都可能让开发者困惑——他们会奇怪为什么 Renovate 的行为与文档默认行为不一致甚至误以为是 bug继承配置对开发者是可见的它位于他们能看到的仓库中但它是隐式应用的——如果没有日志访问权限、且不清楚要去查找继承配置仓库开发者同样可能困惑为什么默认行为变了。推荐做法让每个仓库显式地extends集中式预设这可以通过把预设纳入你的onboardingConfig轻松实现。集中式预设成为每个仓库 Repository config 的extends一部分后有两个好处你依然可以在一处修改共享设置任何查看仓库的人都能看到被 extend 的预设并顺藤摸瓜理解实际应用了哪些配置。其他边缘情况以下内容涉及一些例外规则属于应尽量避免、通常也用不到的场景但了解它们有助于理解配置系统的边界。Optimize for Disabled为禁用场景优化optimizeForDisabled选项针对大量仓库被配置禁用这种边缘场景设计。当该选项设为true时Renovate 会先通过一次平台 API 调用检查renovate.json是否存在、且是否包含enabled: false如果命中仓库会被直接跳过无需克隆如果文件不存在或并未禁用 Renovate则 Renovate 照常继续相当于浪费了这一次额外的 API 调用。从源码看该选项默认false、仅全局、作用于 repository 阶段见 lib/config/options/index.ts 中optimizeForDisabled的定义。是否启用需要在省下一次克隆与每次多一次 API 调用之间权衡适合仓库数量极大且多数通过enabled: false关闭的场景。Force config强制配置官方建议尽量避免使用force配置选项。force可以将配置强制覆盖到其他之后才合并的配置或规则之上因此有时会造成混乱——尤其是定义在全局配置中、却覆盖了仓库配置里的设置时。源码层面mergeChildConfig的最后一行return { ...config, ...config.force }lib/config/utils.ts揭示了其机制任何位于force对象内的键都会被无条件覆盖到合并结果上。另有forceCli选项默认true决定 CLI 配置是否被移动进force段进一步放大了这种强制语义。除非你确切理解后果否则请避免在生产配置中使用它。从源码看配置的加工流水线在各类配置被合并之前每一份输入配置都要经过 lib/config/migrate-validate.ts 的migrateAndValidate处理流水线包括迁移migration通过 lib/config/migrations/migrations-service.ts 将旧版配置键迁移到新键。例如endpoints→hostRules、masterIssue→dependencyDashboard、regexManagers→customManagers、versionScheme→versioning、baseBranches→baseBranchPatterns等重命名以及一批已删除属性如gitFs、maintainYarnLock的移除按摩massage把字符串形式的配置归一化例如把单个字符串转成数组校验validation调用 lib/config/validation.ts 的validateConfig检查选项名、类型、合法取值如requireConfig仅允许required|optional|ignored、调度表达式与时区等产出 warnings 与 errors 两类结果。经过迁移、按摩与校验后配置还会经历多阶段过滤全局配置中globalOnly的选项会在进入仓库阶段前被剥离lib/config/index.ts 的removeGlobalConfig保证仓库配置无法触碰全局专属设置filterConfig则按global → inherit → repository → package → branch → pr的阶段顺序逐级过滤掉不应在当前阶段出现的选项。这套流水线保证了最终配置既向后兼容旧配置自动迁移、又安全可控全局与仓库边界清晰。小结一份配置从提交到生效的完整路径进程启动时日志变量先行加载LOG_*随后按File config → Additional file config → Environment config → CLI config的顺序解析全局配置其中RENOVATE_CONFIG提供整包JSON 入口单独的RENOVATE_*变量覆盖之CLI 参数最后生效每份输入都经过迁移、按摩、校验lib/config/migrate-validate.ts处理每个仓库前若inheritConfigtrue从{{parentOrg}}/renovate-config仓库拉取org-inherited-config.json并合并到全局配置之上lib/workers/repository/init/inherited.ts读取仓库内第一个配置文件默认renovate.json合并到继承配置之上形成最高优先级的配置层extends预设先解析、优先级低于同文件的原始配置无仓库配置文件时进入 Onboarding 流程按onboardingConfig默认仅含 JSON schema生成 Onboarding PR若存在{{parentOrg}}/renovate-config仓库的default.json等约定预设也会被自动纳入最终配置合并完成后由removeGlobalConfig剥离全局专属选项得到仓库阶段实际执行的配置最终配置不落盘、不缓存但完整记录在日志中是定位配置为什么没生效的第一现场。掌握了这套配置层级、优先级与合并机制你就能准确预判任何配置来源之间的冲突结果并为组织设计出默认配置兜底、组织预设统一、仓库显式扩展的清晰配置治理方案。延伸阅读预设Presets核心概念Mend 托管应用配置自托管实验性环境变量自托管配置完整选项配置实现与测试选项注册表 lib/config/options/index.ts、合并逻辑 lib/config/utils.ts、全局配置解析 lib/workers/global/config/parse/index.ts 及其file.ts/env.ts/cli.ts/additional-config-file.ts子模块、继承配置实现 lib/workers/repository/init/inherited.ts、配置迁移服务 lib/config/migrations/migrations-service.ts【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考