Self-Hosted configuration options

The configuration options listed in this document are applicable to self-hosted instances of Renovate ("the bot").

Please also see Self-Hosted Experimental Options.

allowPostUpgradeCommandTemplating

If true allow templating for post-upgrade commands.

Name	Value
type	boolean
default	`false`

Set to true to allow templating of dependency level post-upgrade commands.

Let's look at an example of configuring packages with existing Angular migrations.

Add two properties to config.js: allowPostUpgradeCommandTemplating and allowedPostUpgradeCommands:

module.exports = {
  allowPostUpgradeCommandTemplating: true,
  allowedPostUpgradeCommands: ['^npm ci --ignore-scripts$', '^npx ng update'],
};

In the renovate.json file, define the commands and files to be included in the final commit.

The command to install dependencies (npm ci --ignore-scripts) is necessary because, by default, the installation of dependencies is skipped (see the skipInstalls admin option).

{
  "packageRules": [
    {
      "matchPackageNames": ["@angular/core"],
      "postUpgradeTasks": {
        "commands": [
          "npm ci --ignore-scripts",
          "npx ng update {{{depName}}} --from={{{currentVersion}}} --to={{{newVersion}}} --migrate-only --allow-dirty --force"
        ],
        "fileFilters": ["**/**"]
      }
    }
  ]
}

With this configuration, the executable command for @angular/core looks like this:

npm ci --ignore-scripts
npx ng update @angular/core --from=10.0.0 --to=11.0.0 --migrate-only --allow-dirty --force

allowedPostUpgradeCommands

A list of regular expressions that determine which post-upgrade tasks are allowed.

Name	Value
type	array
subType	string

A list of regular expressions that determine which commands in postUpgradeTasks are allowed to be executed. If this list is empty then no tasks will be executed. Also you need to have "trustLevel": "high", otherwise these tasks will be ignored.

e.g.

{
  "allowedPostUpgradeCommands": ["^tslint --fix$", "^tslint --[a-z]+$"],
  "trustLevel": "high"
}

autodiscover

Autodiscover all repositories.

Name	Value
type	boolean
default	`false`

When you enable autodiscover, by default, Renovate will run on every repository that the bot account can access. If you want Renovate to run on only a subset of those, use the autodiscoverFilter option to limit the bot to only the wanted repositories.

autodiscoverFilter

Filter the list of autodiscovered repositories.

Name	Value
type	string

You can use this option to filter the list of repositories that the Renovate bot account can access through autodiscover. It takes a minimatch glob-style pattern.

e.g.

{
  "autodiscoverFilter": "project/*"
}

baseDir

The base directory for Renovate to store local files, including repository files and cache. If left empty, Renovate will create its own temporary directory to use.

Name	Value
type	string
default	`null`

By default Renovate uses a temporary directory like /tmp/renovate to store its data. You can override this default with the baseDir option.

e.g.

{
  "baseDir": "/my-own-different-temporary-folder"
}

binarySource

Controls whether third party tools like npm or Gradle are called directly, or via Docker sidecar containers.

Name	Value
type	string
allowedValues	global,docker
default	`"global"`

Renovate often needs to use third party binaries in its PRs, e.g. npm to update package-lock.json or go to update go.sum. By default, Renovate will use a child process to run such tools, so they need to be pre-installed before running Renovate and available in the path.

As an alternative, Renovate can use "sidecar" containers for third party tools. If configured, Renovate will use docker run to create containers such as Node.js or Python to run tools within as-needed. For this to work, docker needs to be installed and the Docker socket available to Renovate.

cacheDir

The directory for Renovate for storing caches. If left empty, Renovate will create a subdirectory within baseDir to use.

Name	Value
type	string
default	`null`

By default Renovate uses a temporary directory like /tmp/renovate/cache to store cache data. Use the cacheDir option to override this default.

The baseDir and cacheDir option do not need to point to the same directory. You can use one directory for the repo data, and another for the the cache data.

e.g.

{
  "baseDir": "/my-own-different-temporary-folder",
  "cacheDir": "/my-own-different-cache-folder"
}

composerIgnorePlatformReqs

Enable / disable use of --ignore-platform-reqs in the Composer package manager.

Name	Value
type	boolean
default	`true`

Set to false to prevent usage of --ignore-platform-reqs in the Composer package manager.s

customEnvVariables

Custom environment variables for child processes and sidecar Docker containers.

Name	Value
type	object
default	false

This configuration will be applied after all other environment variables so that it can be used to override defaults.

dockerChildPrefix

Change this value in order to add a prefix to the Renovate Docker sidecar image names and labels.

Name	Value
type	string
default	`"renovate_"`

Adds a custom prefix to the default Renovate sidecar Docker containers name and label.

If this is set to myprefix_ the final image name for renovate/node would be named myprefix_node instead of currently used renovate_node and be labeled myprefix_child instead of renovate_child.

Note that dangling containers will not be removed until Renovate is run with the same prefix again.

dockerImagePrefix

Change this value in order to override the default Renovate Docker sidecar image name prefix.

Name	Value
type	string
default	`"docker.io/renovate"`

By default Renovate pulls the sidecar Docker containers from docker.io/renovate. You can use the dockerImagePrefix option to override this default.

Say you want to pull your images from ghcr.io/renovatebot instead of docker.io/renovate. You would use put this in your configuration file:

{
  "dockerImagePrefix": "ghcr.io/renovatebot"
}

If you pulled a new node image, the final image would be ghcr.io/renovatebot/node instead of docker.io/renovate/node.

dockerMapDotfiles

Map relevant home directory dotfiles into containers when binarySource=docker.

Name	Value
type	boolean
default	`false`

This is used if you want to map "dotfiles" from your host computer home directory to containers that Renovate creates, e.g. for updating lock files. Currently applicable to .npmrc only.

{
  "dockerMapDotfiles": true
}

dockerUser

Specify UID and GID for Docker-based binaries when binarySource=docker is used.

Name	Value
type	string
default	`null`

Override default user and group used by Docker-based binaries. The user-id (UID) and group-id (GID) should match the user that executes Renovate.

Read the Docker run reference for more information on user and group syntax. Set this to 1001:1002 to use UID 1001 and GID 1002. e.g.

{
  "dockerUser": "1001:1002"
}

dryRun

If enabled, perform a dry run by logging messages instead of creating/updating/deleting branches and PRs.

Name	Value
type	boolean
default	`false`

endpoint

Custom endpoint to use.

Name	Value
type	string

force

Any configuration defined within this object will force override existing settings.

Name	Value
type	object

This object is used as a "force override" when you need to make sure certain configuration overrides whatever is configured in the repository. For example, forcing a null (no) schedule to make sure Renovate raises PRs on a run even if the repository itself or its preset defines a schedule that's currently inactive.

In practice, it is implemented by converting the force configuration into a packageRule that matches all packages.

forceCli

Whether CLI configuration options should be moved to the force config section.

Name	Value
type	boolean
default	`true`

This is set to true by default, meaning that any settings (such as schedule) take maximum priority even against custom settings existing inside individual repositories. It will also override any settings in packageRules.

forkMode

Set to true to fork the source repository and create branches there instead.

Name	Value
type	boolean
default	`false`

You probably have no need for this option - it is an experimental setting for the Renovate hosted GitHub App.

gitAuthor

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

Name	Value
type	string
default	`null`

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

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

gitPrivateKey

PGP key to use for signing Git commits.

Name	Value
type	string
default	`null`

This should be an armored private key, e.g. the type you get from running gpg --export-secret-keys --armor 92066A17F0D1707B4E96863955FEF5171C45FAE5 > private.key. Replace the newlines with \n before adding the resulting single-line value to your bot's config.

It will be loaded lazily. Before the first commit in a repository, Renovate will:

Run gpg import (if it hasn't been run before)
Run git config user.signingkey and git config commit.gpgsign true

The git commands are run locally in the cloned repo instead of globally. This reduces the chance of unintended consequences with global Git configs on shared systems.

logContext

Add a global or per-repo log context to each log entry.

Name	Value
type	string

logContext is included with each log entry only if logFormat="json" - it is not included in the pretty log output. If left as default (null), a random short ID will be selected.

logFile

Log file path.

Name	Value
type	string
default	`null`

logFileLevel

Log file log level.

Name	Value
type	string
default	`"debug"`

logLevel

Logging level. Deprecated, use LOG_LEVEL environment.

Name	Value
type	string
allowedValues	fatal,error,warn,info,debug,trace
default	`null`

We recommend that you run the Renovate bot at the debug level if you can. Use the environment variable LOG_LEVEL=debug to run Renovate at the debug level.

When you use LOG_LEVEL=debug, debug logging starts from the beginning of the app. If you had configured debug logging in a file config, then the debug logging starts after the file config is parsed.

Additionally, if you configure LOG_FORMAT=json in env then logging will be done in JSON format instead of "pretty" format, which is usually better if you're doing any ingestion or parsing of the logs.

Warning: Configuring logLevel config option or --log-level cli option is deprecated and will be removed in a major version.

onboarding

Require a Configuration PR first.

Name	Value
type	boolean
default	`true`

Set this to false only if all three statements are true:

You've configured Renovate entirely on the bot side (e.g. empty renovate.json in repositories)
You want to run Renovate on every repository the bot has access to
You want to skip all onboarding PRs

onboardingBranch

Change this value in order to override the default onboarding branch name.

Name	Value
type	string
default	`"renovate/configure"`

Note that this setting is independent of branchPrefix. For example, if you configure branchPrefix to be renovate- then you'd still have the onboarding PR created with branch renovate/configure until you configure onboardingBranch=renovate-configure or similar. If you have an existing Renovate installation and you change onboardingBranch then it's possible that you'll get onboarding PRs for repositories that had previously closed the onboarding PR unmerged.

onboardingCommitMessage

Change this value in order to override the default onboarding commit message.

Name	Value
type	string

Note that if commitMessagePrefix or semanticCommits values are defined then they will be prepended to the commit message using the same logic that is used for adding them to non-onboarding commit messages.

onboardingConfig

Configuration to use in onboarding PRs.

Name	Value
type	object
mergeable	true

onboardingConfigFileName

Change this value in order to override the default onboarding config file name.

Name	Value
type	string
default	`"renovate.json"`

If set to one of the valid config file names, the onboarding PR will create a configuration file with the provided name instead of renovate.json. Falls back to renovate.json if the name provided is not valid.

onboardingPrTitle

Change this value in order to override the default onboarding PR title.

Name	Value
type	string
default	`"Configure Renovate"`

Similarly to onboardingBranch, if you have an existing Renovate installation and you change onboardingPrTitle then it's possible that you'll get onboarding PRs for repositories that had previously closed the onboarding PR unmerged.

optimizeForDisabled

Set to true to first check for disabling in config before cloning.

Name	Value
type	boolean
default	`false`

password

Password for authentication. Currently Bitbucket only (AppPassword).

Name	Value
type	string
default	`null`

persistRepoData

If set to true, repository data will preserved between runs instead of deleted.

Name	Value
type	boolean
default	`false`

Set this to true if you want Renovate to persist repo data between runs. The intention is that this allows Renovate to do a faster git fetch between runs rather than git clone. It also may mean that ignored directories like node_modules can be preserved and save time on operations like npm install.

platform

Platform type of repository.

Name	Value
type	string
allowedValues	azure,bitbucket,bitbucket-server,gitea,github,gitlab
default	`"github"`

prCommitsPerRunLimit

Set a maximum number of commits per Renovate run. Default is no limit.

Name	Value
type	integer
default	0

Parameter to reduce CI load. CI jobs are usually triggered by these events: pull-request creation, pull-request update, automerge events. Set as an integer. Default is no limit.

printConfig

If enabled, log the full resolved config for each repo, including resolved presets.

Name	Value
type	boolean
default	`false`

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.

privateKey

Server-side private key.

Name	Value
type	string
replaceLineReturns	true
default	`null`

This private key is used to decrypt config files.

The corresponding public key can be used to create encrypted values for config files. If you want a simple UI to encrypt values you can put the public key in a HTML page similar to https://renovatebot.com/encrypt.

To create the key pair with OpenSSL use the following commands:

openssl genrsa -out rsa_priv.pem 4096 for generating the private key
openssl rsa -pubout -in rsa_priv.pem -out rsa_pub.pem for extracting the public key

privateKeyPath

Path to the Server-side private key.

Name	Value
type	string
default	`null`

Used as an alternative to privateKey, if you wish for the key to be read from disk instead.

productLinks

Links which are embedded within PRs, issues, etc.

Name	Value
type	object
mergeable	true
additionalProperties	[object Object]

Override this object if you wish to change the URLs that Renovate links to, e.g. if you have an internal forum for asking for help.

redisUrl

If defined, this Redis URL will be used for caching instead of the file system.

Name	Value
type	string
default	`null`

If this value is set then Renovate will use Redis for its global cache instead of the local file system. The global cache is used to store lookup results (e.g. dependency versions and release notes) between repositories and runs. Example url: redis://localhost.

repositories

List of Repositories.

Name	Value
type	array

repositoryCache

Option to do repository extract caching.

Name	Value
type	string
allowedValues	disabled,enabled,reset
default	`"disabled"`

Set this to "enabled" to have Renovate maintain a JSON file cache per-repository to speed up extractions. Set to "reset" if you ever need to bypass the cache and have it overwritten. JSON files will be stored inside the cacheDir beside the existing file-based package cache.

Warning: this is an experimental feature and may be modified or removed in a future non-major release.

requireConfig

Set to true if repositories must have a config to activate.

Name	Value
type	boolean
default	`true`

secrets

Object containing secret name/value pairs

Name	Value
type	object
mergeable	true
additionalProperties	[object Object]

Secrets may be configured by a bot admin in config.js, which will then make them available for templating within repository configs. For example, to configure a GOOGLE_TOKEN to be accessible by all repositories:

module.exports = {
  secrets: {
    GOOGLE_TOKEN: 'abc123',
  },
};

They can also be configured per repository, e.g.

module.exports = {
  repositories: [
    {
      repository: 'abc/def',
      secrets: {
        GOOGLE_TOKEN: 'abc123',
      },
    },
  ],
};

It could then be used in a repository config or preset like so:

{
  "hostRules": [
    {
      "domainName": "google.com",
      "token": "{{ secrets.GOOGLE_TOKEN }}"
    }
  ]
}

Secret names must start with a upper or lower case character and can contain only characters, digits, or underscores.

skipInstalls

Skip installing modules/dependencies if lock file updating is possible alone.

Name	Value
type	boolean
default	`null`

By default, Renovate will use the most efficient approach to updating package files and lock files, which in most cases skips the need to perform a full module install by the bot. If this is set to false, then a full install of modules will be done. This is currently applicable to npm and lerna/npm only, and only used in cases where bugs in npm result in incorrect lock files being updated.

token

Repository Auth Token.

Name	Value
type	string
default	`null`

trustLevel

Set this to "high" if the bot should trust the repository owners/contents.

Name	Value
type	string
default	`"low"`

Setting trustLevel to "high" can make sense in many self-hosted cases where the bot operator trusts the content in each repository.

Setting trustLevel=high means:

Child processes are run with full access to env
.npmrc files can have environment variable substitution performed

username

Username for authentication. Currently Bitbucket only.

Name	Value
type	string
default	`null`