Renovate - Hands On Tutorial (DRAFT) for actual repo: https://github.com/renovatebot/tutorial

Introduction

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 in 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:

1. Installation
2. Onboarding
3. Getting to know Renovate’s update PRs
4. Dependency Dashboard

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.

Part 1 - Installation

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

1. Make sure you are logged in to GitHub.com
2. Fork this RenovateTutorial repository. The tutorial instructions will be based on the contents of this repository
3. 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:
4. If you do have Renovate installed:
   • navigate to the Renovate app page and select configure:
5. 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 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. 🎈

Part 2 - Onboarding

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 -

1. 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 will not create dependency update PRs until the onboarding PR will be merged.

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:

1. Go to the newly created branch - renovate/configure:

2. Go into the renovate.json file:

3. Add the following code segment:

{
  "prHourlyLimit": 3
}

4. Commit the changes
5. 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.

6. 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:

1. 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:

2. 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:

1. Navigate to the main page of the repo and go to settings -> general
2. 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.

3. Go to the Pull requests section
4. Select Update dependency php to v8.1 and select Close pull request

5. 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.

The Dependency Dashboard includes:

• 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:

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 Dasboard, 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 depndency dashboard is affected by this change.

In order to limit all major updates to on-demand creation:

1. Add this code segment to your renovate.json file:

"packageRules": [
    {
      "matchUpdateTypes": ["major"],
      "dependencyDashboardApproval": true
    }
  ]

2. Commit the changes

Note Changing the renovate.json configuraion file is a webhook that triggers Renovate to re-run.

3. Now go back to the Dependency Dashboard in the Issues section

4. 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

5. You can now decide to manually open this PR by checking the box next to it

6. 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. 🎈

What have we learned so far:

• 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

General Comments:

• 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.

Upcoming Tutorials:

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