Skip to content

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
  2. renovate.json5
  3. .github/renovate.json
  4. .github/renovate.json5
  5. .gitlab/renovate.json
  6. .gitlab/renovate.json5
  7. .renovaterc
  8. .renovaterc.json
  9. package.json (within a "renovate" section)

Warning

Storing the Renovate configuration in a package.json file is deprecated and support may be removed in the future.

When renovating a repository, Renovate tries to detect the configuration files in the order listed above, and stops after the first one is found.

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.

Note

Config options with type=string are always non-mergeable, so mergeable=false.


addLabels

Labels to add to Pull Request.

Name Value
type array
subType string
mergeable true
cli --add-labels
env RENOVATE_ADD_LABELS

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 and optional
  • ESLint dependencies will have the label linting
  • All other dependencies will have the label dependencies

additionalBranchPrefix

Additional string value to be appended to branchPrefix.

Name Value
type string
default ""
env RENOVATE_ADDITIONAL_BRANCH_PREFIX

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

Additional reviewers for Pull Requests (in contrast to reviewers, this option adds to the existing reviewer list, rather than replacing it).

Name Value
type array
subType string
mergeable true
cli --additional-reviewers
env RENOVATE_ADDITIONAL_REVIEWERS

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.

assignAutomerge

Assign reviewers and assignees even if the PR is to be automerged.

Name Value
type boolean
default false
cli --assign-automerge
env RENOVATE_ASSIGN_AUTOMERGE

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

Assignees for Pull Request (either username or email address depending on the platform).

Name Value
type array
subType string
cli --assignees
env RENOVATE_ASSIGNEES

Must be valid usernames on the platform in use.

assigneesFromCodeOwners

Determine assignees based on configured code owners and changes in PR.

Name Value
type boolean
default false
cli --assignees-from-code-owners
env RENOVATE_ASSIGNEES_FROM_CODE_OWNERS

If enabled Renovate tries 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

Take a random sample of given size from assignees.

Name Value
type integer
cli --assignees-sample-size
env RENOVATE_ASSIGNEES_SAMPLE_SIZE

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

Whether to automerge branches/PRs automatically, without human intervention.

Name Value
type boolean
default false
cli --automerge
env RENOVATE_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:

{
  "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:

{
  "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 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.

automergeComment

PR comment to add to trigger automerge. Only used if automergeType=pr-comment.

Name Value
type string
default "automergeComment"
cli --automerge-comment
env RENOVATE_AUTOMERGE_COMMENT

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

Example use:

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

automergeSchedule

Limit automerge to these times of day or week.

Name Value
type array
subType string
cli --automerge-schedule
default
["at any time"]

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 as the syntax is the same.

automergeStrategy

The merge strategy to use when automerging PRs. Used only if automergeType=pr.

Name Value
type string
allowedValues auto, fast-forward, merge-commit, rebase, squash
default "auto"
supportedPlatforms bitbucket, gitea
cli --automerge-strategy
env RENOVATE_AUTOMERGE_STRATEGY

This setting is only applicable if you opt-in by configuring automerge to true and automergeType to pr for any of your dependencies.

The automerge strategy defaults to auto, in which Renovate will make its best guess as to how to merge pull requests. This generally results in Renovate respecting the strategy configured in the platform itself for the repository if possible. Acceptable values are:

  • auto, in which the choice is left to Renovate
  • fast-forward, which generally involves no new commits in the resultant tree, but "fast-forwarding" the main branch reference
  • merge-commit, which generally involves synthesizing a new merge commit
  • rebase, which generally involves rewriting history as part of the merge — but usually retaining the individual commits
  • squash, which generally involves flattening the commits that are being merged into a single new commit

Not all platforms support all pull request merge strategies. In cases where a merge strategy is not supported by the platform, Renovate will hold off on merging instead of silently merging in a way you didn't wish for.

automergeType

How to automerge, if enabled.

Name Value
type string
allowedValues branch, pr, pr-comment
default "pr"
cli --automerge-type
env RENOVATE_AUTOMERGE_TYPE

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.

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 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

If set to true, Azure DevOps PRs will be automatically approved.

Name Value
type boolean
default false
supportedPlatforms azure
cli --azure-auto-approve
env RENOVATE_AZURE_AUTO_APPROVE

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).

azureWorkItemId

The id of an existing work item on Azure Boards to link to each PR.

Name Value
type integer
default 0
supportedPlatforms azure
cli --azure-work-item-id
env RENOVATE_AZURE_WORK_ITEM_ID

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

An array of one or more custom base branches to be processed. If left empty, the default branch will be chosen.

Name Value
type array
env RENOVATE_BASE_BRANCHES

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"]

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.

Note

The baseBranches config option is not supported when forkMode is enabled, including in the Forking Renovate app.

bbUseDefaultReviewers

Use the default reviewers (Bitbucket only).

Name Value
type boolean
default true
supportedPlatforms bitbucket, bitbucket-server
cli --bb-use-default-reviewers
env RENOVATE_BB_USE_DEFAULT_REVIEWERS

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

branchConcurrentLimit

Limit to a maximum of x concurrent branches. 0 means no limit, null (default) inherits value from prConcurrentLimit.

Name Value
type integer
cli --branch-concurrent-limit
env RENOVATE_BRANCH_CONCURRENT_LIMIT

By default, Renovate won't enforce any concurrent branch limits. The config:base 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 just set a value for prConcurrentLimit and it will be reused 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:

{
  "branchConcurrentLimit": 3
}

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

Branch name template.

Name Value
type string
default "{{{branchPrefix}}}{{{additionalBranchPrefix}}}{{{branchTopic}}}"
env RENOVATE_BRANCH_NAME

Warning

We strongly recommended that you do not 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 expect and we should have a feature request from you to add it to the project

branchPrefix

Prefix to use for all branch names.

Name Value
type string
default "renovate/"
cli --branch-prefix
env RENOVATE_BRANCH_PREFIX

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

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

Old Prefix to check for existing PRs.

Name Value
type string
default "renovate/"
cli --branch-prefix-old
env RENOVATE_BRANCH_PREFIX_OLD

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

Branch topic.

Name Value
type string
default "{{{depNameSanitized}}}-{{{newMajor}}}{{#if separateMinorPatch}}{{#if isPatch}}.{{{newMinor}}}{{/if}}{{/if}}.x{{#if isLockfileUpdate}}-lockfile{{/if}}"
env RENOVATE_BRANCH_TOPIC

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

Bump the version in the package file being updated.

Name Value
type string
allowedValues major, minor, patch, prerelease
supportedManagers helmv3, npm, maven, sbt
cli --bump-version
env RENOVATE_BUMP_VERSION
default null

Currently this setting supports helmv3, npm, maven 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 package file 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 "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

Set to true to enable initialization of submodules during repository clone.

Name Value
type boolean
default false
cli --clone-submodules
env RENOVATE_CLONE_SUBMODULES

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

Commit message body template. Will be appended to commit message, separated by two line returns.

Name Value
type string
env RENOVATE_COMMIT_BODY
default null

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.

If you want Renovate to signoff its commits, add the :gitSignOff preset to your extends array:

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

commitBodyTable

If enabled, append a table in the commit message body describing all updates in the commit.

Name Value
type boolean
default false
cli --commit-body-table
env RENOVATE_COMMIT_BODY_TABLE

commitMessage

Message to use for commit messages and pull request titles.

Name Value
type string
default "{{{commitMessagePrefix}}} {{{commitMessageAction}}} {{{commitMessageTopic}}} {{{commitMessageExtra}}} {{{commitMessageSuffix}}}"
env RENOVATE_COMMIT_MESSAGE

Warning

Editing of commitMessage directly is now deprecated and not recommended. Please instead edit the fields such as commitMessageAction, commitMessageExtra, etc.

commitMessageAction

Action verb to use in commit messages and PR titles.

Name Value
type string
default "Update"
env RENOVATE_COMMIT_MESSAGE_ACTION

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

Extra description used after the commit message topic - typically the version.

Name Value
type string
default "to {{#if isPinDigest}}{{{newDigestShort}}}{{else}}{{#if isMajor}}{{prettyNewMajor}}{{else}}{{#if isSingleVersion}}{{prettyNewVersion}}{{else}}{{#if newValue}}{{{newValue}}}{{else}}{{{newDigestShort}}}{{/if}}{{/if}}{{/if}}{{/if}}"
env RENOVATE_COMMIT_MESSAGE_EXTRA

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

Prefix to add to start of commit messages and PR titles. Uses a semantic prefix if semanticCommits is enabled.

Name Value
type string
env RENOVATE_COMMIT_MESSAGE_PREFIX
default null

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

Suffix to add to end of commit messages and PR titles.

Name Value
type string
env RENOVATE_COMMIT_MESSAGE_SUFFIX
default null

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

commitMessageTopic

The upgrade topic/noun used in commit messages and PR titles.

Name Value
type string
default "dependency {{depName}}"
env RENOVATE_COMMIT_MESSAGE_TOPIC

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".

composerIgnorePlatformReqs

Configure use of --ignore-platform-reqs or --ignore-platform-req for the Composer package manager.

Name Value
type array
subType string
cli --composer-ignore-platform-reqs
env RENOVATE_COMPOSER_IGNORE_PLATFORM_REQS

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 behaviour, 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 behaviour.

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, issues created by Renovate are set as confidential.

Name Value
type boolean
default false
supportedPlatforms gitlab
cli --confidential
env RENOVATE_CONFIDENTIAL

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

Note

The Dependency Dashboard issue will also be confidential. By default issues created by Renovate are visible to all users.

Note

This option is applicable to GitLab only.

configMigration

Enable this to get config migration PRs when needed.

Name Value
type boolean
default false
cli --config-migration
env RENOVATE_CONFIG_MIGRATION

If enabled, Renovate will raise a pull request if config file migration is needed.

We're adding new features to Renovate bot often. Most times you can keep using your Renovate config and benefit from the new features right away. But sometimes you need to change your Renovate configuration. To help you with this, Renovate will create config migration pull requests.

Example:

After we changed the baseBranches feature, the Renovate configuration migration pull request would make this change:

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

Info

This feature writes plain JSON for .json files, and JSON5 for .json5 files. JSON5 content can potentially be down leveled (.json files) and all comments will be removed.

This feature is flagged as experimental

Config migration PRs are still being improved, in particular to reduce the amount of reordering and whitespace changes.
To track this feature visit the following GitHub issue #16359.

configWarningReuseIssue

Set this to false to make Renovate create a new issue for each config warning, instead of reopening or reusing an existing issue.

Name Value
type boolean
default true
cli --config-warning-reuse-issue
env RENOVATE_CONFIG_WARNING_REUSE_ISSUE

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

Configuration object to define language or manager version constraints.

Name Value
type object
mergeable true
supportedManagers bundler, composer, gomod, npm, pipenv, poetry
env RENOVATE_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. Manually specifying constraints is supported for ruby, bundler, composer, go, npm, yarn, pnpm, python, pipenv, and poetry.

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.

{
  "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.

defaultRegistryUrls

List of registry URLs to use as the default for a datasource.

Name Value
type array
subType string

Override a datasource's default registries with this config option. The datasources's customRegistrySupport value must be true for the config option to work.

Default registries are only used when both:

  • The manager did not extract any registryUrls values, and
  • No registryUrls values have been applied via config, such as packageRules

Think of defaultRegistryUrls as a way to specify the "fallback" registries for a datasource, for use when no registryUrls are extracted or configured. Compare that to registryUrls, which are a way to override registries.

dependencyDashboard

Whether to create a "Dependency Dashboard" issue in the repository.

Name Value
type boolean
default false
cli --dependency-dashboard
env RENOVATE_DEPENDENCY_DASHBOARD

Starting from version v26.0.0 the "Dependency Dashboard" is enabled by default as part of the commonly-used config:base preset.

To disable the Dependency Dashboard, add the preset :disableDependencyDashboard or set dependencyDashboard to false.

{
  "extends": ["config:base", ":disableDependencyDashboard"]
}

Configuring dependencyDashboard to true will lead to the creation of a "Dependency Dashboard" issue within the repository. This issue has 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)

Tip

Just enabling the Dependency Dashboard doesn't change the "control flow" of Renovate. Renovate still creates and manages PRs, and still follows your schedules and rate limits. The Dependency Dashboard gives you extra visibility and control over your updates.

dependencyDashboardApproval

Controls if updates need manual approval from the Dependency Dashboard issue before PRs are created.

Name Value
type boolean
default false
cli --dependency-dashboard-approval
env RENOVATE_DEPENDENCY_DASHBOARD_APPROVAL

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.

Tip

When you set dependencyDashboardApproval to true the Dependency Dashboard issue will be created automatically, you do not need to turn on dependencyDashboard explicitly.

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

Set to true to let Renovate close the Dependency Dashboard issue if there are no more updates.

Name Value
type boolean
default false
cli --dependency-dashboard-autoclose
env RENOVATE_DEPENDENCY_DASHBOARD_AUTOCLOSE

You can configure this to true if you prefer Renovate to close an existing Dependency Dashboard whenever there are no outstanding PRs left.

dependencyDashboardFooter

Any text added here will be placed last in the Dependency Dashboard issue body, with a divider separator before it.

Name Value
type string
cli --dependency-dashboard-footer
env RENOVATE_DEPENDENCY_DASHBOARD_FOOTER
default null

dependencyDashboardHeader

Any text added here will be placed first in the Dependency Dashboard issue body.

Name Value
type string
default "This issue lists Renovate updates and detected dependencies. Read the [Dependency Dashboard](https://docs.renovatebot.com/key-concepts/dashboard/) docs to learn more."
cli --dependency-dashboard-header
env RENOVATE_DEPENDENCY_DASHBOARD_HEADER

dependencyDashboardLabels

These labels will always be applied on the Dependency Dashboard issue, even when they have been removed manually.

Name Value
type array
subType string
cli --dependency-dashboard-labels
env RENOVATE_DEPENDENCY_DASHBOARD_LABELS

The labels only get updated when the Dependency Dashboard issue updates its content and/or title. It is pointless to edit the labels, as Renovate bot restores the labels on each run.

dependencyDashboardTitle

Title to use for the Dependency Dashboard issue.

Name Value
type string
default "Dependency Dashboard"
cli --dependency-dashboard-title
env RENOVATE_DEPENDENCY_DASHBOARD_TITLE

Configure this option if you prefer a different title for the Dependency Dashboard.

description

Plain text description for a config or preset.

Name Value
type array
subType string
mergeable true

The description field can be used inside any configuration object to add a human-readable description of the object's config purpose. Descriptions fields embedded within presets are also collated as part of the onboarding description.

digest

Configuration to apply when updating a digest (no change in tag/version).

Name Value
type object
default
{
  "branchTopic": "{{{depNameSanitized}}}-digest",
  "commitMessageExtra": "to {{newDigestShort}}",
  "commitMessageTopic": "{{{depName}}} digest"
}
mergeable true
env RENOVATE_DIGEST

Add to this object if you wish to define rules that apply only to PRs that update digests.

docker

Configuration object for Docker language.

Name Value
type object
default
{"versioning": "docker"}
mergeable true
env RENOVATE_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

Configuration object for .NET language.

Name Value
type object
mergeable true
env RENOVATE_DOTNET

draftPR

If set to true then Renovate creates draft PRs, instead of normal status PRs.

Name Value
type boolean
default false
supportedPlatforms azure, gitea, github, gitlab
cli --draft-p-r
env RENOVATE_DRAFT_P_R

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.

Note

GitLab and Gitea implement draft status by checking if the PR's title starts with certain strings. This means that draftPR on GitLab and Gitea are incompatible with the legacy method of triggering Renovate to rebase a PR by renaming the PR to start with rebase!.

enabled

Enable or disable Renovate bot.

Name Value
type boolean
default true

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

A list of package managers to enable. If defined, then all managers not on the list are disabled.

Name Value
type array
cli --enabled-managers
env RENOVATE_ENABLED_MANAGERS

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

An object containing configuration encrypted with project key.

Name Value
type object
cli --encrypted
env RENOVATE_ENCRYPTED

See Private module support for details on how this is used to encrypt npm tokens.

Note

Encrypted secrets must have at least an org/group scope, and optionally a repository scope. This means that Renovate will check if a secret's scope matches the current repository before applying it, and warn/discard if there is a mismatch.

excludeCommitPaths

A file that matches any of these glob patterns will not be committed, even if it has been updated.

Name Value
type array
subType string
cli --exclude-commit-paths
env RENOVATE_EXCLUDE_COMMIT_PATHS

Warning

For advanced users only!

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

Configuration presets to use or extend.

Name Value
type array
subType string
env RENOVATE_EXTENDS

See shareable config presets for details.

extractVersion

A regex (re2) to extract a version from a datasource's raw version string.

Name Value
type string
format regex
default null

Only use this config option when the raw version strings from the datasource do not match the expected format that you need in your package file. You must define a "named capture group" called version like in the examples below.

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

Controls if release notes are fetched.

Name Value
type boolean
default true

Set this to false if you want to disable release notes fetching.

Renovate can fetch release notes when they are hosted on one of these platforms:

  • GitHub (.com and Enterprise Server)
  • GitLab (.com and CE/EE)

Note

Renovate can only show release notes from some platforms and some package managers. We're planning improvements so that Renovate can show more release notes. Read issue 14138 on GitHub to get a overview of the planned work.

fileMatch

RegEx (re2) pattern for matching manager files.

Name Value
type array
subType string
format regex
mergeable true

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 have 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

Filter reviewers and assignees based on their availability.

Name Value
type boolean
default false
supportedPlatforms gitlab
cli --filter-unavailable-users
env RENOVATE_FILTER_UNAVAILABLE_USERS

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

If defined, packages will follow this release tag exactly.

Name Value
type string
default null

Warning

Advanced functionality. Only use this if you're sure you know what you're doing.

For followTag to work, the datasource must support distribution streams or tags, like for example npm does.

The main usecase is to follow a pre-release tag of a dependency, say TypeScripts's "insiders" build:

{
  "packageRules": [
    {
      "matchPackageNames": ["typescript"],
      "followTag": "insiders"
    }
  ]
}

If you've set a followTag then Renovate skips its normal major/minor/patch upgrade logic and stable/unstable consistency logic, and instead keeps your dependency version synced strictly to the version in the tag.

Renovate follows tags strictly, this can cause problems when a tagged stream is no longer maintained. For example: you're following the next tag, but later the stream you actually want is called stable instead. If next is no longer getting updates, you must switch your followTag to stable to get updates again.

gitAuthor

Author to use for Git commits. Must conform to RFC5322.

Name Value
type string
cli --git-author
env RENOVATE_GIT_AUTHOR
default null

You can customize the Git author that's used whenever Renovate creates a commit. The gitAuthor option accepts a RFC5322-compliant string.

Danger

We strongly recommend that the Git author email you use is unique to Renovate. Otherwise, if another bot or human shares the same email and pushes to one of Renovate's branches then Renovate will mistake the branch as unmodified and potentially force push over the changes.

gitIgnoredAuthors

Additional Git authors which are ignored by Renovate. Must conform to RFC5322.

Name Value
type array
subType string
cli --git-ignored-authors
env RENOVATE_GIT_IGNORED_AUTHORS

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"]
}

gitLabIgnoreApprovals

Ignore approval rules for MRs created by Renovate, which is useful for automerge.

Name Value
type boolean
default false
cli --git-lab-ignore-approvals
env RENOVATE_GIT_LAB_IGNORE_APPROVALS

Ignore the default project level approval(s), so that Renovate bot can automerge its merge requests, without needing approval(s). Under the hood, it creates a MR-level approval rule where approvals_required is set to 0. This option works only when automerge=true, automergeType=pr or automergeType=branch and platformAutomerge=true. Also, approval rules overriding should not be prevented in GitLab settings.

golang

Configuration object for Go language.

Name Value
type object
default
{"commitMessageTopic": "module {{depName}}"}
mergeable true
env RENOVATE_GOLANG

Configuration added here applies for all Go-related updates. The only supported package manager for Go is the native Go Modules (the gomod manager).

For self-hosted users, GOPROXY, GONOPROXY, GOPRIVATE and GOINSECURE environment variables are supported (reference).

Usage of direct will fallback to the Renovate-native release fetching mechanism. Also we support the off keyword which will stop any fetching immediately.

group

Config if groupName is enabled.

Name Value
type object
default
{"branchTopic": "{{{groupSlug}}}", "commitMessageTopic": "{{{groupName}}}"}
mergeable true

Warning

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. But you may add settings to any group by defining your own group configuration object.

groupName

Human understandable name for the dependency group.

Name Value
type string
cli --group-name
env RENOVATE_GROUP_NAME

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

Slug to use for group (e.g. in branch name). Will be calculated from groupName if null.

Name Value
type string

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

If enabled, branch names will use a hashing function to ensure each branch has that length.

Name Value
type integer
env RENOVATE_HASHED_BRANCH_LENGTH

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 correct 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

Host rules/configuration including credentials.

Name Value
type array
subType object
default
[{"timeout": 60000}]
cli --host-rules
mergeable true
env RENOVATE_HOST_RULES

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>"
    }
  ]
}

If multiple hostRules match a request, then they will be applied in the following order/priority:

  1. rules with only hostType specified
  2. rules with only matchHost specified (sorted by matchHost length if multiple match)
  3. rules with both matchHost and hostType specified (sorted by matchHost length if multiple match)

To disable requests to a particular host, you can configure a rule like:

{
  "hostRules": [
    {
      "matchHost": "registry.npmjs.org",
      "enabled": false
    }
  ]
}

A preset alternative to the above is:

{
  "extends": [":disableHost(registry.npmjs.org)"]
}

Note

Disabling a host is only 100% effective if added to self-hosted config. Renovate currently still checks its cache for results first before trying to connect, so if a public host is blocked in your repository config (e.g. renovate.json) then it's possible you may get cached results from that host if another repository using the same bot has successfully queried for the same dependency recently.

abortIgnoreStatusCodes

A list of HTTP status codes safe to ignore even when abortOnError=true.

Name Value
type array
subType number
parent hostRules

This field can be used to configure status codes that Renovate ignores and passes through when abortOnError is set to true. For example to also skip 404 responses then configure the following:

{
  "hostRules": [
    {
      "abortOnError": true,
      "abortIgnoreStatusCodes": [404]
    }
  ]
}

Tip

This field is not mergeable, so the last-applied host rule takes precedence.

abortOnError

If enabled, Renovate will abort its run when HTTP request errors occur.

Name Value
type boolean
parent hostRules
default false

Use this field to configure Renovate to abort runs for custom hosts. By default, Renovate will only abort for known public hosts, which has the downside that transient errors for other hosts can cause autoclosing of PRs.

To abort Renovate runs for http failures from any host:

{
  "hostRules": [
    {
      "abortOnError": true
    }
  ]
}

To abort Renovate runs for any docker datasource failures:

{
  "hostRules": [
    {
      "hostType": "docker",
      "abortOnError": true
    }
  ]
}

To abort Renovate for errors for a specific docker host:

{
  "hostRules": [
    {
      "matchHost": "docker.company.com",
      "abortOnError": true
    }
  ]
}

When this field is enabled, Renovate will abort its run if it encounters either (a) any low-level http error (e.g. ETIMEDOUT) or (b) gets a response not matching any of the configured abortIgnoreStatusCodes (e.g. 500 Internal Error);

authType

Authentication type for http header. e.g. "Bearer" or "Basic". Use "Token-Only" to use only the token without an authorization type.

Name Value
type string
parent hostRules
default "Bearer"

You may use the authType option to create a custom HTTP authorization header. For authType to work, you must also set your own token.

Do not set authType=Bearer: it's the default setting for Renovate anyway. Do not set a username or password when you're using authType, as authType doesn't use usernames or passwords.

An example for npm basic auth with token:

{
  "hostRules": [
    {
      "matchHost": "npm.custom.org",
      "token": "<some-token>",
      "authType": "Basic"
    }
  ]
}

This will generate the following header: authorization: Basic <some-token>.

To use a bare token in the authorization header (required by e.g. Hex) - use the authType "Token-Only":

{
  "hostRules": [
    {
      "matchHost": "https://hex.pm/api/repos/private_repo/",
      "token": "<some-token>",
      "authType": "Token-Only"
    }
  ]
}

This will generate the header authorization: <some-token>.

concurrentRequestLimit

Limit concurrent requests per host.

Name Value
type integer
parent hostRules

Usually the default setting is fine, but you can use concurrentRequestLimit to limit the number of concurrent outstanding requests. You only need to adjust this setting if a datasource is rate limiting Renovate or has problems with the load. The limit will be set for any host it applies to.

Example config:

{
  "hostRules": [
    {
      "matchHost": "github.com",
      "concurrentRequestLimit": 2
    }
  ]
}

enableHttp2

Enable got HTTP/2 support.

Name Value
type boolean
parent hostRules
default false

Enable got http2 support.

hostType

hostType for a package rule. Can be a platform name or a datasource name.

Name Value
type string
parent hostRules
default null

hostType is another way to filter rules and can be either a platform such as github and bitbucket-server, or it can be a datasource such as docker and rubygems. You usually don't need to configure it in a host rule if you have already configured matchHost and only one host type is in use for those, as is usually the case. hostType can help for cases like an enterprise registry that serves multiple package types and has different authentication for each, although it's often the case that multiple matchHost rules could achieve the same thing.

insecureRegistry

Explicitly turn on insecure Docker registry access (HTTP).

Name Value
type boolean
parent hostRules
default true

Warning

Advanced config, use at your own risk.

Enable this option to allow Renovate to connect to an insecure Docker registry that is http only. This is insecure and is not recommended.

Example:

{
  "hostRules": [
    {
      "matchHost": "reg.insecure.com",
      "insecureRegistry": true
    }
  ]
}

matchHost

A domain name, host name or base URL to match against.

Name Value
type string
parent hostRules
default null

This can be a base URL (e.g. https://api.github.com) or a hostname like github.com or api.github.com. If the value starts with http(s) then it will only match against URLs which start with the full base URL. Otherwise, it will be matched by checking if the URL's hostname matches the matchHost directly or ends with it. When checking the end of the hostname, a single dot is prefixed to the value of matchHost, if one is not already present, to ensure it can only match against whole domain segments.

timeout

Timeout (in milliseconds) for queries to external endpoints.

Name Value
type integer
parent hostRules

Use this figure to adjust the timeout for queries. The default is 60s, which is quite high. To adjust it down to 10s for all queries, do this:

{
  "hostRules": [
    {
      "timeout": 10000
    }
  ]
}

ignoreDeprecated

Avoid upgrading from a non-deprecated version to a deprecated one.

Name Value
type boolean
default true
cli --ignore-deprecated
env RENOVATE_IGNORE_DEPRECATED

By default, Renovate won't update a dependency version to a deprecated release unless the current version was itself deprecated. The goal of this is to make sure you don't upgrade from a non-deprecated version to a deprecated one just because it's higher than the current version.

If for some reason you wish to force deprecated updates with Renovate, you can configure ignoreDeprecated to false, but this is not recommended for most situations.

ignoreDeps

Dependencies to ignore.

Name Value
type array
subType string
mergeable true
cli --ignore-deps
env RENOVATE_IGNORE_DEPS

The ignoreDeps configuration field allows you to define a list of dependency names to be ignored by Renovate. Currently it supports only "exact match" dependency names and not any patterns. e.g. to ignore both eslint and eslint-config-base you would add this to your config:

{
  "ignoreDeps": ["eslint", "eslint-config-base"]
}

The above is the same as if you wrote this package rule:

{
  "packageRules": [
    {
      "matchPackageNames": ["eslint", "eslint-config-base"],
      "enabled": false
    }
  ]
}

ignorePaths

Skip any package file whose path matches one of these. Can be a string or glob pattern.

Name Value
type array
mergeable false
subType string
default
["**/node_modules/**", "**/bower_components/**"]
cli --ignore-paths
env RENOVATE_IGNORE_PATHS

Renovate will extract dependencies from every file it finds in a repository, unless that file is explicitly ignored. With this setting you can selectively ignore package files that would normally be "autodiscovered" and updated by Renovate.

For instance if you have a project with an "examples/" directory you wish to ignore:

{
  "ignorePaths": ["**/examples/**"]
}

Renovate's default ignore is node_modules and bower_components only. If you are extending from the popular config:base preset then it adds ignore patterns for vendor, examples, test(s) and fixtures directories too.

ignorePlugins

Set this to true if allowPlugins=true but you wish to skip running plugins when updating lock files.

Name Value
type boolean
default false
cli --ignore-plugins
env RENOVATE_IGNORE_PLUGINS

Set this to true if running plugins causes problems. Applicable for Composer only for now.

ignorePrAuthor

Set to true to fetch the entire list of PRs instead of only those authored by the Renovate user.

Name Value
type boolean
default false
cli --ignore-pr-author
env RENOVATE_IGNORE_PR_AUTHOR

This is usually needed if someone needs to migrate bot accounts, including from hosted app to self-hosted. If ignorePrAuthor is configured to true, it means Renovate will fetch the entire list of repository PRs instead of optimizing to fetch only those PRs which it created itself. You should only want to enable this if you are changing the bot account (e.g. from @old-bot to @new-bot) and want @new-bot to find and update any existing PRs created by @old-bot. It's recommended to revert this setting once that transition period is over and all old PRs are resolved.

ignorePresets

A list of presets to ignore, including any that are nested inside an extends array.

Name Value
type array
subType string
env RENOVATE_IGNORE_PRESETS

Use this if you are extending a complex preset but don't want to use every "sub preset" that it includes. For example, consider this config:

{
  "extends": ["config:base"],
  "ignorePresets": [":prHourlyLimit2"]
}

It would take the entire "config:base" preset - which has a lot of sub-presets - but ignore the ":prHourlyLimit2" rule.

ignoreScripts

Set this to true if allowScripts=true but you wish to skip running scripts when updating lock files.

Name Value
type boolean
default false
supportedManagers npm, composer
cli --ignore-scripts
env RENOVATE_IGNORE_SCRIPTS

Applicable for npm and Composer only for now. Set this to true if running scripts causes problems.

ignoreTests

Set to true to enable automerging without tests.

Name Value
type boolean
default false
cli --ignore-tests
env RENOVATE_IGNORE_TESTS

Currently Renovate's default behavior is to only automerge if every status check has succeeded.

Setting this option to true means that Renovate will ignore all status checks. You can set this if you don't have any status checks but still want Renovate to automerge PRs. Beware: configuring Renovate to automerge without any tests can lead to broken builds on your base branch, please think again before enabling this!

ignoreUnstable

Ignore versions with unstable SemVer.

Name Value
type boolean
cli --ignore-unstable
env RENOVATE_IGNORE_UNSTABLE
default true

By default, Renovate won't update any package versions to unstable versions (e.g. 4.0.0-rc3) unless the current version has the same major.minor.patch and was already unstable (e.g. it was already on 4.0.0-rc2). Renovate will also not "jump" unstable versions automatically, e.g. if you are on 4.0.0-rc2 and newer versions 4.0.0 and 4.1.0-alpha.1 exist then Renovate will update you to 4.0.0 only. If you need to force permanent unstable updates for a package, you can add a package rule setting ignoreUnstable to false.

Also check out the followTag configuration option above if you wish Renovate to keep you pinned to a particular release tag.

includeForks

Whether to process forked repositories. By default, all forked repositories are skipped.

Name Value
type boolean
default false
cli --include-forks
env RENOVATE_INCLUDE_FORKS

By default, Renovate will skip over any repositories that are forked. This includes if the forked repository has a Renovate config file, because Renovate can't tell if that file was added by the original repository or not. If you wish to enable processing of a forked repository by Renovate, you need to add "includeForks": true to your repository config or run the CLI command with --include-forks=true.

If you are using the hosted Mend Renovate then this option will be configured to true automatically if you "Selected" repositories individually but remain as false if you installed for "All" repositories.

includePaths

Include package files only within these defined paths.

Name Value
type array
subType string
cli --include-paths
env RENOVATE_INCLUDE_PATHS

If you wish for Renovate to process only select paths in the repository, use includePaths.

Alternatively, if you need to just exclude certain paths in the repository then consider ignorePaths instead. If you are more interested in including only certain package managers (e.g. npm), then consider enabledManagers instead.

internalChecksFilter

When and how to filter based on internal checks.

Name Value
type string
allowedValues strict, flexible, none
default "none"
cli --internal-checks-filter
env RENOVATE_INTERNAL_CHECKS_FILTER

This setting determines whether Renovate controls when and how filtering of internal checks are performed, particularly when multiple versions of the same update type are available. Currently this applies to the stabilityDays check only.

  • none: No filtering will be performed, and the highest release will be used regardless of whether it's pending or not
  • strict: All pending releases will be filtered. PRs will be skipped unless a non-pending version is available
  • flexible: Similar to strict, but in the case where all versions are pending then a PR will be created with the highest pending version

The flexible mode can result in "flapping" of Pull Requests, where e.g. a pending PR with version 1.0.3 is first released but then downgraded to 1.0.2 once it passes stabilityDays. We recommend that you use the strict mode, and enable the dependencyDashboard so that you have visibility into suppressed PRs.

java

Configuration object for all Java package managers.

Name Value
type object
mergeable true
env RENOVATE_JAVA

Use this configuration option for shared config across all Java projects (Gradle and Maven).

js

Configuration object for JavaScript language.

Name Value
type object
mergeable true
cli --js
env RENOVATE_JS

Use this configuration option for shared config across npm/Yarn/pnpm and meteor package managers.

labels

Labels to set in Pull Request.

Name Value
type array
subType string
cli --labels
env RENOVATE_LABELS

By default, Renovate won't add any labels to its PRs. If you want Renovate to do so then define a labels array of one or more label strings. If you want the same label(s) for every PR then you can configure it at the top level of config. However you can also fully override them on a per-package basis.

Consider this example:

{
  "labels": ["dependencies"],
  "packageRules": [
    {
      "matchPackagePatterns": ["eslint"],
      "labels": ["linting"]
    }
  ]
}

With the above config, every PR raised by Renovate will have the label dependencies while PRs containing eslint-related packages will instead have the label linting.

lockFileMaintenance

Configuration for lock file maintenance.

Name Value
type object
default
{
  "enabled": false,
  "recreateClosed": true,
  "rebaseStalePrs": true,
  "branchTopic": "lock-file-maintenance",
  "commitMessageAction": "Lock file maintenance",
  "commitMessageTopic": null,
  "commitMessageExtra": null,
  "schedule": ["before 5am on monday"],
  "groupName": null,
  "prBodyDefinitions": {"Change": "All locks refreshed"}
}
mergeable true
env RENOVATE_LOCK_FILE_MAINTENANCE

This feature can be used to refresh lock files and keep them up-to-date. "Maintaining" a lock file means recreating it so that every dependency version within it is updated to the latest. Supported lock files are:

  • package-lock.json
  • yarn.lock
  • composer.lock
  • Gemfile.lock
  • poetry.lock
  • Cargo.lock
  • jsonnetfile.lock.json

Others may be added via feature request.

This feature is disabled by default. If you wish to enable this feature then you could add this to your configuration:

{
  "lockFileMaintenance": { "enabled": true }
}

To reduce "noise" in the repository, it defaults its schedule to "before 5am on monday", i.e. to achieve once-per-week semantics. Depending on its running schedule, Renovate may run a few times within that time window - even possibly updating the lock file more than once - but it hopefully leaves enough time for tests to run and automerge to apply, if configured.

major

Configuration to apply when an update type is major.

Name Value
type object
mergeable true
env RENOVATE_MAJOR

Add to this object if you wish to define rules that apply only to major updates.

minor

Configuration to apply when an update type is minor.

Name Value
type object
mergeable true
env RENOVATE_MINOR

Add to this object if you wish to define rules that apply only to minor updates.

node

Configuration object for Node version renovation.

Name Value
type object
default
{"commitMessageTopic": "Node.js"}
mergeable true
env RENOVATE_NODE

Using this configuration option allows you to apply common configuration and policies across all Node.js version updates even if managed by different package managers (npm, yarn, etc.).

Check out our Node.js documentation for a comprehensive explanation of how the node option can be used.

npmToken

npm token used to authenticate with the default registry.

Name Value
type string
cli --npm-token
env RENOVATE_NPM_TOKEN
default null

See Private npm module support for details on how this is used. Typically you would encrypt it and put it inside the encrypted object.

npmrc

String copy of .npmrc file. Use \n instead of line breaks.

Name Value
type string
cli --npmrc
env RENOVATE_NPMRC
default null

See Private npm module support for details on how this is used.

npmrcMerge

Whether to merge config.npmrc with repo .npmrc content if both are found.

Name Value
type boolean
default false
cli --npmrc-merge
env RENOVATE_NPMRC_MERGE

This option exists to provide flexibility about whether npmrc strings in config should override .npmrc files in the repo, or be merged with them. In some situations you need the ability to force override .npmrc contents in a repo (npmrcMerge=false) while in others you might want to simply supplement the settings already in the .npmrc (npmrcMerge=true). A use case for the latter is if you are a Renovate bot admin and wish to provide a default token for npmjs.org without removing any other .npmrc settings which individual repositories have configured (such as scopes/registries).

If false (default), it means that defining config.npmrc will result in any .npmrc file in the repo being overridden and its values ignored. If configured to true, it means that any .npmrc file in the repo will have config.npmrc prepended to it before running npm.

packageRules

Rules for matching package names.

Name Value
type array
mergeable true

packageRules is a powerful feature that lets you apply rules to individual packages or to groups of packages using regex pattern matching.

Here is an example if you want to group together all packages starting with eslint into a single branch/PR:

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^eslint"],
      "groupName": "eslint packages"
    }
  ]
}

Note how the above uses matchPackagePatterns with a regex value.

Here is an example where you might want to limit the "noisy" package aws-sdk to updates just once per week:

{
  "packageRules": [
    {
      "matchPackageNames": ["aws-sdk"],
      "schedule": ["after 9pm on sunday"]
    }
  ]
}

For Maven dependencies, the package name is <groupId:artefactId>, e.g. "matchPackageNames": ["com.thoughtworks.xstream:xstream"]

Note how the above uses matchPackageNames instead of matchPackagePatterns because it is an exact match package name. This is the equivalent of defining "matchPackagePatterns": ["^aws\-sdk$"] and hence much simpler. However you can mix together both matchPackageNames and matchPackagePatterns in the same package rule and the rule will be applied if either match. Example:

{
  "packageRules": [
    {
      "matchPackageNames": ["neutrino"],
      "matchPackagePatterns": ["^@neutrino/"],
      "groupName": "neutrino monorepo"
    }
  ]
}

The above rule will group together the neutrino package and any package matching @neutrino/*.

Path rules are convenient to use if you wish to apply configuration rules to certain package files using patterns. For example, if you have an examples directory and you want all updates to those examples to use the chore prefix instead of fix, then you could add this configuration:

{
  "packageRules": [
    {
      "matchPaths": ["examples/**"],
      "extends": [":semanticCommitTypeAll(chore)"]
    }
  ]
}

If you wish to limit Renovate to apply configuration rules to certain files in the root repository directory, you have to use matchPaths with either a partial string match or a minimatch pattern. For example you have multiple package.json and want to use dependencyDashboardApproval only on the root package.json:

{
  "packageRules": [
    {
      "matchPaths": ["+(package.json)"],
      "dependencyDashboardApproval": true
    }
  ]
}

Important to know: Renovate will evaluate all packageRules and not stop once it gets a first match. You should order your packageRules in order of importance so that later rules can override settings from earlier rules if needed.

Warning

Avoid nesting any object-type configuration in a packageRules array, such as a major or minor block.

allowedVersions

A version range or regex pattern capturing allowed versions for dependencies.

Name Value
type string
parent packageRules
default null

Use this - usually within a packageRule - to limit how far to upgrade a dependency. For example, if you wish to upgrade to Angular v1.5 but not to angular v1.6 or higher, you could define this to be <= 1.5 or < 1.6.0:

{
  "packageRules": [
    {
      "matchPackageNames": ["angular"],
      "allowedVersions": "<=1.5"
    }
  ]
}

The valid syntax for this will be calculated at runtime because it depends on the versioning scheme, which is itself dynamic.

This field also supports Regular Expressions if they begin and end with /. For example, the following will enforce that only 3 or 4-part versions are supported, without any prefixes:

{
  "packageRules": [
    {
      "matchPackageNames": ["com.thoughtworks.xstream:xstream"],
      "allowedVersions": "/^[0-9]+\\.[0-9]+\\.[0-9]+(\\.[0-9]+)?$/"
    }
  ]
}

This field also supports a special negated regex syntax for ignoring certain versions. Use the syntax !/ / like the following:

{
  "packageRules": [
    {
      "matchPackageNames": ["chalk"],
      "allowedVersions": "!/java$/"
    }
  ]
}

matchDepTypes

List of depTypes to match (e.g. [peerDependencies]). Valid only within packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field if you want to limit a packageRule to certain depType values. Invalid if used outside of a packageRule.

excludePackageNames

Package names to exclude. Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Important: Do not mix this up with the option ignoreDeps. Use ignoreDeps instead if all you want to do is have a list of package names for Renovate to ignore.

Use excludePackageNames if you want to have one or more exact name matches excluded in your package rule. See also matchPackageNames.

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^eslint"],
      "excludePackageNames": ["eslint-foo"]
    }
  ]
}

The above will match all package names starting with eslint but exclude the specific package eslint-foo.

excludePackagePatterns

Package name patterns to exclude. Valid only within a packageRules object.

Name Value
type array
subType string
format regex
parent packageRules
mergeable true

Use this field if you want to have one or more package name patterns excluded in your package rule. See also matchPackagePatterns.

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^eslint"],
      "excludePackagePatterns": ["^eslint-foo"]
    }
  ]
}

The above will match all package names starting with eslint but exclude ones starting with eslint-foo.

excludePackagePrefixes

Package name prefixes to exclude. Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field if you want to have one or more package name prefixes excluded in your package rule, without needing to write a regex. See also matchPackagePrefixes.

{
  "packageRules": [
    {
      "matchPackagePrefixes": ["eslint"],
      "excludePackagePrefixes": ["eslint-foo"]
    }
  ]
}

The above will match all package names starting with eslint but exclude ones starting with eslint-foo.

matchLanguages

List of languages to match (e.g. ["python"]). Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field to restrict rules to a particular language. e.g.

{
  "packageRules": [
    {
      "matchPackageNames": ["request"],
      "matchLanguages": ["python"],
      "enabled": false
    }
  ]
}

matchBaseBranches

List of strings containing exact matches (e.g. ["main"]) and/or regex expressions (e.g. ["/^release\/.*/"]). Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field to restrict rules to a particular branch. e.g.

{
  "packageRules": [
    {
      "matchBaseBranches": ["main"],
      "excludePackagePatterns": ["^eslint"],
      "enabled": false
    }
  ]
}

This field also supports Regular Expressions if they begin and end with /. e.g.

{
  "packageRules": [
    {
      "matchBaseBranches": ["/^release\\/.*/"],
      "excludePackagePatterns": ["^eslint"],
      "enabled": false
    }
  ]
}

matchManagers

List of package managers to match (e.g. ["pipenv"]). Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field to restrict rules to a particular package manager. e.g.

{
  "packageRules": [
    {
      "matchPackageNames": ["node"],
      "matchManagers": ["dockerfile"],
      "enabled": false
    }
  ]
}

matchDatasources

List of datasources to match (e.g. ["orb"]). Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field to restrict rules to a particular datasource. e.g.

{
  "packageRules": [
    {
      "matchDatasources": ["orb"],
      "labels": ["circleci-orb!!"]
    }
  ]
}

matchCurrentVersion

A version or range of versions to match against the current version of a package. Valid only within a packageRules object.

Name Value
type string
parent packageRules
mergeable true
default null

matchCurrentVersion can be an exact SemVer version or a SemVer range:

{
  "packageRules": [
    {
      "matchCurrentVersion": ">=1.0.0",
      "matchPackageNames": ["angular"]
    }
  ]
}

This field also supports Regular Expressions which must begin and end with /. For example, the following enforces that only 1.* versions will be used:

{
  "packageRules": [
    {
      "matchPackagePatterns": ["io.github.resilience4j"],
      "matchCurrentVersion": "/^1\\./"
    }
  ]
}

This field also supports a special negated regex syntax to ignore certain versions. Use the syntax !/ / like this:

{
  "packageRules": [
    {
      "matchPackagePatterns": ["io.github.resilience4j"],
      "matchCurrentVersion": "!/^0\\./"
    }
  ]
}

matchFiles

List of strings to do an exact match against package files with full path. Will only work inside a packageRules object.

Name Value
type array
subType string
parent packageRules

Renovate will compare matchFiles for an exact match against the dependency's package file or lock file.

For example the following would match package.json but not package/frontend/package.json:

  "matchFiles": ["package.json"],

Use matchPaths instead if you need more flexible matching.

matchPackageNames

Package names to match. Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field if you want to have one or more exact name matches in your package rule. See also excludePackageNames.

{
  "packageRules": [
    {
      "matchPackageNames": ["angular"],
      "rangeStrategy": "pin"
    }
  ]
}

The above will configure rangeStrategy to pin only for the package angular.

matchPackagePatterns

Package name patterns to match. Valid only within a packageRules object.

Name Value
type array
subType string
format regex
parent packageRules
mergeable true

Use this field if you want to have one or more package names patterns in your package rule. See also excludePackagePatterns.

{
  "packageRules": [
    {
      "matchPackagePatterns": ["^angular"],
      "rangeStrategy": "replace"
    }
  ]
}

The above will configure rangeStrategy to replace for any package starting with angular.

matchPackagePrefixes

Package name prefixes to match. Valid only within a packageRules object.

Name Value
type array
subType string
parent packageRules
mergeable true

Use this field to match a package prefix without needing to write a regex expression. See also excludePackagePrefixes.

{
  "packageRules": [
    {
      "matchPackagePrefixes": ["angular"],
      "rangeStrategy": "replace"
    }
  ]
}

Just like the earlier matchPackagePatterns example, the above will configure rangeStrategy to replace for any package starting with angular.

matchPaths

List of strings or glob patterns to match against package files. Will only work inside a packageRules object.

Name Value
type array
subType string
parent packageRules

Renovate will match matchPaths against both a partial string match or a minimatch glob pattern. If you want to avoid the partial string matching so that only glob matching is performed, wrap your string in +(...) like so:

  "matchPaths": ["+(package.json)"],

The above will match only the root package.json, whereas the following would match any package.json in any subdirectory too:

  "matchPaths": ["package.json"],

matchSourceUrlPrefixes

A list of source URL prefixes to match against, commonly used to group monorepos or packages from the same organization.

Name Value
type array
subType string
parent packageRules
mergeable true

Here's an example of where you use this to group together all packages from the Vue monorepo:

{
  "packageRules": [
    {
      "matchSourceUrlPrefixes": ["https://github.com/vuejs/vue"],
      "groupName": "Vue monorepo packages"
    }
  ]
}

Here's an example of where you use this to group together all packages from the renovatebot GitHub org:

{
  "packageRules": [
    {
      "matchSourceUrlPrefixes": ["https://github.com/renovatebot/"],
      "groupName": "All renovate packages"
    }
  ]
}

matchSourceUrls

A list of source URLs to exact match against.

Name Value
type array
subType string
parent packageRules
mergeable true

Here's an example of where you use this to match exact package urls:

{
  "packageRules": [
    {
      "matchSourceUrls": ["https://github.com/facebook/react"],
      "groupName": "React"
    }
  ]
}

matchUpdateTypes

Update types to match against (major, minor, pin, pinDigest, etc). Valid only within packageRules object.

Name Value
type array
subType string
allowedValues major, minor, patch, pin, pinDigest, digest, lockFileMaintenance, rollback, bump
parent packageRules
mergeable true

Use this field to match rules against types of updates. For example to apply a special label for Major updates:

{
  "packageRules": [
    {
      "matchUpdateTypes": ["major"],
      "labels": ["UPDATE-MAJOR"]
    }
  ]
}

replacementName

The name of the new dependency that replaces the old deprecated dependency.

Name Value
type string
parent packageRules
mergeable true
default null

This config option only works with the npm manager. We're working to support more managers, subscribe to issue renovatebot/renovate#14149 to follow our progress.

Use this field to define the name of a replacement package. Must be used with replacementVersion (see example below). You can suggest a new community package rule by editing the replacements.ts file on the Renovate repository and opening a pull request.

replacementVersion

The version of the new dependency that replaces the old deprecated dependency.

Name Value
type string
parent packageRules
mergeable true
default null

This config option only works with the npm manager. We're working to support more managers, subscribe to issue renovatebot/renovate#14149 to follow our progress.

Use this field to define the version of a replacement package. Must be used with replacementName. For example to replace the npm package jade with version 2.0.0 of the package pug:

{
  "packageRules": [
    {
      "matchDatasources": ["npm"],
      "matchPackageNames": ["jade"],
      "replacementName": "pug",
      "replacementVersion": "2.0.0"
    }
  ]
}

patch

Configuration to apply when an update type is patch.

Name Value
type object
mergeable true
env RENOVATE_PATCH

Add to this object if you wish to define rules that apply only to patch updates.

php

Configuration object for PHP.

Name Value
type object
mergeable true
env RENOVATE_PHP

pin

Configuration to apply when an update type is pin.

Name Value
type object
default
{
  "rebaseWhen": "behind-base-branch",
  "groupName": "Pin Dependencies",
  "groupSlug": "pin-dependencies",
  "commitMessageAction": "Pin",
  "group": {"commitMessageTopic": "dependencies", "commitMessageExtra": ""}
}
mergeable true
env RENOVATE_PIN

Add to this object if you wish to define rules that apply only to PRs that pin dependencies.

pinDigest

Configuration to apply when pinning a digest (no change in tag/version).

Name Value
type object
default
{
  "groupName": "Pin Dependencies",
  "groupSlug": "pin-dependencies",
  "commitMessageAction": "Pin",
  "group": {"commitMessageTopic": "dependencies", "commitMessageExtra": ""}
}
mergeable true
env RENOVATE_PIN_DIGEST

Add to this object if you wish to define rules that apply only to PRs that pin digests.

pinDigests

Whether to add digests to Dockerfile source images.

Name Value
type boolean
default false
cli --pin-digests
env RENOVATE_PIN_DIGESTS

If enabled Renovate will pin Docker images by means of their SHA256 digest and not only by tag so that they are immutable.

platformAutomerge

Controls if platform-native auto-merge is used.

Name Value
type boolean
supportedPlatforms azure, gitea, github, gitlab
default false
cli --platform-automerge
env RENOVATE_PLATFORM_AUTOMERGE

Warning

Before you enable platformAutomerge you should enable your Git hosting platform's capabilities to enforce test passing before PR merge. If you don't do this, the platform might merge Renovate PRs even if the repository's tests haven't started, are in still in progress, or possibly even when they have failed. On GitHub this is called "Require status checks before merging", which you can find in the "Branch protection rules" section of the settings for your repository. GitHub docs, about protected branches GitHub docs, require status checks before merging If you're using another platform, search their documentation for a similar feature.

If you have enabled automerge and set automergeType=pr in the Renovate config, then you can also set platformAutomerge to true to speed up merging via the platform's native automerge functionality.

Renovate tries platform-native automerge only when it initially creates the PR. Any PR that is being updated will be automerged with the Renovate-based automerge.

platformAutomerge will configure PRs to be merged after all (if any) branch policies have been met. This option is available for Azure, GitHub and GitLab. It falls back to Renovate-based automerge if the platform-native automerge is not available.

You can also fine-tune the behavior by setting packageRules if you want to use it selectively (e.g. per-package).

Note that the outcome of rebaseWhen=auto can differ when platformAutomerge=true. Normally when you set rebaseWhen=auto Renovate rebases any branch that's behind the base branch automatically, and some people rely on that. This behavior is no longer guaranteed when you enable platformAutomerge because the platform might automerge a branch which is not up-to-date. For example, GitHub might automerge a Renovate branch even if it's behind the base branch at the time.

Please check platform specific docs for version requirements.

platformCommit

Use platform API to perform commits instead of using Git directly.

Name Value
type boolean
default false
supportedPlatforms github
cli --platform-commit
env RENOVATE_PLATFORM_COMMIT

Only use this option if you run Renovate as a GitHub App. It does not apply when you use a Personal Access Token as credential.

When platformCommit is enabled, Renovate will create commits with GitHub's API instead of using git directly. This way Renovate can use GitHub's Commit signing support for bots and other GitHub Apps feature.

postUpdateOptions

Enable post-update options to be run after package/artifact updating.

Name Value
type array
allowedValues bundlerConservative, gomodMassage, gomodUpdateImportPaths, gomodTidy, gomodTidy1.17, npmDedupe, yarnDedupeFewer, yarnDedupeHighest
mergeable true
  • bundlerConservative: Enable conservative mode for bundler (Ruby dependencies). This will only update the immediate dependency in the lockfile instead of all subdependencies
  • gomodMassage: Enable massaging replace directives before calling go commands
  • gomodTidy: Run go mod tidy after Go module updates. This is implicitly enabled for major module updates when gomodUpdateImportPaths is enabled
  • gomodTidy1.17: Run go mod tidy -compat=1.17 after Go module updates.
  • gomodUpdateImportPaths: Update source import paths on major module updates, using mod
  • npmDedupe: Run npm dedupe after package-lock.json updates
  • yarnDedupeFewer: Run yarn-deduplicate --strategy fewer after yarn.lock updates
  • yarnDedupeHighest: Run yarn-deduplicate --strategy highest (yarn dedupe --strategy highest for Yarn >=2.2.0) after yarn.lock updates

postUpgradeTasks

Post-upgrade tasks that are executed before a commit is made by Renovate.

Name Value
type object
default
{"commands": [], "fileFilters": [], "executionMode": "update"}
cli --post-upgrade-tasks
env RENOVATE_POST_UPGRADE_TASKS

Note

Post-upgrade tasks can only be used on self-hosted Renovate instances.

Post-upgrade tasks are commands that are executed by Renovate after a dependency has been updated but before the commit is created. The intention is to run any additional command line tools that would modify existing files or generate new files when a dependency changes.

Each command must match at least one of the patterns defined in allowedPostUpgradeCommands (a global-only configuration option) in order to be executed. If the list of allowed tasks is empty then no tasks will be executed.

e.g.

{
  "postUpgradeTasks": {
    "commands": ["tslint --fix"],
    "fileFilters": ["yarn.lock", "**/*.js"],
    "executionMode": "update"
  }
}

The postUpgradeTasks configuration consists of three fields:

commands

A list of post-upgrade commands that are executed before a commit is made by Renovate.

Name Value
type array
subType string
parent postUpgradeTasks
env RENOVATE_COMMANDS

A list of commands that are executed after Renovate has updated a dependency but before the commit is made.

You can use variable templating in your commands if allowPostUpgradeCommandTemplating is enabled.

fileFilters

Files that match the glob pattern will be committed after running a post-upgrade task.

Name Value
type array
subType string
parent postUpgradeTasks
env RENOVATE_FILE_FILTERS

A list of glob-style matchers that determine which files will be included in the final commit made by Renovate.

executionMode

Controls when the post upgrade tasks run: on every update, or once per upgrade branch.

Name Value
type string
parent postUpgradeTasks
allowedValues update, branch
default "update"
env RENOVATE_EXECUTION_MODE

Defaults to update, but can also be set to branch. This sets the level the postUpgradeTask runs on, if set to update the postUpgradeTask will be executed for every dependency on the branch. If set to branch the postUpgradeTask is executed for the whole branch.

prBodyColumns

List of columns to use in PR bodies.

Name Value
type array
subType string
default
["Package", "Type", "Update", "Change", "Pending"]
cli --pr-body-columns
env RENOVATE_PR_BODY_COLUMNS

Use this array to provide a list of column names you wish to include in the PR tables.

For example, if you wish to add the package file name to the table, you would add this to your config:

{
  "prBodyColumns": [
    "Package",
    "Update",
    "Type",
    "New value",
    "Package file",
    "References"
  ]
}

Note

"Package file" is predefined in the default prBodyDefinitions object so does not require a definition before it can be used.

prBodyDefinitions

Table column definitions for use in PR tables.

Name Value
type object
freeChoice true
mergeable true
default
{
  "Package": "{{{depNameLinked}}}",
  "Type": "{{{depType}}}",
  "Update": "{{{updateType}}}",
  "Current value": "{{{currentValue}}}",
  "New value": "{{{newValue}}}",
  "Change": "`{{{displayFrom}}}` -> `{{{displayTo}}}`",
  "Pending": "{{{displayPending}}}",
  "References": "{{{references}}}",
  "Package file": "{{{packageFile}}}"
}
cli --pr-body-definitions
env RENOVATE_PR_BODY_DEFINITIONS

You can configure this object to either (a) modify the template for an existing table column in PR bodies, or (b) you wish to add a definition for a new/additional column.

Here is an example of modifying the default value for the "Package" column to put it inside a <code></code> block:

{
  "prBodyDefinitions": {
    "Package": "`{{{depName}}}`"
  }
}

Here is an example of adding a custom "Sourcegraph" column definition:

{
  "prBodyDefinitions": {
    "Sourcegraph": "[![code search for \"{{{depName}}}\"](https://sourcegraph.com/search/badge?q=repo:%5Egithub%5C.com/{{{repository}}}%24+case:yes+-file:package%28-lock%29%3F%5C.json+{{{depName}}}&label=matches)](https://sourcegraph.com/search?q=repo:%5Egithub%5C.com/{{{repository}}}%24+case:yes+-file:package%28-lock%29%3F%5C.json+{{{depName}}})"
  },
  "prBodyColumns": [
    "Package",
    "Update",
    "New value",
    "References",
    "Sourcegraph"
  ]
}

Tip

Columns must also be included in the prBodyColumns array in order to be used, so that's why it's included above in the example.

prBodyNotes

List of additional notes/templates to be included in the Pull Request bodies.

Name Value
type array
subType string
mergeable true
cli --pr-body-notes
env RENOVATE_PR_BODY_NOTES

Use this field to add custom content inside PR bodies, including conditionally.

e.g. if you wish to add an extra Warning to major updates:

{
  "prBodyNotes": ["{{#if isMajor}}:warning: MAJOR MAJOR MAJOR :warning:{{/if}}"]
}

prBodyTemplate

Pull Request body template. Controls which sections are rendered in the body.

Name Value
type string
default "{{{header}}}{{{table}}}{{{notes}}}{{{changelogs}}}{{{configDescription}}}{{{controls}}}{{{footer}}}"
env RENOVATE_PR_BODY_TEMPLATE

This setting controls which sections are rendered in the body of the pull request.

The available sections are header, table, notes, changelogs, configDescription, controls, footer.

prConcurrentLimit

Limit to a maximum of x concurrent branches/PRs. 0 (default) means no limit.

Name Value
type integer
default 0
cli --pr-concurrent-limit
env RENOVATE_PR_CONCURRENT_LIMIT

This setting - if enabled - limits Renovate to a maximum of x concurrent PRs open at any time.

This limit is enforced on a per-repository basis.

Note: Renovate always creates security PRs, even if the concurrent PR limit is already reached. Security PRs have [SECURITY] in their PR title.

prCreation

When to create the PR for a branch.

Name Value
type string
allowedValues immediate, not-pending, status-success, approval
default "immediate"
cli --pr-creation
env RENOVATE_PR_CREATION

This setting tells Renovate when you would like it to raise PRs:

  • immediate (default): Renovate will create PRs immediately after creating the corresponding branch
  • not-pending: Renovate will wait until status checks have completed (passed or failed) before raising the PR
  • status-success: Renovate won't raise PRs unless tests pass

Renovate defaults to immediate but you might want to change this to not-pending instead.

With prCreation set to immediate, you'll get a Pull Request and possible associated notification right away when a new update is available. Your test suite takes a bit of time to complete, so if you go look at the new PR right away, you don't know if your tests pass or fail. You're basically waiting until you have the test results, before you can decide if you want to merge the PR or not.

With prCreation set to not-pending, Renovate waits until all tests have finished running, and only then creates the PR. When you get the PR notification, you can take action immediately, as you have the full test results.

When you set prCreation to not-pending you're reducing the "noise" but get notified of new PRs a bit later.

prFooter

Text added here will be placed last in the PR body, with a divider separator before it.

Name Value
type string
default "This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate)."
cli --pr-footer
env RENOVATE_PR_FOOTER

prHeader

Text added here will be placed first in the PR body.

Name Value
type string
cli --pr-header
env RENOVATE_PR_HEADER
default null

prHourlyLimit

Rate limit PRs to maximum x created per hour. 0 (default) means no limit.

Name Value
type integer
default 0
cli --pr-hourly-limit
env RENOVATE_PR_HOURLY_LIMIT

This setting - if enabled - helps slow down Renovate, particularly during the onboarding phase. What may happen without this setting is:

  1. Onboarding PR is created
  2. User merges onboarding PR to activate Renovate
  3. Renovate creates a "Pin Dependencies" PR (if necessary)
  4. User merges Pin PR
  5. Renovate then creates every single upgrade PR necessary - potentially dozens

The above can result in swamping CI systems, as well as a lot of retesting if branches need to be rebased every time one is merged. Instead, if prHourlyLimit is configure to a value like 1 or 2, it will mean that Renovate creates at most that many new PRs within each hourly period (:00-:59). So the project should still result in all PRs created perhaps within the first 24 hours maximum, but at a rate that may allow users to merge them once they pass tests. It does not place a limit on the number of concurrently open PRs - only on the rate they are created.

This limit is enforced on a per-repository basis.

prNotPendingHours

Timeout in hours for when prCreation=not-pending.

Name Value
type integer
default 25
cli --pr-not-pending-hours
env RENOVATE_PR_NOT_PENDING_HOURS

If you configure prCreation=not-pending, then Renovate will wait until tests are non-pending (all pass or at least one fails) before creating PRs. However there are cases where PRs may remain in pending state forever, e.g. absence of tests or status checks that are configure to pending indefinitely. This is why we configured an upper limit for how long we wait until creating a PR.

Note

If the option stabilityDays is non-zero then Renovate disables the prNotPendingHours functionality.

prPriority

Set sorting priority for PR creation. PRs with higher priority are created first, negative priority last.

Name Value
type integer
default 0

Sometimes Renovate needs to rate limit its creation of PRs, e.g. hourly or concurrent PR limits. In such cases it sorts/prioritizes by default based on the update type (e.g. patches raised before minor, minor before major). If you have dependencies that are more or less important than others then you can use the prPriority field for PR sorting. The default value is 0, so setting a negative value will make dependencies sort last, while higher values sort first.

Here's an example of how you would define PR priority so that devDependencies are raised last and react is raised first:

{
  "packageRules": [
    {
      "matchDepTypes": ["devDependencies"],
      "prPriority": -1
    },
    {
      "matchPackageNames": ["react"],
      "prPriority": 5
    }
  ]
}

prTitle

Pull Request title template (deprecated). Inherits from commitMessage if null.

Name Value
type string
env RENOVATE_PR_TITLE

The PR title is important for some of Renovate's matching algorithms (e.g. determining whether to recreate a PR or not) so ideally don't modify it much.

printConfig

If enabled, Renovate logs the fully resolved config for each repo, plus the fully resolved presets.

Name Value
type boolean
default false
cli --print-config
env RENOVATE_PRINT_CONFIG

This option is useful for troubleshooting, particularly if using presets. e.g. run renovate foo/bar --print-config > config.log and the fully-resolved config will be included in the log file.

pruneBranchAfterAutomerge

Set to true to enable branch pruning after automerging.

Name Value
type boolean
default true
cli --prune-branch-after-automerge
env RENOVATE_PRUNE_BRANCH_AFTER_AUTOMERGE

By default Renovate deletes, or "prunes", the branch after automerging. Set pruneBranchAfterAutomerge to false to keep the branch after automerging.

pruneStaleBranches

Set to false to disable pruning stale branches.

Name Value
type boolean
default true
cli --prune-stale-branches
env RENOVATE_PRUNE_STALE_BRANCHES

Configure to false to disable deleting orphan branches and autoclosing PRs. Defaults to true.

python

Configuration object for Python.

Name Value
type object
mergeable true
env RENOVATE_PYTHON

Currently the only Python package manager is pip - specifically for requirements.txt and requirements.pip files - so adding any config to this python object is essentially the same as adding it to the pip_requirements object instead.

rangeStrategy

Determines how to modify or update existing ranges.

Name Value
type string
default "replace"
allowedValues auto, pin, bump, replace, widen, update-lockfile, in-range-only

Behavior:

  • auto = Renovate decides (this will be done on a manager-by-manager basis)
  • pin = convert ranges to exact versions, e.g. ^1.0.0 -> 1.1.0
  • bump = e.g. bump the range even if the new version satisfies the existing range, e.g. ^1.0.0 -> ^1.1.0
  • replace = Replace the range with a newer one if the new version falls outside it, and update nothing otherwise
  • widen = Widen the range with newer one, e.g. ^1.0.0 -> ^1.0.0 || ^2.0.0
  • update-lockfile = Update the lock file when in-range updates are available, otherwise replace for updates out of range. Works for bundler, composer, npm, yarn, terraform and poetry so far
  • in-range-only = Update the lock file when in-range updates are available, ignore package file updates

Renovate's "auto" strategy works like this for npm:

  1. Always pin devDependencies
  2. Pin dependencies if we detect that it's an app and not a library
  3. Widen peerDependencies
  4. If an existing range already ends with an "or" operator - e.g. "^1.0.0 || ^2.0.0" - then Renovate will widen it, e.g. making it into "^1.0.0 || ^2.0.0 || ^3.0.0"
  5. Otherwise, replace the range. e.g. "^2.0.0" would be replaced by "^3.0.0"

By default, Renovate assumes that if you are using ranges then it's because you want them to be wide/open. Renovate won't deliberately "narrow" any range by increasing the semver value inside.

For example, if your package.json specifies a value for left-pad of ^1.0.0 and the latest version on npmjs is 1.2.0, then Renovate won't change anything because 1.2.0 satisfies the range. If instead you'd prefer to be updated to ^1.2.0 in cases like this, then configure rangeStrategy to bump in your Renovate config.

This feature supports simple caret (^) and tilde (~) ranges only, like ^1.0.0 and ~1.0.0.

The in-range-only strategy may be useful if you want to leave the package file unchanged and only do update-lockfile within the existing range. The in-range-only strategy behaves like update-lockfile, but discards any updates where the new version of the dependency is not equal to the current version. We recommend you avoid using the in-range-only strategy unless you strictly need it. Using the in-range-only strategy may result in you being multiple releases behind without knowing it.

rebaseLabel

Label to request a rebase from Renovate bot.

Name Value
type string
default "rebase"
cli --rebase-label
env RENOVATE_REBASE_LABEL

On supported platforms it is possible to add a label to a PR to manually request Renovate to recreate/rebase it. By default this label is "rebase" but you can configure it to anything you want by changing this rebaseLabel field.

rebaseWhen

Controls when Renovate rebases an existing branch.

Name Value
type string
allowedValues auto, never, conflicted, behind-base-branch
default "auto"
cli --rebase-when
env RENOVATE_REBASE_WHEN

Possible values and meanings:

  • auto: Renovate will autodetect the best setting. It will use behind-base-branch if configured to automerge or repository has been set to require PRs to be up to date. Otherwise, conflicted will be used instead
  • never: Renovate will never rebase the branch or update it unless manually requested
  • conflicted: Renovate will rebase only if the branch is conflicted
  • behind-base-branch: Renovate will rebase whenever the branch falls 1 or more commit behind its base branch

rebaseWhen=conflicted is not recommended if you have enabled Renovate automerge, because:

  • It could result in a broken base branch if two updates are merged one after another without testing the new versions together
  • If you have enforced that PRs must be up-to-date before merging (e.g. using branch protection on GitHub), then automerge won't be possible as soon as a PR gets out-of-date but remains non-conflicted

It is also recommended to avoid rebaseWhen=never as it can result in conflicted branches with outdated PR descriptions and/or status checks.

Avoid setting rebaseWhen=never and then also setting prCreation=not-pending as this can prevent creation of PRs.

recreateClosed

Recreate PRs even if same ones were closed previously.

Name Value
type boolean
default false
cli --recreate-closed
env RENOVATE_RECREATE_CLOSED

By default, Renovate will detect if it has proposed an update to a project before and not propose the same one again. For example the Webpack 3.x case described above. This field lets you customise this behavior down to a per-package level. For example we override it to true in the following cases where branch names and PR titles need to be reused:

  • Package groups
  • When pinning versions
  • Lock file maintenance

Typically you shouldn't need to modify this setting.

regexManagers

Custom managers using regex matching.

Name Value
type array
subType object
cli --regex-managers
mergeable true
env RENOVATE_REGEX_MANAGERS

Use regexManagers entries to configure the regex manager in Renovate.

You can define custom managers for cases such as:

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

The custom manager concept is based on using Regular Expression named capture groups.

You must have a named capture group matching (e.g. (?<depName>.*)) or configure it's corresponding template (e.g. depNameTemplate) for these fields:

  • datasource
  • depName
  • 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, see our documentation for the regex manager. For template fields, use the triple brace {{{ }}} notation to avoid Handlebars escaping any special characters.

matchStrings

Regex capture rule to use. Valid only within a regexManagers object.

Name Value
type array
subType string
format regex
parent regexManagers

matchStrings should each be a valid regular expression, optionally with named capture groups.

Example:

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

matchStringsStrategy

Strategy how to interpret matchStrings.

Name Value
type string
default "any"
allowedValues any, recursive, combination
parent regexManagers

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 3 lines in the Dockerfile. renovate.json:

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

a Dockerfile:

FROM amd64/ubuntu:18.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 used as basis be used as 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 regex 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 regex manager will upgrade both definitions as its first matchStrings matches both test keys.

renovate.json:

{
  "regexManagers": [
    {
      "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"
    }
  ]
}

example.json:

{
  "backup": {
    "test": {
      "name": "grafana/loki",
      "type": "docker",
      "value": "1.6.1"
    }
  },
  "setup": {
    "test": {
      "name": "python",
      "type": "docker",
      "value": "3.9.0"
    }
  }
}

combination

This option allows the possibility to combine the values of multiple lines inside a file. While using multiple lines is also possible using both other matchStringStrategy values, the combination approach is less susceptible to white space or line breaks stopping a match.

combination will only match at most one dependency per file, so if you want to update multiple dependencies using combination you have to define multiple regex managers.

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

renovate.json:

{
  "regexManagers": [
    {
      "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"
    }
  ]
}

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 regex manager will match a single dependency each.

depNameTemplate

Optional depName for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional extractVersion for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional packageName for extracted dependencies, else defaults to depName value. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional currentValue for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional datasource for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional depType for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional versioning for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional registry URL for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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

Optional extractVersion for extracted dependencies. Valid only within a regexManagers object.

Name Value
type string
parent regexManagers
default null

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.

helm-values.yaml:

# The image of the service <registry>/<repo>/<image>:<tag>
image: my.old.registry/aRepository/andImage:1.18-alpine

regex definition:

{
  "regexManagers": [
    {
      "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:

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

registryAliases

Aliases for registries.

Name Value
type object
additionalProperties [object Object]
supportedManagers helm-requirements, helmv3, helmfile, gitlabci
cli --registry-aliases
env RENOVATE_REGISTRY_ALIASES

You can use the registryAliases object to set registry aliases.

This feature works with the following managers:

registryUrls

List of URLs to try for dependency lookup. Package manager specific.

Name Value
type array
subType string

Usually Renovate is able to either (a) use the default registries for a datasource, or (b) automatically detect during the manager extract phase which custom registries are in use. In case there is a need to configure them manually, it can be done using this registryUrls field, typically using packageRules like so:

{
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "registryUrls": ["https://docker.mycompany.domain"]
    }
  ]
}

The field supports multiple URLs but it is datasource-dependent on whether only the first is used or multiple.

replacement

Configuration to apply when replacing a dependency.

Name Value
type object
default
{
  "branchTopic": "{{{depNameSanitized}}}-replacement",
  "commitMessageAction": "Replace",
  "commitMessageExtra": "with {{newName}} {{#if isMajor}}{{{prettyNewMajor}}}{{else}}{{#if isSingleVersion}}{{{prettyNewVersion}}}{{else}}{{{newValue}}}{{/if}}{{/if}}",
  "prBodyNotes": [
    "This is a special PR that replaces `{{{depNameSanitized}}}` with the community suggested minimal stable replacement version."
  ]
}
mergeable true
env RENOVATE_REPLACEMENT

Add to this object if you wish to define rules that apply only to PRs that replace dependencies.

respectLatest

Ignore versions newer than npm "latest" version.

Name Value
type boolean
cli --respect-latest
env RENOVATE_RESPECT_LATEST
default true

Similar to ignoreUnstable, this option controls whether to update to versions that are greater than the version tagged as latest in the repository. By default, renovate will update to a version greater than latest only if the current version is itself past latest.

reviewers

Requested reviewers for Pull Requests (either username or email address depending on the platform).

Name Value
type array
subType string
cli --reviewers
env RENOVATE_REVIEWERS

Must be valid usernames.

If on GitHub and assigning a team to review, you must use the prefix team: and add the last part of the team name. Say the full team name on GitHub is @organization/foo, then you'd set the config option like this:

{
  "reviewers": ["team:foo"]
}

reviewersFromCodeOwners

Determine reviewers based on configured code owners and changes in PR.

Name Value
type boolean
default false
cli --reviewers-from-code-owners
env RENOVATE_REVIEWERS_FROM_CODE_OWNERS

If enabled Renovate tries to determine PR reviewers 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.

reviewersSampleSize

Take a random sample of given size from reviewers.

Name Value
type integer
cli --reviewers-sample-size
env RENOVATE_REVIEWERS_SAMPLE_SIZE

rollback

Configuration to apply when rolling back a version.

Name Value
type object
default
{
  "branchTopic": "{{{depNameSanitized}}}-rollback",
  "commitMessageAction": "Roll back",
  "semanticCommitType": "fix"
}
mergeable true
env RENOVATE_ROLLBACK

Add to this object if you wish to define rules that apply only to PRs that roll back versions.

rollbackPrs

Create PRs to roll back versions if the current version is not found in the registry.

Name Value
type boolean
default false
cli --rollback-prs
env RENOVATE_ROLLBACK_PRS

There are times when a dependency version in use by a project gets removed from the registry. For some registries, existing releases or even whole packages can be removed or "yanked" at any time, while for some registries only very new or unused releases can be removed. Renovate's "rollback" feature exists to propose a downgrade to the next-highest release if the current release is no longer found in the registry.

Renovate does not create these rollback PRs by default, with one exception: npm packages get a rollback PR if needed.

You can configure the rollbackPrs property globally, per-language, or per-package to override the default behavior.

ruby

Configuration object for Ruby language.

Name Value
type object
mergeable true
env RENOVATE_RUBY

rust

Configuration option for Rust package management.

Name Value
type object
mergeable true
env RENOVATE_RUST

schedule

Limit branch creation to these times of day or week.

Name Value
type array
subType string
cli --schedule
default
["at any time"]

The schedule option allows you to define times of week or month for Renovate updates. Running Renovate around the clock can be too "noisy" for some projects. To reduce the noise you can use the schedule config option to limit the time frame in which Renovate will perform actions on your repository. You can use the standard Cron syntax and Later syntax to define your schedule.

The default value for schedule is "at any time", which is functionally the same as declaring a null schedule. i.e. Renovate will run on the repository around the clock.

The easiest way to define a schedule is to use a preset if one of them fits your requirements. See Schedule presets for details and feel free to request a new one in the source repository if you think others would benefit from it too.

Otherwise, here are some text schedules that are known to work:

every weekend
before 5:00am
after 10pm and before 5:00am
after 10pm and before 5am every weekday
on friday and saturday
every 3 months on the first day of the month
* 0 2 * *

Warning

For Cron schedules, you must use the * wildcard for the minutes value, as Renovate doesn't support minute granularity.

One example might be that you don't want Renovate to run during your typical business hours, so that your build machines don't get clogged up testing package.json updates. You could then configure a schedule like this at the repository level:

{
  "schedule": ["after 10pm and before 5am every weekday", "every weekend"]
}

This would mean that Renovate can run for 7 hours each night plus all the time on weekends.

This scheduling feature can also be particularly useful for "noisy" packages that are updated frequently, such as aws-sdk.

To restrict aws-sdk to only monthly updates, you could add this package rule:

{
  "packageRules": [
    {
      "matchPackageNames": ["aws-sdk"],
      "extends": ["schedule:monthly"]
    }
  ]
}

Technical details: We mostly rely on the text parsing of the library @breejs/later but only its concepts of "days", "time_before", and "time_after". Read the parser documentation at breejs.github.io/later/parsers.html#text. To parse Cron syntax, Renovate uses @cheap-glitch/mi-cron. Renovate does not support scheduled minutes or "at an exact time" granularity.

Note

Actions triggered via the Dependency Dashboard are not restricted by a configured schedule.

Tip

To validate your later schedule before updating your renovate.json, you can use this CodePen.

semanticCommitScope

Commit scope to use if Semantic Commits are enabled.

Name Value
type string
default "deps"
cli --semantic-commit-scope
env RENOVATE_SEMANTIC_COMMIT_SCOPE

By default you will see Angular-style commit prefixes like "chore(deps):". If you wish to change it to something else like "package" then it will look like "chore(package):". You can also use parentDir or baseDir to namespace your commits for monorepos e.g. "{{parentDir}}".

semanticCommitType

Commit type to use if Semantic Commits is enabled.

Name Value
type string
default "chore"
cli --semantic-commit-type
env RENOVATE_SEMANTIC_COMMIT_TYPE

By default you will see Angular-style commit prefixes like "chore(deps):". If you wish to change it to something else like "ci" then it will look like "ci(deps):".

semanticCommits

Enable Semantic Commit prefixes for commits and PR titles.

Name Value
type string
allowedValues auto, enabled, disabled
default "auto"
cli --semantic-commits
env RENOVATE_SEMANTIC_COMMITS

If you are using a semantic prefix for your commits, then you will want to enable this setting. Although it's configurable to a package-level, it makes most sense to configure it at a repository level. If configured to enabled, then the semanticCommitScope and semanticCommitType fields will be used for each commit message and PR title.

Renovate autodetects if your repository is already using semantic commits or not and follows suit, so you only need to configure this if you wish to override Renovate's autodetected setting.

separateMajorMinor

If set to false, Renovate will upgrade dependencies to their latest release only. Renovate will not separate major or minor branches.

Name Value
type boolean
cli --separate-major-minor
env RENOVATE_SEPARATE_MAJOR_MINOR
default true

Renovate's default behavior is to create a separate branch/PR if both minor and major version updates exist (note that your choice of rangeStrategy value can influence which updates exist in the first place however). For example, if you were using Webpack 2.0.0 and versions 2.1.0 and 3.0.0 were both available, then Renovate would create two PRs so that you have the choice whether to apply the minor update to 2.x or the major update of 3.x. If you were to apply the minor update then Renovate would keep updating the 3.x branch for you as well, e.g. if Webpack 3.0.1 or 3.1.0 were released. If instead you applied the 3.0.0 update then Renovate would clean up the unneeded 2.x branch for you on the next run.

It is recommended that you leave this option to true, because of the polite way that Renovate handles this. For example, let's say in the above example that you decided you wouldn't update to Webpack 3 for a long time and don't want to build/test every time a new 3.x version arrives. In that case, simply close the "Update Webpack to version 3.x" PR and it won't be recreated again even if subsequent Webpack 3.x versions are released. You can continue with Webpack 2.x for as long as you want and get any updates/patches that are made for it. Then eventually when you do want to update to Webpack 3.x you can make that update to package.json yourself and commit it to the base branch once it's tested. After that, Renovate will resume providing you updates to 3.x again! i.e. if you close a major upgrade PR then it won't come back again, but once you make the major upgrade yourself then Renovate will resume providing you with minor or patch updates.

This option also has priority over package groups configured by packageRule. So Renovate will propose separate PRs for major and minor updates of packages even if they are grouped. If you want to enforce grouped package updates, you need to set this option to false within the packageRule.

separateMinorPatch

If set to true, Renovate will separate minor and patch updates into separate branches.

Name Value
type boolean
default false
cli --separate-minor-patch
env RENOVATE_SEPARATE_MINOR_PATCH

By default, Renovate won't distinguish between "patch" (e.g. 1.0.x) and "minor" (e.g. 1.x.0) releases - it groups them together. E.g., if you are running version 1.0.0 of a package and both versions 1.0.1 and 1.1.0 are available then Renovate will raise a single PR for version 1.1.0. If you wish to distinguish between patch and minor upgrades, for example if you wish to automerge patch but not minor, then you can configured this option to true.

separateMultipleMajor

If set to true, PRs will be raised separately for each available major upgrade version.

Name Value
type boolean
default false
cli --separate-multiple-major
env RENOVATE_SEPARATE_MULTIPLE_MAJOR

Configure this to true if you wish to get one PR for every separate major version upgrade of a dependency. e.g. if you are on webpack@v1 currently then default behavior is a PR for upgrading to webpack@v3 and not for webpack@v2. If this setting is true then you would get one PR for webpack@v2 and one for webpack@v3.

stabilityDays

Number of days required before a new release is considered stable.

Name Value
type integer
default 0
cli --stability-days
env RENOVATE_STABILITY_DAYS

If this is set to a non-zero value, and an update has a release timestamp header, then Renovate will check if the "stability days" have passed.

Note: Renovate will wait for the set number of stabilityDays to pass for each separate version. Renovate does not wait until the package has seen no releases for x stabilityDays. stabilityDays is not intended to help with slowing down fast releasing project updates. If you want to slow down PRs for a specific package, setup a custom schedule for that package. Read our selective-scheduling help to learn how to set the schedule.

If the number of days since the release is less than the set stabilityDays a "pending" status check is added to the branch. If enough days have passed then the "pending" status is removed, and a "passing" status check is added.

Some datasources do not provide a release timestamp (in which case this feature is not compatible), and other datasources may provide a release timestamp but it's not supported by Renovate (in which case a feature request needs to be implemented).

Maven users: you cannot use stabilityDays if a Maven source returns unreliable last-modified headers.

There are a couple of uses for stabilityDays:

Suppress branch/PR creation for X days

If you combine stabilityDays=3 and internalChecksFilter="strict" then Renovate will hold back from creating branches until 3 or more days have elapsed since the version was released. It's recommended that you enable dependencyDashboard=true so you don't lose visibility of these pending PRs.

Prevent holding broken npm packages

npm packages less than 72 hours (3 days) old can be unpublished, which could result in a service impact if you have already updated to it. Set stabilityDays to 3 for npm packages to prevent relying on a package that can be removed from the registry:

{
  "packageRules": [
    {
      "matchDatasources": ["npm"],
      "stabilityDays": 3
    }
  ]
}

Await X days before Automerging

If you have both automerge as well as stabilityDays enabled, it means that PRs will be created immediately but automerging will be delayed until X days have passed. This works because Renovate will add a "renovate/stability-days" pending status check to each branch/PR and that pending check will prevent the branch going green to automerge.

stopUpdatingLabel

Label to make Renovate stop updating a PR.

Name Value
type string
default "stop-updating"
supportedPlatforms azure, github, gitlab, gitea
cli --stop-updating-label
env RENOVATE_STOP_UPDATING_LABEL

This feature only works on supported platforms, check the table above.

If you want Renovate to stop updating a PR, you can apply a label to the PR. By default, Renovate listens to the label: "stop-updating".

You can set your own label name with the "stopUpdatingLabel" field:

{
  "stopUpdatingLabel": "take-a-break-renovate"
}

suppressNotifications

Options to suppress various types of warnings and other notifications.

Name Value
type array
subType string
default
["deprecationWarningIssues"]
allowedValues prIgnoreNotification, branchAutomergeFailure, lockFileErrors, artifactErrors, deprecationWarningIssues, onboardingClose, configErrorIssue
mergeable true

Use this field to suppress various types of warnings and other notifications from Renovate. Example:

{
  "suppressNotifications": ["prIgnoreNotification"]
}

The above config will suppress the comment which is added to a PR whenever you close a PR unmerged.

timezone

IANA Time Zone

Name Value
type string
cli --timezone
env RENOVATE_TIMEZONE
default null

It is only recommended to configure this field if you wish to use the schedules feature and want to write them in your local timezone. Please see the above link for valid timezone names.

transitiveRemediation

Enable remediation of transitive dependencies.

Name Value
type boolean
default false
supportedManagers npm
supportedPlatforms github
cli --transitive-remediation
env RENOVATE_TRANSITIVE_REMEDIATION

When enabled, Renovate tries to remediate vulnerabilities even if they exist only in transitive dependencies.

Applicable only for GitHub platform (with vulnerability alerts enabled) and npm manager. When the lockfileVersion is higher than 1 in package-lock.json, remediations are only possible when changes are made to package.json.

This is considered a feature flag with the aim to remove it and default to this behavior once it has been more widely tested.

updateInternalDeps

Whether to update internal dep versions in a monorepo. Works on Lerna or Yarn Workspaces.

Name Value
type boolean
default false
cli --update-internal-deps
env RENOVATE_UPDATE_INTERNAL_DEPS

Renovate defaults to skipping any internal package dependencies within monorepos. In such case dependency versions won't be updated by Renovate.

To opt in to letting Renovate update internal package versions normally, set this configuration option to true.

updateLockFiles

Set to false to disable lock file updating.

Name Value
type boolean
cli --update-lock-files
env RENOVATE_UPDATE_LOCK_FILES
default true

updateNotScheduled

Whether to update branches when not scheduled. Renovate will not create branches outside of the schedule.

Name Value
type boolean
cli --update-not-scheduled
env RENOVATE_UPDATE_NOT_SCHEDULED
default true

When schedules are in use, it generally means "no updates". However there are cases where updates might be desirable - e.g. if you have configured prCreation=not-pending, or you have rebaseWhen=behind-base-branch and the base branch is updated so you want Renovate PRs to be rebased.

This defaults to true, meaning that Renovate will perform certain "desirable" updates to existing PRs even when outside of schedule. If you wish to disable all updates outside of scheduled hours then configure this field to false.

updatePinnedDependencies

Whether to update pinned (single version) dependencies or not.

Name Value
type boolean
default true
cli --update-pinned-dependencies
env RENOVATE_UPDATE_PINNED_DEPENDENCIES

By default, Renovate will try to update all detected dependencies, regardless of whether they are defined using pinned single versions (e.g. 1.2.3) or constraints/ranges (e.g. (^1.2.3). You can set this option to false if you wish to disable updating for pinned (single version) dependencies specifically.

useBaseBranchConfig

Whether to read configuration from baseBranches instead of only the default branch.

Name Value
type string
allowedValues merge, none
default "none"
cli --use-base-branch-config
env RENOVATE_USE_BASE_BRANCH_CONFIG

By default, Renovate will read config file from the default branch only and will ignore any config files in base branches. You can configure useBaseBranchConfig=merge to instruct Renovate to merge the config from each base branch over the top of the config in the default branch.

The config file name in the base branch must be the same as in the default branch and cannot be package.json. This scenario may be useful for testing the config changes in base branches instantly.

userStrings

User-facing strings for the Renovate comment when a PR is closed.

Name Value
type object
freeChoice true
default
{
  "ignoreTopic": "Renovate Ignore Notification",
  "ignoreMajor": "As this PR has been closed unmerged, Renovate will ignore this upgrade and you will not receive PRs for *any* future {{{newMajor}}}.x releases. However, if you upgrade to {{{newMajor}}}.x manually then Renovate will reenable minor and patch updates automatically.",
  "ignoreDigest": "As this PR has been closed unmerged, Renovate will ignore this upgrade and you will not receive PRs for the `{{{depName}}}` `{{{newDigestShort}}}` update again.",
  "ignoreOther": "As this PR has been closed unmerged, Renovate will now ignore this update ({{{newValue}}}). You will still receive a PR once a newer version is released, so if you wish to permanently ignore this dependency, please add it to the `ignoreDeps` array of your renovate config."
}
cli --user-strings
env RENOVATE_USER_STRINGS

When a PR is closed, Renovate posts a comment to let users know that future updates will be ignored. If you want, you can change the text in the comment with the userStrings config option.

You can edit these user-facing strings:

  • ignoreDigest: Text of the PR comment for digest upgrades.
  • ignoreMajor: Text of the PR comment for major upgrades.
  • ignoreOther: Text of the PR comment for other (neither digest nor major) upgrades.
  • ignoreTopic: Topic of the PR comment.

Example:

{
  "userStrings": {
    "ignoreTopic": "Custom topic for PR comment",
    "ignoreMajor": "Custom text for major upgrades.",
    "ignoreDigest": "Custom text for digest upgrades.",
    "ignoreOther": "Custom text for other upgrades."
  }
}

versioning

Versioning to use for filtering and comparisons.

Name Value
type string
allowedValues aws-machine-image, cargo, composer, conan, debian, docker, git, gradle, hashicorp, helm, hermit, hex, ivy, loose, maven, node, npm, nuget, pep440, perl, poetry, python, redhat, regex, rez, ruby, semver, semver-coerced, swift, ubuntu
default null

Usually, each language or package manager has a specific type of "versioning": JavaScript uses npm's SemVer implementation, Python uses pep440, etc.

Renovate also uses custom versioning, like "docker" to address the most common way people tag versions using Docker, and "loose" as a fallback that tries SemVer first but otherwise just does its best to sort and compare.

By exposing versioning to config, you can override the default versioning for a package manager if needed. We do not recommend overriding the default versioning, but there are some cases such as Docker or Gradle where versioning is not strictly defined and you may need to specify the versioning type per-package.

Renovate supports 4-part versions (1.2.3.4) in full for the NuGet package manager. Other managers can use the "loose" versioning fallback: the first 3 parts are used as the version, all trailing parts are used for alphanumeric sorting.

vulnerabilityAlerts

Config to apply when a PR is needed due to a vulnerability in the existing package version.

Name Value
type object
default
{
  "groupName": null,
  "schedule": [],
  "dependencyDashboardApproval": false,
  "stabilityDays": 0,
  "rangeStrategy": "update-lockfile",
  "commitMessageSuffix": "[SECURITY]",
  "branchTopic": "{{{datasource}}}-{{{depName}}}-vulnerability",
  "prCreation": "immediate"
}
mergeable true
supportedPlatforms github

Renovate can read GitHub's Vulnerability Alerts to customize its Pull Requests. For this to work, you must enable the Dependency graph, and Dependabot alerts. Follow these steps:

  1. While logged in to GitHub, navigate to your repository
  2. Click on the "Settings" tab
  3. Click on "Code security and analysis" in the sidebar
  4. Enable the "Dependency graph"
  5. Enable "Dependabot alerts"
  6. If you're running Renovate in app mode: make sure the app has read permissions for "Vulnerability alerts". If you're the account administrator, browse to the app (for example https://github.com/apps/renovate), select "Configure", and then scroll down to the "Permissions" section and make sure that read access to "vulnerability alerts" is mentioned

Once the above conditions are met, and you got one or more vulnerability alerts from GitHub for this repository, then Renovate tries to raise fix PRs.

You may use the vulnerabilityAlerts configuration object to customize vulnerability-fix PRs. For example, to set custom labels and assignees:

{
  "vulnerabilityAlerts": {
    "labels": ["security"],
    "automerge": true,
    "assignees": ["@rarkins"]
  }
}

Warning

There's a small chance that an incorrect vulnerability alert could result in flapping/looping vulnerability fixes, so observe carefully if enabling automerge.

To disable the vulnerability alerts feature, set enabled=false in a vulnerabilityAlerts config object, like this:

{
  "vulnerabilityAlerts": {
    "enabled": false
  }
}