Renovate CircleCI Manager 使用指南自动更新 Docker 镜像与 Orb 依赖【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate导读本文围绕 Renovate 仓库中 circleci manager 的官方文档展开介绍如何让 Renovate 自动解析 CircleCI 配置文件.circleci/config.yml并从中提取两类依赖——docker镜像与orbOrb 引用——进行版本更新。读完本文你将掌握 CircleCI manager 的默认文件匹配规则、支持的数据源与版本策略、YAML 锚点与私有 orb 的处理方法以及通过hostRules加密 Token 访问私有 orb 的完整配置方式并了解其背后的源码级实现原理。一、CircleCI manager 是什么circlecimanager 是 Renovate 内置的包管理器之一专门用于解析 CircleCI 配置文件从中提取两类数据源docker数据源提取executors、jobs以及aliases中声明的 Docker 镜像如node:18、cimg/ruby:3.0.3-browsersorb数据源提取orbs段落中引用的第三方 Orb如circleci/python2.1.1。该 manager 的类别为ci显示名称为CircleCI其官方默认配置在 index.ts 中定义export const defaultConfig { managerFilePatterns: [/(^|/)\\.circleci/.\\.ya?ml$/], }; export const supportedDatasources [DockerDatasource.id, OrbDatasource.id];managerFilePatterns默认匹配所有位于.circleci目录下、扩展名为.yml或.yaml的配置文件正则/\.circleci/.\.ya?ml$/无需在 Renovate 配置中额外指定fileMatchsupportedDatasources明确声明该 manager 只支持 Docker 与 Orb 两种数据源。从 dep-types.ts 可以看到 Renovate 官方对两种依赖类型的描述depType描述orbCircleCI orb referenceCircleCI Orb 引用dockerDocker image in executor/job configurationexecutor/job 配置中的 Docker 镜像注意该 manager 不处理machine类型的 executor。测试用例 extract.spec.ts 证实machine: { image: android:202102-01 }这类配置会被跳过并返回null。二、支持的文件结构与提取范围2.1 提取的配置字段从 schema.ts 的 Zod 模型可以看出manager 会解析 CircleCI 配置文件中的以下顶层字段orbsOrb 引用字符串形式或内嵌 Orb 定义对象形式executors自定义 executor 定义其中的docker镜像会被提取jobs任务定义其中docker数组中的镜像会被提取aliasesYAML 锚点定义的 Docker 镜像。对应到 extract.ts 的提取逻辑其处理顺序为遍历orbs字段若值为字符串按拆分为packageName与currentValue提取为orb依赖若值为对象内嵌 Orb 定义则递归处理其内部的orbs、executors与jobs合并executors与jobs对其中每个docker镜像调用getDep()复用 dockerfile manager 的镜像解析逻辑提取为docker依赖遍历顶层aliases同样提取为docker依赖若没有任何依赖被提取返回null表示该文件无需 Renovate 处理。2.2 支持的镜像写法结合测试用例与 fixtures以下写法均能被正确提取# 无 tag 的镜像视为无版本仅跟踪 digest - image: node # 带 tag 的镜像 - image: node:4 - image: cimg/node:14.8.0 # 带 digest 的镜像tag 与 digest 均会被更新 - image: python:3.7sha256:3870d35b962a943df72d948580fc66ceaaee1c4fbd205930f32e0f0760eb1077完整示例可见 config.yml 与 config2.yml。三、Orb 依赖的提取规则Orb 的写法为命名空间/包名版本提取时depName使用配置文件中的别名键名packageName使用命名空间/包名全名currentValue为后的版本versioning固定为 npm 版本策略Orb 版本遵循 semverdatasource为orb。orbs: release-workflows: hutson/library-release-workflows4.1.0 no-version: abc/def # 无版本号不触发更新 volatile: zzz/zzzvolatile # 非 semver 版本按原样保留对应测试 extract.spec.ts 验证了上述提取结果release-workflows被解析为depName: release-workflows、packageName: hutson/library-release-workflows、currentValue: 4.1.0、versioning: npm、datasource: orb。此外manager 还支持在配置文件中直接内嵌定义 Orb常见于本地复用此时会递归进入 Orb 定义内部继续提取其依赖version: 2.1 orbs: myorb: orbs: python: circleci/python2.1.1 executors: python: docker: - image: cimg/python:3.9 jobs: test_image: docker: - image: cimg/python:3.7 workflows: Test: jobs: - myorb/test_image该场景由测试 “extracts orb definitions” 覆盖。四、YAML 锚点与合并键Merge Key的处理CircleCI 配置大量使用 YAML 锚点与合并键复用配置片段例如jobs: node-base: node-base docker: - image: node steps: - checkout node-v4: : *node-base docker: - image: node:4Renovate 的 circleci manager 在解析时做了两个关键设计按 YAML 1.1 规范解析。源码注释extract.ts明确指出必须使用 YAML 1.1 的锚点合并语义来匹配 CircleCI 自身的行为。因为 YAML 1.2 会把同一映射中多个键判定为重复键而整体报错导致整个文件被跳过递归展开。即使同一映射中同时出现多个合并键如: *node-base与: *node-env共存也能正确合并并提取其中的镜像。测试 “extracts deps from configs with multiple merge keys per mapping” 专门验证了这种边界场景node:18从被合并进build任务的锚点中被正确提取而不会被重复键问题阻断。五、registryAliases私有镜像仓库别名如果镜像托管在私有/镜像仓库可以通过registryAliases配置将原始镜像名映射到实际拉取地址。circleci manager 会读取该配置并传递给getDep(){ registryAliases: { quay.io: my-quay-mirror.registry.com, index.docker.io: my-docker-mirror.registry.com } }当配置文件中出现quay.io/myName/myPackage:0.6.2时Renovate 会以packageName: my-quay-mirror.registry.com/myName/myPackage去查询数据源但更新时仍会在原位置写回quay.io/myName/myPackage:新版本由autoReplaceStringTemplate保证。该行为由测试 “handles registry alias” 验证。六、版本策略rangeStrategycircleci manager 通过 range.ts 定义默认的版本范围策略export function getRangeStrategy({ rangeStrategy }: RangeConfig): RangeStrategy { return rangeStrategy auto ? pin : rangeStrategy!; }即当全局rangeStrategy为auto时circleci manager 固定采用pin策略——将镜像/Orb 的 tag 固定为精确版本若用户显式指定了其他策略则遵循用户配置。这与 CI 配置“版本应明确可复现”的实践一致。七、私有 Orb 的访问配置hostRules 加密 Token原文档重点讲解了私有 Orb 的接入方法。CircleCI 的 Orb 数据源 OrbDatasource 通过 CircleCI APIhttps://circleci.com/api/v3/orb/packages查询版本信息私有 Orb 需要携带个人 API Token 才能访问。配置分为三步加密 Token将你的 CircleCI Token 通过 Renovate 官方加密页面https://app.renovatebot.com/encrypt加密需配合你的 Renovate 公钥新增hostRules条目在 Renovate 配置文件的hostRules数组中添加一条规则填入加密 Token将加密后的内容放入token字段。最终配置形如{ hostRules: [ { matchHost: circleci.com, authType: Token-Only, encrypted: { token: **** } } ] }关键点说明matchHost匹配 CircleCI 的请求主机circleci.com也支持匹配其子域名authType设置为Token-Only表示直接将 Token 原样放入authorization请求头而不附加Bearer或Basic前缀。原文档明确指出This config strips the Bearer/Basic prefix from the authorization header.该配置会去掉authorization头中的 Bearer/Basic 前缀encrypted.token使用仓库公钥加密后的 Token 值****仅为占位符。该行为与 HTTP 层认证实现 auth.ts 完全对应当authType Token-Only时options.headers.authorization options.token即 Token 直接作为请求头值不做任何前缀拼接其他authType才会拼成${authType} ${token}的格式。若你使用 Renovate 自托管self-hosted也可以在RENOVATE_TOKEN环境变量或配置中直接提供明文 Token未加密方式但这会降低安全性官方推荐优先使用上面的加密方案。八、典型配置速查一个完整的 Renovate 配置示例同时覆盖公共镜像、公共 Orb 与私有 Orb{ extends: [config:recommended], circleci: { fileMatch: [/(^|/)\\.circleci/.\\.ya?ml$/] }, hostRules: [ { matchHost: circleci.com, authType: Token-Only, encrypted: { token: **** } } ], registryAliases: { quay.io: my-quay-mirror.registry.com } }circleci.fileMatch可自定义匹配范围默认即为.circleci目录下的 yaml/yml 文件需要调整版本格式时可参考 versioning 文档 学习如何在 packageRules 中覆盖versioning字段circleci manager 默认对 orb 使用 npm semver 版本策略。九、验证与排错提取是否生效运行 Renovate 的 dry-run 或查看日志中的extract阶段输出若某文件未被识别先确认其路径是否符合默认fileMatch正则无依赖文件当文件中只有machineexecutor 或没有任何可识别依赖时manager 返回null参考 extract.ts这是预期行为而非报错私有 Orb 拉取失败检查hostRules的matchHost是否覆盖了实际请求域名Token 是否已加密且与公钥匹配YAML 解析被跳过若日志出现 “Error extracting circleci images”见 extract.ts通常意味着配置文件不符合 YAML 1.1 可解析的锚点/合并键语法请检查合并键的使用方式。十、延伸阅读manager 完整源码index.ts、extract.ts、schema.ts测试用例extract.spec.ts、index.spec.ts、range.spec.ts示例配置文件config.yml、config2.yml、config3.yml、config4.yml数据源实现DockerDatasource、OrbDatasource版本策略说明versioning 文档配置项详解configuration-options【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Renovate CircleCI Manager 使用指南：自动更新 Docker 镜像与 Orb 依赖
Renovate CircleCI Manager 使用指南自动更新 Docker 镜像与 Orb 依赖【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate导读本文围绕 Renovate 仓库中 circleci manager 的官方文档展开介绍如何让 Renovate 自动解析 CircleCI 配置文件.circleci/config.yml并从中提取两类依赖——docker镜像与orbOrb 引用——进行版本更新。读完本文你将掌握 CircleCI manager 的默认文件匹配规则、支持的数据源与版本策略、YAML 锚点与私有 orb 的处理方法以及通过hostRules加密 Token 访问私有 orb 的完整配置方式并了解其背后的源码级实现原理。一、CircleCI manager 是什么circlecimanager 是 Renovate 内置的包管理器之一专门用于解析 CircleCI 配置文件从中提取两类数据源docker数据源提取executors、jobs以及aliases中声明的 Docker 镜像如node:18、cimg/ruby:3.0.3-browsersorb数据源提取orbs段落中引用的第三方 Orb如circleci/python2.1.1。该 manager 的类别为ci显示名称为CircleCI其官方默认配置在 index.ts 中定义export const defaultConfig { managerFilePatterns: [/(^|/)\\.circleci/.\\.ya?ml$/], }; export const supportedDatasources [DockerDatasource.id, OrbDatasource.id];managerFilePatterns默认匹配所有位于.circleci目录下、扩展名为.yml或.yaml的配置文件正则/\.circleci/.\.ya?ml$/无需在 Renovate 配置中额外指定fileMatchsupportedDatasources明确声明该 manager 只支持 Docker 与 Orb 两种数据源。从 dep-types.ts 可以看到 Renovate 官方对两种依赖类型的描述depType描述orbCircleCI orb referenceCircleCI Orb 引用dockerDocker image in executor/job configurationexecutor/job 配置中的 Docker 镜像注意该 manager 不处理machine类型的 executor。测试用例 extract.spec.ts 证实machine: { image: android:202102-01 }这类配置会被跳过并返回null。二、支持的文件结构与提取范围2.1 提取的配置字段从 schema.ts 的 Zod 模型可以看出manager 会解析 CircleCI 配置文件中的以下顶层字段orbsOrb 引用字符串形式或内嵌 Orb 定义对象形式executors自定义 executor 定义其中的docker镜像会被提取jobs任务定义其中docker数组中的镜像会被提取aliasesYAML 锚点定义的 Docker 镜像。对应到 extract.ts 的提取逻辑其处理顺序为遍历orbs字段若值为字符串按拆分为packageName与currentValue提取为orb依赖若值为对象内嵌 Orb 定义则递归处理其内部的orbs、executors与jobs合并executors与jobs对其中每个docker镜像调用getDep()复用 dockerfile manager 的镜像解析逻辑提取为docker依赖遍历顶层aliases同样提取为docker依赖若没有任何依赖被提取返回null表示该文件无需 Renovate 处理。2.2 支持的镜像写法结合测试用例与 fixtures以下写法均能被正确提取# 无 tag 的镜像视为无版本仅跟踪 digest - image: node # 带 tag 的镜像 - image: node:4 - image: cimg/node:14.8.0 # 带 digest 的镜像tag 与 digest 均会被更新 - image: python:3.7sha256:3870d35b962a943df72d948580fc66ceaaee1c4fbd205930f32e0f0760eb1077完整示例可见 config.yml 与 config2.yml。三、Orb 依赖的提取规则Orb 的写法为命名空间/包名版本提取时depName使用配置文件中的别名键名packageName使用命名空间/包名全名currentValue为后的版本versioning固定为 npm 版本策略Orb 版本遵循 semverdatasource为orb。orbs: release-workflows: hutson/library-release-workflows4.1.0 no-version: abc/def # 无版本号不触发更新 volatile: zzz/zzzvolatile # 非 semver 版本按原样保留对应测试 extract.spec.ts 验证了上述提取结果release-workflows被解析为depName: release-workflows、packageName: hutson/library-release-workflows、currentValue: 4.1.0、versioning: npm、datasource: orb。此外manager 还支持在配置文件中直接内嵌定义 Orb常见于本地复用此时会递归进入 Orb 定义内部继续提取其依赖version: 2.1 orbs: myorb: orbs: python: circleci/python2.1.1 executors: python: docker: - image: cimg/python:3.9 jobs: test_image: docker: - image: cimg/python:3.7 workflows: Test: jobs: - myorb/test_image该场景由测试 “extracts orb definitions” 覆盖。四、YAML 锚点与合并键Merge Key的处理CircleCI 配置大量使用 YAML 锚点与合并键复用配置片段例如jobs: node-base: node-base docker: - image: node steps: - checkout node-v4: : *node-base docker: - image: node:4Renovate 的 circleci manager 在解析时做了两个关键设计按 YAML 1.1 规范解析。源码注释extract.ts明确指出必须使用 YAML 1.1 的锚点合并语义来匹配 CircleCI 自身的行为。因为 YAML 1.2 会把同一映射中多个键判定为重复键而整体报错导致整个文件被跳过递归展开。即使同一映射中同时出现多个合并键如: *node-base与: *node-env共存也能正确合并并提取其中的镜像。测试 “extracts deps from configs with multiple merge keys per mapping” 专门验证了这种边界场景node:18从被合并进build任务的锚点中被正确提取而不会被重复键问题阻断。五、registryAliases私有镜像仓库别名如果镜像托管在私有/镜像仓库可以通过registryAliases配置将原始镜像名映射到实际拉取地址。circleci manager 会读取该配置并传递给getDep(){ registryAliases: { quay.io: my-quay-mirror.registry.com, index.docker.io: my-docker-mirror.registry.com } }当配置文件中出现quay.io/myName/myPackage:0.6.2时Renovate 会以packageName: my-quay-mirror.registry.com/myName/myPackage去查询数据源但更新时仍会在原位置写回quay.io/myName/myPackage:新版本由autoReplaceStringTemplate保证。该行为由测试 “handles registry alias” 验证。六、版本策略rangeStrategycircleci manager 通过 range.ts 定义默认的版本范围策略export function getRangeStrategy({ rangeStrategy }: RangeConfig): RangeStrategy { return rangeStrategy auto ? pin : rangeStrategy!; }即当全局rangeStrategy为auto时circleci manager 固定采用pin策略——将镜像/Orb 的 tag 固定为精确版本若用户显式指定了其他策略则遵循用户配置。这与 CI 配置“版本应明确可复现”的实践一致。七、私有 Orb 的访问配置hostRules 加密 Token原文档重点讲解了私有 Orb 的接入方法。CircleCI 的 Orb 数据源 OrbDatasource 通过 CircleCI APIhttps://circleci.com/api/v3/orb/packages查询版本信息私有 Orb 需要携带个人 API Token 才能访问。配置分为三步加密 Token将你的 CircleCI Token 通过 Renovate 官方加密页面https://app.renovatebot.com/encrypt加密需配合你的 Renovate 公钥新增hostRules条目在 Renovate 配置文件的hostRules数组中添加一条规则填入加密 Token将加密后的内容放入token字段。最终配置形如{ hostRules: [ { matchHost: circleci.com, authType: Token-Only, encrypted: { token: **** } } ] }关键点说明matchHost匹配 CircleCI 的请求主机circleci.com也支持匹配其子域名authType设置为Token-Only表示直接将 Token 原样放入authorization请求头而不附加Bearer或Basic前缀。原文档明确指出This config strips the Bearer/Basic prefix from the authorization header.该配置会去掉authorization头中的 Bearer/Basic 前缀encrypted.token使用仓库公钥加密后的 Token 值****仅为占位符。该行为与 HTTP 层认证实现 auth.ts 完全对应当authType Token-Only时options.headers.authorization options.token即 Token 直接作为请求头值不做任何前缀拼接其他authType才会拼成${authType} ${token}的格式。若你使用 Renovate 自托管self-hosted也可以在RENOVATE_TOKEN环境变量或配置中直接提供明文 Token未加密方式但这会降低安全性官方推荐优先使用上面的加密方案。八、典型配置速查一个完整的 Renovate 配置示例同时覆盖公共镜像、公共 Orb 与私有 Orb{ extends: [config:recommended], circleci: { fileMatch: [/(^|/)\\.circleci/.\\.ya?ml$/] }, hostRules: [ { matchHost: circleci.com, authType: Token-Only, encrypted: { token: **** } } ], registryAliases: { quay.io: my-quay-mirror.registry.com } }circleci.fileMatch可自定义匹配范围默认即为.circleci目录下的 yaml/yml 文件需要调整版本格式时可参考 versioning 文档 学习如何在 packageRules 中覆盖versioning字段circleci manager 默认对 orb 使用 npm semver 版本策略。九、验证与排错提取是否生效运行 Renovate 的 dry-run 或查看日志中的extract阶段输出若某文件未被识别先确认其路径是否符合默认fileMatch正则无依赖文件当文件中只有machineexecutor 或没有任何可识别依赖时manager 返回null参考 extract.ts这是预期行为而非报错私有 Orb 拉取失败检查hostRules的matchHost是否覆盖了实际请求域名Token 是否已加密且与公钥匹配YAML 解析被跳过若日志出现 “Error extracting circleci images”见 extract.ts通常意味着配置文件不符合 YAML 1.1 可解析的锚点/合并键语法请检查合并键的使用方式。十、延伸阅读manager 完整源码index.ts、extract.ts、schema.ts测试用例extract.spec.ts、index.spec.ts、range.spec.ts示例配置文件config.yml、config2.yml、config3.yml、config4.yml数据源实现DockerDatasource、OrbDatasource版本策略说明versioning 文档配置项详解configuration-options【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考