Versions and Renovate Management

This skill covers adding and maintaining version entries in kubernetes/platform/versions.env and configuring Renovate to automatically update them.

How Version Updates Flow

Renovate detects new version --> Updates versions.env in a PR
  --> PR merges --> OCI artifact built --> integration cluster deploys
  --> Flux substitutes ${var} into HelmRelease specs
  --> Tuppr reads Talos/K8s versions for rolling upgrades

Every entry in versions.env needs a # renovate: annotation on the line above it. Renovate's custom regex manager in .github/renovate.json5 parses these annotations to determine how to check for updates.

Annotation Syntax

# renovate: datasource=<source> depName=<name> [packageName=<pkg>] [extractVersion=<regex>] [registryUrl=<url>] [versioning=<scheme>]
variable_name=<value>

Key ordering is fixed: datasource, depName, packageName, extractVersion, registryUrl, versioning. Rearranging keys causes Renovate to silently skip the entry.

Adding a New Version Entry

Step 1: Select Datasource

What kind of dependency?
|
+-- Helm chart from HTTP registry    --> datasource=helm + registryUrl=<url>
+-- Helm chart from OCI registry     --> datasource=docker + packageName=<full-path>
+-- GitHub release (Talos, Flux)      --> datasource=github-releases + packageName=<org/repo>
+-- GitHub tag (no release object)    --> datasource=github-tags + packageName=<org/repo>

Step 2: Write the Annotation

HTTP Helm registry -- use registryUrl, depName is the chart name:

# renovate: datasource=helm depName=grafana registryUrl=https://grafana.github.io/helm-charts
grafana_version=10.5.15

OCI Helm registry -- use packageName with the full image path (no oci:// prefix):

# renovate: datasource=docker depName=app-template packageName=ghcr.io/bjw-s-labs/helm/app-template
app_template_version=4.6.2

GitHub releases -- use packageName as org/repo:

# renovate: datasource=github-releases depName=talos packageName=siderolabs/talos
talos_version=v1.12.2

GitHub tags -- same pattern, different datasource:

# renovate: datasource=github-tags depName=kubernetes packageName=kubernetes/kubernetes extractVersion=^v(?<version>.*)$
kubernetes_version=1.35.0

Step 3: Handle Version Prefix

If the upstream releases as v1.0.0 but your stored value omits the v, add extractVersion:

# renovate: datasource=helm depName=cert-manager extractVersion=^v(?<version>.*)$ registryUrl=https://charts.jetstack.io
cert_manager_version=1.19.3

Real examples from the codebase:

• Talos: stores v1.12.2 (keeps v) -- no extractVersion needed
• Cilium: stores 1.18.6 (strips v) -- extractVersion required
• Cert-manager: stores 1.19.3 (strips v) -- extractVersion required

Step 4: Handle Non-Semver Versions

For versions that don't follow semver, add versioning=loose:

# renovate: datasource=docker depName=cloudnative-vectorchord packageName=ghcr.io/tensorchord/cloudnative-vectorchord versioning=loose
vectorchord_version=18.1-1.0.0

Step 5: Add Package Rule (if needed)

If the dependency should be grouped or has special automerge needs, add to .github/renovate.json5:

{
  "matchDepNames": ["my-chart", "related-chart"],
  "groupName": "my stack"
}

Step 6: Validate

task renovate:validate

YAML Container Image Annotations

For container image tags hardcoded in Helm values files (not in versions.env), annotate directly in the YAML. The custom regex manager matches these patterns.

Tag field pattern:

image:
  repository: ghcr.io/kashalls/kromgo
  # renovate: datasource=docker depName=ghcr.io/kashalls/kromgo
  tag: v0.7.5

Inline image:tag pattern:

initContainers:
  # renovate: datasource=docker depName=ghcr.io/home-operations/postgres-init
  image: ghcr.io/home-operations/postgres-init:18

When to use which:

• versions.env: Helm chart versions (Flux-substituted into HelmRelease specs)
• YAML annotations: Container image tags in values files (sidecars, init containers)

Package Rules

Package rules in .github/renovate.json5 control grouping and automerge. By default, minor/patch updates automerge after 3 days (.renovate/automerge.json5).

Existing Groups

When to add a rule:

• Multiple related charts that should update together (grouping)
• Infrastructure-critical dependencies that must not automerge
• The matchDepNames values must match the depName in the annotation

Debugging

Dependency Not Being Updated

1. Check key order: Must be datasource depName [packageName] [extractVersion] [registryUrl] [versioning]
2. Run task renovate:validate: Catches config syntax errors
3. Check dependency dashboard: Look for the dep in the Renovate dashboard issue on GitHub
4. Verify datasource: Ensure registry URL or package name is correct and accessible
5. Check ignorePaths: Confirm the file isn't excluded in renovate.json5

Wrong Version Detected

• extractVersion mismatch: Regex doesn't match upstream tag format
• Wrong datasource: helm vs docker vs github-releases produce different version lists
• Non-semver: Missing versioning=loose causes Renovate to skip

Common Mistakes