Day 0: The Training Ground
Goal: Set up Node 24, the Renovate CLI, and a local Forgejo with a bot user and a demo repo, and let Renovate loose on
shop/shop-apifor the first time without any risk. · Duration: approx. 45 min · Prerequisite: none
Briefing
- Renovate runs as a CLI on your laptop (Node 24, installed locally), not as an app in the cloud.
- The platform is Forgejo in Docker at
http://127.0.0.1:3000. That is where Renovate creates real branches, PRs, and issues – without a GitHub account. - Renovate works as its own user
renovate-botwith a token. You yourself arelab-adminand play the human who merges PRs. - You set up Forgejo, the two users, the token, and the demo repo with individual commands (Drills 4 and 5).
Laptop Docker
┌───────────────────────────────┐ ┌──────────────────────────────┐
│ ~/renovate-lab/ │ REST API │ Container "forgejo" │
│ tools/ renovate 44.153.1 │ ─────────► │ http://127.0.0.1:3000 │
│ setup/ env.sh gitconfig │ git push │ Org shop │
│ code/ companion code │ ◄────────► │ Repo shop/shop-api │
│ Node 24, git, jq, curl │ │ lab-admin, renovate-bot │
└───────────────────────────────┘ └──────────────────────────────┘
│ Lookups (npm, Docker Hub, GitHub)
▼
Internet
Drill 1: Check your tools
docker version --format '{{.Server.Version}}'
node -v
npm -v
git --version
jq --version
curl --version | head -1 | cut -d' ' -f1-2
gh --version | head -1 # optionalExpected (may differ depending on version):
29.5.2
v24.21.0
11.19.0
git version 2.56.0
jq-1.8.2
curl 8.7.1
gh version 2.102.0 (2026-09-30)
You only need gh for the optional GitHub token in Drill
7. If node -v shows something other than
v24.x, continue with Drill 2, otherwise skip it.
Save your progress? Sign up for free
Drill 2: Provide Node 24
Renovate 44 requires Node ^24.11.0 (field
engines in its package.json). Node 25 or 26 is
too new, Node 22 too old. With mise you pin the version for the lab
directory only:
mkdir -p ~/renovate-lab && cd ~/renovate-lab
mise use node@24 # writes mise.toml, applies in ~/renovate-lab and below
node -vExpected (may differ depending on version):
v24.21.0
Without mise: brew install node@24 and
export PATH="$(brew --prefix node@24)/bin:$PATH" (keg-only,
otherwise it does not end up in your PATH). The checkpoint
shows which Node is active in your terminal.
And with the wrong Node? This is what the run from Drill 6 looks like under Node v25.3.0:
WARN: RE2 not usable, falling back to RegExp
...
ERROR: Unsupported node environment detected. Please update your node version.
"versions": {
"node": "25.3.0",
...
INFO: Renovate is exiting with a non-zero code due to the following logged errors
Renovate runs to the end but finishes with exit code 1 – in a pipeline every run is red. The native regex module RE2 is built for Node 24 and is lost as well.
Save your progress? Sign up for free
Drill 3: Working directory, companion code, and Renovate CLI
You fetch the companion code once from GitHub into
~/renovate-lab/code, and copy its setup folder
to ~/renovate-lab/setup:
mkdir -p ~/renovate-lab/tag00 && cd ~/renovate-lab
git clone https://github.com/thomaszachmann/renovate-zum-anfassen.git \
~/renovate-lab/code
cp -R ~/renovate-lab/code/setup ~/renovate-lab/setup
ls ~/renovate-lab/setup
ls ~/renovate-lab/setup/shop-apiExpected:
Cloning into '…/renovate-lab/code'...
env.sh shop-api
Dockerfile index.js package-lock.json package.json README.md
You install Renovate locally in ~/renovate-lab/tools,
not globally – the version stays pinned at 44.153.1:
npm install --prefix ~/renovate-lab/tools [email protected]Expected (shortened, may differ depending on version):
npm warn deprecated [email protected]: This module is not supported, and leaks memory. …
...
added 618 packages in 25s
...
npm warn install-scripts 4 packages have install scripts not yet covered by …
The warnings are harmless; RE2 comes along as a prebuilt binary. The
installation takes up about 350 MB. env.sh only sets
variables – everything Renovate, curl, and git
need:
grep -v '^#' ~/renovate-lab/setup/env.shExpected:
LAB="${LAB:-$HOME/renovate-lab}"
export PATH="$LAB/tools/node_modules/.bin:$PATH"
export FORGEJO_PORT="${FORGEJO_PORT:-3000}"
export FORGEJO="http://127.0.0.1:$FORGEJO_PORT"
export ADMIN="lab-admin:lab-admin-pw-123" # Lab-Wert!
export RENOVATE_PLATFORM=forgejo
export RENOVATE_ENDPOINT="$FORGEJO/api/v1"
export RENOVATE_TOKEN="$(cat "$LAB/setup/bot-token" 2>/dev/null)"
export RENOVATE_GIT_AUTHOR="Renovate Bot <[email protected]>"
export LOG_LEVEL="${LOG_LEVEL:-info}"
export GIT_CONFIG_GLOBAL="$LAB/setup/gitconfig"
GIT_CONFIG_GLOBAL points git to a separate
configuration file in the lab (Drill 5); your ~/.gitconfig
stays untouched. Every Renovate option can be set as
RENOVATE_<OPTION> (platform →
RENOVATE_PLATFORM). Renovate reads LOG_LEVEL
and LOG_FORMAT without a prefix. Load it:
source ~/renovate-lab/setup/env.sh
renovate --version
renovate-config-validator --help | head -1Expected:
44.153.1
Usage: renovate-config-validator [options] [config-files...]
RENOVATE_TOKEN is still empty; the
bot-token file is only created in the next drill.
Save your progress? Sign up for free
Drill 4: Start Forgejo
The settings for Forgejo live in a file. It turns off the
installation wizard, uses SQLite, and allows creating a repo simply with
git push (ENABLE_PUSH_CREATE_ORG):
cat > ~/renovate-lab/setup/forgejo.env <<'EOF'
# forgejo.env – settings for the lab container (Forgejo reads FORGEJO__section__key)
FORGEJO__security__INSTALL_LOCK=true
FORGEJO__server__ROOT_URL=http://127.0.0.1:3000/
FORGEJO__database__DB_TYPE=sqlite3
FORGEJO__service__DISABLE_REGISTRATION=true
FORGEJO__repository__DEFAULT_BRANCH=main
FORGEJO__repository__ENABLE_PUSH_CREATE_ORG=true
FORGEJO__repository__DEFAULT_PUSH_CREATE_PRIVATE=false
EOF
docker run -d --name forgejo -p 127.0.0.1:3000:3000 \
-v forgejo-data:/var/lib/gitea -v forgejo-conf:/etc/gitea \
--env-file ~/renovate-lab/setup/forgejo.env \
codeberg.org/forgejo/forgejo:16.0.6-rootless
docker ps --filter name=forgejo --format '{{.Names}} {{.Status}} {{.Ports}}'Expected (the first time, Docker pulls the image first):
66771dfb12752c3a29a6bfae9be8848b3314abed55a9437e67601c38903e9baa
forgejo Up Less than a second 2222/tcp, 127.0.0.1:3000->3000/tcp
Forgejo needs a few seconds. curl --retry asks up to 30
times, once per second, until the API responds:
curl -s --retry 30 --retry-all-errors --retry-delay 1 \
http://127.0.0.1:3000/api/v1/version; echoExpected:
{"version":"16.0.6+gitea-1.22.0"}
You create the users with the admin tool inside the container –
yourself as lab-admin, the bot as a regular user:
docker exec forgejo forgejo admin user create --admin --username lab-admin \
--password lab-admin-pw-123 --email [email protected] --must-change-password=false
docker exec forgejo forgejo admin user create --username renovate-bot \
--password lab-bot-pw-123 --email [email protected] --must-change-password=falseExpected:
New user 'lab-admin' has been successfully created!
New user 'renovate-bot' has been successfully created!
The bot gets a token. --raw prints only the token, and
the file is readable only by you:
docker exec forgejo forgejo admin user generate-access-token \
--username renovate-bot --token-name renovate --raw \
--scopes write:repository,write:issue,read:user,read:organization,read:package \
> ~/renovate-lab/setup/bot-token
chmod 600 ~/renovate-lab/setup/bot-token
wc -c < ~/renovate-lab/setup/bot-tokenExpected:
41
Now there is a token. Reload env.sh and ask Forgejo who
you are as the bot:
source ~/renovate-lab/setup/env.sh
curl -s "$FORGEJO/api/v1/version"; echo
curl -s -H "Authorization: token $RENOVATE_TOKEN" "$FORGEJO/api/v1/user" \
| jq -c '{login, is_admin}'Expected:
{"version":"16.0.6+gitea-1.22.0"}
{"login":"renovate-bot","is_admin":false}
The token scopes (write:repository,
write:issue, read:user,
read:organization, read:package) are enough
for branches, PRs, issues, and presets. You can reach the web UI at
http://127.0.0.1:3000 as lab-admin /
lab-admin-pw-123. Everything you click there, the book also
does with curl or git.
Security: The passwords and the token are lab values. The
bot-tokenfile never belongs in a Git repo.
Save your progress? Sign up for free
Drill 5: Organization, bot team, and demo repo
You create the organization shop via the API. A team
bots with write access to all repos of the
organization saves you from adding the bot to every new repo
individually:
curl -s -u "$ADMIN" -X POST "$FORGEJO/api/v1/orgs" \
-H 'Content-Type: application/json' -d '{"username":"shop"}' | jq -r .username
curl -s -u "$ADMIN" -X POST "$FORGEJO/api/v1/orgs/shop/teams" \
-H 'Content-Type: application/json' -d '{"name":"bots","permission":"write",
"includes_all_repositories":true,"units":["repo.code","repo.issues","repo.pulls"]}' \
| jq -c '{id, name, permission}'Expected:
shop
{"id":2,"name":"bots","permission":"write"}
You need the team’s id to add the bot:
curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" \
-X PUT "$FORGEJO/api/v1/teams/2/members/renovate-bot"Expected:
204
git gets its own lab configuration
(GIT_CONFIG_GLOBAL from env.sh): who commits
and how forgejo: is resolved as an address – with the lab
credentials:
cat > ~/renovate-lab/setup/gitconfig <<'EOF'
# gitconfig – lab only (GIT_CONFIG_GLOBAL), credentials are lab values
[user]
name = Lab Admin
email = [email protected]
[url "http://lab-admin:[email protected]:3000/"]
insteadOf = forgejo:
EOF
git config --get user.nameExpected:
Lab Admin
Now the demo repo. You turn setup/shop-api into a local
Git repo and push it. Because Forgejo allows push-to-create,
shop/shop-api is created automatically:
cp -R ~/renovate-lab/setup/shop-api ~/renovate-lab/shop-api
cd ~/renovate-lab/shop-api
git init -q -b main
git add -A
git commit -qm "Initialer Stand"
git push -q forgejo:shop/shop-api.git mainExpected: no output, -q keeps git
quiet.
~/renovate-lab/shop-api remains the starting state for
all days – you do not keep working there. Is the bot allowed to
write?
curl -s -H "Authorization: token $RENOVATE_TOKEN" \
"$FORGEJO/api/v1/repos/shop/shop-api" | jq -c .permissionsExpected:
{"admin":false,"push":true,"pull":true}
What is in the repo?
curl -s -u "$ADMIN" "$FORGEJO/api/v1/repos/shop/shop-api/contents" \
| jq -r '[.[].path] | join(" ")'
curl -s -u "$ADMIN" "$FORGEJO/api/v1/repos/shop/shop-api/raw/package.json" \
| jq -c '.dependencies, .devDependencies'Expected:
.github .gitignore Dockerfile README.md index.js package-lock.json package.json
{"express":"4.18.2","lodash":"^4.17.20"}
{"prettier":"3.0.0"}
All deliberately outdated: plus FROM node:20.11.0-alpine
in the Dockerfile and actions/checkout@v3 in
.github/workflows/ci.yml. Food for Renovate.
Save your progress? Sign up for free
Drill 6: First contact – read only
Renovate knows three dry-run modes. None of them writes anything to Forgejo:
| Mode | What Renovate does | Network |
|---|---|---|
extract |
clones the repo, finds dependencies | Forgejo only |
lookup |
additionally: looks for new versions | Forgejo + registries |
full |
additionally: plans branches and PRs | Forgejo + registries |
cd ~/renovate-lab/tag00
renovate --dry-run=extract shop/shop-apiExpected (shortened):
INFO: Renovate started
...
INFO: DRY-RUN: Would commit files to onboarding branch (repository=shop/shop-api)
INFO: Dependency extraction complete (repository=shop/shop-api, baseBranch=main)
"stats": {
"managers": {
"dockerfile": {"fileCount": 1, "depCount": 1},
"github-actions": {"fileCount": 1, "depCount": 4},
"npm": {"fileCount": 1, "depCount": 3}
},
"total": {"fileCount": 3, "depCount": 8}
}
INFO: Extracted dependencies (repository=shop/shop-api)
...
"depName": "express",
"currentValue": "4.18.2",
"datasource": "npm",
...
INFO: Repository finished (repository=shop/shop-api)
Three managers (dockerfile,
github-actions, npm) found eight dependencies.
Each has a datasource that Renovate later asks for new
versions. github-actions counts four because
runs-on: ubuntu-latest and node-version: 20
also count as dependencies. Details follow on Day 3.
Would commit files to onboarding branch shows: the repo
is not “onboarded” yet. A real run would first open an onboarding PR
(Day 1). With LOG_LEVEL=debug you see how Renovate reaches
this conclusion:
LOG_LEVEL=debug renovate --dry-run=extract shop/shop-api 2>&1 \
| grep -E 'onboarded|Found [0-9]+ package|Would' | head -3Expected:
DEBUG: Repo is not onboarded (repository=shop/shop-api)
DEBUG: Found 3 package file(s) (repository=shop/shop-api)
INFO: DRY-RUN: Would commit files to onboarding branch (repository=shop/shop-api)
Check that really nothing was written:
for e in branches pulls issues; do
echo "$e: $(curl -s -u "$ADMIN" \
"$FORGEJO/api/v1/repos/shop/shop-api/$e?state=all" | jq length)"
doneExpected:
branches: 1
pulls: 0
issues: 0
The one branch is main. No
renovate/configure, no PR, no issue.
Save your progress? Sign up for free
Drill 7: A foretaste – which updates would there be?
A lookup on a repo that is not onboarded stops at
onboarding. To look ahead, you turn off onboarding for this one run
(--onboarding=false --require-config=optional) and let
Renovate log in JSON format. The list of updates appears only in the
debug log:
cd ~/renovate-lab/tag00
LOG_LEVEL=debug LOG_FORMAT=json \
renovate --dry-run=lookup --onboarding=false --require-config=optional \
shop/shop-api > lookup.json
jq -r 'select(.msg == "packageFiles with updates") | .config[][].deps[]
| [.depName, .currentValue, "->", (.updates[].newValue), .skipReason]
| map(values) | join(" ")' lookup.jsonExpected (without a GitHub token):
node 20.11.0-alpine -> 20.20.2-alpine 26.11.1-alpine
actions/checkout v3 -> github-token-required
actions/setup-node v3 -> github-token-required
ubuntu latest -> invalid-version
node 20 -> github-token-required
express 4.18.2 -> 4.22.3 5.3.0
lodash ^4.17.20 ->
prettier 3.0.0 -> 3.9.10
The target versions come from the test run; yours will be newer. For
each dependency there is usually one minor and one major update
(express 4.22.3 and 5.3.0). lodash gets none:
the range ^4.17.20 already covers the version in the
lockfile.
Three entries are skipped with github-token-required,
and the log also contains the warning
GitHub token is required for some dependencies. Renovate
looks up GitHub Actions and Node versions on github.com, and that
requires a token. If you are logged in with gh, one line is
enough; then repeat the lookup:
export RENOVATE_GITHUB_COM_TOKEN=$(gh auth token)
LOG_LEVEL=debug LOG_FORMAT=json \
renovate --dry-run=lookup --onboarding=false --require-config=optional \
shop/shop-api > lookup.json
jq -r 'select(.msg == "packageFiles with updates") | .config[][].deps[]
| [.depName, .currentValue, "->", (.updates[].newValue), .skipReason]
| map(values) | join(" ")' lookup.json | head -5Expected:
node 20.11.0-alpine -> 20.20.2-alpine 26.11.1-alpine
actions/checkout v3 -> v7
actions/setup-node v3 -> v7
ubuntu latest -> invalid-version
node 20 -> 24
Actions and the Node version now have targets.
ubuntu-latest stays skipped: latest is not a
version Renovate can compare. Without a token, npm and Docker updates
still work; only GitHub-based dependencies and release notes are
missing.
Security:
gh auth tokenhas the permissions of yourghlogin. A fine-grained token without repository permissions is better. The token lives only in the environment, never in a file under~/renovate-lab.
Save your progress? Sign up for free
Drill 8: Reset and teardown
Many days need a fresh state of shop/shop-api. You
delete the repo along with its branches, PRs, and issues and push the
starting state again. Users, token, team, and other repos remain:
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 mainExpected:
204
git -C works in the given folder without you changing
into it. After a Docker or laptop restart the container is stopped, but
the data is still in the volumes:
docker stop forgejo
docker start forgejo
curl -s --retry 30 --retry-all-errors --retry-delay 1 \
http://127.0.0.1:3000/api/v1/version; echoExpected:
forgejo
forgejo
{"version":"16.0.6+gitea-1.22.0"}
Complete rebuild with a fresh database: delete the container and
volumes – and the token file, because the old token belongs to the old
database. Then do Drills 4 and 5 again; for the demo repo you only need
the git push, because ~/renovate-lab/shop-api
already exists. Finally, reload env.sh:
docker rm -f forgejo
docker volume rm forgejo-data forgejo-conf
rm ~/renovate-lab/setup/bot-tokenExpected:
forgejo
forgejo-data
forgejo-conf
Warning: Without a new
source ~/renovate-lab/setup/env.sh, your shell still holds the old value ofRENOVATE_TOKEN, and Renovate reports an invalid token.
At the very end of the book, you clean up like this:
docker rm -f forgejo,
docker volume rm forgejo-data forgejo-conf,
rm -rf ~/renovate-lab.
Save your progress? Sign up for free
Checkpoint
Renovate in the right version on Node 24, env.sh
loaded:
source ~/renovate-lab/setup/env.sh
node -v
renovate --version
echo "$RENOVATE_PLATFORM"Expected (Node patch version differs):
v24.22.2
44.153.1
forgejo
Forgejo is running, and the token belongs to the bot:
docker ps --filter name=forgejo --format '{{.Names}} {{.Status}}'
curl -s -H "Authorization: token $RENOVATE_TOKEN" "$FORGEJO/api/v1/user" | jq -r .loginExpected (time differs):
forgejo Up 19 seconds
renovate-bot
shop/shop-api exists, the bot may write, and there are
no PRs yet:
curl -s -H "Authorization: token $RENOVATE_TOKEN" \
"$FORGEJO/api/v1/repos/shop/shop-api" | jq .permissions.push
curl -s -u "$ADMIN" "$FORGEJO/api/v1/repos/shop/shop-api/pulls?state=all" | jq lengthExpected:
true
0
Challenge
From Day 1 on, you constantly want to know what Renovate has created.
Write ~/renovate-lab/tag00/status.sh [org/repo] that lists
the open PRs and issues of a repo (default shop/shop-api)
with number, title, and author – via the API only, without a
browser.
Hint: In Forgejo a PR is also an issue; the
/issues endpoint filters with type=pulls or
type=issues.
Solution
The file is also available at
~/renovate-lab/code/tag00/status.sh.
cat > ~/renovate-lab/tag00/status.sh <<'EOF'
#!/usr/bin/env bash
# status.sh [org/repo] – lists open PRs and issues (default: shop/shop-api)
set -euo pipefail
source "${LAB:-$HOME/renovate-lab}/setup/env.sh"
REPO="${1:-shop/shop-api}"
for kind in pulls issues; do
json=$(curl -sf -u "$ADMIN" \
"$FORGEJO/api/v1/repos/$REPO/issues?state=open&type=$kind")
echo "== $kind: $(jq length <<<"$json") offen"
jq -r '.[] | "#\(.number) \(.title) (\(.user.login))"' <<<"$json"
done
EOF
chmod +x ~/renovate-lab/tag00/status.shTo try it out, you create an issue and a PR as admin, take a look, and reset the repo again:
R="$FORGEJO/api/v1/repos/shop/shop-api"
curl -s -u "$ADMIN" -X POST "$R/issues" -H 'Content-Type: application/json' \
-d '{"title":"Testissue vom Admin"}' | jq -r .number
cd ~/renovate-lab/tag00
git clone -q forgejo:shop/shop-api.git test-pr
cd test-pr
git switch -q -c test
echo hi > x.txt
git add x.txt
git commit -qm x
git push -q origin test
curl -s -u "$ADMIN" -X POST "$R/pulls" -H 'Content-Type: application/json' \
-d '{"title":"Test-PR","head":"test","base":"main"}' | jq -r .number
~/renovate-lab/tag00/status.sh
cd ~/renovate-lab/tag00
rm -rf test-pr
curl -s -o /dev/null -w '%{http_code}\n' -u "$ADMIN" -X DELETE "$R"
git -C ~/renovate-lab/shop-api push -q forgejo:shop/shop-api.git mainExpected (shortened):
1
remote: Create a new pull request for 'test':
…
2
== pulls: 1 offen
#2 Test-PR (lab-admin)
== issues: 1 offen
#1 Testissue vom Admin (lab-admin)
204
Save your progress? Sign up for free
Enterprise Note
- There, Renovate runs as a scheduled job (Day 10); Node and Renovate versions are pinned as they are here.
- The bot is a technical account with minimal permissions (Day 12); its token lives in the secret store.
- Behind a proxy or without internet access, Renovate needs access to
registries or internal mirrors; otherwise only
extractremains. - For github.com lookups: a dedicated fine-grained token without repo permissions, never the personal token of a human.
- At a customer site,
--dry-run=lookupshows a repo’s update backlog without a single PR.