Skip to content
Hands-on IT IT Drills

Day 6: Versions and Ranges

Goal: You determine how Renovate writes versions into files (range, pin, lockfile, digest) and which versions it is allowed to offer at all. · Duration: approx. 120 min · Prerequisite: Day 2, Day 4

Briefing

  • rangeStrategy determines what ends up in package.json: keep the range, bump it, widen it, pin it, or change only the lockfile. Default auto.
  • versioning decides what a valid, stable, and greater version is. The datasource brings a default, and config:recommended changes it for Node images.
  • allowedVersions, ignoreDeps, enabled, matchCurrentVersion, and followTag filter what is offered at all.
  • For Docker images, a suffix like -alpine is part of compatibility. pinDigests appends the digest to the tag.
 Datasource ──► all versions ──► versioning (valid? stable? greater? suffix?)
            ──► allowedVersions / followTag / enabled / ignoreDeps ──► candidates
            ──► rangeStrategy (+ pinDigests) ──► new value in file and lockfile

Drill 1: Starting point with your own config

You start with a fresh shop-api and merge the onboarding PR with your own renovate.json: config:recommended, only the npm manager for now, no hourly limit for PRs (Day 4).

source ~/renovate-lab/setup/env.sh
curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" \
  -X DELETE "$FORGEJO/api/v1/repos/shop/shop-api"
git -C ~/renovate-lab/shop-api push -q forgejo:shop/shop-api.git main
export RENOVATE_GITHUB_COM_TOKEN=$(gh auth token)   # optional, see Day 0
mkdir -p ~/renovate-lab/tag06 && cd ~/renovate-lab/tag06
R="$FORGEJO/api/v1/repos/shop/shop-api"
renovate shop/shop-api > lauf-onboarding.log 2>&1
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'

Expected (shortened):

204
#1 renovate/configure | Configure Renovate

Tip: If the log reports “Repository is empty - skipping” right after the push, Forgejo was not done with the push yet. Simply start the run again.

Today a pattern repeats: change renovate.json, validate, commit, push, run Renovate, and count what it did. Afterwards, a short loop shows the changed lines in package.json and Dockerfile for each Renovate branch.

git clone -q -b renovate/configure \
  forgejo:shop/shop-api.git
cd shop-api
cat > renovate.json <<'EOF'
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "enabledManagers": ["npm"],
  "prHourlyLimit": 0
}
EOF
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Tag 6: Startkonfiguration"
git push -q origin HEAD
curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" -X POST "$R/pulls/1/merge" \
  --json '{"Do":"merge","delete_branch_after_merge":true}'
git checkout -q main
git pull -q

Expected:

200

In the seed, lodash in the lockfile is already at the newest 4.x. To give rangeStrategy something to do, you roll the lockfile back to 4.17.21, as in a project that has been sitting around for a few months:

npm install -s --package-lock-only [email protected]
npm pkg set dependencies.lodash=^4.17.20
npm install -s --package-lock-only
git diff --stat
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Lockfile: lodash auf 4.17.21"
git push -q origin HEAD

Expected:

 package-lock.json | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

package.json stays unchanged (^4.17.20). npm keeps a locked version as long as it satisfies the range.

Save your progress? Sign up for free

Drill 2: auto, bump, and pin

First run with the default rangeStrategy: auto. A run takes 20 to 60 seconds.

renovate shop/shop-api > ../lauf-auto.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-auto.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done
git diff origin/main...origin/renovate/lodash-monorepo | grep -E '^[-+] +"version"'

Expected (shortened, your target versions will be newer):

   4 Branch created
   4 PR created
#2 renovate/express-4.x | Update dependency express to v4.22.3
#3 renovate/lodash-monorepo | Update dependency lodash to v4.18.1
#4 renovate/prettier-3.x | Update dependency prettier to v3.9.10
#5 renovate/express-5.x | Update dependency express to v5
== renovate/express-4.x
-    "express": "4.18.2",
+    "express": "4.22.3",
== renovate/lodash-monorepo
   (nur package-lock.json)
-      "version": "4.17.21",
+      "version": "4.18.1",

For npm, auto means update-lockfile (the line (nur package-lock.json) means “only package-lock.json”). If the new version is within the range, Renovate changes only the lockfile. Exact versions like express’s are replaced. Now bump, then pin:

jq '.rangeStrategy = "bump"' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-bump.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-bump.log | sort | uniq -c
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done
jq '.rangeStrategy = "pin"' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-pin.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-pin.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done

Expected (shortened):

   1 Branch updated
   1 PR updated
== renovate/lodash-monorepo
-    "lodash": "^4.17.20"
+    "lodash": "^4.18.1"
   1 Branch created
   1 PR created
#3 renovate/lodash-monorepo | Update dependency lodash to ^4.18.1
#7 renovate/pin-dependencies | Pin dependency lodash to 4.17.21
== renovate/pin-dependencies
-    "lodash": "^4.17.20"
+    "lodash": "4.17.21"

bump raises the lower bound; the range stays a range. pin first creates a separate PR “Pin dependency” that pins exactly the version from the lockfile. Only after it is merged do the updates themselves become exact:

curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" -X POST "$R/pulls/7/merge" \
  --json '{"Do":"merge","delete_branch_after_merge":true}'
git checkout -q main
git pull -q
renovate shop/shop-api > ../lauf-pin2.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-pin2.log | sort | uniq -c
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/ | grep -E lodash); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done

Expected:

200
   3 Branch updated
   1 PR updated
== renovate/lodash-monorepo
-    "lodash": "4.17.21"
+    "lodash": "4.18.1"

Warning: Renovate detects Conventional Commits from the most recent commits on main. Commit messages like config: … while experimenting therefore turn on semanticCommits, and PR titles suddenly read fix(deps): …. That is why the commits are called “Konfiguration” without a colon.

Save your progress? Sign up for free

Drill 3: Range meets major

The difference between replace and widen only shows once the new version leaves the range. For that, you briefly turn express into the range ^4.18.2.

npm pkg set dependencies.express=^4.18.2
npm install -s --package-lock-only
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "express als Bereich ^4.18.2"
git push -q origin HEAD
for s in replace widen bump update-lockfile in-range-only; do
jq ".rangeStrategy = \"$s\"" renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-$s.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-$s.log | sort | uniq -c
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/ | grep -E '== renovate/express'); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done
done

Expected (shortened):

   1 Autoclosing PR
== renovate/express-5.x
-    "express": "^4.18.2",
+    "express": "^5.0.0",
== renovate/express-5.x
-    "express": "^4.18.2",
+    "express": "^4.18.2 || ^5.0.0",
== renovate/express-4.x
-    "express": "^4.18.2",
+    "express": "^4.22.3",
== renovate/express-5.x
-    "express": "^4.18.2",
+    "express": "^5.3.0",
   1 Autoclosing PR
== renovate/express-4.x-lockfile
   (nur package-lock.json)
== renovate/express-5.x
-    "express": "^4.18.2",
+    "express": "^5.0.0",
   3 Autoclosing PR
== renovate/express-4.x-lockfile
   (nur package-lock.json)

Whatever no longer fits the strategy, Renovate closes by itself (“Autoclosing PR”, the title gets - autoclosed). The results of this drill and the previous one:

Strategy lodash ^4.17.20, lock 4.17.21 express ^4.18.2 → 5.3.0
auto (npm) like update-lockfile like update-lockfile
update-lockfile lockfile only → 4.18.1 ^5.0.0 (+ lockfile PR 4.x)
bump ^4.18.1 ^5.3.0 (+ ^4.22.3)
replace nothing (in range) ^5.0.0
widen nothing (in range) ^4.18.2 \|\| ^5.0.0
pin first 4.17.21, then 4.18.1 exact (see Drill 2)
in-range-only lockfile only nothing, major PR closed

Rule of thumb: apps pin or use update-lockfile, libraries use replace or widen, so that users of the library are not pinned down unnecessarily. Back to the starting state:

npm pkg set dependencies.express=4.18.2
npm install -s --package-lock-only
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "express wieder exakt"
git push -q origin HEAD
jq 'del(.rangeStrategy)' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD

lodash stays pinned (4.17.21); that was the merge from Drill 2.

Tip: The same applies to the go directive from Day 3. A packageRule with "matchDatasources": ["golang-version"] and "rangeStrategy": "bump" turns go 1.21 into an update to the current Go version.

Save your progress? Sign up for free

Drill 4: Presets instead of manual work

Does config:recommended set a rangeStrategy? The presets are JavaScript in the installed Renovate version.

D=~/renovate-lab/tools/node_modules/renovate/dist/config/presets/internal
grep -l rangeStrategy $D/*.preset.js | xargs -n1 basename
grep -oE '^[[:space:]][a-zA-Z]+: \{' $D/default.preset.js | tr -d '\t :{' \
  | grep -iE 'pin|preserve|widen' | xargs -n3
grep -A2 -E '"js-(app|lib)": \{' $D/config.preset.js | grep extends | tr -d '\t'

Expected:

default.preset.js
doNotPinPackage pinAllExceptPeerDependencies pinDependencies
pinDevDependencies pinDigestsDisabled pinOnlyDevDependencies
pinSkipCi pinVersions preserveSemverRanges
widenPeerDependencies
extends: ["config:recommended", ":pinAllExceptPeerDependencies"]
extends: ["config:recommended", ":pinOnlyDevDependencies"]

Only the : presets from default.preset.js set rangeStrategy, and none of them is part of config:recommended. So it stays at auto. What the most important ones do (look it up with grep -A8 'pinDependencies: {' $D/default.preset.js):

Preset pins leaves ranges
:pinDependencies dependencies devDependencies, peerDependencies, …
:pinAllExceptPeerDependencies (config:js-app) everything peerDependencies, engines
:pinOnlyDevDependencies (config:js-lib) devDependencies the rest via replace/widen
:preserveSemverRanges nothing all, strategy replace

config:best-practices additionally pulls in :pinDevDependencies and docker:pinDigests. That is the step from “keeping things current” to “keeping things reproducible”.

Save your progress? Sign up for free

Drill 5: versioning – which is greater?

Now the Dockerfile joins in. --dry-run=lookup only queries the datasources. The report shows the effective versioning per dependency, and the second query the offered updates.

jq '.enabledManagers += ["dockerfile"]' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate --dry-run=lookup --report-type=file --report-path=../look.json \
  shop/shop-api > ../look.log 2>&1
jq -r '.repositories[].packageFiles[][].deps[]
  | "\(.depName) \(.currentValue) \(.versioning)"' \
  ../look.json
jq -c '.repositories[].packageFiles[][].deps[] | [.depName, [.updates[]?.newValue]]' \
  ../look.json

Expected:

node      20.11.0-alpine  node  minor: 20.20.2-alpine, major: 24.21.0-alpine
express   4.18.2          npm   minor: 4.22.3, major: 5.3.0
lodash    4.17.21         npm   minor: 4.18.1
prettier  3.0.0           npm   minor: 3.9.10

The suffix -alpine is preserved; a switch to -bookworm is never offered. The Node image uses the node versioning, not docker: the preset workarounds:nodeDockerVersioning from config:recommended allows only LTS versions as major targets. Force the generic docker:

jq '.packageRules = [
  {"matchPackageNames": ["node"], "versioning": "docker"}]' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate --dry-run=lookup --report-type=file --report-path=../look.json \
  shop/shop-api > ../look.log 2>&1
jq -r '.repositories[].packageFiles[][].deps[]
  | "\(.depName) \(.currentValue) \(.versioning)"' \
  ../look.json | grep node
jq -c '.repositories[].packageFiles[][].deps[] | [.depName, [.updates[]?.newValue]]' \
  ../look.json | grep node

Expected:

node      20.11.0-alpine  docker  minor: 20.20.2-alpine, major: 26.11.1-alpine

With docker, Node 26 is the target, even though it is not yet an LTS (as of October 2026). semver and loose behave the same way with this tag. For tags that follow no standard, there is regex: with named groups:

jq '.packageRules[0].versioning =
  "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)(?<compatibility>-alpine)$"' \
  renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
LOG_LEVEL=debug renovate --dry-run=lookup --report-type=file \
  --report-path=../look.json shop/shop-api > ../look.log 2>&1
jq -r '.repositories[].packageFiles[][].deps[]
  | "\(.depName) \(.currentValue) \(.versioning)"' \
  ../look.json | grep node
jq -c '.repositories[].packageFiles[][].deps[] | [.depName, [.updates[]?.newValue]]' \
  ../look.json | grep node
grep -o 'Dependency node has unsupported/unversioned value [^ ]*' ../look.log

Expected:

node      20.11.0-alpine  regex  -
Dependency node has unsupported/unversioned value 20.11.0

No update. For Node images, the workaround additionally sets versionCompatibility and splits off -alpine before the versioning sees the rest. The regex receives only 20.11.0 and requires -alpine. Without the suffix group it matches:

jq '.packageRules[0].versioning =
  "regex:^(?<major>\\d+)\\.(?<minor>\\d+)\\.(?<patch>\\d+)$"' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate --dry-run=lookup --report-type=file --report-path=../look.json \
  shop/shop-api > ../look.log 2>&1
jq -r '.repositories[].packageFiles[][].deps[]
  | "\(.depName) \(.currentValue) \(.versioning)"' \
  ../look.json | grep node
jq -c '.repositories[].packageFiles[][].deps[] | [.depName, [.updates[]?.newValue]]' \
  ../look.json | grep node

Expected:

node      20.11.0-alpine  regex  minor: 20.20.2-alpine, major: 26.11.1-alpine

Tip: When an update “just won’t come”, search the debug log for unsupported/unversioned. That is almost always a versioning that does not match the value.

Save your progress? Sign up for free

Drill 6: Filtering – allowedVersions, ignoreDeps, enabled, followTag

Four tools, one run. description is a real field in packageRules and documents why a rule exists.

cat > renovate.json <<'EOF'
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "enabledManagers": ["npm", "dockerfile"],
  "prHourlyLimit": 0,
  "ignoreDeps": ["prettier"],
  "packageRules": [
    {
      "description": "express 5 erst nach Migration (Ticket SHOP-42)",
      "matchPackageNames": ["express"],
      "allowedVersions": "<5"
    },
    {
      "description": "Node: nur gerade Majors",
      "matchPackageNames": ["node"],
      "versioning": "docker",
      "allowedVersions": "/^\\d*[02468]\\./"
    },
    {
      "matchPackageNames": ["lodash"],
      "enabled": false
    }
  ]
}
EOF
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Versionsfilter"
git push -q origin HEAD
renovate --dry-run=lookup --report-type=file --report-path=../look.json \
  shop/shop-api > ../look.log 2>&1
jq -r '.repositories[].packageFiles[][].deps[]
  | "\(.depName) \(.currentValue) \(.versioning)"' \
  ../look.json
jq -c '.repositories[].packageFiles[][].deps[] | [.depName, [.updates[]?.newValue]]' \
  ../look.json
jq -r '.. | objects | select(.skipReason?) | "\(.depName): \(.skipReason)"' ../look.json

Expected:

node      20.11.0-alpine  docker  minor: 20.20.2-alpine, major: 26.11.1-alpine
express   4.18.2          npm     minor: 4.22.3
lodash    4.17.21         -       -
prettier  3.0.0           -       -
lodash: disabled
prettier: ignored

allowedVersions: "<5" is a range in the package’s versioning, /…/ a regex on the version string. “Even majors” lets Node 26 through: even does not mean LTS. For LTS, stick with the node versioning or name the lines explicitly. ignoreDeps is the short form of enabled: false, but the packageRule can match more precisely.

followTag follows an npm dist-tag instead of the highest version. npm view shows which tags exist:

npm view express dist-tags; npm view prettier dist-tags
jq 'del(.ignoreDeps) | .packageRules = [
  {"matchPackageNames": ["prettier"], "followTag": "next"},
  {"matchPackageNames": ["express"], "followTag": "latest-4"}]' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate --dry-run=lookup --report-type=file --report-path=../look.json \
  shop/shop-api > ../look.log 2>&1
jq -r '.repositories[].packageFiles[][].deps[]
  | "\(.depName) \(.currentValue) \(.versioning)"' \
  ../look.json
jq -c '.repositories[].packageFiles[][].deps[] | [.depName, [.updates[]?.newValue]]' \
  ../look.json

Expected (shortened):

{ latest: '5.3.0', 'latest-4': '4.22.3' }
{ next: '4.0.0-alpha.13', latest: '3.9.10' }
node      20.11.0-alpine  node  minor: 20.20.2-alpine, major: 24.21.0-alpine
express   4.18.2          npm   minor: 4.22.3
lodash    4.17.21         npm   minor: 4.18.1
prettier  3.0.0           npm   major: 4.0.0-alpha.13

express follows the maintenance line 4, prettier the pre-release channel. If the tag later points to a lower version, Renovate also proposes a downgrade.

Save your progress? Sign up for free

Drill 7: Blocking and allowing major updates

Rules based on matchUpdateTypes only take effect when branches are formed. The lookup report does not show them; here you need real runs. First, all majors off:

jq '.packageRules = [] | .major = {"enabled": false}' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-major1.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-major1.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'

Expected:

   1 Autoclosing PR
   4 Branch created
   4 PR created
#10 renovate/express-4.x | Update dependency express to v4.22.3
#11 renovate/lodash-monorepo | Update dependency lodash to v4.18.1
#12 renovate/prettier-3.x | Update dependency prettier to v3.9.10
#13 renovate/node-20.x | Update Node.js to v20.20.2

major is an update type object like minor and patch (preset :disableMajorUpdates). More precisely: block only express majors while express is still on 4.x. All other majors are allowed again.

jq 'del(.major) | .packageRules = [
  {"matchPackageNames": ["express"], "matchCurrentVersion": "<5.0.0",
   "matchUpdateTypes": ["major"], "enabled": false}]' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-major2.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-major2.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'

Expected (shortened):

   1 Branch created
   1 PR created
#13 renovate/node-20.x | Update Node.js to v20.20.2
#14 renovate/node-24.x | Update Node.js to v24

Node gets its major PR, express does not. The difference from allowedVersions: "<5": if you raise express to 5 by hand, matchCurrentVersion no longer applies and the rule retires itself. allowedVersions, on the other hand, would hold you on 4.x.

Save your progress? Sign up for free

Drill 8: Pinning Docker digests

A tag like 20.11.0-alpine can be rebuilt and then points to a different image. Only the digest makes the build reproducible.

jq '.pinDigests = true' renovate.json > tmp.json
mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Konfiguration"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-digest1.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-digest1.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/ | grep -E '/\(node\|pin\)'); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done

Expected (shortened):

   1 Branch created
   1 PR created
#15 renovate/pin-dependencies | Pin Node.js to 2f46fd4
== renovate/node-24.x
-FROM node:20.11.0-alpine
+FROM node:24.21.0-alpine
== renovate/pin-dependencies
-FROM node:20.11.0-alpine
+FROM node:20.11.0-alpine@sha256:2f46fd49c767…

The tag stays readable, the digest is binding. After the merge, Renovate rebuilds the Node branches, now with a digest:

curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" -X POST "$R/pulls/15/merge" \
  --json '{"Do":"merge","delete_branch_after_merge":true}'
git checkout -q main
git pull -q
renovate shop/shop-api > ../lauf-digest2.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-digest2.log | sort | uniq -c
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/ | grep -E '/node'); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done

Expected:

200
   2 Branch updated
== renovate/node-20.x
-FROM node:20.11.0-alpine@sha256:2f46fd49c767…
+FROM node:20.20.2-alpine@sha256:fb4cd12c85ee…
== renovate/node-24.x
-FROM node:20.11.0-alpine@sha256:2f46fd49c767…
+FROM node:24.21.0-alpine@sha256:ebfe2f904627…

Waiting for a rebuild of the tag under the same name is hard in the lab. You simulate it by writing a different digest under the old tag. Renovate then sees: same tag, different digest.

ALT=$(git show origin/renovate/node-20.x:Dockerfile | grep -o 'sha256:[0-9a-f]*')
sed -i.bak "s/sha256:[0-9a-f]*/$ALT/" Dockerfile && rm Dockerfile.bak
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Digest veraltet (Simulation)"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-digest3.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-digest3.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/ | grep -E '/node-20.11'); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done

Expected (shortened):

   1 Branch created
   2 Branch updated
   1 PR created
#16 renovate/node-20.11.0-alpine | Update Node.js to 2f46fd4
== renovate/node-20.11.0-alpine
-FROM node:20.11.0-alpine@sha256:fb4cd12c85ee…
+FROM node:20.11.0-alpine@sha256:2f46fd49c767…

In the PR body, the update type is digest (fb4cd12 → 2f46fd4), and the branch is named after the full tag. Such PRs come often in practice, because official images are regularly rebuilt with security fixes. Candidates for automerge (Day 5).

Save your progress? Sign up for free

Checkpoint

The config is valid, lodash and express are exact, and the Dockerfile has a digest:

cd ~/renovate-lab/tag06/shop-api
git pull -q
renovate-config-validator --no-global renovate.json >/dev/null 2>&1; echo "Exit: $?"
grep -E '"(lodash|express)"' package.json
grep '^FROM' Dockerfile | cut -c1-60

Expected:

R06_KP1

The digest PR is open, an express 5 PR is not:

curl -s -u "$ADMIN" "$R/pulls" | jq -r '.[].head.ref'

Expected:

R06_KP2

Challenge

The platform team mandates: the Node image stays on the LTS line 22.x, always with a digest. express majors are ignored, no matter which version. Write the renovate.json so that after one run exactly one Node major PR to 22.x is open.

Hint: allowedVersions and pinDigests may be in the same packageRule.

Solution

cat > renovate.json <<'EOF'
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "enabledManagers": ["npm", "dockerfile"],
  "prHourlyLimit": 0,
  "packageRules": [
    {
      "description": "Node-Image: nur LTS-Linie 22, immer mit Digest",
      "matchDatasources": ["docker"],
      "matchPackageNames": ["node"],
      "allowedVersions": "/^22\\./",
      "pinDigests": true
    },
    {
      "description": "express 5 ignorieren",
      "matchPackageNames": ["express"],
      "matchUpdateTypes": ["major"],
      "enabled": false
    }
  ]
}
EOF
renovate-config-validator --no-global renovate.json >/dev/null
git add -A
git commit -qm "Challenge Tag 6"
git push -q origin HEAD
renovate shop/shop-api > ../lauf-challenge.log 2>&1
grep -hoE 'Branch (created|updated)|PR (created|updated)|Autoclosing PR' \
  ../lauf-challenge.log | sort | uniq -c
curl -s -u "$ADMIN" "$R/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.head.ref) | \(.title)"'
git fetch -q --prune origin
for b in $(git branch -r | grep renovate/ | grep -E '/node'); do
  echo "== $b"
  git diff origin/main...$b -- package.json Dockerfile | grep -E '^[-+][^-+]'
done

Expected (shortened):

   2 Autoclosing PR
   1 Branch created
   1 PR created
#16 renovate/node-20.11.0-alpine | Update Node.js to 2f46fd4
#17 renovate/node-22.x | Update Node.js to v22
== renovate/node-20.11.0-alpine
-FROM node:20.11.0-alpine@sha256:fb4cd12c85ee…
+FROM node:20.11.0-alpine@sha256:2f46fd49c767…
== renovate/node-22.x
-FROM node:20.11.0-alpine@sha256:fb4cd12c85ee…
+FROM node:22.23.3-alpine@sha256:0a7108bf6c7b…

node-20.x and node-24.x are closed because 20.20.2 and 24.x are no longer allowed. The digest PR for the current tag stays; allowedVersions filters only versions, not digests. The file is also available at code/tag06/renovate.json.

Save your progress? Sign up for free

Enterprise Note

  • Define rangeStrategy centrally per repo type (org preset, Day 11): apps config:js-app or update-lockfile, libraries config:js-lib. Mixed strategies in the same monorepo are a source of discussion in every PR.
  • Every block (allowedVersions, enabled: false, ignoreDeps) needs a description with a ticket and an expiry date, otherwise it becomes silent legacy baggage. The Dependency Dashboard (Day 14) makes it visible.
  • Digests are mandatory when images are signed or checked by policy (e.g. Kyverno, OpenShift ImagePolicy). Plan for the flood of digest PRs: automerge with tests or grouping (Days 4/5).
  • Internal registries need the same tags and digests as the original. A mirror that repackages images produces different digests (Day 8).
  • Node and Java base images only on LTS lines: do not carelessly override the node versioning or the workarounds from config:recommended.