Welcome to the Renovate hands-on tutorial.
The easiest way to start is using the Renovate GitHub App. you can also run Renovate as a CLI tool or a self-hosted application.
In this tutorial, you will learn how to configure Renovate to your GitHub account and become familiar with some of Renovate’s basic features.
Although this tutorial is based in the GitHub App, the concepts discussed apply to all environments.
What you will learn:
- Installation
- Onboarding
- Getting to know Renovate’s update PRs
- Dependency Dashboard
We will begin this tutorial by providing basic getting started
information. This includes: Renovate App configuration and installation, default settings, and basic Renovate functionality.
Later, we will dive deeper into functional use-cases, advanced features, and best practices
capabilities in order to use 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.
- Make sure you are logged in to GitHub.com
- Fork this RenovateTutorial repository. The tutorial instructions will be based on the contents of this repository
- The following instructions are directed at those that don’t have Renovate installed:
- Install the Renovate App to your account by navigating to the Renovate App GitHub installation page and select Install:
- Install the Renovate App to your account by navigating to the Renovate App GitHub installation page and select Install:
- If you do have Renovate installed:
- navigate to the Renovate app page and select configure:
- navigate to the Renovate app page and select configure:
- You will reach an installation configuration page where you are asked to configure Repository Access.
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 repoNote each selected repo gets an onboarding PR.
If you select
All repositories
, forked repos will be skipped by default (including RenovateTutorial). -
click on
Install
(“Save” for existing users)
For new installs:
- You will be redirected to our “Thank you for installing Renovate” page while we are setting up your account.
- After a few seconds, you will be automatically directed to a dashboard where you can login and view the Renovate logs. We recommend saving this link for future use.
Congratulations! You have successfully installed Renovate to your account. 🎈
Now that you have Renovate installed, 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.
- Upon installing Renovate, an onboarding PR will be automatically generated.
- This PR is there to help you understand Renovate and its default settings before Renovate starts running on your repository.
- The Onboarding PR creates a configuration file called
renovate.json
, which contains Renovate’s default settings and can be modified during onboarding.
Now let’s review the onboarding PR -
- Navigate to the
Pull Requests
section in GitHub, and open the newly generated PR -Configure Renovate
- Detected Package Files - All package files detected by Renovate in your code.
- Configuration Summary - The default configuration settings that will be applied.
- What to Expect - The dependency update PRs that Renovate is about to automatically create.
- The link to Renovate’s official documentation.
- The link to review jobs logs in the Renovate dashboard.
Note Renovate will not create dependency update PRs until the onboarding PR will be merged.
- Enables creation of the “Dependency Dashboard” - a dashboard that shows an overview of the state of your repositories' dependencies.
- PRs will be created at a rate of 2 PRs per hour.
- The limit of simultaneous open Renovate PRs is set to 10.
- Renovate automatically groups known monorepo packages to a single PR (example can be seen in the
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:
- Go to the newly created branch -
renovate/configure
:
- Go into the
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
- Merge the onboarding pull request.
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.
- By default, Renovate will create up to 2 update PRs per hour. However, if you completed the onboarding section of this tutorial, Renovate will now create 3 PRs.
- You should already see notifications for these pull requests in the
Pull Requests
section of the repo.
Let’s go ahead and take a look at a Renovate update PR:
- Navigate to the
Pull requests
section and open -Update dependency lodash to x.y.z
- Dependency information (name and version changes)
- Merge Confidence values
- Up-to-date release notes
- Renovate configuration-related info
- Option to rebase PR
- Link to view Renovate logs
- Renovate’s update PRs will update the relevant dependency across your entire repo. In our RenovateTutorial repo, this will be both the
package.json
file and thepackage-lock.json
file:
- Merge this pull request
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:
- Navigate to the main page of the repo and go to
settings
->general
- Check the
issues
checkbox under the Features section:
- In order for the Dependency Dashboard to become available, we will need to re-run Renovate by triggering a webhook (for example, closing an update PR).
Note This is usually done in a click via the Dependency Dashboard.
- Go to the
Pull requests
section - Select
Update dependency php to v8.1
and selectClose pull request
- This will trigger Renovate to run and the Dependency Dashboard will appear under the
Issues
section - navigate to it
Note it may take a minute to appear.
-
Overview of all updates that are still to-do:
- Open PRs
- Rate Limited - PRs blocked by rate limit setting and will be opened based on preferences.
- Pending Approval - PRs that require manual triggering based on configurations.
- Awaiting Schedule - PRs creation blocked by Renovate scheduling settings.
- Pending Status Checks - updates that await pending status checks in order to be created.
-
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:
-
Before advancing, edit the
renovate.json
file and changeprHourlyLimit
value to -1.This setting disables the rate limit on PR creation for future parts of this tutorial.
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 order to limit all major updates to on-demand creation:
- Add this code segment to your
renovate.json
file:
"packageRules": [
{
"matchUpdateTypes": ["major"],
"dependencyDashboardApproval": true
}
]
- Commit the changes
To demonstrate this change in configuration, we need a dependency with a major update available. In our RenovateTutorial repo, the commander
dependency fits that description. Since we already have an open PR for commander
, we will perform a small work-around to rebase the update PR and have it appear immediately in the Dependency Dashboard:
-
Go to the
Pull requests
section and openUpdate dependency commander to vX
-
Change the PR title as you like (if the title is not changed, Renovate will not re-open the PR after we close it in the next step):
- Close pull request:
- Delete the associated branch:
-
Now go back to the Dependency Dashboard in the Issues section and re-run Renovate.
-
As you can see,
commander
major update PR now appears under the Pending Approval section and will not be opened unless manually triggeredNote it make take a minute to complete Renovate's run
-
You can now manually open this PR by checking the box next to it
-
Navigate to the
Pull requests
section to review the generated PR and merge it to the repo.
Congratulations! You are now familiar with Renovate’s Dependency Dashboard. 🎈
- How to install Renovate
- Onboarding Renovate by reviewing, configuring, and merging the onboarding PR
- How to update a dependency with Renovate
- How to utilize the Dependency Dashboard
- Granting access to all repositories or change repo selections can be modified at any time on the Renovate App GitHub page.
- Renovate configuration can be modified by manual configurations, global organization configurations and existing Renovate presets.
Congratulations! 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 have more advanced Renovate tutorials in the pipeline and will post updates when they are published.
What’s coming next?
- Merge confidence
- Auto Merge
- Labeling
- Grouping
- Schedule
- Package Rules
- GitHub actions
- Assignees and reviewers
- Regex Managers