Skip to content
Snippets Groups Projects
Select Git revision
21 results Searching

configuration-options.md

Blame
  • user avatar
    HonkingGoose authored and GitHub committed
    Co-authored-by: default avatarJamie Magee <jamie.magee@gmail.com>
    5f325748
    History
    configuration-options.md 83.60 KiB
    title: Configuration Options
    description: Configuration Options usable in renovate.json or package.json

    Configuration Options

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

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

    • .github/renovate.json
    • .github/renovate.json5
    • .gitlab/renovate.json
    • .gitlab/renovate.json5
    • .renovaterc.json
    • renovate.json
    • renovate.json5
    • .renovaterc
    • package.json (within a "renovate" section)

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

    Also, be sure to check out Renovate's shareable config presets to save yourself from reinventing any wheels. Shareable config presets only work with the JSON format.

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

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

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

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


    addLabels

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

    Consider this example:

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

    With the above config:

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

    additionalBranchPrefix

    This value defaults to an empty string, and is typically not necessary. Some managers previously populated this field, but they no longer do so by default. You normally don't need to configure this, but one example where it can be useful is combining with parentDir in monorepos to split PRs based on where the package definition is located, e.g.

    {
      "additionalBranchPrefix": "{{parentDir}}-"
    }

    additionalReviewers

    In contrast to reviewers, this option adds to the existing reviewer list, rather than replacing it. This makes it suitable for augmenting a preset or base list without displacing the original, for example when adding focused reviewers for a specific package group.

    aliases

    The aliases object is used for configuring registry aliases. Currently it is needed/supported for the helm-requirements manager only.

    helm-requirements includes this default alias:

    {
      "aliases": {
        "stable": "https://charts.helm.sh/stable"
      }
    }

    Alias values must be properly formatted URIs.

    assignAutomerge

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

    assignees

    Must be valid usernames on the platform in use.

    assigneesFromCodeOwners

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

    See GitHub or GitLab documentation for details on syntax and possible file locations.

    assigneesSampleSize

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

    automerge

    By default, Renovate raises PRs but leaves them to someone or something else to merge them. By configuring this setting, you can enable Renovate to automerge PRs or even branches itself, therefore reducing the amount of human intervention required.

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

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

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

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

    Important: Renovate won't automerge on GitHub if a PR has a negative review outstanding.

    Note: on Azure there can be a delay between a PR being set as completed by Renovate, and Azure merging the PR / finishing its tasks. Renovate will try to delay until Azure is in the expected state, however if it takes too long it will continue. In some cases this can result in a dependency not being merged, and a fresh PR being created for the dependency.

    automergeComment

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

    Example use:

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

    automergeType

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

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

    Note: if you have no tests but still want Renovate to automerge, you need to add "requiredStatusChecks": null to your configuration.

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

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

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

    azureAutoApprove

    Setting this to true will automatically approve the PRs in Azure DevOps.

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

    azureAutoComplete

    Setting this to true will configure PRs in Azure DevOps to auto-complete after all (if any) branch policies have been met.

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

    azureWorkItemId

    When creating a PR in Azure DevOps, some branches can be protected with branch policies to check for linked work items. Creating a work item in Azure DevOps is beyond the scope of Renovate, but Renovate can link an already existing work item when creating PRs.

    baseBranches

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

    • You wish Renovate to process only a non-default branch, e.g. dev: "baseBranches": ["dev"]
    • You have multiple release streams you need Renovate to keep up to date, e.g. in branches main 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.

    bbUseDefaultReviewers

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

    branchConcurrentLimit

    By default, Renovate won't enforce any concurrent branch limits. If you want the same limit for both concurrent branches and concurrent PRs, then just set a value for prConcurrentLimit and it will be reused for branch calculations too. However, if you want to allow more concurrent branches than concurrent PRs, you can configure both values ( e.g. branchConcurrentLimit=5 and prConcurrentLimit=3).

    This limit is enforced on a per-repository basis.

    Example config:

    {
      "branchConcurrentLimit": 3
    }

    branchName

    Warning: it's strongly recommended not to configure this field directly. Use at your own risk. If you truly need to configure this then it probably means either:

    • You are hopefully mistaken, and there's a better approach you should use, so open a new "config help" discussion at the Renovate discussions tab or
    • You have a use case we didn't anticipate and we should have a feature request from you to add it to the project

    branchPrefix

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

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

    Note that this setting does not change the default onboarding branch name, i.e. renovate/configure. If you wish to change that too, you need to also configure the field onboardingBranch in your admin bot config.

    branchTopic

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

    bumpVersion

    Currently this setting supports helmv3, npm and sbt only, so raise a feature request if you have a use for it with other package managers. Its purpose is if you want Renovate to update the version field within your file's package.json any time it updates dependencies within. Usually this is for automatic release purposes, so that you don't need to add another step after Renovate before you can release a new version.

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

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

    cloneSubmodules

    commitBody

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

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

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

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

    commitBodyTable

    commitMessage

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

    commitMessageAction

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

    commitMessageExtra

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

    commitMessagePrefix

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

    commitMessageSuffix

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

    commitMessageTopic

    This is used to alter commitMessage and prTitle without needing to copy/paste the whole string. The "topic" is usually refers to the dependency being updated, e.g. "dependency react".

    configWarningReuseIssue

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

    constraints

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

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

    {
      "constraints": {
        "python": "2.7"
      }
    }

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

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

    Note: make sure not to mix this up with the term compatibility, which Renovate uses in the context of version releases, e.g. if a Docker image is node:12.16.0-alpine then the -alpine suffix represents compatibility.

    dependencyDashboard

    Configuring dependencyDashboard to true will lead to the creation of a "Dependency Dashboard" issue within the repository. This issue contains a list of all PRs pending, open, closed (unmerged) or in error. The goal of this issue is to give visibility into all updates that Renovate is managing.

    Examples of what having a Dependency Dashboard will allow you to do:

    • View all PRs in one place, rather than having to filter PRs by author
    • Rebase/retry multiple PRs without having to open each individually
    • Override any rate limiting (e.g. concurrent PRs) or scheduling to force Renovate to create a PR that would otherwise be suppressed
    • Recreate an unmerged PR (e.g. for a major update that you postponed by closing the original PR)

    Note: Enabling the Dependency Dashboard does not itself change any of the "control flow" of Renovate, e.g. it will otherwise still create and manage PRs exactly as it always has, including scheduling and rate limiting. The Dependency Dashboard therefore provides visibility as well as additional control.

    dependencyDashboardApproval

    This feature allows you to use Renovate's Dependency Dashboard to force approval of updates before they are created.

    By setting dependencyDashboardApproval to true in config (including within packageRules), you can tell Renovate to wait for your approval from the Dependency Dashboard before creating a branch/PR. You can approve a pending PR by ticking the checkbox in the Dependency Dashboard issue.

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

    You can configure Renovate to wait for approval for:

    • all package upgrades
    • major, minor, patch level upgrades
    • specific package upgrades
    • upgrades coming from specific package managers

    If you want to approve all upgrades, set dependencyDashboardApproval to true:

    {
      "dependencyDashboardApproval": true
    }

    If you want to require approval for major updates, set dependencyDashboardApproval to true within a major object:

    {
      "major": {
        "dependencyDashboardApproval": true
      }
    }

    If you want to approve specific packages, set dependencyDashboardApproval to true within a packageRules entry where you have defined a specific package or pattern.

    {
      "packageRules": [
        {
          "matchPackagePatterns": ["^@package-name"],
          "dependencyDashboardApproval": true
        }
      ]
    }

    dependencyDashboardAutoclose

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

    dependencyDashboardFooter

    dependencyDashboardHeader

    dependencyDashboardTitle

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

    description

    The description field is used by config presets to describe what they do. They are then collated as part of the onboarding description.

    digest

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

    docker

    Add config here if you wish it to apply to Docker package managers Dockerfile and Docker Compose. If instead you mean to apply settings to any package manager that updates using the Docker datasource, use a package rule instead, e.g.

    {
      "packageRules": [
        {
          "matchDatasources": ["docker"],
          "labels": ["docker-update"]
        }
      ]
    }

    dotnet

    draftPR

    If you want the PRs created by Renovate to be considered as drafts rather than normal PRs, you could add this property to your renovate.json:

    {
      "draftPR": true
    }

    This option is evaluated at PR/MR creation time and is only supported on the following platforms: GitHub, GitLab, Azure.

    Note that GitLab implements draft status by checking whether the PR's title starts with certain strings. Therefore, draftPR on GitLab is incompatible with the legacy method of triggering Renovate to rebase a PR by renaming the PR to start with rebase!.

    enabled

    The most common use of enabled is if you want to turn Renovate's functionality off, for some reason.

    For example, if you wanted to disable Renovate completely on a repository, you could make this your renovate.json:

    {
      "enabled": false
    }

    To disable Renovate for all eslint packages, you can configure a package rule like:

    {
      "packageRules": [
        {
          "matchPackagePatterns": ["^eslint"],
          "enabled": false
        }
      ]
    }

    To disable Renovate for npm devDependencies but keep it for dependencies you could configure:

    {
      "packageRules": [
        {
          "matchManagers": ["npm"],
          "matchDepTypes": ["devDependencies"],
          "enabled": false
        }
      ]
    }

    enabledManagers

    This is a way to allow only certain package managers and implicitly disable all others.

    Example:

    {
      "enabledManagers": ["dockerfile", "npm"]
    }

    For the full list of available managers, see the Supported Managers documentation.

    encrypted

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

    excludeCommitPaths

    Warning: Advanced use!

    Be careful you know what you're doing with this option. The initial intended use is to allow the user to exclude certain dependencies from being added/removed/modified when "vendoring" dependencies. Example:

    {
      "excludeCommitPaths": ["vendor/golang.org/x/text/**"]
    }

    The above would mean Renovate would not include files matching the above glob pattern in the commit, even if it thinks they should be updated.

    extends

    See shareable config presets for details.

    extractVersion

    Use this only when the raw version strings from the datasource do not match the expected format that you need in your package file. You must defined a "named capture group" called version as shown in the below examples.

    For example, to extract only the major.minor precision from a GitHub release, the following would work:

    {
      "packageRules": [
        {
          "matchPackageNames": ["foo"],
          "extractVersion": "^(?<version>v\\d+\\.\\d+)"
        }
      ]
    }

    The above will change a raw version of v1.31.5 to v1.31, for example.

    Alternatively, to strip a release- prefix:

    {
      "packageRules": [
        {
          "matchPackageNames": ["bar"],
          "extractVersion": "^release-(?<version>.*)$"
        }
      ]
    }

    The above will change a raw version of release-2.0.0 to 2.0.0, for example. A similar one could strip leading v prefixes:

    {
      "packageRules": [
        {
          "matchPackageNames": ["baz"],
          "extractVersion": "^v(?<version>.*)$"
        }
      ]
    }

    fetchReleaseNotes

    Configure this to false if you want to disable release notes fetching

    fileMatch

    fileMatch is used by Renovate to know which files in a repository to parse and extract, and it is possible to override the default values to customize for your project's needs.

    Sometimes file matches are really simple - for example with Go Modules Renovate looks for any go.mod file, and you probably don't need to change that default.

    At other times, the possible files is too vague for Renovate to have any default. For default, Kubernetes manifests can exist in any *.yaml file and we don't want Renovate to parse every single YAML file in every repository just in case some of them contain a Kubernetes manifest, so Renovate's default fileMatch for manager kubernetes is actually empty ([]) and needs the user to tell Renovate what directories/files to look in.

    Finally, there are cases where Renovate's default fileMatch is good, but you may be using file patterns that a bot couldn't possibly guess about. For example, Renovate's default fileMatch for Dockerfile is ['(^|/|\\.)Dockerfile$', '(^|/)Dockerfile\\.[^/]*$']. This will catch files like backend/Dockerfile, prefix.Dockerfile or Dockerfile.suffix, but it will miss files like ACTUALLY_A_DOCKERFILE.template. Because fileMatch is mergeable, you don't need to duplicate the defaults and could just add the missing file like this:

    {
      "dockerfile": {
        "fileMatch": ["^ACTUALLY_A_DOCKERFILE\\.template$"]
      }
    }

    If you configure fileMatch then it must be within a manager object (e.g. dockerfile in the above example). The full list of supported managers can be found here.

    filterUnavailableUsers

    When this option is enabled PRs are not assigned to users that are unavailable. This option only works on platforms that support the concept of user availability. For now, you can only use this option on the GitLab platform.

    followTag

    Caution: advanced functionality. Only use it if you're sure you know what you're doing.

    This functionality requires that the datasource to support distribution streams/tags, such as npm does.

    The primary use case for this option is if you are following a pre-release tag of a certain dependency, e.g. typescript's "insiders" build. If configured, Renovate bypasses its normal major/minor/patch upgrade logic and stable/unstable consistency logic and keeps your dependency version sync'd strictly to whatever version is in the tag.

    Beware that Renovate follows tags strictly. For example, if you are following a tag like next and then that stream is released as stable and next is no longer being updated then that means your dependencies also won't be getting updated.

    gitIgnoredAuthors

    Specify commit authors ignored by Renovate.

    By default, Renovate will treat any PR as modified if another git author has added to the branch. When a PR is considered modified, Renovate won't perform any further commits such as if it's conflicted or needs a version update. If you have other bots which commit on top of Renovate PRs, and don't want Renovate to treat these PRs as modified, then add the other git author(s) to gitIgnoredAuthors.

    Example:

    {
      "gitIgnoredAuthors": ["some-bot@example.org"]
    }

    gitLabAutomerge

    Caution (fixed in GitLab >= 12.7): when this option is enabled it is possible due to a bug in GitLab that MRs with failing pipelines might still get merged. This is caused by a race condition in GitLab's Merge Request API - read the corresponding issue for details.

    golang

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

    group

    Caution: Advanced functionality only. Do not use unless you know what you're doing.

    The default configuration for groups are essentially internal to Renovate and you normally shouldn't need to modify them. However, you may choose to add settings to any group by defining your own group configuration object.

    groupName

    There are multiple cases where it can be useful to group multiple upgrades together. Internally Renovate uses this for branches such as "Pin Dependencies", "Lock File Maintenance", etc. Another example used previously is to group together all related eslint packages, or perhaps angular or babel. To enable grouping, you configure the groupName field to something non-null.

    The groupName field allows free text and does not have any semantic interpretation by Renovate. All updates sharing the same groupName will be placed into the same branch/PR. For example, to group all non-major devDependencies updates together into a single PR:

    {
      "packageRules": [
        {
          "matchDepTypes": ["devDependencies"],
          "matchUpdateTypes": ["patch", "minor"],
          "groupName": "devDependencies (non-major)"
        }
      ]
    }

    groupSlug

    By default, Renovate will "slugify" the groupName to determine the branch name. For example if you named your group "devDependencies (non-major)" then the branchName would be renovate/devdependencies-non-major. If you wished to override this then you could configure like this:

    {
      "packageRules": [
        {
          "matchDepTypes": ["devDependencies"],
          "matchUpdateTypes": ["patch", "minor"],
          "groupName": "devDependencies (non-major)",
          "groupSlug": "dev-dependencies"
        }
      ]
    }

    As a result of the above, the branchName would be renovate/dev-dependencies instead.

    Note: you shouldn't usually need to configure this unless you really care about your branch names.

    hashedBranchLength

    Some code hosting systems have restrictions on the branch name lengths, this option lets you get around these restrictions. You can set the hashedBranchLength option to a number of characters that works for your system and then Renovate will generate branch names with the appropriate length by hashing additionalBranchPrefix and branchTopic, and then truncating the hash so that the full branch name (including branchPrefix) has the right number of characters.

    Example: If you have set branchPrefix: "deps-" and hashedBranchLength: 12 it will result in a branch name like deps-5bf36ec instead of the traditional pretty branch name like deps-react-17.x.

    hostRules

    The primary purpose of hostRules is to configure credentials for host authentication. You tell Renovate how to match against the host you need authenticated, and then you also tell it which credentials to use.

    The lookup keys for hostRules are: hostType and matchHost, both of which are optional.

    Supported credential fields are token, username, password, timeout, enabled and insecureRegistry.

    Example for configuring docker auth:

    {
      "hostRules": [
        {
          "matchHost": "docker.io",
          "username": "<some-username>",
          "password": "<some-password>"
        }
      ]
    }

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