Version Transforms

Version transforms are an optional post-processing step applied to version strings extracted by scrape jobs. They normalize the version format so it matches the format used by upstream releases, enabling accurate comparison.

Available transforms

When to use a transform

Transforms solve the common problem where your deployed version string uses a different format than the upstream releases you’re comparing against. Without a transform, 1.2.3 and v1.2.3 are treated as different versions, which causes incorrect rule evaluation.

Example: Chart.yaml version vs GitHub tags

Your Chart.yaml contains:

version: 1.2.3

But the upstream GitHub releases use tags like v1.2.3. Without a transform, the rule engine cannot match the deployed version to any upstream release and the alert defaults to critical severity.

Solution: Apply add_v_lower to the scrape job. The extracted 1.2.3 becomes v1.2.3 before comparison.

Example: Dockerfile FROM tag vs Helm chart versions

Your Dockerfile contains:

FROM nginx:v1.25.3

But the Helm repository publishes versions as 1.25.3 (no prefix). The scrape job extracts v1.25.3 which doesn’t match.

Solution: Apply strip_v_lower to the scrape job. The extracted v1.25.3 becomes 1.25.3 before comparison.

How transforms interact with manual versions

Version transforms also apply to versions entered via the manual entry mode. When you set a version on a manual scrape job, the transform is applied before the version is stored as a snapshot.

For example, if a manual scrape job has strip_v_lower configured and you enter v2.0.0, the stored version snapshot will be 2.0.0.

Configuring a transform

In the UI

1. Open the scrape job’s create or edit form.
2. Select a transform from the Version transform dropdown.
3. Save the job.

Via the API

Include the version_transform field when creating or updating a scrape job:

{
  "parse_type": "yq",
  "repository_url": "https://github.com/my-org/my-repo.git",
  "ref": "main",
  "target_file": "Chart.yaml",
  "parse_expression": ".version",
  "version_transform": "add_v_lower"
}

Tips

• If you’re unsure whether a transform is needed, create the scrape job without one first. Run it once and compare the extracted version with the upstream release versions. If they differ only by a v prefix, add the appropriate transform.
• The strip_v transforms are safe to apply even if the version doesn’t have a v prefix – a version like 1.2.3 passes through unchanged.
• The add_v transforms always prepend, so applying add_v_lower to v1.2.3 would produce vv1.2.3. Only use these when you know the source version never has a prefix.