configuration-options.md

---
title: Configuration Options
description: Configuration Options usable in renovate.json or package.json
---

# Configuration Options

This document describes all the configuration options you may use in a Renovate configuration file.
Any config you define applies to the whole repository (e.g. if you have a monorepo).

You can store your Renovate configuration file in one of these locations:

1. `renovate.json`
1. `renovate.json5`
1. `.github/renovate.json`
1. `.github/renovate.json5`
1. `.gitlab/renovate.json`
1. `.gitlab/renovate.json5`
1. `.renovaterc`
1. `.renovaterc.json`
1. `.renovaterc.json5`
1. `package.json` _(within a `"renovate"` section)_

<!-- prettier-ignore -->
!!! warning
    Storing the Renovate configuration in a `package.json` file is deprecated and support may be removed in the future.

When Renovate runs on a repository, it tries to find the configuration files in the order listed above.
Renovate stops the search after it finds the first match.

Renovate always uses the config from the repository's default branch, even if that configuration specifies multiple `baseBranches`.
Renovate does not read/override the config from within each base branch if present.

Also, be sure to check out Renovate's [shareable config presets](./config-presets.md) to save yourself from reinventing any wheels.
Shareable config presets only work with the JSON format.

If you have any questions about the config options, or want to get help/feedback about a config, go to the [discussions tab in the Renovate repository](https://github.com/renovatebot/renovate/discussions) and start a new "config help" discussion.
We will do our best to answer your question(s).

A `subtype` in the configuration table specifies what type you're allowed to use within the main element.

If a config option has a `parent` defined, it means it's only allowed to configure it within an object with the parent name, such as `packageRules` or `hostRules`.

When an array or object configuration option is `mergeable`, it means that values inside it will be added to any existing object or array that existed with the same name.

<!-- prettier-ignore -->
!!! note
    Config options with `type=string` are always non-mergeable, so `mergeable=false`.

---

## addLabels

The `labels` field is non-mergeable, meaning that any config setting a list of PR labels will replace any existing list.
If you want to append labels for matched rules, then define an `addLabels` array with one (or more) label strings.
All matched `addLabels` strings will be attached to the PR.

Consider this example:

```json
{
  "labels": ["dependencies"],
  "packageRules": [
    {
      "matchPackagePatterns": ["eslint"],
      "labels": ["linting"]
    },
    {
      "matchDepTypes": ["optionalDependencies"],
      "addLabels": ["optional"]
    }
  ]
}
```

With the above config:

- Optional dependencies will have the labels `dependencies` and `optional`
- ESLint dependencies will have the label `linting`
- All other dependencies will have the label `dependencies`

## additionalBranchPrefix

By default, the value for this config option is an empty string.
Normally you don't need to set this config option.

Here's an example where `additionalBranchPrefix` can help you.
Say you're using a monorepo and want to split pull requests based on the location of the package definition, so that individual teams can manage their own Renovate pull requests.
This can be done with this configuration:

```json
{
  "additionalBranchPrefix": "{{parentDir}}-"
}
```

## additionalReviewers

This option _adds_ to the existing reviewer list, rather than _replacing_ it like `reviewers`.

Use `additionalReviewers` when you want to add to a preset or base list, without replacing the original.
For example, when adding focused reviewers for a specific package group.

## assignAutomerge

By default, Renovate will not assign reviewers and assignees to an automerge-enabled PR unless it fails status checks.
By configuring this setting to `true`, Renovate will instead always assign reviewers and assignees for automerging PRs at time of creation.

## assignees

Must be valid usernames on the platform in use.

## assigneesFromCodeOwners

If enabled Renovate tries to determine PR assignees by matching rules defined in a CODEOWNERS file against the changes in the PR.

Read the docs for your platform for details on syntax and allowed file locations:

- [GitHub Docs, About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
- [GitLab, Code Owners](https://docs.gitlab.com/ee/user/project/code_owners.html)
- [Bitbucket, Set up and use code owners](https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-use-code-owners/)

## assigneesSampleSize

If configured, Renovate will take a random sample of given size from assignees and assign them only, instead of assigning the entire list of `assignees` you have configured.

## autoApprove

Setting this to `true` will automatically approve the PRs.

You can also configure this using `packageRules` if you want to use it selectively (e.g. per-package).

## autoReplaceGlobalMatch

Setting this to `false` will replace only the first match during replacements updates.

Disabling this is useful for situations where values are repeated within the dependency string, such as when the `currentVersion` is also featured somewhere within the `currentDigest`, but you only want to replace the first instance.

Consider this example:

```dockerfile
FROM java:8@sha256:0e8b2a860
```

```json
{
  "packageRules": [
    {
      "matchPackageNames": ["java"],
      "replacementName": "eclipse-temurin",
      "replacementVersion": "11"
    }
  ]
}
```

With the above replacement scenario, the current dependency has a version of `8`, which also features several times within the digest section.

When using the default `autoReplaceGlobalMatch` configuration, Renovate will try to replace all instances of `8` within the dependency string with the `replacementVersion` value of `11`.
This will replace more than is intended and will be caught during replacement validation steps, resulting in the replacement PR to not be created.

When setting `autoReplaceGlobalMatch` configuration to `false`, Renovate will only replace the first occurrence of `8` and will successfully create a replacement PR.

## automerge

By default, Renovate raises PRs but leaves them to someone or something else to merge them.
By configuring this setting, you allow Renovate to automerge PRs or even branches.
Using automerge reduces the amount of human intervention required.

Usually you won't want to automerge _all_ PRs, for example most people would want to leave major dependency updates to a human to review first.
You could configure Renovate to automerge all but major this way:

```json
{
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch", "pin", "digest"],
      "automerge": true
    }
  ]
}
```

Also note that this option can be combined with other nested settings, such as dependency type.
So for example you could choose to automerge all (passing) `devDependencies` only this way:

```json
{
  "packageRules": [
    {
      "matchDepTypes": ["devDependencies"],
      "automerge": true
    }
  ]
}
```

<!-- prettier-ignore -->
!!! note
    Branches creation follows [`schedule`](#schedule) and the automerge follows [`automergeSchedule`](#automergeschedule).

<!-- prettier-ignore -->
!!! warning "Negative reviews on GitHub block Renovate automerge"
    Renovate won't automerge on GitHub if a PR has a negative review.

<!-- prettier-ignore -->
!!! note
    On Azure there can be a delay between a PR being set as completed by Renovate, and Azure merging the PR / finishing its tasks.
    Renovate tries to delay until Azure is in the expected state, but it will continue if it takes too long.
    In some cases this can result in a dependency not being merged, and a fresh PR being created for the dependency.

**Automerge and GitHub branch protection rules**

You must select at least one status check in the _Require status checks to pass before merging_ section of your branch protection rules on GitHub, if you match all three conditions:

- `automerge=true`
- `platformAutomerge=true`, Renovate defaults to `true`
- You use GitHub's _Require status checks to pass before merging_ branch protection rule

If you don't select any status check, and you use platform automerge, then GitHub might automerge PRs with failing tests!

## automergeComment

Use this only if you configure `automergeType="pr-comment"`.

Example use:

```json
{
  "automerge": true,
  "automergeType": "pr-comment",
  "automergeComment": "bors: r+"
}
```

## automergeSchedule

Use the `automergeSchedule` option to define times of week or month during which Renovate may automerge its PRs.
The default value for `automergeSchedule` is "at any time", which functions the same as setting a `null` schedule.
To configure this option refer to [`schedule`](#schedule) as the syntax is the same.

<!-- prettier-ignore -->
!!! warning
    When `platformAutomerge` is enabled, Renovate enqueues the platform PR automerge at time of creation, so the schedule specified in `automergeSchedule` cannot be followed.
    If it's essential that automerging only happens within the specific `automergeSchedule` time window, then you need to set `platformAutomerge` to `false` and instead rely on Renovate's automerge instead of the platform one.

## automergeStrategy

The automerge strategy defaults to `auto`, so Renovate decides how to merge pull requests as best it can.
If possible, Renovate follows the merge strategy set on the platform itself for the repository.

If you've set `automerge=true` and `automergeType=pr` for any of your dependencies, then you may choose what automerge strategy Renovate uses by setting the `automergeStrategy` config option.
If you're happy with the default behavior, you don't need to do anything.

You may choose from these values:

- `auto`, Renovate decides how to merge
- `fast-forward`, "fast-forwarding" the main branch reference, no new commits in the resultant tree
- `merge-commit`, create a new merge commit
- `rebase`, rewrite history as part of the merge, but usually keep the individual commits
- `squash`, flatten the commits that are being merged into a single new commit

Platforms may only support _some_ of these merge strategies.

If the chosen automerge strategy is not supported on your platform then Renovate stops automerging.
In that case you'll have to set a supported automerge strategy.

## automergeType

This setting is only applicable if you opt in to configure `automerge` to `true` for any of your dependencies.

Automerging defaults to using Pull Requests (`automergeType="pr"`).
In that case Renovate first creates a branch and associated Pull Request, and then automerges the PR on a subsequent run once it detects the PR's status checks are "green".
If by the next run the PR is already behind the base branch it will be automatically rebased, because Renovate only automerges branches which are up-to-date and green.
If Renovate is scheduled for hourly runs on the repository but commits are made every 15 minutes to the main branch, then an automerge like this will keep getting deferred with every rebase.

<!-- prettier-ignore -->
!!! tip
    If you have no tests but still want Renovate to automerge, you need to add `"ignoreTests": true` to your configuration.

If you prefer that Renovate more silently automerge _without_ Pull Requests at all, you can configure `"automergeType": "branch"`. In this case Renovate will:

- Create the branch, wait for test results
- Rebase it any time it gets out of date with the base branch
- Automerge the branch commit if it's: (a) up-to-date with the base branch, and (b) passing all tests
- As a backup, raise a PR only if either: (a) tests fail, or (b) tests remain pending for too long (default: 24 hours)

The final value for `automergeType` is `"pr-comment"`, intended only for users who already have a "merge bot" such as [bors-ng](https://github.com/bors-ng/bors-ng) and want Renovate to _not_ actually automerge by itself and instead tell `bors-ng` to merge for it, by using a comment in the PR.
If you're not already using `bors-ng` or similar, don't worry about this option.

## azureWorkItemId

When creating a PR in Azure DevOps, some branches can be protected with branch policies to [check for linked work items](https://docs.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops#check-for-linked-work-items).
Creating a work item in Azure DevOps is beyond the scope of Renovate, but Renovate can link an already existing work item when creating PRs.

## baseBranches

By default, Renovate will detect and process only the repository's default branch.
For most projects, this is the expected approach.
Renovate also allows users to explicitly configure `baseBranches`, e.g. for use cases such as:

- You wish Renovate to process only a non-default branch, e.g. `dev`: `"baseBranches": ["dev"]`
- You have multiple release streams you need Renovate to keep up to date, e.g. in branches `main` and `next`: `"baseBranches": ["main", "next"]`
- You want to update your main branch and consistently named release branches, e.g. `main` and `release/<version>`: `"baseBranches": ["main", "/^release\\/.*/"]`

It's possible to add this setting into the `renovate.json` file as part of the "Configure Renovate" onboarding PR.
If so then Renovate will reflect this setting in its description and use package file contents from the custom base branch(es) instead of default.

`baseBranches` supports Regular Expressions that must begin and end with `/`, e.g.:

```json
{
  "baseBranches": ["main", "/^release\\/.*/"]
}
```

You can negate the regex by prefixing it with `!`.
Only use a single negation and do not mix it with other branch names, since all branches are combined with `or`.
With a negation, all branches except those matching the regex will be added to the result:

```json
{
  "baseBranches": ["!/^pre-release\\/.*/"]
}
```

You can also use the special `"$default"` string to denote the repository's default branch, which is useful if you have it in an org preset, e.g.:

```json
{
  "baseBranches": ["$default", "/^release\\/.*/"]
}
```

<!-- prettier-ignore -->
!!! note
    Do _not_ use the `baseBranches` config option when you've set a `forkToken`.
    You may need a `forkToken` when you're using the Forking Renovate app.

## bbUseDefaultReviewers

Configuring this to `true` means that Renovate will detect and apply the default reviewers rules to PRs (Bitbucket only).

## branchConcurrentLimit

By default, Renovate won't enforce any concurrent branch limits.
The `config:recommended` preset that many extend from limits the number of concurrent branches to 10, but in many cases a limit as low as 3 or 5 can be most efficient for a repository.

If you want the same limit for both concurrent branches and concurrent PRs, then set a value for `prConcurrentLimit` and it will be re-used for branch calculations too.
But if you want to allow more concurrent branches than concurrent PRs, you can configure both values (e.g. `branchConcurrentLimit=5` and `prConcurrentLimit=3`).

This limit is enforced on a per-repository basis.

Example config:

```json
{
  "branchConcurrentLimit": 3
}
```

<!-- prettier-ignore -->
!!! warning
    Leaving PRs/branches as unlimited or as a high number increases the time it takes for Renovate to process a repository.
    If you find that Renovate is too slow when rebasing out-of-date branches, decrease the `branchConcurrentLimit`.

If you have too many concurrent branches which rebase themselves each run, Renovate can take a lot of time to rebase.
Solutions:

- Decrease the concurrent branch limit (note: this won't go and delete any existing, so won't have an effect until you either merge or close existing ones manually)
- Remove automerge and/or automatic rebasing (set `rebaseWhen` to `conflicted`). However if you have branch protection saying PRs must be up to date then it's not ideal to remove automatic rebasing

## branchName

If you truly need to configure this then it probably means either:

- You are hopefully mistaken, and there's a better approach you should use, so open a new "config help" discussion at the [Renovate discussions tab](https://github.com/renovatebot/renovate/discussions) or
- You have a use case we didn't expect, please open a discussion to see if we want to get a feature request from you

## branchNameStrict

If `true`, Renovate removes special characters when slugifying the branch name:

- all special characters are removed
- only alphabetic characters are allowed
- hyphens `-` are used to separate sections

The default `false` behavior will mean that special characters like `.` may end up in the branch name.

## branchPrefix

You can modify this field if you want to change the prefix used.
For example if you want branches to be like `deps/eslint-4.x` instead of `renovate/eslint-4.x` then you configure `branchPrefix` = `deps/`.
Or if you wish to avoid forward slashes in branch names then you could use `renovate_` instead, for example.

`branchPrefix` must be configured at the root of the configuration (e.g. not within any package rule) and is not allowed to use template values.
e.g. instead of `renovate/{{parentDir}}-`, configure the template part in `additionalBranchPrefix`, like `"additionalBranchPrefix": "{{parentDir}}-"`.

<!-- prettier-ignore -->
!!! note
    This setting does not change the default _onboarding_ branch name, i.e. `renovate/configure`.
    If you wish to change that too, you need to also configure the field `onboardingBranch` in your global bot config.

## branchPrefixOld

Renovate uses branch names as part of its checks to see if an update PR was created previously, and already merged or ignored.
If you change `branchPrefix`, then no previously closed PRs will match, which could lead to Renovate recreating PRs in such cases.
Instead, set the old `branchPrefix` value as `branchPrefixOld` to allow Renovate to look for those branches too, and avoid this happening.

## branchTopic

This field is combined with `branchPrefix` and `additionalBranchPrefix` to form the full `branchName`. `branchName` uniqueness is important for dependency update grouping or non-grouping so be cautious about ever editing this field manually.
This is an advanced field, and it's recommend you seek a config review before applying it.

## bumpVersion

Currently, this config option only works with these managers:

- `cargo`
- `helmv3`
- `npm`
- `nuget`
- `maven`
- `ocb`
- `pep621`
- `poetry`
- `sbt`

Raise a feature request if you want to use this config option with other package managers.

Use `bumpVersion` if you want Renovate to update the `version` field in your package file when it updates the dependencies in that file.
This can be handy when you have automated your package's release, as you you don't need extra steps after the Renovate upgrade, you can just release a new version.

Configure this value to `"prerelease"`, `"patch"`, `"minor"` or `"major"` to have Renovate update the version in your edited package file.
e.g. if you wish Renovate to always increase the target `package.json` version with a patch update, configure this to `"patch"`.

For `npm` only you can also configure this field to `"mirror:x"` where `x` is the name of a package in the `package.json`.
Doing so means that the `package.json` `version` field will mirror whatever the version is that `x` depended on.
Make sure that version is a pinned version of course, as otherwise it won't be valid.

For `sbt` note that Renovate will update the version string only for packages that have the version string in their project's `built.sbt` file.

## cloneSubmodules

Enabling this option will mean that any detected Git submodules will be cloned at time of repository clone.

Important: private submodules aren't supported by Renovate, unless the underlying `ssh` layer already has the correct permissions.

## commitBody

Configure this if you wish Renovate to add a commit body, otherwise Renovate uses a regular single-line commit.

For example, To add `[skip ci]` to every commit you could configure:

```json
{
  "commitBody": "[skip ci]"
}
```

Another example would be if you want to configure a DCO sign off to each commit.

If you want Renovate to sign off its commits, add the [`:gitSignOff` preset](./presets-default.md#gitsignoff) to your `extends` array:

```json
{
  "extends": [":gitSignOff"]
}
```

## commitBodyTable

## commitMessage

## commitMessageAction

This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string.
Actions may be like `Update`, `Pin`, `Roll back`, `Refresh`, etc.
Check out the default value for `commitMessage` to understand how this field is used.

## commitMessageExtra

This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string.
The "extra" is usually an identifier of the new version, e.g. "to v1.3.2" or "to tag 9.2".

## commitMessageLowerCase

With `semanticCommits` pr- and commit-titles will by default (`"auto"`) be converted to all-lowercase.
Set this to `"never"` to leave the titles untouched, allowing uppercase characters in semantic commit titles.

## commitMessagePrefix

This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string.
The "prefix" is usually an automatically applied semantic commit prefix, but it can also be statically configured.

## commitMessageSuffix

This is used to add a suffix to commit messages.
Usually left empty except for internal use (multiple base branches, and vulnerability alerts).

## commitMessageTopic

You can use `commitMessageTopic` to change the `commitMessage` and `prTitle` without copy/pasting the whole string.
The "topic" usually refers to the dependency being updated, for example: `"dependency react"`.

We recommend you use `matchManagers` and `commitMessageTopic` in a `packageRules` array to set the commit message topic, like this:

```json
{
  "packageRules": [
    {
      "matchManagers": ["github-actions"],
      "commitMessageTopic": "{{depName}}"
    }
  ]
}
```

## composerIgnorePlatformReqs

By default, Renovate will ignore Composer platform requirements as the PHP platform used by Renovate most probably won't match the required PHP environment of your project as configured in your `composer.json` file.

Composer `2.2` and up will be run with `--ignore-platform-req='ext-*' --ignore-platform-req='lib-*'`, which ignores extension and library platform requirements but not the PHP version itself and should work in most cases.

Older Composer versions will be run with `--ignore-platform-reqs`, which means that all platform constraints (including the PHP version) will be ignored by default.
This can result in updated dependencies that are not compatible with your platform.

To customize this behavior, you can explicitly ignore platform requirements (for example `ext-zip`) by setting them separately in this array.
Each item will be added to the Composer command with `--ignore-platform-req`, resulting in it being ignored during its invocation.
Note that this requires your project to use Composer V2, as V1 doesn't support excluding single platform requirements.
The used PHP version will be guessed automatically from your `composer.json` definition, so `php` should not be added as explicit dependency.

If an empty array is configured, Renovate uses its default behavior.

Set to `null` (not recommended) to fully omit `--ignore-platform-reqs/--ignore-platform-req` during Composer invocation.
This requires the Renovate image to be fully compatible with your Composer platform requirements in order for the Composer invocation to succeed, otherwise Renovate will fail to create the updated lock file.
The Composer output should inform you about the reasons the update failed.

## confidential

If enabled, all issues created by Renovate are set as confidential, even in a public repository.

<!-- prettier-ignore -->
!!! note
    The Dependency Dashboard issue will also be confidential.
    By default issues created by Renovate are visible to all users.

<!-- prettier-ignore -->
!!! note
    This option is applicable to GitLab only.

## configMigration

If enabled, Renovate raises a pull request when it needs to migrate the Renovate config file.
Renovate only performs `configMigration` on `.json` and `.json5` files.

We're adding new features to Renovate bot often.
Often you can keep using your Renovate config and use the new features right away.
But sometimes you need to update your Renovate configuration.
To help you with this, Renovate will create config migration pull requests, when you enable `configMigration`.

Example:

After we changed the [`baseBranches`](#basebranches) feature, the Renovate configuration migration pull request would make this change:

```diff
{
- "baseBranch": "main"
+ "baseBranches": ["main"]
}
```

<!-- prettier-ignore -->
!!! warning
    The `configMigration` feature writes plain JSON for `.json` files, and JSON5 for `.json5` files.
    Renovate may downgrade JSON5 content to plain JSON.
    When downgrading JSON5 to JSON Renovate may also remove the JSON5 comments.
    This can happen because Renovate wrongly converts JSON5 to JSON, thus removing the comments.

<!-- prettier-ignore -->
!!! note
    When you close a config migration PR, Renovate ignores it forever.
    This also means that Renovate won't create a config migration PR in future.
    If you closed the PR by accident, find the closed PR and re-name the PR title to get a new PR.

## configWarningReuseIssue

Renovate's default behavior is to reuse/reopen a single Config Warning issue in each repository so as to keep the "noise" down.
However for some people this has the downside that the config warning won't be sorted near the top if you view issues by creation date.
Configure this option to `false` if you prefer Renovate to open a new issue whenever there is a config warning.

## constraints

Constraints are used in package managers which use third-party tools to update "artifacts" like lock files or checksum files.
Typically, the constraint is detected automatically by Renovate from files within the repository and there is no need to manually configure it.

Constraints are also used to manually restrict which _datasource_ versions are possible to upgrade to based on their language support.
For now this datasource constraint feature only supports `python`, other compatibility restrictions will be added in the future.

```json
{
  "constraints": {
    "python": "2.7"
  }
}
```

If you need to _override_ constraints that Renovate detects from the repository, wrap it in the `force` object like so:

```json
{
  "force": {
    "constraints": {
      "node": "< 15.0.0"
    }
  }
}
```

<!-- prettier-ignore -->
!!! note
    Make sure not to mix this up with the term `compatibility`, which Renovate uses in the context of version releases, e.g. if a Docker image is `node:12.16.0-alpine` then the `-alpine` suffix represents `compatibility`.

## constraintsFiltering

This option controls whether Renovate filters new releases based on configured or detected `constraints`.
Renovate supports two options:

- `none`: No release filtering (all releases allowed)
- `strict`: If the release's constraints match the package file constraints, then it's included

More advanced filtering options may come in future.

There must be a `constraints` object in your Renovate config, or constraints detected from package files, for this to work.
Additionally, the "datasource" within Renovate must be capable of returning `constraints` values about each package's release.

This feature is limited to the following datasources:

- `crate`
- `jenkins-plugins`
- `npm`
- `packagist`
- `pypi`
- `rubygems`

Sometimes when using private registries they may omit constraints information, which then is another reason such filtering may not work even if the datasource and corresponding default public registry supports it.

<!-- prettier-ignore -->
!!! warning
    Enabling this feature may result in many package updates being filtered out silently.
    See below for a description of how it works.

When `constraintsFiltering=strict`, the following logic applies:

- Are there `constraints` for this repository, either detected from source or from config?
- Does this package's release declare constraints of its own (e.g. `engines` in Node.js)?
- If so, filter out this release unless the repository constraint is a _subset_ of the release constraint

Here are some examples:

| Your repo engines.node   | Dependency release engines.node | Result   |
| ------------------------ | ------------------------------- | -------- |
| `18`                     | `16 \|\| 18`                    | allowed  |
| `^18.10.0`               | `>=18`                          | allowed  |
| `^16.10.0 \|\| >=18.0.0` | `>= 16.0.0`                     | allowed  |
| `>=16`                   | `16 \|\| 18`                    | filtered |
| `16`                     | `^16.10.0`                      | filtered |

When using with `npm`, we recommend you:

- Use `constraintsFiltering` on `dependencies`, not `devDependencies` (usually you do not need to be strict about development dependencies)
- Do _not_ enable `rollbackPrs` at the same time (otherwise your _current_ version may be rolled back if it's incompatible)

## customDatasources

Use `customDatasources` to fetch releases from APIs or statically hosted sites and Renovate has no own datasource.
These datasources can be referred by `customManagers` or can be used to overwrite default datasources.

For more details see the [`custom` datasource documentation](modules/datasource/custom/index.md).

## customManagers

Use `customManagers`(previously `regexManagers`) entries to configure the custom managers in Renovate.

You can define custom managers to handle:

- Proprietary file formats or conventions
- Popular file formats not yet supported as a manager by Renovate

Currently we only have one custom manager.
The `regex` manager which is based on using Regular Expression named capture groups.

You must have a named capture group matching (e.g. `(?<depName>.*)`) _or_ configure its corresponding template (e.g. `depNameTemplate`) for these fields:

- `datasource`
- `depName` and / or `packageName`
- `currentValue`

Use named capture group matching _or_ set a corresponding template.
We recommend you use only _one_ of these methods, or you'll get confused.

We recommend that you also tell Renovate what `versioning` to use.
If the `versioning` field is missing, then Renovate defaults to using `semver` versioning.

For more details and examples about it, see our [documentation for the `regex` manager](modules/manager/regex/index.md).
For template fields, use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters.

<!-- prettier-ignore -->
!!! tip
    Look at our [Custom Manager Presets](./presets-customManagers.md), they may have what you need.

### customType

Example:

```json
{
  "customManagers": [
    {
      "customType": "regex",
      "matchStrings": [
        "ENV .*?_VERSION=(?<currentValue>.*) # (?<datasource>.*?)/(?<depName>.*?)\\s"
      ]
    }
  ]
}
```

### matchStrings

Each `matchStrings` must be a valid regular expression, optionally with named capture groups.

Example:

```json
{
  "matchStrings": [
    "ENV .*?_VERSION=(?<currentValue>.*) # (?<datasource>.*?)/(?<depName>.*?)\\s"
  ]
}
```

### matchStringsStrategy

`matchStringsStrategy` controls behavior when multiple `matchStrings` values are provided.
Three options are available:

- `any` (default)
- `recursive`
- `combination`

#### any

Each provided `matchString` will be matched individually to the content of the `packageFile`.
If a `matchString` has multiple matches in a file each will be interpreted as an independent dependency.

As example the following configuration will update all three lines in the Dockerfile.

```json title="renovate.json"
{
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": ["^Dockerfile$"],
      "matchStringsStrategy": "any",
      "matchStrings": [
        "ENV [A-Z]+_VERSION=(?<currentValue>.*) # (?<datasource>.*?)/(?<depName>.*?)(\\&versioning=(?<versioning>.*?))?\\s",
        "FROM (?<depName>\\S*):(?<currentValue>\\S*)"
      ],
      "datasourceTemplate": "docker"
    }
  ]
}
```

```dockerfile title="Dockerfile"
FROM amd64/ubuntu:24.04
ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven
ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node
```

#### recursive

If using `recursive` the `matchStrings` will be looped through and the full match of the last will define the range of the next one.
This can be used to narrow down the search area to prevent multiple matches.
But the `recursive` strategy still allows the matching of multiple dependencies as described below.
All matches of the first `matchStrings` pattern are detected, then each of these matches will be used as basis for the input for the next `matchStrings` pattern, and so on.
If the next `matchStrings` pattern has multiple matches then it will split again.
This process will be followed as long there is a match plus a next `matchingStrings` pattern is available.

Matched groups will be available in subsequent matching layers.

This is an example how this can work.
The first custom manager will only upgrade `grafana/loki` as looks for the `backup` key then looks for the `test` key and then uses this result for extraction of necessary attributes.
But the second custom manager will upgrade both definitions as its first `matchStrings` matches both `test` keys.

```json title="renovate.json"
{
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": ["^example.json$"],
      "matchStringsStrategy": "recursive",
      "matchStrings": [
        "\"backup\":\\s*{[^}]*}",
        "\"test\":\\s*\\{[^}]*}",
        "\"name\":\\s*\"(?<depName>.*)\"[^\"]*\"type\":\\s*\"(?<datasource>.*)\"[^\"]*\"value\":\\s*\"(?<currentValue>.*)\""
      ],
      "datasourceTemplate": "docker"
    },
    {
      "fileMatch": ["^example.json$"],
      "matchStringsStrategy": "recursive",
      "matchStrings": [
        "\"test\":\\s*\\{[^}]*}",
        "\"name\":\\s*\"(?<depName>.*)\"[^\"]*\"type\":\\s*\"(?<datasource>.*)\"[^\"]*\"value\":\\s*\"(?<currentValue>.*)\""
      ],
      "datasourceTemplate": "docker"
    }
  ]
}
```

```json title="example.json"
{
  "backup": {
    "test": {
      "name": "grafana/loki",
      "type": "docker",
      "value": "1.6.1"
    }
  },
  "setup": {
    "test": {
      "name": "python",
      "type": "docker",
      "value": "3.9.0"
    }
  }
}
```

#### combination

You may use this option to combine the values of multiple lines inside a file.
You can combine multiple lines with `matchStringStrategy` values, but the `combination` approach is less susceptible to white space or line breaks stopping a match.

`combination` can only match _one_ dependency per file.
To update multiple dependencies with `combination` you must define multiple custom managers.

Matched group values will be merged to form a single dependency.

```json title="renovate.json"
{
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": ["^main.yml$"],
      "matchStringsStrategy": "combination",
      "matchStrings": [
        "prometheus_image:\\s*\"(?<depName>.*)\"\\s*//",
        "prometheus_version:\\s*\"(?<currentValue>.*)\"\\s*//"
      ],
      "datasourceTemplate": "docker"
    },
    {
      "fileMatch": ["^main.yml$"],
      "matchStringsStrategy": "combination",
      "matchStrings": [
        "thanos_image:\\s*\"(?<depName>.*)\"\\s*//",
        "thanos_version:\\s*\"(?<currentValue>.*)\"\\s*//"
      ],
      "datasourceTemplate": "docker"
    }
  ]
}
```

```yaml title="Ansible variable file (YAML)"
prometheus_image: "prom/prometheus"  // a comment
prometheus_version: "v2.21.0" // a comment
------
thanos_image: "prom/prometheus"  // a comment
thanos_version: "0.15.0" // a comment
```

In the above example, each custom manager will match a single dependency each.

### depNameTemplate

If `depName` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field.
It will be compiled using Handlebars and the regex `groups` result.

### extractVersionTemplate

If `extractVersion` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field.
It will be compiled using Handlebars and the regex `groups` result.

### packageNameTemplate

`packageName` is used for looking up dependency versions.
It will be compiled using Handlebars and the regex `groups` result.
It will default to the value of `depName` if left unconfigured/undefined.

### currentValueTemplate

If the `currentValue` for a dependency is not captured with a named group then it can be defined in config using this field.
It will be compiled using Handlebars and the regex `groups` result.

### datasourceTemplate

If the `datasource` for a dependency is not captured with a named group then it can be defined in config using this field.
It will be compiled using Handlebars and the regex `groups` result.

### depTypeTemplate

If `depType` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field.
It will be compiled using Handlebars and the regex `groups` result.

### versioningTemplate

If the `versioning` for a dependency is not captured with a named group then it can be defined in config using this field.
It will be compiled using Handlebars and the regex `groups` result.

### registryUrlTemplate

If the `registryUrls` for a dependency is not captured with a named group then it can be defined in config using this field.
It will be compiled using Handlebars and the regex `groups` result.

### autoReplaceStringTemplate

Allows overwriting how the matched string is replaced.
This allows for some migration strategies.
E.g. moving from one Docker image repository to another one.

```yaml title="helm-values.yaml"
# The image of the service <registry>/<repo>/<image>:<tag>
image: my.old.registry/aRepository/andImage:1.18-alpine
```

```json title="The regex definition"
{
  "customManagers": [
    {
      "customType": "regex",
      "fileMatch": ["values.yaml$"],
      "matchStrings": [
        "image:\\s+(?<depName>my\\.old\\.registry/aRepository/andImage):(?<currentValue>[^\\s]+)"
      ],
      "depNameTemplate": "my.new.registry/aRepository/andImage",
      "autoReplaceStringTemplate": "image: {{{depName}}}:{{{newValue}}}",
      "datasourceTemplate": "docker"
    }
  ]
}
```

This will lead to following update where `1.21-alpine` is the newest version of `my.new.registry/aRepository/andImage`:

```yaml
# The image of the service <registry>/<repo>/<image>:<tag>
image: my.new.registry/aRepository/andImage:1.21-alpine
```

## customizeDashboard

You may use the `customizeDashboard` object to customize the Dependency Dashboard.

Supported fields:

- `repoProblemsHeader`: This field will replace the header of the Repository Problems in the Dependency Dashboard issue.

### defaultRegistryUrlTemplate

This field is used to build a `registryUrl` for the dependency.
It is not needed if either:

- The dependency can be found with the default `registryUrls` of the datasource (e.g. npmjs registry if the datasource is `npm`), or
- The matching groups you specified as part of the matching already include a `registryUrl` group
  As this is a template it can be dynamically set.
  E.g. add the `packageName` as part of the URL:

```json5
{
  customDatasources: {
    foo: {
      defaultRegistryUrlTemplate: 'https://example.foo.bar/v1/{{ packageName }}',
    },
  },
}
```

### format

Defines which format the API is returning.
Currently `json` or `plain` are supported, see the `custom` [datasource documentation](modules/datasource/custom/index.md) for more information.

### transformTemplates

`transformTemplates` is a list of [jsonata rules](https://docs.jsonata.org/simple) which get applied serially.