Skip to content
Hands-on IT IT Drills

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-api for 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-bot with a token. You yourself are lab-admin and 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        # optional

Expected (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 -v

Expected (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-api

Expected:

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.sh

Expected:

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 -1

Expected:

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; echo

Expected:

{"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=false

Expected:

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-token

Expected:

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-token file 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.name

Expected:

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 main

Expected: 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 .permissions

Expected:

{"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-api

Expected (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 -3

Expected:

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)"
done

Expected:

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.json

Expected (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 -5

Expected:

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 token has the permissions of your gh login. 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 main

Expected:

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; echo

Expected:

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-token

Expected:

forgejo
forgejo-data
forgejo-conf

Warning: Without a new source ~/renovate-lab/setup/env.sh, your shell still holds the old value of RENOVATE_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 .login

Expected (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 length

Expected:

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.sh

To 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 main

Expected (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 extract remains.
  • 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=lookup shows a repo’s update backlog without a single PR.