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 robots do our boring job!
In this article, you will learn tips on running a self-hosted Renovate bot with GitLab as an example. If you’re looking for a guide on how to start using Renovate on GitHub, I’d highly recommend you to read this.
TL;DR
- Why use Renovate
- Getting started on self-hosted Renovate (GitLab as an example)
- How to run Renovate locally
- Debugging Renovate jobs
- 12 useful Renovate tips
Disclaimer: these tips are my own opinions from lessons gathered from hours working. Enjoy!
Why Use Renovate
In short, Renovate (official doc) helps to update project dependencies (private or third-party) automatically.
How? Renovate parses our projects’ dependency management files such as package.json
, pyproject.toml
, go.mod
file and raises a pull/merge request (PR/MR) with the updated dependencies accordingly.
Renovate is highly customizable via a simple configuration file (config.js
). With rather intuitive configuration settings, it also supports a wide range of package managers.
Today, Renovate supports many other Git platforms such as Bitbucket, Gitea, or even Azure DevOps. On top of that, it’s used by a lot of popular development communities or companies such as Uber, GitLab, Prisma, Netlify, etc.
Highlight
The best part about Renovate is its ability to auto-merge PRs/MRs.
That aside, the flexibility provided by the [packageRules
feature](https://docs.renovatebot.com/configuration-options/#packagerules) which is used to apply rules to specific dependencies (in individual or group) is incredibly handy.
How To Run Self-hosted Renovate on GitLab
To run Renovate on self-hosted GitLab, you’ll need a private 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:read_user
,api
, andwrite_repository
. -
GITHUB_COM_TOKEN
— GitHub PAT with minimum scope.
-
-
config.js
(NOTE: here’s a more complex example).
// Example config.js from https://github.com/renovatebot/renovate/blob/main/docs/usage/examples/self-hosting.md module.exports = { endpoint: 'https://self-hosted.gitlab/api/v4/', token: '**gitlab_token**', platform: 'gitlab', onboardingConfig: { extends: ['config:base'], }, repositories: ['username/repo', 'orgname/repo'], };
-
.gitlab-ci.yml
. If you need a more complex example, check out this example from the GitLab team. Otherwise, here’s a minimal example; do update accordingly:
image: renovate/renovate:32.6.12 variables: LOG_LEVEL: debug renovate:on-schedule: tags: - your-gitlab-runner-tag-if-any only: - schedules script: - renovate $RENOVATE_EXTRA_FLAGS renovate: tags: - your-gitlab-runner-tag-if-any except: - schedules script: - renovate $RENOVATE_EXTRA_FLAGS
Lastly, you’ll need to run Renovate at regular intervals (e.g. every hour) using the GitLab project’s CI/CD Schedules feature. Do note that this is different from Renovate’s own schedule.
Check the source for more details. Though, the steps above should be sufficient.
How To Run Renovate Locally
While I was working with a large repository (>6GB for full clone), each Renovate job may take hours 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
Next, update your
config.js
accordingly. You’ll need to update your targetrepositories
accordingly.-
Finally, you can run Renovate using the following. To grab the latest Renovate version, check out Docker hub. Do change the following command accordingly:
docker run \ --rm \ -e LOG_LEVEL="debug" \ -e GITHUB_COM_TOKEN="$GITHUB_COM_TOKEN" \ -v "/path/to/local/config.js:/usr/src/app/config.js" \ renovate/renovate:"32.6.12" \ --token "$RENOVATE_TOKEN" \ --dry-run="true"
With this, testing Renovate configuration in a fast-feedback loop manner is now possible. In case you need more comprehensive logs, try setting
LOG_LEVEL=”trace”
instead.To perform an actual run, update
--dry-run="false"
.
12 Useful Renovate Bot Tips
General tips
- Not sure how to get the most out of Renovate quickly? Check out this Renovate bot cheat sheet instead of the verboseness of the official Renovate doc.
- 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: false
under the respective[packageRule](https://docs.renovatebot.com/configuration-options/#packagerules)
. Example:
// Example config.js module.exports = { endpoint: 'https://your.domain.com/api/v4/', token: '**gitlab_token**', platform: 'gitlab', onboardingConfig: { extends: ['config:base'], }, repositories: [ { repository: 'john/next-generation-repo', packageRules: [ { description: "'Disable MAJOR update types'," matchUpdateTypes: ['major'], enabled: false, }, ], }, ], }
Need to run some custom task or script after upgrading (e.g. a script that posts messages to Slack)? Try
postUpgradeTasks
.Keep project-specific Renovate configs on the bot repository instead of having
renovate.json
in every other repository. For this, set[onboarding: false](https://docs.renovatebot.com/self-hosted-configuration/#onboarding)
undermodule.exports
. This allows for Renovate-related configs to be abstracted away to a single repository only.
Tips on debugging Renovate jobs
When it comes to self-hosted solutions, there’s no running away from debugging your own 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 to have a faster feedback loop instead of relying on your CI/CD pipelines. Plus, running locally is practically free!
- Use
trace
LOG_LEVEL
in casedebug
doesn’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 ”. (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 attempt to run Renovate on a large repository, you may encounter a
SIGTERM
signal (which can be seen in your Renovate job log) due to timeout. To cope with this, increase the[executionTimeout
setting](https://docs.renovatebot.com/self-hosted-configuration/#executiontimeout) in yourconfig.js
.
// Example config.js module.exports = { endpoint: 'https://your.domain.com/api/v4/', executionTimeout: 1440, // minutes token: '**gitlab_token**', platform: 'gitlab', onboardingConfig: { extends: ['config:base'], }, repositories: ['john/large-repo', 'doe/huge-repo'], };
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.
-
You may want to set
persistRepoData: true
for fastergit fetch
between runs.
// Example config.js module.exports = { endpoint: 'https://your.domain.com/api/v4/', token: '**gitlab_token**', platform: 'gitlab', persistRepoData: true, onboardingConfig: { extends: ['config:base'], }, repositories: ['john/repo'], }
On some occasions, you may run into
ERROR: Disk space error - skipping
. Here, you may want to provision a runner with increased disk size. E.g. if you are using AWS EC2, try to increase the size of the volume.
Conclusion
Over the past few months, I have been using Renovate bot 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 such 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!
This article was originally published on jerrynsh.com
Top comments (0)