Configuring custom dependency managers in Renovate

Published: 2026-09-22

Renovate CI is an amazing tool for managing your dependencies. It has some great support for many dependency sources and is a big part of how I keep my homelab maintained. However, it’s sometimes necessary to declare a dependency using nonstandard syntax or from a source Renovate doesn’t recognize.

With a little bit of regex wizardry, however, you can get Renovate to maintain these kinds of dependencies using the custom-managers key in your renovate.json configurations!

---

Anatomy of a custom manager

A custom manager in Renovate needs to supply these components:

• customType: The means to extract the data; currently Renovate supports regex or jsonata to capture information.
• managerFilePatterns: An array of file patters to scan for information.
• datasourceTemplate: If your custom dependency pulls from an already supported data source, you can instruct Renovate to use a predefined configuration.
• versioningTemplate: Set to follow a preexisting versioning convention.
• matchSrings: An array of regex or JSONata queries to extract specific variables.
• autoReplaceStringTemplate: A Handlebars string instructing Renovate on how new values should be formatted.

Both matchSrings and autoReplaceStringTemplate operate on a specific set of variables:

• depName: The name of the dependency.
• currentValue → newValue: Semantic version or image tag for versioning the dependency.
• currentDigest → newDigest: The digest for pinning the dependency (optional if you don’t pin digests for your images).

Putting it all together

For my own use, I found it helpful to use custom managers for updating blue-build recipe.yaml files. Blue-build recipes are a means to automate generating Containerfiles for Fedora Atomic based operating systems. At the time of writing, there’s no built-in support to parse these recipes. And the Docker manager cannot extract any dependencies properly because the recipe schema defines the image name and the tag in separate keys.

# recipes/recipe.yaml
name: bazzite-dx-niri
base-image: ghcr.io/ublue-os/bazzite-dx-gnome
image-version: stable@sha256:34e2d7c977eb4c1d24ed7dc741b704efff941a99e5d025586911b4b040ab8ec6

Because blue-builds are image based, the already provided docker data source and versioning templates suffice for a new custom manager. One would just need to instruct Renovate on where to look for dependencies, how to extract them, and how to output them. Using the information in the previous section, the custom manager would look like this:

{
	"customManagers": [
    {
      "customType": "regex",
      "managerFilePatterns": ["recipes/recipe.yaml"],
      "matchStrings": [
        "base-image:\\s*(?<depName>[^\\s]+)\\s*\\nimage-version:\\s*(?<currentValue>[^@\\s]+)@(?<currentDigest>sha256:[a-f0-9]{64})"
      ],
      "datasourceTemplate": "docker",
      "versioningTemplate": "docker",
      "autoReplaceStringTemplate": "base-image: {{depName}}\nimage-version: {{newValue}}@{{newDigest}}"
    }
  ]
}

Some things to note:

• The each item in the matchStrings array is one set of dependency variables. The regex you provide has to capture at least depName and currentValue in the same string in order to properly extract a dependency.
• Regex strings in renovate configurations should use capture groups, each one should be named after the previously mentioned variables.
• Regex strings in renovate need to double escape using \\ to properly parse special regex sequences within the string. Otherwise, Renovate will parse regex sequences as escape sequences.

I hope this has been useful. With custom managers, you can open up so many more possibilities of what Renovate can manage for you without having to build your own tooling!