Skip to content
Hands-on IT IT Drills

Day 1: The First Run

Goal: You bring Renovate into shop/shop-api via the onboarding PR, read the first update PRs, and know what closing, merging, and the Dependency Dashboard do. · Duration: approx. 75 min · Prerequisite: Day 0

Briefing

  • A repo without a Renovate configuration first gets only an onboarding PR. Only after it is merged do update PRs appear.
  • Self-hosted, Renovate writes only $schema into renovate.json, no config:recommended. Whatever you want, you add yourself.
  • At most two new PRs are created per hour (prHourlyLimit).
  • Closing a PR means: this update is ignored.
 Run 1: renovate/configure ──► onboarding PR #1 ──(merge)──► renovate.json on main
 Run 2: renovate/<dep>-<major>.x ──► update PRs (max. 2/h) + Dependency Dashboard
 after: merge ──► branch is cleaned up   close ──► update is ignored

Drill 1: Fresh start and first run

You reset shop/shop-api to the state of Day 0 and let Renovate run for real for the first time, without --dry-run.

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 Warning
mkdir -p ~/renovate-lab/tag01 && cd ~/renovate-lab/tag01

Expected:

204

Warning: Without RENOVATE_GITHUB_COM_TOKEN, Renovate skips actions/checkout, actions/setup-node, and the Node version in the workflow (“GitHub token is required for some dependencies”). Then you will see fewer PRs today than in the book, and different numbers. A token without scopes is enough.

All API calls of this day go to the same repo. You keep the address in a variable:

API="$FORGEJO/api/v1/repos/shop/shop-api"
curl -s -u "$ADMIN" "$API/contents" | jq -r '.[].name'

Expected:

.github
.gitignore
Dockerfile
README.md
index.js
package-lock.json
package.json

No renovate.json. Now the run:

renovate shop/shop-api 2>&1 | tee lauf1.log | grep -E '^ ?INFO|"(result|pr)"'
curl -s -u "$ADMIN" "$API/pulls?state=all" | jq -r '.[] | "#\(.number) \(.title)"'
curl -s -u "$ADMIN" "$API/branches" | jq -r '.[].name'

Expected (shortened):

 INFO: Repository started (repository=shop/shop-api)
 INFO: Branch created (repository=shop/shop-api, branch=renovate/configure)
 INFO: Dependency extraction complete (repository=shop/shop-api, baseBranch=main)
 INFO: Onboarding PR created (repository=shop/shop-api)
       "pr": "Pull Request #1"
 INFO: Repository finished (repository=shop/shop-api)
       "result": "onboarding",
#1 Configure Renovate
renovate/configure
main

Renovate has not changed anything on main. It created a branch renovate/configure with a renovate.json and opened PR #1 from it. As long as that is not merged, every run ends with "result": "onboarding".

Save your progress? Sign up for free

Drill 2: Read the onboarding PR

Open PR #1 in your browser (http://127.0.0.1:3000/shop/shop-api/pulls/1) or read the most important lines via the API:

curl -s -u "$ADMIN" "$API/issues/1" | jq -r .body > pr1.md
grep -E '^###|^ \* |will create|<summary>|limited' pr1.md | cut -c1-88

Expected:

### Detected Package Files
 * `Dockerfile` (dockerfile)
 * `.github/workflows/ci.yml` (github-actions)
 * `package.json` (npm)
### What to Expect
With your current configuration, Renovate will create 8 Pull Requests:
<summary>Update dependency express to v4.22.3</summary>
<summary>Update dependency prettier to v3.9.10</summary>
<summary>Update node Docker tag to v20.20.2</summary>
<summary>Update actions/checkout action to v7</summary>
<summary>Update actions/setup-node action to v7</summary>
<summary>Update dependency express to v5</summary>
<summary>Update dependency node to v24</summary>
<summary>Update node Docker tag to v26</summary>
🚸 PR creation will be limited to maximum 2 per hour, so it doesn't swamp any CI resource

“Detected Package Files” shows which managers kicked in (Day 3). “What to Expect” is a preview of the PRs with title and branch name. The target versions come from the test run; yours will be newer. lodash is missing because ^4.17.20 already covers the newest version and the lockfile already contains it.

And what is in the proposed configuration?

curl -s -u "$ADMIN" "$API/raw/renovate.json?ref=renovate/configure"
curl -s -u "$ADMIN" "$API/commits?sha=renovate/configure&limit=2" \
  | jq -r '.[] | "\(.commit.author.name): \(.commit.message)"'

Expected:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json"
}
R01_COMMITS

Only $schema. That is the default of the global option onboardingConfig in the CLI. The hosted Mend app, on the other hand, suggests config:recommended. If you merge blindly when self-hosting, you get Renovate’s bare defaults: no Dependency Dashboard, no grouping of monorepos, no workarounds.

Tip: All defaults are in the schema of the installed version, at ~/renovate-lab/tools/node_modules/renovate/renovate-schema.json (see Drill 4).

Save your progress? Sign up for free

Drill 3: Change the configuration in the onboarding branch

The PR text invites you: “Add your custom config to renovate.json in this branch”. That is exactly what you do, with git as lab-admin.

cd ~/renovate-lab/tag01
git clone -q -b renovate/configure forgejo:shop/shop-api.git shop-api
cd shop-api
cat > renovate.json <<'EOF'
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"]
}
EOF
renovate-config-validator
git commit -qam "Renovate: config:recommended"
git push -q origin renovate/configure
cd ..

Expected (shortened):

 INFO: Validating renovate.json
 INFO: Config validated successfully against 1 file(s)
remote: Visit the existing pull request:
remote:   http://127.0.0.1:3000/shop/shop-api/pulls/1 merges into main

Without an argument, renovate-config-validator looks for the repo config in the usual places. With a file name (renovate-config-validator renovate.json) it checks the file as a global self-hosted config; for repo configs you then need --no-global (Day 2).

Next run:

renovate shop/shop-api 2>&1 | grep -E 'Onboarding|"result"'
curl -s -u "$ADMIN" "$API/issues/1" | jq -r .body > pr1.md
grep -E '^###|will create|limited|Dependency Dashboard|<summary>' pr1.md | cut -c1-88

Expected:

 INFO: Onboarding PR updated (repository=shop/shop-api)
       "result": "onboarding",
### Detected Package Files
### Configuration Summary
  - Enable Renovate Dependency Dashboard creation.
### What to Expect
With your current configuration, Renovate will create 7 Pull Requests:
<summary>Update dependency express to v4.22.3</summary>
<summary>Update dependency prettier to v3.9.10</summary>
<summary>Update Node.js to v20.20.2</summary>
<summary>Update actions/checkout action to v7</summary>
<summary>Update actions/setup-node action to v7</summary>
<summary>Update dependency express to v5</summary>
<summary>Update dependency node to v24</summary>
🚸 PR creation will be limited to maximum 2 per hour, so it doesn't swamp any CI resource

Three changes caused by config:recommended:

  • A new section “Configuration Summary” with the enabled presets, among them the Dependency Dashboard.
  • Node in the Dockerfile and node-version in the workflow end up in one PR for v24.
  • Node 26 disappears: workarounds:nodeDockerVersioning switches the node image to Node versioning, which counts only LTS versions as stable.

The line about the limit appears in both versions. config:recommended does not change prHourlyLimit.

Save your progress? Sign up for free

Drill 4: Merge the onboarding – the brake kicks in

You merge PR #1 via the API and let Renovate run with a debug log.

curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" -X POST "$API/pulls/1/merge" \
  --json '{"Do":"merge","delete_branch_after_merge":true}'
curl -s -u "$ADMIN" "$API/raw/renovate.json"
LOG_LEVEL=debug renovate shop/shop-api > lauf3.log 2>&1
grep -E '^ ?INFO: (Branch|PR) created' lauf3.log
curl -s -u "$ADMIN" "$API/pulls" | jq -r '.[] | "#\(.number) \(.title)"'
curl -s -u "$ADMIN" "$API/issues?type=issues" | jq -r '.[] | "#\(.number) \(.title)"'

Expected:

200
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"]
}
 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)
R01_PRS1

Seven updates announced, two PRs received. The evidence is in the debug log:

grep 'Hourly PRs limit reached' lauf3.log | grep -oE 'branch=[^)]+'
grep -m1 'Hourly PR Count: 2' lauf3.log | cut -c1-88

Expected:

branch=renovate/node-20.x
branch=renovate/actions-checkout-7.x
branch=renovate/actions-setup-node-7.x
branch=renovate/express-5.x
branch=renovate/node-24.x
DEBUG: Open PR Count: 2, Existing Branch Count: 2, Hourly PR Count: 2, Hourly Commit Cou

The limit applies per hour, not per run. An immediate second run brings nothing new:

LOG_LEVEL=debug renovate shop/shop-api > lauf4.log 2>&1
echo "neu: $(grep -c 'PR created' lauf4.log)," \
  "gebremst: $(grep -c 'Hourly PRs limit reached' lauf4.log)"
jq '.definitions.prHourlyLimit | {default, description}' \
  ~/renovate-lab/tools/node_modules/renovate/renovate-schema.json

Expected:

neu: 0, gebremst: 5
{
  "default": 2,
  "description": "Rate limit PRs to maximum x created per hour. 0 means no limit.\nSee
}

(neu means new, gebremst means throttled.) The default of 2 applies with and without config:recommended. Day 4 shows how to set it deliberately.

Save your progress? Sign up for free

Drill 5: Take an update PR apart

PR #2 is a typical Renovate PR. First the metadata and the diff:

curl -s -u "$ADMIN" "$API/pulls/2" | jq -r .title
curl -s -u "$ADMIN" "$API/pulls/2" | jq -r .head.ref
curl -s -u "$ADMIN" "$API/pulls/2" | jq -r .user.login
curl -s -u "$ADMIN" "$API/pulls/2/commits" | jq -r '.[].commit.message'
curl -s -u "$ADMIN" "$API/pulls/2/files" | jq -r '.[] | "\(.filename) +\(.additions)"'
curl -s -u "$ADMIN" "$API/pulls/2.diff" | grep -E '^[-+] .*"express"'

Expected:

R01_PR2
-        "express": "4.18.2",
+        "express": "4.22.3",
-    "express": "4.18.2",
+    "express": "4.22.3",
  • The branch name follows branchPrefix + branchTopic: renovate/ + package name + major + .x. A later express 4.23 lands in the same branch.
  • Title and commit message are identical. Renovate recognizes its PRs by branch and title.
  • The diff contains the lockfile. Renovate ran npm install for you, including all transitive changes.

Now the text:

curl -s -u "$ADMIN" "$API/issues/2" | jq -r .body > pr2.md
grep -m1 '^| \[express' pr2.md | grep -oE '`4[^`]*` → `[^`]*`'
grep -E '^(### [RC]|📅|🚦|♻|🔕)' pr2.md | cut -c1-88
grep -c '^### \[`v' pr2.md

Expected:

`4.18.2` → `4.22.3`
### Release Notes
### Configuration
📅 **Schedule**: (UTC)
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
12

The table at the top shows the package, the version jump, and the “Age” and “Confidence” badges (from mergeConfidence:age-confidence-badges). Below it follow the release notes of all twelve skipped versions, here including the CVE fix in 4.22.0. The “Configuration” section summarizes schedule, automerge, rebase behavior, and ignoring. These are exactly the knobs of Days 4 and 5.

Tip: Renovate fetches release notes from github.com. Without RENOVATE_GITHUB_COM_TOKEN the section is missing or incomplete.

Save your progress? Sign up for free

Drill 6: The Dependency Dashboard

config:recommended includes :dependencyDashboard, hence issue #4. It is the remote control for Renovate:

curl -s -u "$ADMIN" "$API/issues/4" | jq -r .body > dashboard.md
grep -E '^## |^ - \[' dashboard.md | cut -c1-88
grep -E '^ - `' dashboard.md

Expected:

## Rate-Limited
 - [ ] <!-- unlimit-branch=renovate/node-20.x -->Update Node.js to v20.20.2
 - [ ] <!-- unlimit-branch=renovate/actions-checkout-7.x -->Update actions/checkout acti
 - [ ] <!-- unlimit-branch=renovate/actions-setup-node-7.x -->Update actions/setup-node
 - [ ] <!-- unlimit-branch=renovate/express-5.x -->Update dependency express to v5
 - [ ] <!-- unlimit-branch=renovate/node-24.x -->Update dependency node to v24
 - [ ] <!-- create-all-rate-limited-prs -->🔐 **Create all rate-limited PRs at once** 🔐
## Open
 - [ ] <!-- rebase-branch=renovate/express-4.x -->[Update dependency express to v4.22.3]
 - [ ] <!-- rebase-branch=renovate/prettier-3.x -->[Update dependency prettier to v3.9.1
 - [ ] <!-- rebase-all-open-prs -->**Click on this checkbox to rebase all open PRs at on
## Detected Dependencies
 - `node 20.11.0-alpine` → [Updates: `20.20.2-alpine`, `24.21.0-alpine`]
 - `actions/checkout v3` → [Updates: `v7`]
 - `actions/setup-node v3` → [Updates: `v7`]
 - `node 20` → [Updates: `24`]
 - `express 4.18.2` → [Updates: `4.22.3`, `5.3.0`]
 - `lodash ^4.17.20`
 - `prettier 3.0.0` → [Updates: `3.9.10`]

Every checkbox carries a marker in an HTML comment. On the next run Renovate reads which ones are ticked. In the browser you click; via the API you set the x yourself and send the text back – jq -Rs wraps the file as a JSON string in body:

sed -i '' 's/- \[ \] <!-- create-all/- [x] <!-- create-all/' dashboard.md
jq -Rs '{body: .}' dashboard.md > dashboard.json
curl -s -u "$ADMIN" -X PATCH --json @dashboard.json "$API/issues/4" | jq -r .number
renovate shop/shop-api 2>&1 | grep -c 'PR created'
curl -s -u "$ADMIN" "$API/pulls" | jq -r '.[] | "#\(.number) \(.title)"'

Expected:

R01_PRS2

A Dashboard checkbox is a manual request and bypasses the hourly limit. express has two PRs: #2 stays in major 4, #8 jumps to 5. That is because of separateMajorMinor (default true). A breaking change should never sit in the same PR as a harmless patch.

curl -s -u "$ADMIN" "$API/issues/8" | jq -r .body | grep -m1 '^| \[express'
curl -s -u "$ADMIN" "$API/pulls/8/files" | jq -r '.[] | "\(.filename) +\(.additions)"'

Expected:

R01_PR8

Save your progress? Sign up for free

Drill 7: Closing means ignoring

index.js should stay on express 4 for now. You close PR #8 without merging:

curl -s -u "$ADMIN" -X PATCH --json '{"state":"closed"}' "$API/pulls/8" | jq -r .state
renovate shop/shop-api 2>&1 | grep -E 'Comment added'
curl -s -u "$ADMIN" "$API/issues/8/comments" | jq -r '.[].user.login'
curl -s -u "$ADMIN" "$API/issues/8/comments" | jq -r '.[].body' | fold -s -w 88
curl -s -u "$ADMIN" "$API/branches" | jq -r '.[].name' | grep express

Expected:

closed
 INFO: Comment added (repository=shop/shop-api, branch=renovate/express-5.x)
renovate-bot
### Renovate Ignore Notification

Because you closed this PR without merging, Renovate will ignore this update. You will
not get PRs for *any* future `5.x` releases. But if you manually upgrade to `5.x` then
Renovate will re-enable `minor` and `patch` updates automatically.

If you accidentally closed this PR, or if you changed your mind: rename this PR to get
a fresh replacement PR.
renovate/express-4.x

Renovate comments on the PR and deletes the branch renovate/express-5.x. What is ignored is the entire major line 5.x, not just 5.3.0. Does it stay that way?

LOG_LEVEL=debug renovate shop/shop-api 2>&1 | grep -E 'PR created|Closed PR #'
curl -s -u "$ADMIN" "$API/issues/4" | jq -r .body > dashboard.md
grep -A1 '^## PR Closed' dashboard.md | cut -c1-88

Expected:

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

Before every branch, Renovate looks for a closed PR with the same title. If it finds one, it skips the update. In the Dashboard it now appears under “PR Closed (Blocked)”.

Warning: A closed PR is a silent decision that is not documented anywhere in the config. Permanent exceptions belong in renovate.json (ignoreDeps, allowedVersions, Day 6).

Save your progress? Sign up for free

Drill 8: Merge and clean up

Now the opposite case: you merge PR #2, this time without deleting the branch.

curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" -X POST "$API/pulls/2/merge" \
  --json '{"Do":"merge"}'
curl -s -u "$ADMIN" "$API/raw/package.json" | jq -r .dependencies.express
curl -s -u "$ADMIN" "$API/branches" | jq -r '.[].name' | grep -c renovate/
renovate shop/shop-api 2>&1 | grep -E 'orphan|PR created'
curl -s -u "$ADMIN" "$API/branches" | jq -r '.[].name' | grep -c renovate/
curl -s -u "$ADMIN" "$API/issues/4" | jq -r .body | grep express | cut -c1-88

Expected:

200
4.22.3
6
 INFO: Deleting orphan branch (repository=shop/shop-api, branch=renovate/express-4.x)
5
 - [ ] <!-- recreate-branch=renovate/express-5.x -->[Update dependency express to v5](pu
 - `express 4.22.3` → [Updates: `5.3.0`]

For renovate/express-4.x there is no open update anymore. The branch is orphaned, and Renovate deletes it (pruneStaleBranches, default true). The Dashboard now shows express at 4.22.3 with 5.3.0 as the only update, still blocked. Renovate checked the other PRs and left them alone: they have no conflict with the new main (with rebaseWhen auto it then rebases only on conflict).

Save your progress? Sign up for free

Checkpoint

renovate.json on main extends config:recommended, PR #1 is merged:

cd ~/renovate-lab/tag01
API="$FORGEJO/api/v1/repos/shop/shop-api"
curl -s -u "$ADMIN" "$API/raw/renovate.json" | jq -c .extends
curl -s -u "$ADMIN" "$API/pulls/1" | jq .merged

Expected:

["config:recommended"]
true

The Dependency Dashboard is open, express is at 4.22:

curl -s -u "$ADMIN" "$API/issues?type=issues" | jq -r '.[].title'
curl -s -u "$ADMIN" "$API/raw/package.json" | jq -r .dependencies.express

Expected (the minor version of express may be newer for you):

Dependency Dashboard
4.22.3

The branch renovate/express-4.x is gone, PR #8 carries the ignore comment:

curl -s -u "$ADMIN" "$API/branches" | jq -r '.[].name' | grep -c express-4
curl -s -u "$ADMIN" "$API/issues/8/comments" | jq -r '.[].body' | head -1

Expected:

0
### Renovate Ignore Notification

Challenge

The team has changed its mind: express 5 should come after all. Bring back the major update PR without changing renovate.json and without waiting an hour.

Hint: The Dashboard has a separate checkbox for blocked updates.

Solution

cd ~/renovate-lab/tag01
API="$FORGEJO/api/v1/repos/shop/shop-api"
curl -s -u "$ADMIN" "$API/issues/4" | jq -r .body > dashboard.md
sed -i '' 's/- \[ \] <!-- recreate-branch/- [x] <!-- recreate-branch/' dashboard.md
jq -Rs '{body: .}' dashboard.md > dashboard.json
curl -s -u "$ADMIN" -X PATCH --json @dashboard.json "$API/issues/4" | jq -r .number
LOG_LEVEL=debug renovate shop/shop-api 2>&1 \
  | grep -E 'dependencyDashboardCheck=recreate|PR created' | cut -c1-88
curl -s -u "$ADMIN" "$API/pulls?state=all" \
  | jq -r '.[] | "#\(.number) \(.state) \(.title)"' | grep express

Expected:

DEBUG: dependencyDashboardCheck=recreate (repository=shop/shop-api, branch=renovate/expr
 INFO: PR created (repository=shop/shop-api, branch=renovate/express-5.x)
R01_CH

Renovate creates a new PR #10; #8 stays closed. The route from the ignore comment works too: if you rename PR #8 (e.g. to the title Update dependency express to v5 - abgelehnt, “rejected”), the title no longer matches and the block is lifted. But then prHourlyLimit applies again. In the test, the update ended up under “Rate-Limited” and additionally needed the tick at unlimit-branch=renovate/express-5.x.

Save your progress? Sign up for free

Enterprise Note

  • Set onboardingConfig globally, e.g. with extends pointing to an org preset (Day 9, Day 11). Otherwise every repo gets only $schema.
  • prHourlyLimit and prConcurrentLimit (default 10) determine the CI load. With hundreds of repos, calculate per run, not per repo (Day 4).
  • Closed PRs are invisible decisions. Establish that rejections belong in the config as packageRules and that the Dashboard is mandatory.
  • Branch protection must allow the bot to push to renovate/*, but not to main. The bot needs write access, not admin rights (Day 12).
  • For release notes from github.com, the service needs a dedicated token without scopes as a Secret (RENOVATE_GITHUB_COM_TOKEN), never a personal one.