Use custom managers in Renovate

Mend Renovate is a wonderful set-and-forget utility that helps you keep your project’s dependencies up to date. It’s similar to Dependabot, only much better regarding automatic dependency discovery, and configurability. Once you grant Renovate access to your Git repo, it’ll automatically open pull/merge requests once it detects new dependency updates. It supports GitHub, GitLab, and BitBucket. The community version is free (both self-hosted and cloud option).

While Renovate supports many package managers, such as Docker, deb, GitHub/GitLab releases, Helm, NPM, and Pypi, you can also use so-called customManagers to instruct Renovate to detect dependencies in configuration files that aren’t supported out-of-the-box. E.g. when your project depends on a DEB package from a 3rd-party Apt repository or a binary published as a GitHub release. And this brings me to…

How to configure Renovate custom managers

Sometimes we have dependencies in awkward places, and they can get neglected because of that. For example, we might have a Dockerfile in which we’re downloading prebuilt Terraform binary. Instead of hardcoding the download URL, we can define the Terraform version as a build argument, and instruct Renovate how to detect it and how to use the value when checking for updates.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

ARG TERRAFORM_VERSION="1.9.7" # github-tags/hashicorp/terraform&versioning=semver

FROM debian:12.7-slim
ARG TERRAFORM_VERSION
ARG TARGETARCH
ENV DEBIAN_FRONTEND=noninteractive

RUN useradd -m terraform -s /bin/bash \
&& apt-get update && apt-get upgrade -V -y \
&& apt-get install -V -y curl unzip \
&& mkdir -p /tmp/terraform \
&& cd /tmp/terraform && curl -o terraform.zip "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_${TARGETARCH}.zip" \
&& unzip terraform.zip && mv terraform /usr/local/bin/ \
&& find /usr/local/bin/ -type f -exec chmod 755 {} \; \
&& rm -rfv /tmp/* /var/lib/apt/lists/*

USER terraform:terraform
ENTRYPOINT ["terraform"]
CMD ["-help"]

The comment in line 1 is important because with it we’ll give Renovate a hint about what datasource, GitHub repository, and versioning scheme to use to detect new updates. Meanwhile, in renovate.json configuration file, we’ll have customManagers configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
  ],
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": ["^Dockerfile$"],
      "matchStringsStrategy": "any",
      "matchStrings": [
        "ARG [A-Z]+_VERSION=\"(?<currentValue>.*)\" # (?<datasource>.*?)/(?<depName>.*?)(\\&versioning=(?<versioning>.*?))?\\s"
      ],
      "datasourceTemplate": "github-releases"
    }
  ]
}

In essence, we’ve instructed Renovate to parse Dockerfile in the root of our project and look for lines that contain build arguments with _VERSION suffix. In the same line, we’ve instructed Renovate how to recognize the current version, along with the aforementioned datasource, GitHub repo, and versioning scheme information.

In a similar fashion, we can use a different datasourceTemplate to detect updates to deb packages in a third-party Apt repository. Let’s say we have a Dockerfile for a PHP-FPM image, and that we’re depending on a specific version of the deb package from deb.sury.org repository.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

ARG PHP_DEB="8.3.11" # php8.3-fpm
ARG PHPVER="8.3"

FROM debian:12.6-slim
ARG PHPVER
ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get upgrade -V -y \
&& apt-get install -V -y lsb-release ca-certificates curl \
&& curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb \
&& dpkg -i /tmp/debsuryorg-archive-keyring.deb \
&& echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list \
&& apt-get update && apt-get install -V -y \
"php${PHPVER}-fpm=${PHP_DEB}*" \
&& rm -rfv /tmp/* /var/lib/apt/lists/*
...

In the first line, we’ve declared build argument PHP-DEB that contains package version. In the same line we’ve defined a special comment, that we’ll use to give Renovate a hint on what deb package to look up for. This time, in renovate.json configuration file, we’ll have to play around with a few more options to get what we want. A great way to demonstrate Renovate’s configurability 😀

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended"
  ],
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": ["^Dockerfile$"],
      "matchStringsStrategy": "any",
      "matchStrings": [
        "ARG [A-Z]+_DEB=\"(?<currentValue>.*)\" # (?<depName>.*?)\\s"
      ],
      "datasourceTemplate": "deb",
      "registryUrlTemplate": "https://packages.sury.org/php?suite=bookworm&components=main&binaryArch=amd64",
      "extractVersionTemplate": "^(?<version>\\d+\\.\\d+\\.\\d+)"
    }
  ]
}

Similar to the previous example, here we’ve also told Renovate to parse Dockerfile. This time we defined that it should look for the build argument with _DEB suffix and find the deb package name from the comment in the same line.

registryUrlTemplate is an important parameter, because this is how Renovate knows about the location of the Apt repository, as well as the repository’s metaparameters required to find the right package (suite, component, and architecture).

Last but not least, the extractVersionTemplate parameter is optional. It allows us to manipulate the version string of the found update. In our example, the Apt repository contains deb packages with a pretty long version string (e.g. 8.3.16-1+0~20250119.51+debian12~1.gbpd60bd2). This is because the packages are rebuilt frequently, but the updated packages don’t necessarily contain the new PHP version. This means that the PHP version at the beginning of the string remains the same, while the rest of the string changes whenever the package is rebuilt.

To minimize the number of pull requests opened by Renovate bot because of frequent deb rebuilds, with extractVersionTemplate parameter we can tell Renovate to extract only the first part of the version string using regex (i.e. the exact PHP version) and get PRs only when the new PHP version is released. Noice! 😎

How to validate Renovate configuration

Renovate is extremely configurable, but let’s face it, the JSON configuration file isn’t exactly human-friendly. We have to comply with the Renovate JSON schema, occasionally escape some characters, and watch out for parameter values. Once we’ve updated the configuration, we still don’t know for sure if Renovate bot will encounter an error or if our changes yield the expected result.

Thankfully, there’s a way to test the Renovate configuration, and it involves running Renovate CLI. My preferred way is to run Renovate in a Docker container.

docker run --rm -v /path/to/your/git/repo:/repo -w /repo -e LOG_LEVEL=debug -e GITHUB_COM_TOKEN=github_pat_XXXXXXXXXXXXXXXXXXXXXXXX renovate/renovate:39.150 --platform=local --repository-cache=reset

The above command is pretty self-explanatory. It runs the official Renovate container published on the Docker hub against the bind-mounted Git repository on our local filesystem. The LOG_LEVEL environment variable tells Renovate to print, well, debug-level output. The GITHUB_COM_TOKEN is optional, but necessary if you want Renovate to use github-releases datasource. If your dependencies are hosted in public repositories, then it’s sufficient that your GitHub PAT (Personal Access Token) has just “Public Repositories (read-only)” privilege enabled.

The command will trigger a single Renovate run. It won’t open any pull request, it will only scan the repository and print details about found dependency updates. If there’s something wrong with the renovate.json, a configuration error will be mentioned.

While not exactly user-friendly, this configtest method is functional.