Skip to content
Hands-on IT IT Drills

Day 14: Dependency Dashboard and troubleshooting

Goal: You control Renovate entirely through checkboxes via the API, read JSON logs with jq and recognize the typical failure patterns at first glance. · Duration: approx. 120 min · Prerequisite: Day 1, Day 4

Briefing

  • The dashboard is an issue with checkboxes. Each one carries a marker in an HTML comment. Renovate reads them on the next run and unticks them afterwards.
  • Every PR also has a checkbox: “If you want to rebase/retry this PR”.
  • dependencyDashboardApproval turns the dashboard into an approval gate.
  • Troubleshooting means: LOG_LEVEL=debug LOG_FORMAT=json, then jq. Four entries answer almost every question.
 human/script  ──PATCH body: [ ] → [x]──► Issue/PR
                                            │  next run reads markers
 renovate ◄─────────────────────────────────┘  acts, rewrites body: [x] → [ ]

Drill 1: Training ground and first run

A fresh state with a config directly on main, without an onboarding PR. You switch off Forgejo Actions, otherwise every PR hangs on “Waiting to run” (Day 5). You create the label for the dashboard beforehand, because Forgejo silently discards unknown labels.

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, Day 1
mkdir -p ~/renovate-lab/tag14 && cd ~/renovate-lab/tag14
cp ~/renovate-lab/code/tag14/sabotage.sh .
API="$FORGEJO/api/v1/repos/shop/shop-api"
rm -rf shop-api
git clone -q forgejo:shop/shop-api.git
curl -s -u "$ADMIN" -X PATCH "$API" --json '{"has_actions":false}' | jq -c '{has_actions}'
curl -s -u "$ADMIN" -X POST "$API/labels" --json '{"name":"renovate","color":"#1f6feb"}' \
  | jq -r .name

Expected (abridged):

204
{"has_actions":false}
renovate

Today you make changes to main in the clone shop-api: first git pull, because Renovate merges in between, then copy, commit, push.

cat > renovate.json <<'EOF'
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "dependencyDashboardLabels": ["renovate"]
}
EOF
renovate-config-validator --no-global renovate.json | tail -1
git -C shop-api pull -q
cp renovate.json shop-api/renovate.json
git -C shop-api add -A
git -C shop-api commit -qm "Renovate einrichten"
git -C shop-api push -q
renovate shop/shop-api 2>&1 | grep -E '(Branch|PR) created' | cut -c1-88
curl -s -u "$ADMIN" "$API/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.state) \(.head.ref) | \(.title)"'
curl -s -u "$ADMIN" "$API/issues?type=issues" \
  | jq -r '.[] | "#\(.number) \(.title) \([.labels[].name])"'

Expected:

 INFO: Config validated successfully against 1 file(s)
 INFO: Branch created (repository=shop/shop-api, branch=renovate/express-4.x)
 INFO: PR created (repository=shop/shop-api, branch=renovate/express-4.x)
 INFO: Branch created (repository=shop/shop-api, branch=renovate/prettier-3.x)
 INFO: PR created (repository=shop/shop-api, branch=renovate/prettier-3.x)
#1 open renovate/express-4.x | Update dependency express to v4.22.3
#2 open renovate/prettier-3.x | Update dependency prettier to v3.9.10
#3 Dependency Dashboard [renovate]

The target versions come from the test run; yours will be newer. Two PRs; the rest is held back by the hourly limit (Day 1).

Save your progress? Sign up for free

Drill 2: Anatomy of the dashboard

curl -s -u "$ADMIN" "$API/issues/3" | jq -r .body | grep -E '^(## |This issue)' | cut -c1-88
curl -s -u "$ADMIN" "$API/issues/3" | jq -r .body \
  | grep -oE '\[[ x]\] <!-- [^ ]+ -->'

Expected:

This issue lists Renovate updates and detected dependencies. Read the [Dependency Dashbo
## Rate-Limited
## Open
## Detected Dependencies
[ ] unlimit-branch=renovate/node-20.x
[ ] unlimit-branch=renovate/actions-checkout-7.x
[ ] unlimit-branch=renovate/actions-setup-node-7.x
[ ] unlimit-branch=renovate/express-5.x
[ ] unlimit-branch=renovate/node-24.x
[ ] create-all-rate-limited-prs
[ ] rebase-branch=renovate/express-4.x
[ ] rebase-branch=renovate/prettier-3.x
[ ] rebase-all-open-prs

A section only appears if it has entries. The most important sections of Renovate 44.153.1 in the order in which Renovate writes them (source: dependency-dashboard.js in the package):

Section Reason Marker (<typ>-branch=…) Bulk checkbox
Repository Problems WARN/ERROR in the run (Day 8, 9) – –
Pending Approval dependencyDashboardApproval approve approve-all-pending-prs
Awaiting Schedule schedule (Day 4) unschedule create-all-awaiting-schedule-prs
Rate-Limited limits (Day 4) unlimit create-all-rate-limited-prs
Errored error in the branch retry –
PR Edited (Blocked) foreign commit in the branch rebase –
Pending Status Checks minimumReleaseAge (Day 4) unpend –
Open open PRs rebase rebase-all-open-prs
PR Closed (Blocked) closed PR (Day 1) recreate –
Detected Dependencies all dependencies found – –

There is no “manual job” or “Run Renovate again” checkbox in CLI 44; the term does not appear in the dashboard’s source code. Only the hosted Mend app offers it, because it decides by itself when to run. Self-hosted, the next run is your CronJob (Day 10) or a manual call.

You set the title, header and footer via config. By the way, Renovate only sets dependencyDashboardLabels when it rewrites the issue body anyway. If you remove the label by hand, it stays gone until something changes on the dashboard (confirmed in testing). Now the new title:

jq '. + {dependencyDashboardTitle: "Renovate-Steuerpult",
  dependencyDashboardFooter: "Zuständig: Platform-Team, Kanal #renovate"}' \
  renovate.json > tmp.json && mv tmp.json renovate.json
git -C shop-api pull -q
cp renovate.json shop-api/renovate.json
git -C shop-api add -A
git -C shop-api commit -qm "Dashboard umbenennen"
git -C shop-api push -q
renovate shop/shop-api >/dev/null 2>&1
curl -s -u "$ADMIN" "$API/issues?type=issues" \
  | jq -r '.[] | "#\(.number) \(.title) \([.labels[].name])"'
curl -s -u "$ADMIN" "$API/issues/4" | jq -r .body | grep -B1 Zuständig

Expected:

#4 Renovate-Steuerpult [renovate]
#3 Dependency Dashboard [renovate]
---
Zuständig: Platform-Team, Kanal #renovate

Renovate finds the dashboard only by its title. It no longer knows the old issue #3 and leaves it open as an orphan. Close it yourself:

curl -s -u "$ADMIN" -X PATCH "$API/issues/3" --json '{"state":"closed"}' | jq -r '"#\(.number) \(.state)"'
D=$(curl -s -u "$ADMIN" "$API/issues?type=issues" \
  | jq -r '.[] | select(.title == "Renovate-Steuerpult") | .number')
echo "Dashboard: #$D"

Expected:

#3 closed
Dashboard: #4

Warning: Whoever changes dependencyDashboardTitle in an org preset (Day 11) leaves an orphaned dashboard behind in every repo. Plan the cleanup accordingly.

Save your progress? Sign up for free

Drill 3: Checkboxes via the API

tick fetches the body, replaces - [ ] <!-- marker --> with - [x] <!-- marker --> and sends it back via PATCH. That is exactly what the browser does. First a single rebase:

curl -s -u "$ADMIN" "$API/branches/renovate%2Fexpress-4.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- rebase-branch=renovate/express-4.x|- [x] <!-- rebase-branch=renovate/express-4.x|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
LOG_LEVEL=debug renovate shop/shop-api > d3.log 2>&1
grep -E 'dependencyDashboardCheck=rebase|User has requested|Branch updated' d3.log \
  | cut -c1-88
curl -s -u "$ADMIN" "$API/branches/renovate%2Fexpress-4.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body \
  | grep -oE '\[[ x]\] <!-- [^ ]+ -->' | grep express-4

Expected (hashes will differ):

vorher:  09a2959 faeee1a
R14_TICK
DEBUG: dependencyDashboardCheck=rebase (repository=shop/shop-api, branch=renovate/expres
DEBUG: User has requested rebase (repository=shop/shop-api, branch=renovate/express-4.x)
 INFO: Branch updated (repository=shop/shop-api, branch=renovate/express-4.x)
nachher: 589c592 faeee1a
[ ] rebase-branch=renovate/express-4.x

Renovate rebuilds the branch on top of main (reuseExistingBranch: false), even without a conflict, and unticks the box afterwards. The checkbox is an order, not a state. Now all open PRs at once:

curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- rebase-all-open-prs|- [x] <!-- rebase-all-open-prs|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
renovate shop/shop-api 2>&1 | grep 'Branch updated' | cut -c1-88
curl -s -u "$ADMIN" "$API/branches/renovate%2Fexpress-4.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'

Expected:

R14_TICK
 INFO: Branch updated (repository=shop/shop-api, branch=renovate/express-4.x)
 INFO: Branch updated (repository=shop/shop-api, branch=renovate/prettier-3.x)
nachher: a93c4bb a18cbe7

Tip: For scripts and emergencies, the same orders exist as global, experimental CLI options: --checked-branches=renovate/prettier-3.x acts like a tick on this branch, --rebase-all-open-branches=true like rebase-all-open-prs. In testing, the first variant produced “Branch updated” for exactly this branch.

Save your progress? Sign up for free

Drill 4: Approval gate with dependencyDashboardApproval

Majors should only come after a tick, everything else immediately. You remove the hourly limit so that only the approval slows things down. The file is also included as code/tag14/renovate-freigabe.json.

cat > renovate.json <<'EOF'
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "dependencyDashboardLabels": ["renovate"],
  "dependencyDashboardTitle": "Renovate-Steuerpult",
  "dependencyDashboardFooter": "Zuständig: Platform-Team, Kanal #renovate",
  "prHourlyLimit": 0,
  "packageRules": [
    {
      "description": "Majors nur nach Freigabe im Dashboard",
      "matchUpdateTypes": ["major"],
      "dependencyDashboardApproval": true
    }
  ]
}
EOF
renovate-config-validator --no-global renovate.json | tail -1
git -C shop-api pull -q
cp renovate.json shop-api/renovate.json
git -C shop-api add -A
git -C shop-api commit -qm "Majors nur nach Freigabe"
git -C shop-api push -q
renovate shop/shop-api 2>&1 | grep 'PR created' | cut -c1-88
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body | sed -n '/^## Pending Approval/,/^## Open/p' | grep '^ - ' | cut -c1-88

Expected:

 INFO: Config validated successfully against 1 file(s)
 INFO: PR created (repository=shop/shop-api, branch=renovate/node-20.x)
 - [ ] <!-- approve-branch=renovate/actions-checkout-7.x -->Update actions/checkout acti
 - [ ] <!-- approve-branch=renovate/actions-setup-node-7.x -->Update actions/setup-node
 - [ ] <!-- approve-branch=renovate/express-5.x -->Update dependency express to v5
 - [ ] <!-- approve-branch=renovate/node-24.x -->Update dependency node to v24
 - [ ] <!-- approve-all-pending-prs -->🔐 **Create all pending approval PRs at once** 🔐

The minor PR for Node comes immediately, the four majors wait. Without a tick, Renovate does not even create the branch. You approve express 5:

curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- approve-branch=renovate/express-5.x|- [x] <!-- approve-branch=renovate/express-5.x|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
LOG_LEVEL=debug renovate shop/shop-api > d4.log 2>&1
grep -E 'dependencyDashboardCheck=approve|creation is disabled|PR created' d4.log \
  | sed -E 's/ \(repository=[^)]*\)$//' | cut -c1-88
curl -s -u "$ADMIN" "$API/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.state) \(.head.ref) | \(.title)"' | tail -2

Expected:

R14_TICK
DEBUG: Branch renovate/actions-checkout-7.x creation is disabled because dependencyDashb
DEBUG: Branch renovate/actions-setup-node-7.x creation is disabled because dependencyDas
DEBUG: dependencyDashboardCheck=approve
 INFO: PR created
DEBUG: Branch renovate/node-24.x creation is disabled because dependencyDashboardApprova
#5 open renovate/node-20.x | Update Node.js to v20.20.2
#6 open renovate/express-5.x | Update dependency express to v5

After the approval, express 5 moves to the “Open” section. The approval applies to the branch, not permanently: if express 6 comes along later, it waits again.

Tip: dependencyDashboardApproval: true at the top level turns on the gate for all updates. That suits repos that are barely maintained and should only get updates on request.

Save your progress? Sign up for free

Drill 5: PR checkbox, foreign commits and recreateWhen

A colleague “helps” and commits to Renovate’s prettier branch:

git clone -q -b renovate/prettier-3.x \
  forgejo:shop/shop-api.git shop-api
echo "Hinweis vom Team" >> shop-api/README.md
git -C shop-api -c user.name="Lab Admin" -c [email protected] \
  commit -qam "README im Renovate-Branch"
git -C shop-api push -q origin renovate/prettier-3.x 2>/dev/null; rm -rf shop-api
LOG_LEVEL=debug renovate shop/shop-api > d5.log 2>&1
grep 'prettier-3.x' d5.log | grep -E 'isModified\(\) =|has been edited' | cut -c1-88
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body | grep -E '^## '
curl -s -u "$ADMIN" "$API/issues/2/comments" | jq -r '.[-1].body' | head -4 | fold -s -w 88

Expected:

DEBUG: Checking if PR has been edited (repository=shop/shop-api, branch=renovate/prettie
DEBUG: branch.isModified() = true (repository=shop/shop-api, baseBranch=main, branch=ren
DEBUG: PR has been edited, PrNo:2 (repository=shop/shop-api, branch=renovate/prettier-3.
## Pending Approval
## PR Edited (Blocked)
## Open
## Detected Dependencies
### Edited/Blocked Notification

Renovate will not automatically rebase this PR, because it does not recognize the last 
commit author and assumes somebody else may have edited the PR.

From now on Renovate no longer touches PR #2, even if prettier gets a new release. You get it back with the checkbox in the PR itself:

curl -s -u "$ADMIN" "$API/issues/2" | jq -r .body \
  | grep -oE '\[[ x]\] <!-- [^ ]+ -->'
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/issues/2" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- rebase-check|- [x] <!-- rebase-check|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/2" | jq -r .number
LOG_LEVEL=debug renovate shop/shop-api > d5b.log 2>&1
grep -E 'Manual rebase requested|prettier-3.x\)$' d5b.log | grep -E 'Manual|INFO' \
  | cut -c1-88
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/raw/README.md?ref=renovate/prettier-3.x" | grep -c 'Hinweis vom Team'

Expected:

[ ] rebase-check
vorher:  f95b597
R14_TICK
DEBUG: Manual rebase requested via PR checkbox for #2 (repository=shop/shop-api, branch=
DEBUG: Manual rebase has been requested for PR (repository=shop/shop-api, branch=renovat
 INFO: Branch updated (repository=shop/shop-api, branch=renovate/prettier-3.x)
 INFO: PR updated (repository=shop/shop-api, branch=renovate/prettier-3.x)
nachher: c13c7df
0

The README change is gone, as the comment warned (“custom changes will be lost”). Instead of the checkbox, the label rebase (option rebaseLabel) also works: Renovate rebases and removes the label again (debug: “Manual rebase requested via PR labels”). That suits bots that are only allowed to set labels. On Bitbucket and Azure DevOps, Renovate writes “rename this PR to start with rebase!” into the PR body instead of the checkbox.

Now recreateWhen. You close the express patch PR #1:

curl -s -u "$ADMIN" -X PATCH "$API/pulls/1" --json '{"state":"closed"}' | jq -r '"#\(.number) \(.state)"'
LOG_LEVEL=debug renovate shop/shop-api 2>&1 | grep -E 'Closed PR #|PR created' \
  | cut -c1-88

Expected:

#1 closed
DEBUG: Closed PR #1 already exists. Skipping branch. (repository=shop/shop-api, branch=r

With recreateWhen: "auto" (default), a closed single PR stays ignored. Only groups, digest updates and lock file maintenance come back by themselves. But express patches should never be silently left behind:

jq '.packageRules += [{description: "express-Patches nie dauerhaft ignorieren",
  matchPackageNames: ["express"], matchUpdateTypes: ["minor", "patch"],
  recreateWhen: "always"}]' renovate.json > tmp.json && mv tmp.json renovate.json
renovate-config-validator --no-global renovate.json | tail -1
git -C shop-api pull -q
cp renovate.json shop-api/renovate.json
git -C shop-api add -A
git -C shop-api commit -qm "express immer neu anlegen"
git -C shop-api push -q
LOG_LEVEL=debug renovate shop/shop-api 2>&1 \
  | grep -E 'recreateClosed is true|PR created' | cut -c1-88
curl -s -u "$ADMIN" "$API/pulls?state=all" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.state) \(.head.ref) | \(.title)"' | grep express

Expected:

 INFO: Config validated successfully against 1 file(s)
DEBUG: recreateClosed is true. No need to check for closed PR. (repository=shop/shop-api
 INFO: PR created (repository=shop/shop-api, branch=renovate/express-4.x)
#1 closed renovate/express-4.x | Update dependency express to v4.22.3
#6 open renovate/express-5.x | Update dependency express to v5
#7 open renovate/express-4.x | Update dependency express to v4.22.3
recreateWhen a closed PR is …
auto recreated only for groups, digests, lock file maintenance
always recreated on every run – closing it is pointless
never never recreated, not even for groups

Save your progress? Sign up for free

Drill 6: Evaluating JSON logs with jq

The text output of LOG_LEVEL=debug is good for grep, but not for questions like “Which updates did Renovate find?”. Five short jq queries answer the most common questions: entries per level, everything from WARN up, updates found, the decision per branch and all messages about one branch.

LOG_LEVEL=debug LOG_FORMAT=json renovate shop/shop-api > lauf.json 2>&1
jq -r .level lauf.json | sort | uniq -c
jq -c 'select(.level >= 40) | {level, branch, msg}' lauf.json
jq -r 'select(.msg == "packageFiles with updates") | .config[][].deps[]
  | "\(.depName) \(.currentValue) \([.updates[]?.newVersion])"' lauf.json

Expected:

 634 20
   6 30
Dockerfile: node 20.11.0-alpine -> 20.20.2 (minor), 24.21.0 (major)
.github/workflows/ci.yml: actions/checkout v3 -> v7.0.1 (major)
.github/workflows/ci.yml: actions/setup-node v3 -> v7.1.0 (major)
.github/workflows/ci.yml: ubuntu latest ->  [skip: invalid-version]
.github/workflows/ci.yml: node 20 -> 24.21.0 (major)
package.json: express 4.18.2 -> 4.22.3 (minor), 5.3.0 (major)
package.json: lodash ^4.17.20 ->
package.json: prettier 3.0.0 -> 3.9.10 (minor)

probleme is empty; the run was clean. updates reads the entry packageFiles with updates: the complete result of extraction and lookup, with skipReason and lookup warnings per dependency. Without a GitHub token, the Actions would show [skip: github-token-required]. What Renovate decided per branch:

jq -r 'select(.msg == "branches info extended") | .branchesInformation[]
  | "\(.result) \(.branchName)"' lauf.json
jq -r 'select(.branch == "renovate/node-24.x") | .msg' lauf.json | tail -3

Expected:

done    #7  renovate/express-4.x
done    #2  renovate/prettier-3.x
done    #5  renovate/node-20.x
needs-approval  #-  renovate/actions-checkout-7.x
needs-approval  #-  renovate/actions-setup-node-7.x
done    #6  renovate/express-5.x
needs-approval  #-  renovate/node-24.x
findPr(renovate/node-24.x, Update dependency node to v24, !open)
prAlreadyExisted=false
Branch renovate/node-24.x creation is disabled because dependencyDashboardApproval=true

branches reads branches info extended. The result field is the same cause from which the dashboard builds its sections: needs-approval, not-scheduled, pr-limit-reached, already-existed, pr-edited, error. warum tells the decision chain of a branch in Renovate’s own words.

Finally, --dry-run=full versus the real run. You approve node 24 and ask the trial run first:

curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- approve-branch=renovate/node-24.x|- [x] <!-- approve-branch=renovate/node-24.x|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
renovate --dry-run=full shop/shop-api 2>&1 | grep DRY-RUN | cut -c1-88
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body \
  | grep -oE '\[[ x]\] <!-- [^ ]+ -->' | grep node-24
curl -s -u "$ADMIN" "$API/pulls" \
  | jq -r 'sort_by(.number)[] | "#\(.number) \(.state) \(.head.ref) | \(.title)"' | grep -c node-24
renovate shop/shop-api 2>&1 | grep -E '(Branch|PR) created' | cut -c1-88
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body \
  | grep -oE '\[[ x]\] <!-- [^ ]+ -->' | grep node-24

Expected:

R14_TICK
 INFO: DRY-RUN: Would commit files to branch renovate/node-24.x. See debug logs for raw
 INFO: DRY-RUN: Would ensure Dependency Dashboard (repository=shop/shop-api)
 INFO: DRY-RUN: Would save repository cache. (repository=shop/shop-api)
[x] approve-branch=renovate/node-24.x
0
 INFO: Branch created (repository=shop/shop-api, branch=renovate/node-24.x)
 INFO: PR created (repository=shop/shop-api, branch=renovate/node-24.x)
[ ] rebase-branch=renovate/node-24.x

The trial run reads the checkbox but leaves it ticked. You won’t see a “Would create PR”: without a real branch, the simulation ends at the commit. For questions about the PR title or body, --dry-run=full is therefore only half an answer.

Save your progress? Sign up for free

Drill 7: Failure pattern broken config

A typo, as happens when editing in the browser:

cp renovate.json renovate.gut.json
sed 's/"prHourlyLimit": 0,/&,/' renovate.gut.json > kaputt.json
git -C shop-api pull -q
cp kaputt.json shop-api/renovate.json
git -C shop-api add -A
git -C shop-api commit -qm "Limit anpassen"
git -C shop-api push -q
LOG_LEVEL=debug LOG_FORMAT=json renovate shop/shop-api > kaputt.log 2>&1
echo "exit=$?"
jq -c 'select(.level >= 40) | {level, branch, msg}' kaputt.log
jq -c 'select(.msg == "Repository finished") | {result, status}' kaputt.log
curl -s -u "$ADMIN" "$API/issues?type=issues" \
  | jq -r '.[] | "#\(.number) \(.title) \([.labels[].name])"'
curl -s -u "$ADMIN" "$API/issues/9" | jq -r .body | fold -s -w 88

Expected:

exit=0
40 - Repository has invalid config | Invalid JSON (parsing failed)
40 - Configuration Warning
{"result":"config-validation","status":"onboarded"}
#9 Action Required: Fix Renovate Configuration []
#4 Renovate-Steuerpult [renovate]
There is an error with this repository's Renovate configuration that needs to be fixed. 
As a precaution, Renovate will stop PRs until it is resolved.

Location: `renovate.json`
Error type: Invalid JSON (parsing failed)
Message: Syntax error: expecting String near ": 0,,
  "

“Stop PRs” means: Renovate touches nothing at all anymore, not even orders from checkboxes. Test it with the rebase tick in PR #2, then repair:

curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/issues/2" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- rebase-check|- [x] <!-- rebase-check|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/2" | jq -r .number
renovate shop/shop-api 2>&1 | grep -E 'WARN|Branch updated' | cut -c1-88
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
git -C shop-api pull -q
cp renovate.gut.json shop-api/renovate.json
git -C shop-api add -A
git -C shop-api commit -qm "Config repariert"
git -C shop-api push -q
renovate shop/shop-api 2>&1 | grep -E 'WARN|Branch updated' | cut -c1-88
curl -s -u "$ADMIN" "$API/branches/renovate%2Fprettier-3.x" | jq -r '.commit.id[0:7]'
curl -s -u "$ADMIN" "$API/issues/9" | jq -r .state

Expected:

vorher:  c13c7df
R14_TICK
 WARN: Repository has invalid config (repository=shop/shop-api)
nachher: c13c7df
 INFO: Branch updated (repository=shop/shop-api, branch=renovate/prettier-3.x)
repariert: 7d7e68d, Issue #9: closed

The tick survived the outage and was carried out afterwards; Renovate closes the issue itself. The exit code was 0 (Day 9: exitCodeForErrors). And renovate-config-validator --no-global kaputt.json would have found it before the push (“JSON5: invalid character ‘,’ at 11:22”, exit 1, Day 2).

Save your progress? Sign up for free

Drill 8: Lookup, artifact and permission errors

Someone adds express-validator and makes a typo. Be careful when choosing the typo: many obvious names are taken on npmjs.com.

for p in lodahs expresss expres-validator; do
  printf '%s: ' $p; npm view $p version 2>&1 | head -1; done

Expected:

lodahs: 0.0.1-security
expresss: 0.0.0
expres-validator: npm error code E404

Security: lodahs is a security placeholder from npm, expresss a third-party package. Such a typo produces no lookup error, but installs foreign code, and Renovate dutifully keeps it up to date. Read new entries in “Detected Dependencies” critically.

curl -s -u "$ADMIN" "$API/raw/package.json" | jq '.dependencies["expres-validator"] = "7.2.1"' \
  > package.json
git -C shop-api pull -q
cp package.json shop-api/package.json
git -C shop-api add -A
git -C shop-api commit -qm "Validierung ergänzen"
git -C shop-api push -q
LOG_LEVEL=debug LOG_FORMAT=json renovate shop/shop-api > lookup.log 2>&1
jq -c 'select(.level >= 40) | {level, branch, msg}' lookup.log | sort | uniq -c
jq -r 'select(.msg == "packageFiles with updates") | .config[][].deps[]
  | "\(.depName) \(.currentValue) \([.updates[]?.newVersion])"' lookup.log | grep expres- | cut -c1-88

Expected:

   1 40 - Package lookup failures
   1 40 renovate/express-4.x artifactErrors
   1 40 renovate/express-4.x Package lookup failures
   1 40 renovate/express-5.x artifactErrors
   1 40 renovate/express-5.x Package lookup failures
   1 40 renovate/node-20.x Package lookup failures
   1 40 renovate/node-24.x Package lookup failures
   1 40 renovate/prettier-3.x Package lookup failures
package.json: expres-validator 7.2.1 ->  [warn: Failed to look up npm package expres-va

One error, two failure patterns. First, the lookup error: Renovate finds no versions, writes a block “⚠️ Warning – Renovate failed to look up the following dependencies” into the dashboard and into every PR body, but carries on.

Second, the artifact error: the express PRs change the same spot in package.json as your commit, so Renovate rebuilt them. In doing so it calls npm install --package-lock-only, and npm fails on the unknown package.

jq -r 'select(.artifactErrors) | [.branch, (.artifactErrors[0].stderr
  | split("\n") | map(select(startswith("npm error code"))) | first)]
  | join(": ")' lookup.log
curl -s -u "$ADMIN" "$API/commits/renovate%2Fexpress-4.x/status" \
  | jq -r '.statuses[] | "\(.context) = \(.status) – \(.description)"'
curl -s -u "$ADMIN" "$API/issues/7/comments" | jq -r '.[-1].body' | grep -E '^#|E404' | cut -c1-88

Expected:

renovate/express-4.x: npm error code E404
renovate/express-5.x: npm error code E404
renovate/artifacts = failure – Artifact file update failure
### ⚠️ Artifact update problem
##### File name: package-lock.json
npm error code E404

prettier and node remained untouched because their branches had no conflict. So an artifact error only shows up where Renovate is currently touching the lockfile. The repair happens on main:

curl -s -u "$ADMIN" "$API/raw/package.json" | jq 'del(.dependencies["expres-validator"])' \
  > package.json
git -C shop-api pull -q
cp package.json shop-api/package.json
git -C shop-api add -A
git -C shop-api commit -qm "Tippfehler entfernt"
git -C shop-api push -q
renovate shop/shop-api 2>&1 | grep -E 'WARN|Branch updated' | cut -c1-88
curl -s -u "$ADMIN" "$API/commits/renovate%2Fexpress-4.x/status" | jq -c '[.statuses[]?.status]'

Expected:

 INFO: Branch updated (repository=shop/shop-api, branch=renovate/express-4.x)
 INFO: Branch updated (repository=shop/shop-api, branch=renovate/express-5.x)
[]

The new commit no longer carries a failure. Renovate only sets renovate/artifacts in the error case. Had there been no conflict, rebase-check in the PR would have been the way, see the comment (“you click the rebase/retry checkbox”).

The last failure pattern: the bot loses its write permission.

curl -s -u "$ADMIN" -X DELETE "$API/collaborators/renovate-bot" && echo "Bot entfernt"
curl -s -H "Authorization: token $RENOVATE_TOKEN" "$API" | jq -c .permissions
LOG_LEVEL=debug renovate shop/shop-api > rechte.log 2>&1; echo "exit=$?"
grep -E 'does not permit|"result"' rechte.log | cut -c1-88
curl -s -u "$ADMIN" -X PUT "$API/collaborators/renovate-bot" --json '{"permission":"write"}' \
  && echo "Bot wieder Collaborator"

Expected:

Bot entfernt
{"admin":false,"push":false,"pull":true}
exit=0
DEBUG: Repository does not permit pull or push - aborting renovation (repository=shop/sh
       "result": "forbidden",
Bot wieder Collaborator

No issue (the bot would not even be allowed to write it), no WARN, exit 0, finished after 11 ms. At level info you only see “Repository is forbidden”. This is the most insidious failure pattern: Renovate simply goes quiet. With autodiscover, the repo does not even show up in the list anymore (Day 9).

Save your progress? Sign up for free

Diagnosis checklist

Symptom First look Cause Fix
Issue “Action Required: Fix Renovate Configuration”, nothing happens anymore issue body, probleme renovate.json invalid (JSON, option, preset) validator, repair; the issue closes itself
Dashboard warning “failed to look up” updates … [warn: …] typo, private package without hostRules (Day 8) correct the name, credentials
renovate/artifacts: failure + comment “Artifact update problem” comment, artifactErrors in the log lockfile tool fails: E404, engine, missing toolchain fix on main, then rebase-check
Repo is silently skipped, result: forbidden “Repository finished” bot without write permission collaborator write, token scopes (Day 12)
Update never comes, “PR Closed (Blocked)” branches: already-existed closed PR with the same title recreate-branch, recreateWhen, config rule
PR is no longer updated, “PR Edited (Blocked)” comment “Edited/Blocked Notification” foreign commit in the branch rebase-check or label rebase
Update is listed in “Pending Approval” branches: needs-approval dependencyDashboardApproval approve-branch
Update missing completely, even in the dashboard updates … [skip: …] skipReason, e.g. github-token-required token, check enabled/ignoreDeps
Dashboard duplicated issues dependencyDashboardTitle changed close the old issue
CronJob green despite errors exit code default: repo errors result in exit 0 exitCodeForErrors: true (Day 9)

Checkpoint

The dashboard is called Renovate-Steuerpult (“Renovate control panel”) and carries the label renovate. No old dashboard and no “Action Required” is open anymore:

cd ~/renovate-lab/tag14
curl -s -u "$ADMIN" "$API/issues?type=issues" \
  | jq -r '.[] | "\(.title) \([.labels[].name])"'

Expected:

R14_KP1

Majors need an approval, and the typo has been removed from package.json:

git -C shop-api pull -q
jq -c '.packageRules[] | {matchUpdateTypes, dependencyDashboardApproval}' \
  shop-api/renovate.json
git -C shop-api log --oneline -1 -- package.json

Expected:

R14_KP2

The bot may write, and no Renovate branch is at failure:

curl -s -H "Authorization: token $RENOVATE_TOKEN" "$API" | jq .permissions.push
for b in $(git -C shop-api branch -r | grep renovate/); do
  curl -s -u "$ADMIN" "$API/commits/${b#origin/}/status" | jq -r .state
done | sort | uniq -c

Expected:

R14_KP3

Challenge

sabotage.sh from the companion code reenacts a turbulent morning – what exactly it does is for you to find out: one colleague closes a PR, another commits to a Renovate branch. Using only the JSON log, find out which branches are blocked and why. Then, with checkboxes and exactly one Renovate run, bring all updates back as open PRs, without touching renovate.json.

Hint: The per-branch decision shows you the cause, the table in Drill 2 the corresponding marker.

Solution

cd ~/renovate-lab/tag14
bash sabotage.sh
LOG_LEVEL=debug LOG_FORMAT=json renovate shop/shop-api > ch.log 2>&1
jq -r 'select(.msg == "branches info extended") | .branchesInformation[]
  | "\(.result) \(.branchName)"' ch.log | grep -v '^done'
jq -r 'select(.branch == "renovate/node-20.x") | .msg' ch.log | grep 'edited,'
jq -r 'select(.branch == "renovate/express-5.x") | .msg' ch.log | grep 'Closed PR'

Expected:

pr-edited   #5  renovate/node-20.x
needs-approval  #-  renovate/actions-checkout-7.x
needs-approval  #-  renovate/actions-setup-node-7.x
already-existed #6  renovate/express-5.x
PR has been edited, PrNo:5
Closed PR #6 already exists. Skipping branch.

Three causes, three markers. The two Actions majors are still waiting for approval from Drill 4; the bulk checkbox is enough for them.

D=$(curl -s -u "$ADMIN" "$API/issues?type=issues" \
  | jq -r '.[] | select(.title == "Renovate-Steuerpult") | .number')
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- rebase-branch=renovate/node-20.x|- [x] <!-- rebase-branch=renovate/node-20.x|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- recreate-branch=renovate/express-5.x|- [x] <!-- recreate-branch=renovate/express-5.x|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
curl -s -u "$ADMIN" "$API/issues/$D" | jq -r .body > box.md
sed -i '' 's|- \[ \] <!-- approve-all-pending-prs|- [x] <!-- approve-all-pending-prs|' box.md
jq -Rs '{body: .}' box.md > box.json
curl -s -u "$ADMIN" -X PATCH --json @box.json "$API/issues/$D" | jq -r .number
LOG_LEVEL=debug LOG_FORMAT=json renovate shop/shop-api > ch2.log 2>&1
jq -r 'select(.msg == "branches info extended") | .branchesInformation[]
  | "\(.result) \(.branchName)"' ch2.log | grep -v '^done'
curl -s -u "$ADMIN" "$API/raw/Dockerfile?ref=renovate/node-20.x" | grep -c Hotfix

Expected:

R14_TICK
R14_TICK
R14_TICK
pr-created  #10 renovate/actions-checkout-7.x
pr-created  #11 renovate/actions-setup-node-7.x
pr-created  #12 renovate/express-5.x
0

node 20 is done again, the hotfix commit discarded. express 5 gets a new PR #12; the closed #6 stays closed. In the browser this would have taken three clicks; via the API it is three lines that you can write into a runbook.

Save your progress? Sign up for free

Enterprise Note

  • Declare the dashboard the official interface: approvals, rebase requests and rejections go through checkboxes, not through commits in renovate/* branches.
  • dependencyDashboardApproval for majors is a clean change-gate record. Whoever ticks the box is recorded in the platform’s issue history.
  • Collect Renovate logs centrally as JSON (LOG_FORMAT=json, LOG_FILE with LOG_FILE_LEVEL=debug, Day 9) and alert on result ≠ done, especially on forbidden and config-validation.
  • Check bot permissions regularly via the API (permissions.push per repo). A revoked permission produces neither an issue nor an error exit.
  • Changes to dependencyDashboardTitle or -Labels in the org preset need a cleanup plan for the old issues in all repos.