Renovate 的 galaxy-collection 数据源：为 Ansible Galaxy Collections 配置私有源与自定义仓库
【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate
Renovate 内置的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）：
| 特性 | 默认值 | 含义 |
|---|---|---|
customRegistrySupport | true | 允许用户通过配置覆盖/追加注册表地址 |
registryStrategy | 'hunt' | 逐个尝试所有注册表 URL，命中即停止，找不到则全部探测 |
defaultVersioning | pep440 | 使用 PEP 440 版本规则对 Collection 版本排序比较 |
releaseTimestampSupport | true | 发布时间的来源是版本列表中的created_at字段 |
sourceUrlSupport | 'release' | 源码仓库地址取自版本详情中的repository字段 |
也就是说，即使你不做任何自定义，只要在requirements.yml（或requirements.yaml）中声明了collections依赖，Renovate 就会用 PEP 440 语义去解析官方源上的版本并给出升级建议。
为什么要覆盖默认源：私有与内网场景
默认官方源只适用于完全公开的社区集合。当你的团队使用以下任一场景时，就必须覆盖默认地址：
- 私有 Automation Hub：如 Red Hat Automation Hub 或自建 Hub，Collection 存放在受限的内容仓库（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-tags（GitHub 主机）数据源，而不是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（最高版本）字段； - 版本列表请求：请求
<baseUrl>versions/，用GalaxyV3Versionsschema 校验，从data数组取出每个版本的version与created_at（作为releaseTimestamp）； - 逐版本详情请求：对列表中的每个版本，并发（
concurrency: 4）请求<versionsUrl><version>/，用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），仅供参考
