Renovate bot cheat sheet – the 11 most useful customizations

Renovate bot is a tool that automatically updates third-party dependencies declared in your Git repository via pull requests. This Renovate bot cheat sheet helps developers who adopt Renovate to customize the most common (and useful) configuration options, without having to read the entire, extensive Renovate bot documentation.

Introduction

Renovate (Bot) is a CLI tool that regularly scans your Git repositories for outdated dependencies. If it finds any, it automatically creates a pull request (PR) in which the dependency is updated. I recommend my Renovate Bot introduction article to get you started with the basics.

If you want to introduce automatic dependency updates (using Renovate) to the development teams in your organization, you want to make sure that they actually use it, and that they are happy with it. Happiness only comes if your teams manage to configure the Renovate bot well, so that it does the right thing, and does not spam them unnecessarily. Since your developers might shy away from the verboseness of the official Renovate docs, I suggest that you provide them with a simplified cheat sheet, like the one presented here. The cheat sheet (which you need to adapt in some cases) should cover the onboarding process (answering the question: “as a developer, I want to know how to make the Bot visit my Git repository”), and include a set of the most sensible configuration options.

Renovate bot cheat sheet

The following subsections are topics that make sense to be placed on a cheat sheet. Those starting with “[Meta]” are meta-level instructions that require that you adapt them first. The other sections you can simply copy and paste.

You can find a suggestion for the renovate.json5 configuration file here. It incorporates all tips from below in a single file. Just like with the [Meta] sections, you should also adapt this file, prior to offering it to your developers!

#1 [Meta] Configure Renovate bot to visit your Git repository

If your repository is on GitHub.com, your cheat sheet instructions should instruct the developer to follow the official Renovate docs to install the Renovate GitHub app. Here, they can configure which ones of their repositories should be visited by the bot.

Otherwise (e.g. if your repository is on GitLab or other SCM systems), the (IT) team that operates the bot needs to provide instructions. These instructions should also include the bot visitation frequency (and the delay developers should expect), which corresponds to the interval with which the bot is executed (e.g. the cron job interval, in case you use cron to run the bot). Otherwise, developers might wonder why “nothing happens” after they followed the instructions (such as inviting the Renovate Bot SCM user into their repository). It’s not that they did something wrong, it’s just that the bot may visit their repository only once per hour.

#2 Configuring the bot’s behavior

To be flexible, you customize the behavior of the bot for each Git repository it visits. The configuration is stored in the renovate.json5 file, located at the root of the default branch your repository. The official reference for what you can put into this file is found on the Configuration Options documentation page, but a good first start is to just apply the tips from this cheat sheet.

After you configured the bot to visit your repository (as instructed above), the first thing it will do is to look for this renovate.json5 file. If it doesn’t find one, the bot creates an onboarding branch and corresponding Pull Request (PR, or MR in GitLab’s terms).

The initial content of the renovate.json5 file (in the onboarding branch) is a very basic configuration, which you should tweak (following this cheat sheet), prior to clicking “merge” for the onboarding PR. To do this, check out the PR’s corresponding branch (“renovate/configure“) with Git, and update the file’s content with new commits (and push them). The next time the Renovate bot visits your repository, it will detect that you changed the renovate.json5 file, and update the PR’s description text accordingly.

Note that if you make mistakes while changing the renovate.json5 file (e.g. syntax errors), the bot will create an issue in your repository, that contains the error message. To avoid this, you can use the renovate-config-validator CLI tool (see docs) to validate the renovate.json5 file, prior to committing. If you have Docker, you can run the following command to validate the file:

docker run -v /path/on/host/to/renovate.json5:/usr/src/app/renovate.json5 -it renovate/renovate renovate-config-validatorCode language: Bash (bash)

Because it is easy to accidentally make a mistake with mounting the file from the host into the container, I recommend that you also do a sanity check, where you introduce syntax errors in the file on the host on purpose, and verify that renovate-config-validator complains.

Once the onboarding PR was merged, Renovate bot will start creating new branches (and PRs), for outdated dependencies.

#3 Disable updates for specific dependencies or programming languages

Put "enabled": false into one (or more) of the following places:

1) An object inside the packageRules array. For instance, to disable dependency updates for the dependency named neutrino, the packageRules array should look as follows:

"packageRules": [
  {
    "matchPackageNames": ["neutrino"],
    "enabled": false
  }
]Code language: JSON / JSON with Comments (json)

2) In a programming-language-specific block (e.g. golang, python, ruby, php, java, node or js), which disables automatic updates for dependencies of that corresponding language. For instance, to instruct Renovate bot to ignore Go module updates completely (and not create any branches/PRs for them), use this:

"golang": {"enabled": false}Code language: JavaScript (javascript)

Alternatively (to the enabled setting), if you prefer allow-lists over exclude-lists, you can set the enabledManagers option to a narrow list of languages (see official docs for more information), e.g.:

{
  "enabledManagers": ["dockerfile", "npm"]
}Code language: JSON / JSON with Comments (json)

#4 [Meta] Configure PR assignees

If the bot is configured to create a PR (in addition to creating a new branch in which the dependency is updated), which is the default behavior, you may want the bot to automatically assign specific developers from your team to these PRs. This is possible with the assignees setting (docs), which you set to a list of usernames or email addresses (depending on the SCM platform – adapt this!), e.g.:

"assignees": ["peter.pan", "mister.proper"]Code language: JSON / JSON with Comments (json)

#5 Avoid spam via scheduling and grouping

If the dependencies your application uses do change often, the Renovate bot’s activities (constantly creating PRs) will become annoying.

Using schedule (docs), you can tell Renovate bot to only update the dependency on specific times of day/week/month.

Example use case #1: avoid interference during working hours

Set schedule to ["after 10pm every weekday", "before 5am every weekday", "every weekend"], to stop Renovate bot from creating branches and PRs during working hours (in this example: Mo-Fri between 5 AM – 10 PM each). Without such a rule, the bot might interrupt the merge process of your own feature branches into the default branch. In this example, the bot is limited to only update dependencies on weekends (at any time during weekends!), or outside of working hours during week days. Regarding the logic: the bot logically ORs the different array entries, but ANDs the meaning of the words within a specific entry. If none of the entries evaluate to true, the bot will not update this dependency in this execution cycle.

Example use case #2: manually oversee dependency updates

Suppose that you want to manually verify whether new dependencies really work. This might be the case if certain aspects of your application cannot be automatically tested in a CI pipeline, or you simply don’t have automatic tests yet. Suppose you are willing to do this verification once per week, on Wednesday morning. You can achieve this with a schedule set to ["on wednesday before 6am"]. By the time you get to work (let’s say at 8 AM on Wednesday), Renovate bot should have updated the dependencies, and you can take over and confirm that everything still works.

Regarding the scope: you can either configure the schedule option globally (by defining the schedule key at the root level of the renovate.json5 file), or specifically only for some dependencies, by adding the schedule key to an object that is part of the packageRules array.

You can reduce spam even further using the grouping feature. Here you specify a list of dependency / package names (or update types) that should be grouped together. When the bot (in a single execution cycle) discovers that 3 dependencies (matching the group selectors) have updates, then the bot will only create a single branch (and corresponding PR), rather than 3, because of that grouping. The branch / PR will incorporate the updates of all 3 dependencies combined.

It can be beneficial to combine the schedule feature with the grouping feature, as otherwise the grouping may often not take any effect. I recommend you take a closer look at the official docs here (also useful: see here and here).

#6 [Meta] Avoid spam via automatic merging

If a third-party dependency follows semantic versioning, where breaking changes are reserved to major version updates, you can usually safely migrate to minor– or patch-level updates in a fully automated manner. Renovate bot offers the automerge (docs) configuration option for this purpose. A snippet like the following will automatically merge minor and patch updates, for any dependency of any ecosystem / programming language:

"packageRules": [
  {
    "description": "Automatically merge minor and patch-level updates",
    "matchUpdateTypes": ["minor", "patch", "digest"],
    "automerge": true,
    // Force Renovate to not create a PR (but merge its branches directly), to avoid PR-related email spam
    "automergeType": "branch"
  }
]Code language: JSON / JSON with Comments (json)

You may prefer to be notified via email by your SCM (such as GitLab) whenever such an automatic update was merged by Renovate bot, e.g. when you don’t fully trust your CI pipeline (or don’t have one yet) which automatically tests your code (and which would fail if your code stopped working with the updated dependency version, which would also abort the automatic merge). If this is the case, you can remove the "automergeType": "branch" line. In that case, the default automatic merge behavior will apply (which is "automergeType": "pr"), causing the bot to always create a PR right after it created the branch. The creation of the PR, in turn, causes the email notification.

The default flow of an automatic merge is as follows:

1. Renovate bot visits your repository, finds an outdated dependency (for which the bot has not yet created a branch/PR), and thus it creates a branch (and possibly a PR, depending on configuration options like automergeType or prCreation).
2. The CI pipeline runs on the just-created branch
3. Renovate bot visits your repository again (e.g. one hour later, depending on how it is configured – adapt this). It finds the outdated dependency again, recognizes that it has already created a branch/PR for it. Therefore, the bot clicks the “merge” button for you – but only if the CI pipeline for the just-created branch has successfully finished. If this assumption does not hold, Renovate bot does not automatically merge the dependency (yet), and waits for you to fix the branch so that the CI pipeline passes.

As you can see, automatic merging takes some time. It cannot be completed in just a single execution cycle of the bot.

Adapt this if you (don’t) use GitLab: In case you use GitLab as SCM, you can enable the platformAutoMerge (docs) setting, which speeds up the automatic merging process. Here, GitLab will automatically merge the PR for you, once the corresponding pipeline has successfully finished (after step 2 above has finished).

In practice, you may want to limit automatic merging only to specific dependencies/packages, or programming languages. See the Disabling updates section for how to achieve this.

#7 Configure branches considered by the bot

By default, Renovate bot looks for renovate.json5 in the default branch of your repository (typically master or main), and then scans for outdated dependencies only in that default branch. In other words, the bot creates new, temporary branches (in which the dependencies are updated to the newest version) from the default branch, and configures the PR to merge that temporary branch into the default branch again.

If you want Renovate bot to scan for outdated dependencies in other branches, you have to set the baseBranches option (docs) to an array of branch names. A possible use case might be that you are not actively developing on the default branch (but some other one, e.g. dev), or you might want Renovate to keep multiple release streams up to date, e.g. by setting "baseBranches": ["main", "next"].

There are two caveats to be aware of:

• At the time of writing, the bot does not expect a renovate.json5 file to exist in any of the baseBranches that differ from the default branch. Thus, if you set baseBranches to ["master", "foo", "bar"], and there is a renovate.json5 file in foo or bar, the bot doesn’t read or process it. It only reads the renovate.json5 file from the default branch (here: master). Thus, you cannot have varying bot configurations, dependening on the branch. Ticket #2496 addresses this.
• If you specify multiple branches in baseBranches, and the bot detects that a specific dependency is outdated in, say, 2 of these base branches, it will create two new, temporary branches (and corresponding PRs) – one for each base branch.

A possible solution to these caveats is to use the matchBaseBranches (docs) option, which lets you scope packageRules to specific branches, and thus, you can create rules which are branch-specific.

#8 Fix default branch rebasing behavior

Whenever Renovate bot creates a temporary branch from, say, the default branch, this temporary branch (and corresponding PR) might be opened for a longer time period (e.g. until you find time to merge the PR). In the meantime the source branch (here: the default branch) might evolve, and the temporary branch becomes stale.

The default behavior of Renovate bot is to only rebase the temporary branch if the attempted merge with the source branch would cause merge conflicts. However, you can tell Renovate bot to always rebase any still-open temporary branch, whenever its source branch has changed, which is highly recommended. Simply set rebaseWhen to "behind-base-branch", or add :rebaseStalePrs at the end of your "extends" block, e.g.:

"extends": ["config:base", ":rebaseStalePrs"]Code language: JSON / JSON with Comments (json)

#9 Handle pulled dependency updates

We say that a dependency has been “pulled” when the author of that third-party dependency first uploaded it to the corresponding repository (e.g. NPM or PyPi), but then decided to delete (“pull”) it shortly after, e.g. because it was incorrectly packaged, or contained critical bugs. Renovate bot offers two approaches to deal with pulled updates – reaction (via rollbackPrs) and prevention (via stabilityDays):

• rollbackPrs (docs), when set to true, tells the bot to create PRs that roll back versions, if the current version is no longer found in the registry
• stabilityDays (docs) simply delays the creation of a PR for x days (but still immediately creates the temporary branch), after detecting an update for a specific dependency. If the bot detects that this update has unexpectedly disappeared from the registry (within these x days), the bot will simply delete the corresponding branch again. I recommend you read the docs to learn how this feature works in detail.

#10 Improve overview of open PRs (created by Renovate Bot)

Especially in big projects you might lose overview of the large number of PRs. Which ones were created by your team, and which ones are just automatically created by the bot? There are two mechanisms that assist you: the dependency dashboard, and automatically adding labels.

addLabels (docs) tells Renovate bot to add labels to the PRs it created. Since these labels are represented by colored “pills” in the list of PRs (that you can look at in the browser), you can visually tell apart issues created by the bot from other issues. You can also use labels to e.g. indicate the affected programming language, or the severity (how fast you should take care of merging the PR).

Setting dependencyDashboard (docs) to true will create a special “Dependency Dashboard” issue, whose description text lists all PRs created by the bot in one place (where PRs can have any state, including pending, open, closed, or error). It contains clickable links, e.g. to rebase/retry multiple PRs without having to open each one individually. I recommend you read the docs of dependencyDashboard and its sub-options (such as dependencyDashboardApproval) to understand how it works.

#11 Keep up to date with Renovate Bot’s development

Renovate itself is software that is updated frequently. Whenever a new major version of the bot is released, there might be breaking changes, considering the allowed syntax in the renovate.json5 configuration file, or new features. Thus, assuming that whoever operates the bot always uses the most recent (major) version, it makes sense for you to implement a mechanism that notifies you in case of major version updates of Renovate. This allows you to look at Renovate’s changelog, profit from new features, and keep up to speed regarding possible syntax deprecations. Note that if you don’t care about new features or deprecations, you don’t strictly need this – as I explained above, the bot will create an issue in your repository, once the renovate.json5 file contains errors.

As notification mechanism, create a “fake” Dockerfile (which will never be built into an image, but Renovate still processes it), e.g. located at "renovate-update-notification/Dockerfile". Below is an example for it’s content:

# This file is processed by Renovate bot so that it creates a PR (notifying us) on new major Renovate versions
FROM renovate/renovate:25Code language: Dockerfile (dockerfile)

You should also customize the configuration for that Dockerfile in your renovate.json5 file, e.g.:

{
  "packageRules": [
    {
      "description": "Disables the creation of branches/PRs for any minor/patch updates etc. of Renovate bot",
      "matchPaths": ["renovate-update-notification/Dockerfile"],

      "matchUpdateTypes": ["minor", "patch", "pin", "digest", "rollback"],
      "enabled": false
    },
    {
      "description": "Causes the bot to create a PR (and thus, an email notification), whenever there is a new major Renovate version",
      "matchPaths": ["renovate-update-notification/Dockerfile"],
      "matchUpdateTypes": ["major"],
      // you can also set automerge to true - emails for the PRs will already have been sent anyway, so there is
      // no strict reason to keep the PR open - unless you want to associate it with updates you make to renovate.json5
      "automerge": false,
      // just re-states the default and ensures that PRs are really created - you can remove this line
      // if you did not change "prCreation" elsewhere to some non-default value
      "prCreation": "immediate",
    }
  ]
}Code language: JSON / JSON with Comments (json)

At the time of writing, there is a new major Renovate version release coming roughly every 2 months. If this is too noisy for you, you can reduce the update frequency, by adding something like the following to the second object in the packageRules array of the above example.

"schedule": ["every 3 months on the first day of the month"],Code language: JSON / JSON with Comments (json)

Conclusion

Keeping up to date with third-party dependencies is important, to avoid software rot or technical debt. The fact that Renovate bot automates this task is a great time saver. A cheat sheet like the one presented here helps your developers get the most out of the tool, without having to spend extensive amounts of time to study the in’s & out’s of the Renovate bot manual.

However, in some cases, going through the manual may be worth your while. While it does take some time to go through all of the Configuration options, you might discover things (omitted in this cheat sheet) that are perfect for your particular project!