Renovate - npm dependency updater

renovate is an open-source tool for keeping npm dependencies up-to-date automatically with Pull Requests. It offers complete configurability of branch names, commit messages, Pull Request content, labels and assignees - so it can fit in with your existing conventions rather than making you adapt to its.

Why Use It?

  • Receive Pull Requests whenever any of your dependencies are updated
  • Integrates with existing branch-test-merge CI flow
  • Easily self host via cron job or Heroku Scheduler
  • Supports monorepos out of the box
  • Highly configurable via file, CLI, or env
  • Uses GitHub API
  • Open source, so full transparency about what it’s doing with your repo

Here’s a screenshot of us “Dogfooding” renovate: Example Pull Request

How To Use It?

renovate is run as a script from the command line, so therefore is well-suited for running headless on a schedule. Here are the broad instructions:

Set up permissions

You will need a GitHub user and associated Personal Access Token for authentication.

Obtain the code

Either git clone https://github.com/singapore/renovate or install globally via npm with npm install -g renovate.

Configure

renovate can be configured via a config file, from environment variables, or from CLI. You can also configure many options in your package.json. More details here. Usually you can just use default settings.

Deploy

renovate works well when scheduled via cron script, or Heroku Scheduler (which works on their free dyno). More details here.

About the code

We believe that any service or tool that interacts directly with your repository should be well documented and justified. We have therefore endeavored to document all major design decisions within the repo’s docs here.

To summarise some of the key points:

Stateless

Although you need to host renovate somewhere and configure it, it needs to maintain no state itself apart from what’s in GitHub. And as for GitHub - what you see (branches, Pull Requests) is what you get - there’s no other metadata needing to be hidden anywhere. It therefore doesn’t matter if you stop/restart the script and would even still work if you had it running from two different locations, as long as their configuration was the same.

API only

We were really happy to discover that everything we needed to do could be achieved with the GitHub API. Therefore there’s no messy git commands and essentially no risk of repository corruption.

Configurable

A single iteration of the script can process multiple repositories and multiple package.json files within each, and all applicable configuration options can be configured at each level. For example you could configure a global rule to apply the label dependency to all Pull Requests, but override it just for a specific package file in one of the repos.

You are even able to configure the string templates used to generate branch names, commit messages, Pull Request titles, and Pull Request descriptions.

Intelligent

When you are updating dependencies regularly, one of the frustrating things can be merge conflicts in your package.json. renovate detects if any Pull Request it has created for you has become dirty/unmergeable and intelligently recreates it based on the current base branch.

Polite

You don’t always want to update to the latest, especially if it’s a major release. Therefore, if you close any Pull Request that renovate has created, you don’t have to worry about them being recreated like some whack-a-mole game. If you later decide to upgrade the same dependency yourself, renovate will spring back into action to keep that dependency updated again. In the meantime, if the existing major version you are using continues to receive minor and patch updates then you’ll still get those in a separate Pull Request.

Go Get It

GitHub: https://github.com/singapore/renovate

npm: https://www.npmjs.com/package/renovate

Rhys Arkins-

Rhys is the founder of Key Location