RenovateBot
8 min read
RenovateBot is a powerful open-source dependency update tool. It scans repository files, detects outdated dependencies, and creates pull requests to keep packages, lock files, container images, infrastructure manifests, and other versioned references up to date.
Renovate is especially useful because it treats dependency updates as an ongoing lifecycle instead of a one-time cleanup: discover dependencies, propose safe changes, let CI validate them, apply grouping/scheduling rules, and gradually automate low-risk updates.
What Renovate Can Update
Renovate supports many built-in managers, including package managers, CI files, infrastructure files, and container manifests. Common examples:
• Application dependencies: npm, pnpm, yarn, pip, poetry, uv, go, cargo, maven, gradle, composer, etc.
• Lock files and artifact updates, such as package-lock.json, pnpm-lock.yaml, Cargo.lock, flake.lock, .terraform.lock.hcl, and Chart.lock.
• Containers in Dockerfile, Compose files, Kubernetes manifests, Helm values, GitHub Actions, GitLab CI, and other deployment files.
• Infrastructure dependencies such as Terraform providers and modules.
• Custom formats through customManagers, most commonly custom.regex or custom.jsonata.
Setup
Create a bot user for Renovate on your preferred Git forge and generate a Personal Access Token (PAT) or use the platform-native Renovate app if available.
Then add this user as a member to your repositories. Renovate can be configured per repository through a config file such as:
• renovate.json
• renovate.jsonc
• .github/renovate.json
• .gitlab/renovate.json
• .renovaterc
A minimal repository config:
json
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"]
}
config:recommended is the normal baseline preset and includes useful defaults, including the Dependency Dashboard.
Dependency Dashboard
The Dependency Dashboard is an issue created by Renovate that acts as a control panel for dependency updates.
It can show:
• pending, open, closed, ignored, or errored updates
• updates blocked by schedules or PR limits
• deprecated or abandoned dependency warnings
• update checkboxes for manually approving, retrying, rebasing, or recreating updates
• optional vulnerability summaries from OSV
Enable it explicitly with either form:
json
{
"extends": ["config:recommended", ":dependencyDashboard"]
}
json
{
"dependencyDashboard": true
}
Useful dashboard-related options:
json
{
"dependencyDashboard": true,
"dependencyDashboardTitle": "Dependency Dashboard",
"dependencyDashboardLabels": ["dependencies"],
"dependencyDashboardAutoclose": false
}
Approval Workflow
The dashboard can also become an approval gate. This is useful for risky updates like major versions, Terraform providers, cluster components, or rapidly changing packages.
Require approval for all major updates:
json
{
"major": {
"dependencyDashboardApproval": true
}
}
Require approval for specific packages:
json
{
"packageRules": [
{
"matchPackageNames": ["terraform-provider-aws", "kubernetes"],
"dependencyDashboardApproval": true
}
]
}
This is better than disabling updates entirely because the dashboard still shows what is waiting.
Update Management Lifecycle
A good Renovate setup usually evolves through these stages:
1. Discovery — enable Renovate, verify which managers detect dependencies, and review the onboarding PR.
2. Visibility — enable the Dependency Dashboard so blocked, ignored, pending, or failed updates are visible.
3. Noise control — use schedules, PR limits, grouping, and package rules to avoid overwhelming CI or reviewers.
4. Risk separation — treat patch/minor/major updates differently.
5. Validation — rely on CI, branch protection, lock file updates, and artifact update checks.
6. Automation — automerge low-risk updates after tests pass.
7. Maintenance — refresh lock files, prune stale branches, handle migrations, and update custom manager rules as repository conventions change.
Helpful lifecycle options:
json
{
"prHourlyLimit": 2,
"prConcurrentLimit": 5,
"schedule": ["* 22-23,0-4 * * 1-5", "* * * * 0,6"],
"timezone": "Europe/Lisbon",
"lockFileMaintenance": {
"enabled": true,
"schedule": ["before 4am on monday"]
}
}
Automerge Low-Risk Updates
Automerge should be conservative and depend on reliable CI plus branch protection.
json
{
"packageRules": [
{
"matchUpdateTypes": ["patch", "minor", "digest", "pinDigest"],
"automerge": true
},
{
"matchUpdateTypes": ["major"],
"dependencyDashboardApproval": true
}
]
}
On GitHub, make sure branch protection requires status checks before merging. Renovate's platformAutomerge defaults to true on supported platforms, so the platform may perform the actual merge.
Stability Windows
minimumReleaseAge makes Renovate wait before suggesting or automerging very new releases. This is useful for ecosystems where new releases may be yanked or quickly superseded.
json
{
"packageRules": [
{
"matchDatasources": ["npm"],
"minimumReleaseAge": "3 days"
}
]
}
With minimumReleaseAge, Renovate adds an internal stability status check such as renovate/stability-days.
Grouping Updates
Grouping reduces PR noise, but avoid grouping risky updates with routine ones.
json
{
"packageRules": [
{
"matchDepTypes": ["devDependencies"],
"matchUpdateTypes": ["patch", "minor"],
"groupName": "devDependencies non-major"
},
{
"matchManagers": ["github-actions"],
"groupName": "GitHub Actions"
}
]
}
Custom Managers
Use customManagers when your repository stores versions in formats Renovate does not understand natively.
The custom.regex manager needs to extract or template these fields:
• depName or packageName
• currentValue
• datasource
• optionally versioning, registryUrl, extractVersion, etc.
If you restrict managers with enabledManagers, remember to include custom.regex.
Regex custom managers use JavaScript/ECMAScript-style named capture groups, but Renovate uses RE2 internally, so backreferences and lookahead assertions are not supported.
Example: Kubernetes, Nix, and Custom Regex Managers
This configuration focuses Renovate on Kubernetes manifests, Nix flakes, and custom version strings inside .nix files.
json
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"],
"enabledManagers": ["custom.regex", "kubernetes", "nix"],
"nix": {
"enabled": true
},
"kubernetes": {
"managerFilePatterns": ["/\\.(yml|yaml)$/"]
},
"customManagers": [
{
"customType": "regex",
"description": "Update container images in .nix manifests",
"managerFilePatterns": ["/(^|/).*\\.nix$/"],
"matchStrings": [
"\\bimage\\s*(?:=|\\?)\\s*\"(?<depName>[\\w\\-\\.\\/]+):(?<currentValue>[\\w\\.\\-]+)\";?"
],
"datasourceTemplate": "docker"
},
{
"customType": "regex",
"description": "Update Terraform provider versions in required_providers blocks (source of truth lives in terraform/*/module.nix; the .terraform.lock.hcl files and the terrarium mirror list are refreshed by `just terraform-lock`)",
"managerFilePatterns": ["/(^|/)module\\.nix$/"],
"matchStrings": [
"source\\s*=\\s*\"(?<depName>[\\w.-]+/[\\w.-]+)\";\\s*version\\s*=\\s*\"(?<currentValue>[^\"]+)\";"
],
"datasourceTemplate": "terraform-provider",
"versioningTemplate": "hashicorp"
},
{
"customType": "regex",
"description": "Update Helm chart tarball flake inputs (version lives in the .tgz URL; hash is refreshed by `just helm-update`)",
"managerFilePatterns": ["/(^|/)flake\\.nix$/"],
"matchStrings": [
"# renovate: datasource=(?<datasource>\\S+) depName=(?<depName>\\S+) registryUrl=(?<registryUrl>\\S+)\\s+[\\w-]+\\s*=\\s*\\{\\s*url\\s*=\\s*\"\\S+?-(?<currentValue>v?[\\d.]+)\\.tgz\""
]
}
]
}
What This Does
• enabledManagers narrows Renovate to only the managers you want: Kubernetes, Nix, and custom regex extraction.
• nix.enabled opts into Renovate's currently beta Nix manager.
• kubernetes.managerFilePatterns is required because the Kubernetes manager has no default file patterns. Renovate will not scan every YAML file unless told to.
• The first custom manager finds Docker image references embedded in .nix files, such as image = "grafana/loki:2.9.8";.
• The second custom manager updates Terraform provider versions declared inside module.nix files, using the terraform-provider datasource and HashiCorp versioning.
• The third custom manager updates Helm chart tarball URLs in flake.nix, using an inline # renovate: hint to provide datasource, dependency name, and registry URL.
This pattern is powerful for Nix-based infrastructure repositories where the version source of truth is not a standard Terraform, Helm, or Kubernetes file.
Nix Notes
Renovate's Nix manager is currently opt-in/beta. Enable it explicitly:
json
{
"nix": {
"enabled": true
}
}
By default, the Nix manager checks flake.nix and supports lock file maintenance for flake.lock.
json
{
"nix": {
"enabled": true
},
"lockFileMaintenance": {
"enabled": true
}
}
Kubernetes Notes
The Kubernetes manager supports Docker image updates in Kubernetes manifests, but it does not scan YAML files by default because YAML is too generic.
Broad matching:
json
{
"kubernetes": {
"managerFilePatterns": ["/\\.ya?ml$/"]
}
}
Narrow matching:
json
{
"kubernetes": {
"managerFilePatterns": ["/^k8s/.+\\.ya?ml$/", "/^clusters/.+\\.ya?ml$/"]
}
}
Prefer narrow patterns if the repo contains many non-Kubernetes YAML files.
Useful Features and Options
| Feature | Option | Why it is useful |
|---|---|---|
| Dashboard | dependencyDashboard | Central issue for visibility and manual control |
| Dashboard approval | dependencyDashboardApproval | Gate risky updates before PR creation |
| Rate limiting | prHourlyLimit, prConcurrentLimit, commitHourlyLimit | Avoid CI storms |
| Scheduling | schedule, timezone, automergeSchedule | Run updates during quiet windows |
| Lock maintenance | lockFileMaintenance | Periodically refresh lock files |
| Automerge | automerge, platformAutomerge | Merge low-risk updates after CI |
| Stability | minimumReleaseAge | Wait before adopting brand-new releases |
| Grouping | groupName, packageRules | Reduce PR noise |
| Security | vulnerabilityAlerts, osvVulnerabilityAlerts | Create vulnerability remediation PRs |
| Custom formats | customManagers | Update versions in non-standard files |
| Registry auth | hostRules | Authenticate to private registries or APIs |
| Digest pinning | pinDigests | Pin container images or actions immutably |
Best Practices
• Start with config:recommended, then add rules based on actual pain points.
• Enable the Dependency Dashboard early; it makes suppressed and ignored updates visible.
• Keep packageRules ordered from general to specific, because later rules can override earlier ones.
• Require dashboard approval for major updates or risky ecosystems instead of disabling them.
• Use automerge only with trustworthy CI and branch protection.
• Use schedules and PR limits when onboarding large repositories.
• Prefer narrow managerFilePatterns to avoid accidental matches.
• Add descriptions to custom managers and package rules so future readers know why each rule exists.
• For self-hosted Renovate, keep secrets in environment variables, Kubernetes Secrets, or encrypted config—not committed plaintext.
• If post-update commands are needed, remember they are blocked by default and must be allowed by the self-hosted Renovate admin.
K8s Manifest
yml
apiVersion: batch/v1
kind: CronJob
metadata:
name: renovate
spec:
schedule: '@hourly'
concurrencyPolicy: Forbid
jobTemplate:
spec:
template:
spec:
containers:
- name: renovate
# Update this to the latest available and then enable Renovate on
# the manifest
image: renovate/renovate:40.57.0
args:
- user/repo
# Environment Variables
env:
- name: LOG_LEVEL
value: debug
envFrom:
- secretRef:
name: renovate-env
restartPolicy: Never
---
apiVersion: v1
kind: Secret
metadata:
name: renovate-env
type: Opaque
stringData:
RENOVATE_GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs'
# You can set RENOVATE_AUTODISCOVER to true to run Renovate on all repos you have push access to
RENOVATE_AUTODISCOVER: 'false'
RENOVATE_ENDPOINT: 'https://github.company.com/api/v3'
RENOVATE_GIT_AUTHOR: 'Renovate Bot <bot@renovateapp.com>'
RENOVATE_PLATFORM: 'github'
RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token'