From 908777cdcc5c0886987ab5970a890dd559705679 Mon Sep 17 00:00:00 2001
From: Uli <SirUli@users.noreply.github.com>
Date: Tue, 1 Aug 2023 20:09:43 +0200
Subject: [PATCH] docs(datasource): Add additional examples for custom
datasource (#23558)
Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
Co-authored-by: Sebastian Poxhofer <secustor@users.noreply.github.com>
---
lib/modules/datasource/custom/readme.md | 142 +++++++++++++++++++-----
1 file changed, 116 insertions(+), 26 deletions(-)
diff --git a/lib/modules/datasource/custom/readme.md b/lib/modules/datasource/custom/readme.md
index f77236561b..20d35d0246 100644
--- a/lib/modules/datasource/custom/readme.md
+++ b/lib/modules/datasource/custom/readme.md
@@ -18,27 +18,25 @@ Available template variables:
- `packageName`
-```json5
+```json
{
- regexManagers: [
+ "regexManagers": [
{
- fileMatch: ['k3s.version'],
- matchStrings: ['(?<currentValue>\\S+)'],
- // used for display and templating purposes, if combined with customDatasources
- depNameTemplate: 'k3s',
- versioningTemplate: 'semver-coerced',
- // if the datasource is prefixed with `custom.`, Renovate will try to find customDatasource with a fitting name
- datasourceTemplate: 'custom.k3s',
- },
+ "fileMatch": ["k3s.version"],
+ "matchStrings": ["(?<currentValue>\\S+)"],
+ "depNameTemplate": "k3s",
+ "versioningTemplate": "semver-coerced",
+ "datasourceTemplate": "custom.k3s"
+ }
],
- customDatasources: {
- k3s: {
- defaultRegistryUrlTemplate: 'https://update.k3s.io/v1-release/channels',
- transformTemplates: [
- '{"releases":[{"version": $$.(data[id = \'stable\'].latest),"sourceUrl":"https://github.com/k3s-io/k3s","changelogUrl":$join(["https://github.com/k3s-io/k3s/releases/tag/",data[id = \'stable\'].latest])}],"sourceUrl": "https://github.com/k3s-io/k3s","homepage": "https://k3s.io/"}',
- ],
- },
- },
+ "customDatasources": {
+ "k3s": {
+ "defaultRegistryUrlTemplate": "https://update.k3s.io/v1-release/channels",
+ "transformTemplates": [
+ "{\"releases\":[{\"version\": $$.(data[id = 'stable'].latest),\"sourceUrl\":\"https://github.com/k3s-io/k3s\",\"changelogUrl\":$join([\"https://github.com/k3s-io/k3s/releases/tag/\",data[id = 'stable'].latest])}],\"sourceUrl\": \"https://github.com/k3s-io/k3s\",\"homepage\": \"https://k3s.io/\"}"
+ ]
+ }
+ }
}
```
@@ -82,19 +80,111 @@ All available options:
## Examples
-# K3s
+### K3s
You can use this configuration to request the newest version available to [K3s](https://k3s.io/)
-```json5
+```json
{
- customDatasources: {
- k3s: {
- defaultRegistryUrlTemplate: 'https://update.k3s.io/v1-release/channels',
- transformTemplates: [
- '{"releases":[{"version": $$.(data[id = \'stable\'].latest),"sourceUrl":"https://github.com/k3s-io/k3s","changelogUrl":$join(["https://github.com/k3s-io/k3s/releases/tag/",data[id = \'stable\'].latest])}],"sourceUrl": "https://github.com/k3s-io/k3s","homepage": "https://k3s.io/"}',
+ "customDatasources": {
+ "k3s": {
+ "defaultRegistryUrlTemplate": "https://update.k3s.io/v1-release/channels",
+ "transformTemplates": [
+ "{\"releases\":[{\"version\": $$.(data[id = 'stable'].latest),\"sourceUrl\":\"https://github.com/k3s-io/k3s\",\"changelogUrl\":$join([\"https://github.com/k3s-io/k3s/releases/tag/\",data[id = 'stable'].latest])}],\"sourceUrl\": \"https://github.com/k3s-io/k3s\",\"homepage\": \"https://k3s.io/\"}"
+ ]
+ }
+ }
+}
+```
+
+### Hashicorp
+
+You can use this configuration to request the newest versions of the Hashicorp products:
+
+```json
+{
+ "regexManagers": [
+ {
+ "fileMatch": ["\\.yml$"],
+ "datasourceTemplate": "custom.hashicorp",
+ "matchStrings": [
+ "#\\s*renovate:\\s*(datasource=(?<datasource>.*?) )?depName=(?<depName>.*?)( versioning=(?<versioning>.*?))?\\s*\\w*:\\s*(?<currentValue>.*)\\s"
],
- },
+ "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
+ }
+ ],
+ "customDatasources": {
+ "hashicorp": {
+ "defaultRegistryUrlTemplate": "https://api.releases.hashicorp.com/v1/releases/{{packageName}}?license_class=oss",
+ "transformTemplates": [
+ "{ \"releases\": $map($, function($v) { { \"version\": $v.version, \"releaseTimestamp\": $v.timestamp_created, \"changelogUrl\": $v.url_changelog, \"sourceUrl\": $v.url_source_repository } }), \"homepage\": $[0].url_project_website, \"sourceUrl\": $[0].url_source_repository }"
+ ]
+ }
+ }
+}
+```
+
+To have the latest Nomad version in your Ansible variables, use this snippet _after_ adding the above configuration:
+
+```yaml
+# renovate: depName=nomad
+nomad_version: 1.6.0
+```
+
+### Custom offline dependencies
+
+Sometimes the "dependency version source" is _not_ available via an API.
+To work around a missing API, you can create dependency "files". These files are served via HTTP(S), so that Renovate can access them.
+For example, imagine the following file `versiontracker.json` for the software `something``:
+
+```json
+[
+ {
+ "version": "77"
},
+ {
+ "version": "76"
+ }
+]
+```
+
+By writing a custom datasource, Renovate can process the `versiontracker.json` file, see below.
+This example uses Nexus as the webserver.
+
+```json
+{
+ "customDatasources": {
+ "nexus_generic": {
+ "defaultRegistryUrlTemplate": "https://nexus.example.com/repository/versiontrackers/{{packageName}}/versiontracker.json",
+ "transformTemplates": [
+ "{ \"releases\": $map($, function($v) { { \"version\": $v.version, \"sourceUrl\": $v.filelink } }) }"
+ ]
+ }
+ }
+}
+```
+
+This could be used to update Ansible YAML files with the latest version through a regex manager.
+For example, with the following Ansible content:
+
+```yaml
+# renovate: datasource=custom.nexus_generic depName=something versioning=loose
+something_version: '77'
+```
+
+And the following regex manager:
+
+```json
+{
+ "regexManagers": [
+ {
+ "fileMatch": ["\\.yml$"],
+ "datasourceTemplate": "custom.nexus_generic",
+ "matchStrings": [
+ "#\\s*renovate:\\s*(datasource=(?<datasource>.*?)\\s*)?depName=(?<depName>.*?)(\\s*versioning=(?<versioning>.*?))?\\s*\\w*:\\s*[\"']?(?<currentValue>.+?)[\"']?\\s"
+ ],
+ "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}"
+ }
+ ]
}
```
--
GitLab