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 configure 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 the following locations:
.github/renovate.json
.github/renovate.json5
.gitlab/renovate.json
.gitlab/renovate.json5
.renovaterc.json
renovate.json
renovate.json5
.renovaterc
-
package.json
(within a"renovate"
section)
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 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 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.
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:
{
"labels": ["dependencies"],
"packageRules": [
{
"matchPackagePatterns": ["eslint"],
"labels": ["linting"]
},
{
"matchDepTypes": ["optionalDependencies"],
"addLabels": ["optional"]
}
]
}
With the above config:
- Optional dependencies will have the labels
dependencies
andoptional
- ESLint dependencies will have the label
linting
- All other dependencies will have the label
dependencies
additionalBranchPrefix
This value defaults to an empty string, and is typically not necessary.
Some managers previously populated this field, but they no longer do so by default.
You normally don't need to configure this, but one example where it can be useful is combining with parentDir
in monorepos to split PRs based on where the package definition is located, e.g.
{
"additionalBranchPrefix": "{{parentDir}}-"
}
additionalReviewers
In contrast to reviewers
, this option adds to the existing reviewer list, rather than replacing it.
This makes it suitable for augmenting a preset or base list without displacing the original, for example when adding focused reviewers for a specific package group.
aliases
The aliases
object is used for configuring registry aliases.
Currently it is needed/supported for the helm-requirements
manager only.
helm-requirements
includes this default alias:
{
"aliases": {
"stable": "https://charts.helm.sh/stable"
}
}
Alias values must be properly formatted URIs.
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 will try to determine PR assignees by matching rules defined in a CODEOWNERS file against the changes in the PR.
See GitHub or GitLab documentation for details on syntax and possible file locations.
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.
automerge
By default, Renovate raises PRs but leaves them to someone or something else to merge them. By configuring this setting, you can enable Renovate to automerge PRs or even branches itself, therefore reducing 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:
{
"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 elect to automerge all (passing) devDependencies
only this way:
{
"packageRules": [
{
"matchDepTypes": ["devDependencies"],
"automerge": true
}
]
}
Important: Renovate won't automerge on GitHub if a PR has a negative review outstanding.
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 will try to delay until Azure is in the expected state, however if it takes too long it will continue. In some cases this can result in a dependency not being merged, and a fresh PR being created for the dependency.
automergeComment
Use this only if you configure automergeType="pr-comment"
.
Example use:
{
"automerge": true,
"automergeType": "pr-comment",
"automergeComment": "bors: r+"
}
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.
Note: if you have no tests but still want Renovate to automerge, you need to add "requiredStatusChecks": null
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 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.
azureAutoApprove
Setting this to true
will automatically approve the PRs in Azure DevOps.
You can also configure this using packageRules
if you want to use it selectively (e.g. per-package).
azureAutoComplete
Setting this to true
will configure PRs in Azure DevOps to auto-complete after all (if any) branch policies have been met.
You can also configure this using packageRules
if you want to use it selectively (e.g. per-package).
azureWorkItemId
When creating a PR in Azure DevOps, some branches can be protected with branch policies to 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.
However, 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
andnext
:"baseBranches": ["main", "next"]
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.
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. If you want the same limit for both concurrent branches
and concurrent PRs, then just set a value for prConcurrentLimit
and it will be reused for branch calculations too.
However, 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:
{
"branchConcurrentLimit": 3
}
branchName
Warning: it's strongly recommended not to configure this field directly. Use at your own risk. 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 or
- You have a use case we didn't anticipate and we should have a feature request from you to add it to the project
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}}-"
.
Note that 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 admin bot config.
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 advance field and it's recommend you seek a config review before applying it.
bumpVersion
Currently this setting supports helmv3
, npm
and sbt
only, so raise a feature request if you have a use for it with other package managers.
Its purpose is if you want Renovate to update the version
field within your file's package.json
any time it updates dependencies within.
Usually this is for automatic release purposes, so that you don't need to add another step after Renovate before you can release a new version.
Configure this value to "patch"
, "minor"
or "major"
to have Renovate update the version in your edited package.json
.
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.
cloneSubmodules
commitBody
Configure this if you wish Renovate to add a commit body, otherwise Renovate just uses a regular single-line commit.
For example, To add [skip ci]
to every commit you could configure:
{
"commitBody": "[skip ci]"
}
Another example would be if you want to configure a DCO signoff to each commit.
commitBodyTable
commitMessage
Editing of commitMessage
directly is now deprecated and not recommended.
Please instead edit the fields such as commitMessageAction
, commitMessageExtra
, etc.
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".
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, however 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
This is used to alter commitMessage
and prTitle
without needing to copy/paste the whole string.
The "topic" is usually refers to the dependency being updated, e.g. "dependency react"
.
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 only supports python
, other compatibility restrictions will be added in the future.
{
"constraints": {
"python": "2.7"
}
}
If you need to override constraints that Renovate detects from the repository, wrap it in the force
object like so:
{
"force": {
"constraints": {
"node": "< 15.0.0"
}
}
}
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
.
dependencyDashboard
Configuring dependencyDashboard
to true
will lead to the creation of a "Dependency Dashboard" issue within the repository.
This issue contains a list of all PRs pending, open, closed (unmerged) or in error.
The goal of this issue is to give visibility into all updates that Renovate is managing.
Examples of what having a Dependency Dashboard will allow you to do:
- View all PRs in one place, rather than having to filter PRs by author
- Rebase/retry multiple PRs without having to open each individually
- Override any rate limiting (e.g. concurrent PRs) or scheduling to force Renovate to create a PR that would otherwise be suppressed
- Recreate an unmerged PR (e.g. for a major update that you postponed by closing the original PR)
Note: Enabling the Dependency Dashboard does not itself change any of the "control flow" of Renovate, e.g. it will otherwise still create and manage PRs exactly as it always has, including scheduling and rate limiting. The Dependency Dashboard therefore provides visibility as well as additional control.
dependencyDashboardApproval
This feature allows you to use Renovate's Dependency Dashboard to force approval of updates before they are created.
By setting dependencyDashboardApproval
to true
in config (including within packageRules
), you can tell Renovate to wait for your approval from the Dependency Dashboard before creating a branch/PR.
You can approve a pending PR by ticking the checkbox in the Dependency Dashboard issue.
Note: When you set dependencyDashboardApproval
to true
the Dependency Dashboard issue will be created automatically, you do not need to turn on dependencyDashboard
explictly.
You can configure Renovate to wait for approval for:
- all package upgrades
- major, minor, patch level upgrades
- specific package upgrades
- upgrades coming from specific package managers
If you want to approve all upgrades, set dependencyDashboardApproval
to true
:
{
"dependencyDashboardApproval": true
}
If you want to require approval for major updates, set dependencyDashboardApproval
to true
within a major
object:
{
"major": {
"dependencyDashboardApproval": true
}
}
If you want to approve specific packages, set dependencyDashboardApproval
to true
within a packageRules
entry where you have defined a specific package or pattern.
{
"packageRules": [
{
"matchPackagePatterns": ["^@package-name"],
"dependencyDashboardApproval": true
}
]
}
dependencyDashboardAutoclose
You can configure this to true
if you prefer Renovate to close an existing Dependency Dashboard whenever there are no outstanding PRs left.
dependencyDashboardFooter
dependencyDashboardHeader
dependencyDashboardTitle
Configure this option if you prefer a different title for the Dependency Dashboard.
description
The description field is used by config presets to describe what they do. They are then collated as part of the onboarding description.
digest
Add to this object if you wish to define rules that apply only to PRs that update digests.
docker
Add config here if you wish it to apply to Docker package managers Dockerfile and Docker Compose. If instead you mean to apply settings to any package manager that updates using the Docker datasource, use a package rule instead, e.g.
{
"packageRules": [
{
"matchDatasources": ["docker"],
"labels": ["docker-update"]
}
]
}
dotnet
draftPR
If you want the PRs created by Renovate to be considered as drafts rather than normal PRs, you could add this property to your renovate.json
:
{
"draftPR": true
}
This option is evaluated at PR/MR creation time and is only supported on the following platforms: GitHub, GitLab, Azure.
Note that GitLab implements draft status by checking whether the PR's title starts with certain strings.
Therefore, draftPR on GitLab is incompatible with the legacy method of triggering Renovate to rebase a PR by renaming the PR to start with rebase!
.
enabled
The most common use of enabled
is if you want to turn Renovate's functionality off, for some reason.
For example, if you wanted to disable Renovate completely on a repository, you could make this your renovate.json
:
{
"enabled": false
}
To disable Renovate for all eslint
packages, you can configure a package rule like:
{
"packageRules": [
{
"matchPackagePatterns": ["^eslint"],
"enabled": false
}
]
}
To disable Renovate for npm devDependencies
but keep it for dependencies
you could configure:
{
"packageRules": [
{
"matchManagers": ["npm"],
"matchDepTypes": ["devDependencies"],
"enabled": false
}
]
}
enabledManagers
This is a way to allow only certain package managers and implicitly disable all others.
Example:
{
"enabledManagers": ["dockerfile", "npm"]
}
For the full list of available managers, see the Supported Managers documentation.
encrypted
See Private npm module support for details on how this is used to encrypt npm tokens.
excludeCommitPaths
Warning: Advanced use!
Be careful you know what you're doing with this option. The initial intended use is to allow the user to exclude certain dependencies from being added/removed/modified when "vendoring" dependencies. Example:
{
"excludeCommitPaths": ["vendor/golang.org/x/text/**"]
}
The above would mean Renovate would not include files matching the above glob pattern in the commit, even if it thinks they should be updated.
extends
See shareable config presets for details.
extractVersion
Use this only when the raw version strings from the datasource do not match the expected format that you need in your package file.
You must defined a "named capture group" called version
as shown in the below examples.
For example, to extract only the major.minor precision from a GitHub release, the following would work:
{
"packageRules": [
{
"matchPackageNames": ["foo"],
"extractVersion": "^(?<version>v\\d+\\.\\d+)"
}
]
}
The above will change a raw version of v1.31.5
to v1.31
, for example.
Alternatively, to strip a release-
prefix:
{
"packageRules": [
{
"matchPackageNames": ["bar"],
"extractVersion": "^release-(?<version>.*)$"
}
]
}
The above will change a raw version of release-2.0.0
to 2.0.0
, for example.
A similar one could strip leading v
prefixes:
{
"packageRules": [
{
"matchPackageNames": ["baz"],
"extractVersion": "^v(?<version>.*)$"
}
]
}
fetchReleaseNotes
Configure this to false
if you want to disable release notes fetching
fileMatch
fileMatch
is used by Renovate to know which files in a repository to parse and extract, and it is possible to override the default values to customize for your project's needs.
Sometimes file matches are really simple - for example with Go Modules Renovate looks for any go.mod
file, and you probably don't need to change that default.
At other times, the possible files is too vague for Renovate to have any default.
For default, Kubernetes manifests can exist in any *.yaml
file and we don't want Renovate to parse every single YAML file in every repository just in case some of them contain a Kubernetes manifest, so Renovate's default fileMatch
for manager kubernetes
is actually empty ([]
) and needs the user to tell Renovate what directories/files to look in.
Finally, there are cases where Renovate's default fileMatch
is good, but you may be using file patterns that a bot couldn't possibly guess about.
For example, Renovate's default fileMatch
for Dockerfile
is ['(^|/|\\.)Dockerfile$', '(^|/)Dockerfile\\.[^/]*$']
.
This will catch files like backend/Dockerfile
, prefix.Dockerfile
or Dockerfile.suffix
, but it will miss files like ACTUALLY_A_DOCKERFILE.template
.
Because fileMatch
is mergeable, you don't need to duplicate the defaults and could just add the missing file like this:
{
"dockerfile": {
"fileMatch": ["^ACTUALLY_A_DOCKERFILE\\.template$"]
}
}
If you configure fileMatch
then it must be within a manager object (e.g. dockerfile
in the above example).
The full list of supported managers can be found here.
filterUnavailableUsers
When this option is enabled PRs are not assigned to users that are unavailable. This option only works on platforms that support the concept of user availability. For now, you can only use this option on the GitLab platform.
followTag
Caution: advanced functionality. Only use it if you're sure you know what you're doing.
This functionality requires that the datasource to support distribution streams/tags, such as npm does.
The primary use case for this option is if you are following a pre-release tag of a certain dependency, e.g. typescript
's "insiders"
build.
If configured, Renovate bypasses its normal major/minor/patch upgrade logic and stable/unstable consistency logic and keeps your dependency version sync'd strictly to whatever version is in the tag.
Beware that Renovate follows tags strictly.
For example, if you are following a tag like next
and then that stream is released as stable
and next
is no longer being updated then that means your dependencies also won't be getting updated.
gitIgnoredAuthors
Specify commit authors ignored by Renovate.
By default, Renovate will treat any PR as modified if another git author has added to the branch.
When a PR is considered modified, Renovate won't perform any further commits such as if it's conflicted or needs a version update.
If you have other bots which commit on top of Renovate PRs, and don't want Renovate to treat these PRs as modified, then add the other git author(s) to gitIgnoredAuthors
.
Example:
{
"gitIgnoredAuthors": ["some-bot@example.org"]
}
gitLabAutomerge
Caution (fixed in GitLab >= 12.7): when this option is enabled it is possible due to a bug in GitLab that MRs with failing pipelines might still get merged. This is caused by a race condition in GitLab's Merge Request API - read the corresponding issue for details.
golang
Configuration added here applies for all Go-related updates, however currently the only supported package manager for Go is the native Go Modules (the gomod
manager).
group
Caution: Advanced functionality only. Do not use unless you know what you're doing.
The default configuration for groups are essentially internal to Renovate and you normally shouldn't need to modify them.
However, you may choose to add settings to any group by defining your own group
configuration object.
groupName
There are multiple cases where it can be useful to group multiple upgrades together.
Internally Renovate uses this for branches such as "Pin Dependencies", "Lock File Maintenance", etc.
Another example used previously is to group together all related eslint
packages, or perhaps angular
or babel
.
To enable grouping, you configure the groupName
field to something non-null.
The groupName
field allows free text and does not have any semantic interpretation by Renovate.
All updates sharing the same groupName
will be placed into the same branch/PR.
For example, to group all non-major devDependencies updates together into a single PR:
{
"packageRules": [
{
"matchDepTypes": ["devDependencies"],
"matchUpdateTypes": ["patch", "minor"],
"groupName": "devDependencies (non-major)"
}
]
}
groupSlug
By default, Renovate will "slugify" the groupName to determine the branch name.
For example if you named your group "devDependencies (non-major)" then the branchName would be renovate/devdependencies-non-major
.
If you wished to override this then you could configure like this:
{
"packageRules": [
{
"matchDepTypes": ["devDependencies"],
"matchUpdateTypes": ["patch", "minor"],
"groupName": "devDependencies (non-major)",
"groupSlug": "dev-dependencies"
}
]
}
As a result of the above, the branchName would be renovate/dev-dependencies
instead.
Note: you shouldn't usually need to configure this unless you really care about your branch names.
hashedBranchLength
Some code hosting systems have restrictions on the branch name lengths, this option lets you get around these restrictions.
You can set the hashedBranchLength
option to a number of characters that works for your system and then Renovate will generate branch names with the appropriate length by hashing additionalBranchPrefix
and branchTopic
, and then truncating the hash so that the full branch name (including branchPrefix
) has the right number of characters.
Example: If you have set branchPrefix: "deps-"
and hashedBranchLength: 12
it will result in a branch name like deps-5bf36ec
instead of the traditional pretty branch name like deps-react-17.x
.
hostRules
The primary purpose of hostRules
is to configure credentials for host authentication.
You tell Renovate how to match against the host you need authenticated, and then you also tell it which credentials to use.
The lookup keys for hostRules
are: hostType
and matchHost
, both of which are optional.
Supported credential fields are token
, username
, password
, timeout
, enabled
and insecureRegistry
.
Example for configuring docker
auth:
{
"hostRules": [
{
"matchHost": "docker.io",
"username": "<some-username>",
"password": "<some-password>"
}
]
}
To disable requests to a particular host, you can configure a rule like: