Feedback wanted: complexity in Renovate

[jamietanna]

We (the Renovate maintainers) are seeking community feedback on complexity you may feel when working with Renovate.

We're aware that there are areas that both new and experienced folks can find difficult with Renovate, and are trying to understand what these are, from your point of view.

This prompt is being intentionally vague to not "lead the witness", as we want to hear what you have to say.

This could be for Manager-specific behaviour in Renovate, running Renovate as a self-hosted application, or configuring Renovate to match your team's workflow.

Feel free to share high-level feedback, or share specific areas of complexity you've hit before.

Examples are appreciated, too!

Template:

I am a (select multiple if appropriate):

- [ ] user
- [ ] person in a security-focussed role
- [ ] person in a legal-focussed role
- [ ] self-hosted administrator

Feedback:

<!-- any feedback you have -->

[beisenherz]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

There is always some confusion regarding the merging of several config levels. For example, when are extends applied to the configuration? Are they applied before/after merging the repository config? When will keywords in the repository override the ones in the global context?
I believe a flow diagram of when which configuration gets resolved/merged would be beneficial to have as a lookup.

Generally a (basic) flow diagram of how the configurations get resolved, from starting the renovate CLI, in what order are keywords applied/checked, up to creating MRs in the repository.

[jamietanna]

Documentation indicating this sounds very reasonable! (Especially if we had a way to keep it up-to-date)

#39314 may help with this too, where it'll be possible to see what the "final" config is

[marians]

I am a:

• user

I find it difficult to get customManagers (regex based managers) working. In some cases I gave up, as after several slow round-trips of config changes and waiting for renovate to succeed, then reading logs, I didn't find it important enough to justify the effort. In this case I would wish for a local method that would make it easy for me to test my config. (It may be that all this exists. Take it as a sign of complexity that I failed to figure it out.)

[gaeljw]

+1 on this, I've now got a few examples that I reuse to build new custom managers but getting the first one to work and how to test it easily was definitely not easy.

[jamietanna]

#41753 might help in the meantime

[jankatins]

I am a (select multiple if appropriate):

• user
• self-hosted administrator

Feedback:

I setup renovate in a bigger project with ~100 repos (self hosted, azure). Initially only a few repos opted in, now it's for everyone. We run it in a CI Pipeline which split the "found" repos across multiple Jobs.

• Setting up renovate in a ci pipeline is not well documented, especially to get all the package managers, the authentication, ... together. Some clear setup best practises for this would be helpful, especially for typical self host scenarios (azure devops :-)).
  • It would be really nice to have an easier "run locally" mode, I could never get that to work as some PATs and whatnot were missing.
• debugging problems with package manager and our own mirror of pypi/npm/java/dotnet via the azure artifact repositories was (and is) a pain: it took ages to see what went wrong and figuring out why e.g. delayed updates didn't work took ages (azure pypi mirror does not support release info so we need to "rewrite" it to the original pypi sources; npm adds release timestamps, but for the time it got imported, so renovate updates after x days, just to have it refused by pnpm as the timestamp in azure registry is too young) -> it's all possible as the flexibility is sooooo big and everything is possible, but this is also clunky as hell and not well documented.
• It took me awhile to understand how to match on all packages as matchCategories = ["*"] does not match pre-commit (I still don't understand why, just that I need to match on package name = "*").
• We have local presets, but these cannot be tested, you have to push to main to make them available to a repo you run on. We wasted hours until we (first me, then another person until they asked :-)) understood that trying a fix in a branch (which changes config and preset) will only test the config changes, but not the presets. Maybe a "override preset default branch" or so would be nice for testing?

[br3ndonland]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

I think there are some easy wins related to configuration that would help manage complexity.

For one - please just decide on a config file format and use that consistently.

As an admin of a self-hosted Renovate instance, I've found this rather confusing. Renovate config files are supposedly JSONC, but then only support .json or .json5 file extensions (#36141). The docs say,

Renovate supports JSONC for .json files and any config files without file extension (e.g. .renovaterc). We also recommend you prefer using JSONC within a .json file to using a .json5 file if you want to add comments.

Kinda confusing so far. Updates to .gitattributes and files.associations in VSCode settings are needed for proper syntax highlighting and linting when using JSONC with non-.jsonc files.

But then... the config actually doesn't allow JSONC? Running

npx --yes --package renovate -- renovate-config-validator --strict

on this JSONC config file named .renovaterc (expand)

// https://docs.renovatebot.com/configuration-options/
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "addLabels": ["dependencies"],
  "enabledManagers": ["github-actions", "terraform"],
  "extends": ["config:recommended"],
  "lockFileMaintenance": {
    "enabled": true,
    "recreateWhen": "auto",
    "rebaseWhen": "auto",
    "branchTopic": "lockfile",
    "commitMessageAction": "Update",
    "commitMessageTopic": "lockfile",
    "schedule": ["* 8-20 * * *"],
  },
  // https://docs.renovatebot.com/key-concepts/minimum-release-age/
  "minimumReleaseAge": "3 days",
  "packageRules": [
    // automerge only patch version updates
    // https://docs.renovatebot.com/key-concepts/automerge/
    {
      "matchUpdateTypes": ["patch"],
      "automerge": true,
    },
    {
      "matchDatasources": ["terraform-provider", "terraform-module"],
      "registryUrls": ["https://registry.opentofu.org"],
    },
    {
      "matchManagers": ["github-actions"],
      "commitMessagePrefix": "JIRA-1234",
    },
    {
      "matchManagers": ["terraform"],
      "commitMessagePrefix": "JIRA-123",
    },
  ],
  "prConcurrentLimit": 5,
  "prHourlyLimit": 5,
  "rangeStrategy": "update-lockfile",
  "vulnerabilityAlerts": {
    "addLabels": ["dependencies", "security"],
    "enabled": true,
  },
}

returns "Config validated successfully" (#40330)

INFO: Validating .renovaterc
INFO: Config validated successfully

Then running renovatebot/github-action@v46.1.7 (latest) seems to detect valid configs (expand)...

INFO: Renovate started
      "renovateVersion": "43.104.0"
DEBUG: Using RE2 regex engine
DEBUG: Parsing configs
DEBUG: Checking for config file in /github-action/.renovaterc
DEBUG: No additional config file found specified - skipping
DEBUG: File config
       "config": {
         "$schema": "https://docs.renovatebot.com/renovate-schema.json",
         "addLabels": ["dependencies"],
         "enabledManagers": ["github-actions", "terraform"],
         "extends": ["config:recommended"],
         "lockFileMaintenance": {
           "enabled": true,
           "recreateWhen": "auto",
           "rebaseWhen": "auto",
           "branchTopic": "lockfile",
           "commitMessageAction": "Update",
           "commitMessageTopic": "lockfile",
           "schedule": ["* 8-20 * * *"]
         },
         "minimumReleaseAge": "3 days",
         "packageRules": [
           {"matchUpdateTypes": ["patch"], "automerge": true},
           {
             "matchDatasources": ["terraform-provider", "terraform-module"],
             "registryUrls": ["https://registry.opentofu.org"]
           },
           {"matchManagers": ["github-actions"], "commitMessagePrefix": "JIRA-1234"},
           {"matchManagers": ["terraform"], "commitMessagePrefix": "JIRA-123"}
         ],
         "prConcurrentLimit": 5,
         "prHourlyLimit": 5,
         "rangeStrategy": "update-lockfile",
         "vulnerabilityAlerts": {
           "addLabels": ["dependencies", "security"],
           "enabled": true
         }
       }
DEBUG: Additional file config
       "config": {}
DEBUG: CLI config
       "config": {}
DEBUG: Env config
       "config": {
         "hostRules": [],
         "token": "***********",
         "repositories": ["org/repo"]
       }
DEBUG: Resolved global extends
       "config": undefined
DEBUG: Combined config
       "config": {
         "$schema": "https://docs.renovatebot.com/renovate-schema.json",
         "addLabels": ["dependencies"],
         "enabledManagers": ["github-actions", "terraform"],
         "extends": ["config:recommended"],
         "lockFileMaintenance": {
           "enabled": true,
           "recreateWhen": "auto",
           "rebaseWhen": "auto",
           "branchTopic": "lockfile",
           "commitMessageAction": "Update",
           "commitMessageTopic": "lockfile",
           "schedule": ["* 8-20 * * *"]
         },
         "minimumReleaseAge": "3 days",
         "packageRules": [
           {"matchUpdateTypes": ["patch"], "automerge": true},
           {
             "matchDatasources": ["terraform-provider", "terraform-module"],
             "registryUrls": ["https://registry.opentofu.org"]
           },
          {"matchManagers": ["github-actions"], "commitMessagePrefix": "JIRA-1234"},
           {"matchManagers": ["terraform"], "commitMessagePrefix": "JIRA-123"}
         ],
         "prConcurrentLimit": 5,
         "prHourlyLimit": 5,
         "rangeStrategy": "update-lockfile",
         "vulnerabilityAlerts": {
           "addLabels": ["dependencies", "security"],
           "enabled": true
         },
         "hostRules": [],
         "token": "***********",
         "repositories": ["org/repo"]
       }

But then says the config is actually invalid...

DEBUG: Found .renovaterc config file (repository=org/repo)
 WARN: Repository has invalid config (repository=org/repo)
       "error": {
         "validationSource": ".renovaterc",
         "validationError": "Invalid JSON (parsing failed)",
         "validationMessage": "Syntax error: expecting String near ],\n  },\n  ",
         "message": "config-validation",
         "stack": "Error: config-validation\n    at checkForRepoConfigError

Then the action reports a success outcome, but does nothing.

So... is the JSONC config valid or not?

I resorted to just using JSON syntax.

[jamietanna]

Apologies for the confusion! As of #43677 and #43680 it's now possible to use a .jsonc file - this and recent changes appear to have fixed that inconsistency!

[marcaurele]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:
I found it difficult to find the correct recipe to have doubled versioned container images to work (python:3.14.5-alpine3.23). The only stable way despite all the available information (GH issues and discussions or blog post) was through regexp with capture groups as explained here: https://docs.renovatebot.com/modules/manager/regex/#regular-expression-capture-groups

It would be very helpful to have that double syntax built-in I believe. We can agree that it's a common pattern, and the limit is of having 2 dependency versions built in the tag.

[wrslatz]

Shared a similar request with some linked related discussions or issues in #41413 (comment)

[vickysgd]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

I am a new user and have difficulties understandig, what the individual configuration options do. Many of them are explained thoroughly somewhere in the documentation. It would help me tremendously, if you could create links from the options to their explanation in the documentation.
BTW at first I was having trouble finding the options at all, because they are buried in configuration -> repository. I had been looking for a chapter called "reference".
But overall: Great documentation! Keep it up!

[gzm0]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

• Repository config docs: Some more grouping / scoping of the options would help when looking for features. (as in: "these options will only affect PR creation", etc.)
• A major pain point for us is unaddressed pending updates which use up branch / pr limit slots.

[ajacques]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

I find it confusing to create packageRules. I get in theory how they work by reading the documentation, but I get stuck when Renovate doesn't do what I expect it to do. For example, I try to get date based versions working. I can't simulate Renovate or understand what Renovate is doing under the hood.

Running the CLI is tricky requiring a long command (I put this in my package.json)

"renovate": "docker run --rm -ti -e LOG_LEVEL=DEBUG -w /app -e RENOVATE_CONFIG_FILE=/usr/src/app/config.json -v $(pwd):/app -v $(pwd)/renovate2.json:/usr/src/app/config.json ghcr.io/renovatebot/renovate --platform=local | tee renovate.log"

It gives me a lot of log statements, but 99% of the log statements are entirely irrelevant. Looking at a recent log file, I see a lot of logs related to caching, or statements around Docker tags exceeding maxMajorIncrements from years ago, or Docker tags. Not all deps get any log statements, the one I'm interested in just says "there's no updates", so clearly one of my package rules didn't work. It seems like I get all or nothing for logging. I want to be able to see more about why Renovate picked certain versions or didn't, in a easier to digest way. Something that breaks down per dep, it matched these rules, then those rules meant it looked at these versions.

[calle2010]

I totally agree. Most of the time documentation is not enough to understand how to use a feature. Debug logs give me hints, but they are painful to read. As a tangible step, purely technical logs could be demoted to a TRACE level to avoid cluttering the logs with hundreds of messages like

DEBUG: ensureIssue() (repository=x/y)
DEBUG: Using Bearer authentication (JWT detected) (repository=x/y)
DEBUG: getIssueList() (repository=x/y)
DEBUG: Using Bearer authentication (JWT detected) (x/y)
DEBUG: Using Bearer authentication (JWT detected) (x/y)

Logs around logic, decisions, actual values found, should be separated from the technical things.

[jamietanna]

documentation is not enough to understand how to use a feature.

Do you have any specific examples of areas that you've found the documentation lacking?

[ddbtrmatic]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

I self-host renovate via Gitlab CI for a few dozen projects.

The documentation website has a ton of information, but it is not well organized, leading to some confusion. Particularly when searching directly for something like npm, you might end up on several different pages and sections. It becomes unclear if the section I'm reading applies to my use case or not (main config vs repo config, self hosted vs mend-hosted, etc.).

[rQcAnE4pk15VDHVa]

I am new to renovate, hosting in Azure DevOps pipelines and a:

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

I find it hard to unterstand the internal status checks and how they are manipulated using all the different config parameters. A few times I thought that I finally understand them and then a new pipeline run proves me wrong, again. :-D

[lucas-szczepaniak]

I am a:

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

I am a self-hosted Renovate user running it in Azure DevOps for a GitOps repository with Argo CD and Istio.

The setup was easy at first, but became more complex once I needed managerFilePatterns, regex customManagers, grouped updates, and PR-only workflows.

The hardest part was understanding when built-in managers are enough and when a custom manager is needed.

A small cookbook with real examples for Argo CD, regex managers, grouped Helm updates, Azure DevOps self-hosting, and local testing would have helped a lot.

I am going to document my working setup in an article because I could not find one end-to-end example from scheduled Renovate run to the final PR.

[macmenco]

I am a (select multiple if appropriate):

• user
• person in a security-focussed role
• person in a legal-focussed role
• self-hosted administrator

Feedback:

I find the documentation about the hostRules.httpsCertificateAuthority to minimal. Should the name of the CA be put in the variable? Should the CA certificate then be put in the truststore of the system? Or stored somewhere else on disk? Or should the CA certifacte, as PEM, be put into the variable? How about if one has multiple custom CAs?

In general, when dealing with custom CAs, the config is very hard... Should NODE_EXTRA_CA_CERTS, GIT_SSL_CAINFO and/or NPM_CONFIG_cafile be used?