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
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
git clone https://github.com/singapore/renovate or install globally via npm with
npm install -g renovate.
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.
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:
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.
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.
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.
When you are updating dependencies regularly, one of the frustrating things can be merge conflicts in your
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.
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.