Site: Planekeeper Docs — Monitor software versions across your stack. Planekeeper tracks releases, gathers version data, and alerts on drift.
Section: Reference > Version Transforms
Source: https://docs.planekeeper.com/reference/version-transforms/
Title: Version Transforms
Author: Planekeeper
Description: Reference for version transform options that normalize version strings extracted by scrape jobs.
Word count: 424
Reading time: 2 min

Contents:
- [Available transforms](#available-transforms)
- [When to use a transform](#when-to-use-a-transform)
  - [Example: Chart.yaml version vs GitHub tags](#example-chartyaml-version-vs-github-tags)
  - [Example: Dockerfile FROM tag vs Helm chart versions](#example-dockerfile-from-tag-vs-helm-chart-versions)
- [How transforms interact with manual versions](#how-transforms-interact-with-manual-versions)
- [Configuring a transform](#configuring-a-transform)
  - [In the UI](#in-the-ui)
  - [Via the API](#via-the-api)
- [Tips](#tips)

***

# 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

| Transform | Input | Output | Description |
|-----------|-------|--------|-------------|
| `none` | `v1.2.3` | `v1.2.3` | No transformation (default) |
| `add_v_lower` | `1.2.3` | `v1.2.3` | Prepends a lowercase `v` prefix |
| `add_v_upper` | `1.2.3` | `V1.2.3` | Prepends an uppercase `V` prefix |
| `strip_v_lower` | `v1.2.3` | `1.2.3` | Removes a lowercase `v` prefix |
| `strip_v_upper` | `V1.2.3` | `1.2.3` | Removes an uppercase `V` prefix |

## 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:

```yaml
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:

```dockerfile
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:

```json
{
  "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.


---

## Related

- Section: [Reference](https://docs.planekeeper.com/reference/index.md)