Updating dependencies is boring. Despite its importance, we always find excuses to avoid updating them in the phrase of “if it ain't broke, don't fix it” or “there are more important features to work on”. Over time, the maintainability of the projects deteriorates. The team ends up with a 3-year-old dependency where no one is brave enough to bump it.
So, what’s the solution? Let the bots do our boring job!
In this article, you will learn tips on running a self-hosted Renovate bot with GitLab (self-hosted) as an example. If you’re looking for a guide on how to start using Renovate on GitHub, I’d highly recommend you read this instead.
- Why use Renovate
- Getting started on self-hosted Renovate (GitLab as an example)
- How to run Renovate locally
- Debugging Renovate jobs
- 12+ Useful Renovate bot tips (updated 2023)
Why Use Renovate
In short, Renovate helps to update project dependencies (private or third-party) automatically.
How? Renovate parses our projects’ dependency management files such as
go.mod file and raise a pull/merge request (PR/MR) with the updated dependencies accordingly.
Renovate is highly customizable via a simple configuration file. It also supports a wide range of package managers.
Today, Renovate supports many other VCS hosts such as Bitbucket, Gitea, and even Azure DevOps. On top of that, it’s used by a lot of popular development communities or companies such as Uber, GitLab, Netlify, Apollo GraphQL, etc.
Personally, I think the best part about Renovate is its ability to auto-merge PRs/MRs.
How To Run Self-hosted Renovate on GitLab
To run Renovate on self-hosted GitLab, you’ll need a GitLab project (i.e. repository in the following). This bot repository will be used to host GitLab runners which run Renovate for your other projects.
Next, assuming that you already have GitLab runners installed and set up, you’ll need the following in the bot project:
- Configure the following CI/CD variables:
RENOVATE_TOKEN— GitLab Personal Access Token (PAT) with scopes:
GITHUB_COM_TOKEN— GitHub PAT with minimum scope.
config.js – Here's a simple example (source):
.gitlab-ci.yml – If you need a more complex example, see this example from the GitLab team. Otherwise, here’s a minimal example; do update accordingly:
How To Run Renovate Locally
While I was working with a large repository (60+ GiB), each Renovate job may take many hours, sometimes a day to complete. Having the ability to run Renovate locally saves me a bunch of time when it comes to experimentation and debugging.
First, create a minimum reproducible example (MRE) repository. Then, update your
config.js to target or discover the MRE repository. To run Renovate locally:
- It’s a lot easier to just use Docker. So, make sure you’ve installed Docker.
- To start, you’ll need to ensure that these environment variables are being exported in your shell:
export RENOVATE_TOKEN="aa11bb22cc" # GitLab Personal Access token (PAT) export GITHUB_COM_TOKEN="cc33dd44ee" # GitHub PAT
3. Next, update your
config.js accordingly. You’ll need to update your target
repositories accordingly. You could instead choose to
autodiscover repositories but you'll end up running it on multiple repositories instead of just one.
4. Finally, you can run Renovate using the following. To grab the latest Renovate version, check out Docker Hub. Do change the following command accordingly:
With this, testing the Renovate configuration in a fast-feedback loop manner is now possible.
To perform an actual run, update
Useful Renovate Bot Tips
- If you are unsure whether Renovate supports a certain functionality, always check out their FAQ page first. Chances are it’s already there.
- To disable updates for a specific package or library simply set
enabled: falseunder their respective
4. Need to run some custom task or script after upgrading (e.g. a script that posts messages to Slack)? Try
5. Setup a separate GitLab CI job for validating Renovate config using
6. Renovate is creating too many MRs?! Check out these noise reduction tips!
7. You can customize your organization's commit message, branch prefix, PR titles, etc. to fit your organization's push rules.
true to check if extracted dependencies have known vulnerabilities. It prevents the use of risky dependencies, maintains codebase quality, and saves you from future fixes. Customize it using
- Keep project-specific Renovate configs on the bot repository
config.jsinstead of having
renovate.jsonin every repository. This allows for Renovate-related configs to be centralized and abstracted away to a single MRE only.
module.exportsto avoid creating
renovate.jsonin other repositories.
requireConfig: 'optional'as the configs will all be within your
- If you have hundreds if not thousands of
repositoriesto renovate, do use the
autodiscoverfeature instead of adding them directly to your
- Sequentially renovating each repository is going to take a long time. You may want to run Renovate in parallel.
- Here, set
onboarding: trueto automatically onboard new repositories.
- Remember to set your own
- Consider creating sharable config presets for each team/organization in your company and extend them in your
Debugging Renovate jobs
When it comes to self-hosted solutions, there’s no running away from debugging your jobs. There could be scenarios where you’ll need to test connections to your private registry, proxy, etc.
Here are a couple of helpful tips:
- Try running Renovate locally targeting a single repository to have a faster feedback loop instead of relying on your CI/CD pipelines. Plus, running locally is practically free!
debugdoesn’t give you enough information.
- In case you’re working on some bespoke use cases or facing odd encounters/bugs, try Google searching with the prefix “site:github.com/renovatebot/renovate <your keywords or phrases>”. (example). In most cases, you’ll find that there are already others who have filed a similar discussion or issue.
Dealing with a large repository (e.g. GB in size)
- If you have a Go monorepo, consider using a Go module proxy like Athens.
- Under your GitLab project’s CI/CD General pipelines settings, you may want to increase your job timeout (e.g. "10 hours") as Renovate may take a long time on an uncached run on large repositories.
- On some occasions, you may run into
ERROR: Disk space error - skipping. Here, you may want to provision a runner with an increased disk size. E.g. if you are using AWS EC2, try to increase the size of the volume.
- You may want to set
persistRepoData: truefor faster
git fetchbetween runs.
- If you attempt to run Renovate on a large repository, you may encounter a
SIGTERMsignal (which can be seen in your Renovate job log) due to timeout. To cope with this, increase the
executionTimeoutsetting in your
Over the past few months, I have been using Renovate extensively; on GitHub, and self-hosted GitLab. Today, I am using Renovate on most of my active projects on GitHub to automate dependency updates. So far, Renovate was able to fit 99% of my use cases.
Keeping our project dependencies up-to-date is often overlooked. Yet, overlooking such work often comes at a great cost. The fact that we can leverage Renovate’s ability to do this grunt work is quite a blessing.
I hope this article saves you enough time instead of having you groom through pages of GitHub discussions and issues. Thanks for reading!