Welcome to the Renovate hands-on tutorial.
This tutorial is based on the Renovate GitHub App. You can also run Renovate as a CLI tool or a self-hosted application.
Note Although this tutorial is based on the GitHub App, the concepts discussed apply to all environments.
In this tutorial, you will learn how to configure Renovate and become familiar with some of the basic features.
What you will learn:
We will begin this tutorial with configuring and installing the Renovate app and an overview of the default settings and basic functionalities.
Later, we will dive deeper into functional use-cases, advanced features, and best practices
so you'll know how to leverage Renovate to its fullest.
Let’s start by forking the tutorial repo to your account, installing the Renovate GitHub App, and configuring it to your repo.
Note for existing users, installation configuration appears at the bottom of the page.
Mark Only select repositories
and make sure to select the forked RenovateTutorial repo
Note each selected repo gets an onboarding PR.
If you select All repositories
, forked repos will be skipped by default (including RenovateTutorial).
Install
(“Save” for existing users)For new installs:
Congratulations! You have successfully installed Renovate to your account. 🎈
Now you have installed Renovate, we can begin onboarding.
Let’s review the concepts of the Onboarding PR and learn about Renovate’s initial settings.
Note For your convenience, Renovate will not make any changes to your repo or raise PRs until after you finish onboarding.
renovate.json
, which contains Renovate’s default settings and can be modified during onboarding.Let’s review the onboarding PR:
Pull Requests
section in GitHub, and open the newly generated PR - Configure Renovate
Note Renovate will not create dependency update PRs until the onboarding PR will be merged.
date-io
PR under the what to expect section).Renovate offers the ability to change configurations before merging the onboarding PR as well as preview the results of these changes.
At this point, Renovate has created a branch called renovate/configure which contains the renovate.json
configuration file.
By default, Renovate limits branch creation to 2 per hour:
Example
As a user, despite Renovate’s suggestion to limit hourly PR creation to 2, we might want to increase the limit to a different number. Let’s try changing this hourly limitation to 3:
renovate/configure
:renovate.json
file:Add the following code segment:
{
"prHourlyLimit": 3
}
Commit the changes
Revisit the onboarding PR and notice how the onboarding PR automatically updates to reflect the changes you made to the configuration
Note May take a few moments to update.
Congratulations! You have successfully onboarded Renovate. 🎈
Now that you have merged the onboarding PR, Renovate will generate Update PRs to the most recent dependency version based on your configuration.
Note PRs may take a couple of minutes to appear
Here we will review the basic concepts of Renovate update PRs and merge it.
Pull Requests
section of the repo.Let’s go ahead and take a look at a Renovate update PR:
Pull requests
section and open - Update dependency lodash to x.y.z
package.json
file and the package-lock.json
file:Note - Renovate is highly configurable and supports:
- On-demand PR creation.
- Automatic merging of PRs.
- Settings for specific dependencies/package managers.
- Scheduling.
Grouping.
All the above and more will be discussed in future parts of the tutorial.
Congratulations! You have now updated your first dependency with Renovate. 🎈
Renovate’s Dependency Dashboard is a GitHub Issue that enables you to manage and monitor Renovate’s activity in your repo. In this section, we will go over some of its main functionalities and capabilities.
Let’s begin by creating and enabling the Dependency Dashboard.
Since GitHub defaults to disable issues
on forked repositories, we need to enable it on the forked RenovateTutorial repo:
settings
-> general
issues
checkbox under the Features section:Note This is usually done in a click via the Dependency Dashboard.
Pull requests
sectionUpdate dependency php to v8.1
and select Close pull request
Issues
section - navigate to itNote It may take a minute to appear.
Overview of all updates that are still to-do:
Visibility into rejected/deferred updates.
List of all the detected dependencies and package managers in your repository.
Users can manually trigger the creation of dependency updates directly from the dashboard.
You can also re-run the Renovate bot manually directly from the Dependency Dashboard by enabling the “Check this box to trigger a request Renovate to run again on this repository” option:
Let’s dive into one of the Dependency Dashboard capabilities - the Pending Approval feature.
Say we want to take extra measures before updating major versions of a package (either to reduce noise or to handle it more carefully). Renovate offers an option to prevent automatic creation of major version update PRs and create such PRs only upon manual request from the Dependency Dashboard.
In the Dependency Dashboard, under the Rate Limited
section, the Update dependency commander to vX
is waiting to be created.
Note Based on the previously set
prHourlyLimit
configuration, 3 PRs per hour in our case, this PR will be created within an hour.
Since we decided that we want to handle it manually, we will edit configurations and see how the Dependency Dashboard is affected by this change.
In order to limit all major
updates to on-demand creation:
renovate.json
file:
"packageRules": [
{
"matchUpdateTypes": ["major"],
"dependencyDashboardApproval": true
}
]
Note Changing the
renovate.json
configuration file is a webhook that triggers Renovate to re-run.
As you can see, commander
major update PR now appears under the Pending Approval section and will not be opened unless manually triggered
Note it make take a minute to complete Renovate's run
Pull requests
section to review the generated PR and merge it to the repo.Congratulations! You are now familiar with Renovate’s Dependency Dashboard. 🎈
You have successfully completed Renovate’s hands-on tutorial and have taken your first steps to automate dependency updates in your projects. Now, it's time to configure Renovate on the rest of your repositories and let Renovate manage your dependencies' health.
We're working on more advanced Renovate tutorials and will post updates when we publish new tutorials.
What’s coming next: