Day 1: The First Run
Goal: You bring Renovate into
shop/shop-apivia 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
$schemaintorenovate.json, noconfig: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/tag01Expected:
204
Warning: Without
RENOVATE_GITHUB_COM_TOKEN, Renovate skipsactions/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-88Expected:
### 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-88Expected:
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-versionin the workflow end up in one PR for v24. - Node 26 disappears:
workarounds:nodeDockerVersioningswitches thenodeimage 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-88Expected:
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.jsonExpected:
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 installfor 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.mdExpected:
`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_TOKENthe 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.mdExpected:
## 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 expressExpected:
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-88Expected:
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-88Expected:
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 .mergedExpected:
["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.expressExpected (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 -1Expected:
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 expressExpected:
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
onboardingConfigglobally, e.g. withextendspointing to an org preset (Day 9, Day 11). Otherwise every repo gets only$schema. prHourlyLimitandprConcurrentLimit(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
packageRulesand that the Dashboard is mandatory. - Branch protection must allow the bot to push to
renovate/*, but not tomain. 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.