Renovate - Hands On Tutorial

Introduction

Welcome to the Renovate hands-on tutorial.

This tutorial is based on the Mend Renovate App. You can also run Renovate as a CLI tool or a self-hosted application.

[!NOTE] Although this tutorial is based on the Mend Renovate 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:

Installation
Onboarding
Getting to know Renovate’s update PRs
Dependency Dashboard

We will begin this tutorial with configuring and installing the Mend 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.

Part 1 - Installation

Let’s start by forking the tutorial repo to your account, installing the Mend Renovate App, and configuring it to your repo.

Make sure you are logged in to GitHub.com
Fork this repository. The tutorial instructions will be based on its contents.
The following instructions are directed at those that don’t have the Mend Renovate App installed:
- Install the Mend Renovate App to your account by navigating to the the Mend Renovate App installation page and select Install:
If you do have the Mend Renovate App installed:
- navigate to the Mend Renovate App 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 repo

Note 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 redirected to the Mend's developer portal where you can sign in and view the Renovate logs. We recommend saving this link for future use.

Congratulations! You have successfully installed Renovate to your account. 🎈

Part 2 - Onboarding

Now you have installed the Mend Renovate App, we can begin onboarding.

Let’s review the concepts of the Onboarding PR and learn about Renovate’s initial settings.

[!NOTE] Renovate waits for you to finish onboarding, before making changes to your repo or raises PRs.

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.

Let’s review the onboarding PR:

Navigate to the Pull Requests section in GitHub, and open the newly generated PR - Configure Renovate

The onboarding PR contains:

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 only creates dependency update PRs after you merge the onboarding PR.

These are some of the default configurations of Renovate:

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

[!NOTE] May take a few moments to update.

Merge the onboarding pull request.

Congratulations! You have successfully onboarded Renovate. 🎈

Part 3 - Getting to know Renovate’s update PRs

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

Each update PR contains:

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 the package-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. 🎈

Part 4 - Dependency Dashboard

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:

Go to the main page of the repo
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 do

Tutorial

Install / Use

README