Renovate 的 galaxy-collection 数据源：为 Ansible Galaxy Collections 配置私有源与自定义仓库

Renovate 的 galaxy-collection 数据源为 Ansible Galaxy Collections 配置私有源与自定义仓库【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovateRenovate 内置的galaxy-collection数据源datasource负责扫描 Ansible Galaxy Collections 的依赖版本并生成更新 PR。默认情况下它查询官方源https://galaxy.ansible.com但在私有自动化中心Automation Hub、Artifactory 或其他自建 Galaxy 镜像场景下你必须覆盖默认地址才能让 Renovate 正确解析版本。本文以 lib/modules/datasource/galaxy-collection/readme.md 为核心结合该数据源的源码实现与测试用例完整讲解默认行为、两种自定义仓库配置方式以及底层 URL 构造规则与 API 调用流程。默认行为官方 Galaxy 源与自动识别在没有任何额外配置的情况下galaxy-collection数据源会直接查询https://galaxy.ansible.com。这一点在源码中有明确声明GalaxyCollectionDatasource类的defaultRegistryUrls被设置为[https://galaxy.ansible.com/api/]见 lib/modules/datasource/galaxy-collection/index.ts。数据源还声明了以下几个值得注意的默认特性同样定义于 index.ts特性默认值含义customRegistrySupporttrue允许用户通过配置覆盖/追加注册表地址registryStrategyhunt逐个尝试所有注册表 URL命中即停止找不到则全部探测defaultVersioningpep440使用 PEP 440 版本规则对 Collection 版本排序比较releaseTimestampSupporttrue发布时间的来源是版本列表中的created_at字段sourceUrlSupportrelease源码仓库地址取自版本详情中的repository字段也就是说即使你不做任何自定义只要在requirements.yml或requirements.yaml中声明了collections依赖Renovate 就会用 PEP 440 语义去解析官方源上的版本并给出升级建议。为什么要覆盖默认源私有与内网场景默认官方源只适用于完全公开的社区集合。当你的团队使用以下任一场景时就必须覆盖默认地址私有 Automation Hub如 Red Hat Automation Hub 或自建 HubCollection 存放在受限的内容仓库content repository中Artifactory 上的 Ansible 仓库JFrog Artifactory 提供了 Ansible 远程仓库 / 虚拟仓库能力Galaxy Collections 可以托管其中企业内网镜像与公网隔离只能访问内网 Galaxy 服务。官方文档给出的核心思路是你可以覆盖默认值并且提供了两条等价的配置路径。方式一在 requirements.yml 中通过source字段指定最贴近声明处declaration的做法是在requirements.yml的集合条目里直接写上source字段。Renovate 的ansible-galaxymanager 在解析该文件时会读取这个字段并将其转换为数据源的registryUrls。--- collections: - name: community.general version: 3.0.0 source: https://hub.mydomain.com/api/galaxy/content/community/关于这个字段的解析逻辑可以从 lib/modules/manager/ansible-galaxy/collections.ts 看到细节若source以git开头或.git结尾会被判定为Git 依赖转而走git-tags非 GitHub 主机或github-tagsGitHub 主机数据源而不是galaxy-collection其余情况HTTP/HTTPS 的 API 地址source会被直接写入该依赖的registryUrls最终交给GalaxyCollectionDatasource处理。因此只有指向 Galaxy API 的 URL而不是 Git 仓库地址才适用于galaxy-collection数据源。方式二通过 packageRule 批量设置registryUrls如果不想改动每个声明或者希望集中管理某个依赖组的仓库列表可以在 Renovate 配置中写一条packageRule用matchDatasources精确命中galaxy-collection再通过registryUrls一次性提供多个候选源{ packageRules: [ { matchDatasources: [galaxy-collection], registryUrls: [ https://hub.mydomain.com/api/galaxy/content/community/, https://hub.mydomain.com/api/galaxy/content/certified/, https://hub.mydomain.com/api/galaxy/content/myprivaterepo/, https://mydomain.com/artifactory/api/ansible/myrepository/ ] } ] }由于该数据源registryStrategy为hunt见 index.ts当registryUrls包含多个地址时Renovate 会按顺序逐个探测直到某个地址能返回有效版本数据为止。这意味着你可以把「公共源 私有源」混合列出实现类似优先私有、失败回退公共的效果。底层原理两种协议如何构造请求 URL自定义 URL 并非随便填一个服务根地址即可数据源必须知道如何把namespace.collection拼进 API 路径。从源码看constructBaseUrl通过正则区分了两种协议形态见 index.ts 与 constructBaseUrl 实现1. Artifactory Ansible 协议URL 匹配^\S\/api\/ansible\/.如https://mydomain.com/artifactory/api/ansible/myrepository/此时按 Artifactory 的api/v3风格拼接registryUrl/api/v3/collections/namespace/collection/例如对foo.bar与https://my.artifactory.local/artifactory/api/ansible/ansible-repo/最终请求https://my.artifactory.local/artifactory/api/ansible/ansible-repo/api/v3/collections/foo/bar/2. Galaxy / Automation Hub 协议URL 匹配^\S\/api\/galaxy\/content\/(?repository[^/])此时从 URL 中提取内容仓库名repository如community、published、certified再拼接v3/plugin/ansible/content路径registryUrl/v3/plugin/ansible/content/repository/collections/index/namespace/collection/例如对https://my.automationhub.local/api/galaxy/content/community/与foo.bar最终请求https://my.automationhub.local/api/galaxy/content/community/v3/plugin/ansible/content/community/collections/index/foo/bar/需要特别注意的是Artifactory 协议判断优先级更高ansibleProtocolRegex先被测试只有它不匹配时才走 Galaxy 协议。若注册表 URL 既不是api/ansible/也不是api/galaxy/content/形态如示例中的https://my.collectiondatasource.local/api/collection/content/community/repository会回退为默认值published——这正是官方源默认内容仓库的名字。以上三种分支均有对应的单元测试覆盖见 lib/modules/datasource/galaxy-collection/index.spec.ts。请求流程与响应校验确认基础 URL 后数据源按三步请求 并发补全的模式工作见 index.ts基础信息请求请求baseUrl用GalaxyV3schema 校验获取deprecated是否废弃与highest_version最高版本字段版本列表请求请求baseUrlversions/用GalaxyV3Versionsschema 校验从data数组取出每个版本的version与created_at作为releaseTimestamp逐版本详情请求对列表中的每个版本并发concurrency: 4请求versionsUrlversion/用GalaxyV3DetailedVersionschema 校验提取download_url、artifact.sha256、metadata.repository与metadata.dependencies分别映射为downloadUrl、newDigest、sourceUrl和dependencies。三个响应结构均由 lib/modules/datasource/galaxy-collection/schema.ts 中的 Zod schema 定义且均通过.transform()把 API 原始字段snake_case映射为 Renovate 内部字段camelCase。releaseTimestamp、sourceUrl、newDigest这些字段最终会进入 PR 的 Release Notes / Digest 展示因此自定义源只要返回符合 Galaxy v3 规范的 JSON这些能力就能自动生效。请求结果还有两层缓存getReleases使用带fallback的包级缓存getVersionDetails则缓存一周ttlMinutes: 10080避免频繁拉取同一集合的详情见 index.ts 与 index.ts。错误处理与边界情况数据源对错误的处理也值得注意有测试佐证见 index.spec.ts基础请求返回404静默忽略并返回null视为该集合不存在不报错任一阶段返回5xx 等远端错误统一抛出EXTERNAL_HOST_ERROR让 Renovate 按外部主机故障重试返回非法/空数据如空字符串响应校验失败时返回null版本详情请求失败对应的单个版本会被过滤掉filter(isTruthy)不影响其余版本输出见 index.ts。此外若packageName为空getReleases直接返回null若依赖的name不符合namespace.collection形态ansible-galaxymanager 会标记skipReason如no-source-match、unspecified-version这类依赖不会进入版本查询见 lib/modules/manager/ansible-galaxy/collections.ts。实战要点小结优先用requirements.yml的source字段声明即配置每个集合可以指向不同的私有源适合同一仓库混用多个源的场景需要统一管理时用packageRule registryUrls适合一个依赖组共享一组源的场景且hunt策略天然支持多源回退URL 形态必须正确Artifactory 走api/ansible/...Automation Hub / Galaxy 走api/galaxy/content/repo/...否则要么落到默认published仓库要么无法命中任何协议分支版本详情数据尽量完整返回created_at、artifact.sha256、metadata.repository能直接驱动 Renovate 的时间戳、Digest 与源码链接能力私有源需要满足 Galaxy v3 API 结构数据源依赖GalaxyV3/GalaxyV3Versions/GalaxyV3DetailedVersion三个 JSON 结构自建服务需按此规范实现。相关实现与验证文件数据源主体 lib/modules/datasource/galaxy-collection/index.ts、响应校验 lib/modules/datasource/galaxy-collection/schema.ts、单元测试 lib/modules/datasource/galaxy-collection/index.spec.ts、依赖提取逻辑 lib/modules/manager/ansible-galaxy/collections.ts以及真实响应样例fixtures/community_kubernetes_base.json 与fixtures/community_kubernetes_versions.json。【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考