Renovate bot cheat sheet – the 12 most useful customizations

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

Originally posted on 2021-07-25, updated on 2026-08-12.

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) that updates the dependency. I highly recommend my Renovate introduction article, which presents 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 follows if your teams can configure Renovate well, so that it does the right things and does not burden them with unnecessary work. Since your developers might shy away from the verboseness of the official Renovate docs, I suggest you provide them with a simplified cheat sheet, like the one presented below. This cheat sheet covers the onboarding process (answering the question: “as a developer, I want to know how to tell Renovate to visit my Git repository”). It also includes a set of the most sensible configuration options. You will need to adapt this cheat sheet in some places.

Renovate cheat sheet

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

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

Your developers need to know how they can invite Renovate to their repositories. This very much depends on how you chose to operate Renovate. For instance:

• If your repository is on GitHub.com, using the hosted Renovate app, your cheat sheet should guide your developers to follow the official Renovate docs to install the Renovate GitHub app. The app allows the teams to configure which of their repositories Renovate should visit.
• If you self-host Renovate (e.g., because your repository is on GitLab or other SCM systems), the team operating Renovate needs to provide these onboarding instructions. The concrete approach depends on your SCM platform and how you run Renovate (e.g., as a CI/CD pipeline, or using the renovate-operator). If you only run Renovate in regular intervals (that is, you did not set up any webhook triggers), then the onboarding instructions should also inform your developers about Renovate’s execution interval. That interval adds delays the developers need to be aware of. Developers might otherwise wonder why nothing happens after they invited the Renovate SCM user into their repository. They did nothing wrong – it’s just that Renovate may visit their repository only once per hour.

#2 Configuring Renovate’s behavior

You can customize Renovate’s behavior for each Git repository it visits. The configuration is stored in the renovate.json file, located at the root of the default branch of 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 Renovate to visit your repository (as instructed above in tip #1), the first thing it will do is look for this renovate.json file. If it doesn’t find one, Renovate creates an onboarding branch and a corresponding PR.

The initial content of the renovate.json file (in the onboarding branch) is a very basic configuration, which you should tweak (following this cheat sheet) before 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 Renovate visits your repository, it detects that you changed the renovate.json file, and updates the onboarding PR’s description text accordingly.

While you are at it, you should rename renovate.json to renovate.jsonc (see JSON with comments specification). Renovate looks for many alternative config files, including renovate.jsonc. Using that format allows adding comments (“// comments“) to any line, where you explain why you added such changes to the renovate.jsonc. JSONC support was added to Renovate in 2026. In the past, the only alternative was the json5 format. However, whenever Renovate detects that a migration of your config is necessary, the Config Migration PR strips all your comments from a json5 file (while preserving the comments in a jsonc file).

It is also recommended to change the “extends” array in renovate.jsonc from ["config:recommended"] to ["config:best-practices"]. As the documentation explains, the best-practices preset is a combination of the config:recommended preset and various other presets. Presets resolve hierarchically. If you like a preset except for one or more specific subpresets it references, use the ignorePresets setting to disable those subpresets.

Note: if you make mistakes while changing the renovate.jsonc file (like syntax errors), Renovate will create an issue in your repository that contains the error message. To avoid such mistakes, use the renovate-config-validator CLI tool (see docs) to validate the renovate.jsonc file before committing it.

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

#3 Disable updates for specific dependencies or programming languages

Put "enabled": false into an package-rule-object within 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)

An alternative to the enabled setting is the enabledManagers option, where you configure an allow-list of package managers (see official docs for more information), e.g.:

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

#4 [Meta] Configure PR assignees

By default, Renovate creates PRs without assigning any specific users of your code hosting platform. But you may want Renovate to automatically assign specific developers or teams, which also means that they will receive (email) notifications. You do this via the assignees setting (docs), which you set to a list of usernames, team names, 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 your dependencies change often, Renovate constantly creates new PRs, which might become annoying. Even if you merged them right away, new PRs would continuously show up.

Using schedule (docs), you can tell Renovate to limit updating specific dependencies (or even all dependencies) only on specific times of day/week/month. It does not tell when Renovate visits your repository (i.e., it’s not a way to control the trigger/launch-mechanism of Renovate). Instead, it acts as a filter: whenever Renovate visits your repository, it verifies that <current-time> falls within at least one of the time ranges defined by schedule.

The schedule setting should use the Cron syntax as defined here (example: “9-17 * * mon-fri“), with the exception that you must always use * for the first value (which controls the minute granularity). You should read the schedule docs thoroughly, as it contains useful tips, such as controlling the time zone or available presets (note: it is possible to use something like "extends": ["schedule:nonOfficeHours"] within a packageRules object).

To build cron tab entries, use a helper such as crontab.guru, or ask an AI to help you.

Example use case #1: avoid interference during working hours

Set schedule to ["* 0-4,22-23 * * mon-fri", "* * * * sat-sun"], to stop Renovate from creating branches or PRs during working hours (in this example: Mo-Fri between 5 AM – 10 PM each). Without such a rule, Renovate might interrupt the merge process of your own feature branches. Renovate logically ORs the different array entries. If none of the entries evaluate to true, Renovate will not update this dependency in this execution cycle.

Example use case #2: manually oversee dependency updates

Suppose 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 ["0-5 * * wed"]. By the time you get to work (let’s say at 8 AM on Wednesday), Renovate 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.jsonc file), or limit it to particular dependencies by adding the schedule key to a rule 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, via a packageRules object. When Renovate discovers that 3 dependencies (matching the group selectors) have updates, Renovate only creates a single branch (and corresponding PR), rather than 3, because of that grouping. The branch/PR contains the updates of all 3 dependencies combined.

It can be beneficial to combine scheduling with grouping, as this increases the chance that several matched packages have version updates and actually can form a group. Without that, grouping may often come into effect. I recommend you take a closer look at the official grouping docs here (see also packageRules and groupName).

#6 [Meta] Avoid spam via automatic merging

If a third-party dependency follows semantic versioning, where breaking changes only happen in major updates, you can (usually) safely merge minor– or patch-level updates in a fully automated manner. Renovate offers the automerge (docs) configuration option for this purpose. A snippet like the following automatically merges 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 might want to be notified via email by your SCM (such as GitLab) whenever such an automatic update was merged by Renovate. A reason might be that you don’t fully trust your CI pipeline (or don’t have one yet). If you do want PR-related notifications, just remove the "automergeType": "branch" line. Then, the default automatic merge behavior ("automergeType": "pr") applies, where Renovate always creates a PR for the branch it created. The creation of the PR then causes the email notification.

Note that Renovate won’t auto-merge PRs with failed CI pipeline runs.

The default flow of an automatic merge is as follows:

1. Renovate visits your repository, finds an outdated dependency (for which Renovate 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 and/or (virtual) merge commit of the PR
3. Renovate visits your repository again (e.g., one hour later, depending on how you operate Renovate – adapt this). It finds the outdated dependency again, recognizes that it has already created a branch/PR for it. Therefore, Renovate 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 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 Renovate.

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 Renovate

By default, Renovate looks for renovate.json[c] in the default branch of your repository (e.g., main), and then scans for outdated dependencies only in that default branch. In other words, Renovate creates new renovate/xyz branches (in which it updates the dependencies) from the default branch and configures the PR to merge renovate/xyz into the default branch again.

If you want Renovate to scan for outdated dependencies in other branches, you have to set the baseBranchPattern 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:

• By default, Renovate does not read the contents of the renovate.json file in any of the baseBranches, but uses the renovate.json contents of the default branch. If you want to change this behavior, set useBaseBranchConfig to merge.
• If you specify multiple branches in baseBranches, and Renovate detects that a specific dependency is outdated in, say, 2 of these base branches, it will create two new branches (and corresponding PRs) – one for each base branch.

A possible solution to the second caveat 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 creates a renovate/xyz branch from, say, the default branch, the renovate/xyz branch (and its PR) might be open for a long time (e.g., until you find time to merge the PR). In the meantime, the target branch (the default branch) might evolve, and the renovate/xyz branch becomes stale.

The default behavior of Renovate is to only rebase the renovate/xyz branches if merging with the target branch would cause merge conflicts. This choice was made to avoid overloading your CI/CD pipelines (e.g., when you have 10 PRs, rebasing every PR at once would trigger 10 pipelines). However, you can tell Renovate to always rebase any still-open stale temporary branch. Simply set rebaseWhen to "behind-base-branch", or add “:rebaseStalePrs” at the end of your "extends" block:

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

This makes sense if you set up a branch protection rule that forbids your branches from being behind the target branch at the time of the merge. However, only do so if you either expect to have few open Renovate PRs, or if you have unlimited funds/resources for your CI/CD.

Note: Renovate never rebases PRs that have commits made by a SCM user other than Renovate. This avoids losing work done in the commits of those other users. You can still force Renovate to rebase these branches by clicking the Rebase checkbox shown at the bottom of the PR’s description.

#9 Handle pulled dependency updates

A dependency is said to be “pulled” if the author of that dependency first uploaded it to the corresponding registry (such as NPM or PyPi), but then decided to delete (“pull”) it shortly after, e.g. because it was incorrectly packaged, or contained critical bugs. Renovate offers two approaches to deal with pulled updates – reaction (via rollbackPrs) and prevention (via minimumReleaseAge):

• rollbackPrs (docs), when set to true, tells Renovate to create PRs that roll back versions if the currently-pinned version is higher than the newest one found in the registry
• minimumReleaseAge (docs) merely delays the creation of a PR for x days (but still immediately creates the renovate/xyz branch), after detecting an update for a specific dependency. If Renovate detects that this update has unexpectedly disappeared from the registry (within these x days), Renovate will 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)

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 Renovate? Two mechanisms assist you: the dependency dashboard, and automatically adding labels.

The labels setting (docs) tells Renovate to add labels to the PRs it created. Since these labels are represented by colored “pills” in the list of PRs (shown in your web browser), you can visually tell apart PRs created by Renovate from other PRs. You can also use labels to, say, indicate the affected programming language, or the severity (how fast you should take care of merging the PR). The following snippet illustrates this:

"labels": [
   "type:dependencies",
   “deptype:{{{manager}}}”,
   "updatetype:{{updateType}}"
 ]Code language: JSON / JSON with Comments (json)

The above example uses template variables (docs) to dynamically fill values, allowing you to filter PRs in more detail.

The Dependency dashboard (which is enabled by default in the config:recommended or config:best-practices preset, see also dependencyDashboard) is a GitHub/GitLab/etc. issue, whose description lists all PRs created by Renovate. These 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. The Dependency Dashboard also informs you of any errors Renovate encountered while trying to create PRs, e.g., missing credentials for private registries (or the inability to connect to them).

#11 Keep up to date with Renovate’s development

Renovate itself is software that is updated frequently. Whenever a new major version of Renovate is released, there might be breaking changes, such as syntax changes in the renovate.json configuration file. Assuming that whoever operates Renovate always uses the most recent (major) Renovate version, it makes sense for you to implement a mechanism that notifies you about major version updates of Renovate. This makes you 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, because Renovate will create an issue in your repository if your renovate.jsonc file contains errors.

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

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

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

{
  "packageRules": [
    {
      "description": "Ensures that Renovate does NOT try to pin the digest for the renovate/renovate image",
      "matchDatasources": [
        "docker"
      ],
      "matchPackageNames": "renovate/renovate",
      "pinDigests": false
    },
    {
      "description": "Make Renovate create a PR (and thus, an email notification), whenever there is a new major Renovate version",
      "matchFileNames": ["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.jsonc
      "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.

#12 [Meta] Troubleshooting Renovate

If Renovate does not behave the way you want it to, your developers can download and analyze the Renovate debug logs. Provide instructions here that teach your developers how to download these logs (the concrete approach depends on how you operate Renovate).

Once the developers have the logs, analyzing them is challenging for them because the logs are very verbose. Developers can use the Renovate Log Parser to simplify the manual (or AI-assisted) log analysis.

Conclusion

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

However, in some cases, going through the official documentation may be worth your while. While it does take some time to go through all of the Configuration options, you might discover features omitted in this cheat sheet that are a great fit for your particular project!

For advanced Renovate users, I also recommend my advanced tips and tricks article.