Introducing Renovate’s “Master Issue”

Renovate's "Master Issue"

Renovate’s “Master Issue” is like a mini dashboard within your repo. If enabled, Renovate creates and maintains an issue that shows you all PRs at a glance – both pending, open, as well as rejected.

The Master Issue is designed to improve visibility, and provide increased control.

 

Visibility

Without the Master Issue, updates that are pending or blocked for some reason – such as schedule or PR rate limiting – are essentially invisible to the user unless they check the logs carefully. With the Master Issue, you can now not only see a list of those issues and why they’re blocked, but also choose to unblock them by ticking their respective checkbox, as shown in this screenshot:

The Master Issue is also a convenient way to see a list of Renovate PRs that you have previously rejected (i.e. closed without merging). Whether these were closed by accident or deliberately – or you just thought “not now” – you can now see the list and know what you’re missing out on.

 

Control

Each PR listed in the Master Issue has a checkbox next to it, that gives you increased control. If a PR is blocked, then ticking the checkbox means that it will be manually unblocked and created. This allows you to override schedules or rate limiting, for example.

For branches or PRs that are already created, ticking the checkbox will trigger Renovate to rebase the selected branch/PR.

For PRs that were rejected (Closed/Unmerged), ticking the checkbox lets you “change your mind” and have that PR recreated.

 

Approval

By default, the Master Issue itself does not change any of Renovate’s configured behaviour. i.e. your existing settings remain the same for schedules, rate limits, grouping etc.

However there is an optional setting for the Master Issue called “Master Issue Approval” that does enable you to change the workflow substantially – allowing you to block all Renovate PRs until you have manually approved them within the Master Issue.

Before continuing, I would caution you to think carefully before turning on Master Issue Approval for repositories. As the saying goes, “out of sight, out of mind”, and if you block all PRs from being created by default then there may be many times where you simply forget about them and quickly get out of date. I have been “dogfooding” the Master Issue Approval setting in Renovate’s own repository and even though I deal with dependency updates every day, I find it’s still easy to miss important updates. That said, here are some useful scenarios for Master Issue Approval:

 

Onboarding

Renovate’s “onboarding” PR (i.e. the one called Configure Renovate) is pretty good at telling you what will happen, but it can’t tell you everything, such as whether lock file creation will succeed, etc. For projects that are new to Renovate and will unsure whether to jump in, enabling masterIssueApproval before merging the onboarding PR will give even more control over Renovate in the early stages. Once a few PRs are created manually via the Master Issue, the team could choose to remove the approval step.

 

Resistance to Renovate PRs or concern about noise

If you have a development team that is split between whether or not to use Dependency Update Automation like Renovate, enabling Master Issue Approval for all updates could be a great compromise. This way:

  • Those who are worried about noise will be happy that the default setting is just a single issue
  • All team members can view how many updates are outstanding at a glance
  • Team members responsible for dependency updating can manually force PRs with just a single click

Reduce major update noise

It’s fair to say that the majority of projects don’t adopt major updates of dependencies right away. Apart from the time it takes to resolve any breaking changes, it is usually a good idea to wait for the major update to stabilise and any new bugs be found and fixed by others who had a pressing need for the update. So for users of Renovate, this means that major PRs usually sit around unmerged for weeks or even months, clogging up the PR queue.

In such a case, you could enable Master Issue Approval just for major updates, and keep settings the same for minor/patch/digest updates with this setting:

{
  "major": { "masterIssueApproval": true }
}

 

Compatibility

Naturally, you will need to have Issues enabled for your repository in order to create a Master Issue.

Additionally, the checkbox “ticking” feature is an advanced Markdown capability supported by only GitHub and GitLab, which makes it unavailable for Bitbucket and Azure DevOps at this time.

The Master Issue checkbox ticking feature also works best when combined with webhooks. If you are using the hosted Renovate App for github.com or gitlab.com, or you are a self-hosted Renovate Pro customer, then webhooks are already supported and you should see the bot run almost immediately any time you tick a checkbox in the Master Issue.

For self-hosted users of the open source bot, webhooks are unsupported and you will need to wait for whenever the next scheduled bot run occurs before Renovate can react to your ticked checkboxes.

 

Enabling

To enable the Master Issue (without approval), add "masterIssue": true to your Renovate config. You’ll then see the issue created in each repository it’s enabled in.

To enable Master Issue Approval for all PRs in a repository, add "masterIssueApproval": true to your Renovate config. PRs will no longer be automatically created, but the Master Issue will always contain an up-to-date list.

To selectively enable approval for dependencies, you can add the masterIssueApproval option to package rules just like you would for existing settings like schedule or automerge. e.g. to prevent automatic creation of any eslint-related packages, you could do:

{
  "packageRules": [
    {
      "packagePatterns": ["eslint"],
      "masterIssueApproval": true
    }
  ]
}


Future Work and Feedback

We think it would be useful if you could view release notes about updates before you decide whether to create the PR or not, so we are working on a way to achieve that.

In addition, the above feature could be nicely combined with the option to only create PRs upon approval. i.e. Renovate could create branches by default, but not PRs. It would then be up to the user to look at the branch test status plus the release notes before deciding whether to ask Renovate to open the PR.

Even further, maybe you should choose to ask Renovate to merge that branch directly without the need for a PR at all.

If you have any other ideas, please raise a feature request.

 

Examples

If you’d like to see the Master Issue in action, you can browse some example public repositories that have already been using the feature:

  • Renovate: Naturally we have been dogfooding this feature since it was created.
  • Yarn: The idea for Master Issue in fact came from Yarn’s @arcanis himself. In Yarn’s case, they are often held back from accepting major updates if those updates deprecate a major version of Node.js that Yarn itself still supports. Instead of closing such PRs and “losing” them, they now have visibility of them all in one place.
  • Sourcegraph: Sourcegraph rely heavily on schedules, but sometimes have a need to override those to create PRs immediately. The Master Issue gives them visibility and control into PRs that are awaiting their schedule.
  • Prettier TS: This Prettier repo chooses to use an approval step for all PRs.

Rhys Arkins / About Author

Rhys Arkins is Vice President of Product Management, responsible for developer solutions at Mend.io. He was the founder of Renovate Bot – an automated tool for software dependency updating, which was acquired by Mend.io in 2019. Rhys is particularly fond of automation and a firm believer in never sending humans to do a machine’s job.