Self-Hosted configuration options

Only use these configuration options when you self-host Renovate.

Do not put the self-hosted config options listed on this page in your "repository config" file (renovate.json for example), because Renovate will ignore those config options, and may also create a config error issue.

The config options below must be configured in the bot/admin config, so in either a environment variable, CLI option, or a special file like config.js.

Note

Renovate supports JSONC for .json files and any config files without file extension (e.g. .renovaterc).

For information about how to configure Renovate with a config.js see the Using config.js documentation.

Please also see Self-Hosted Experimental Options.

Note

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

allowCustomCrateRegistries

Set this to true to allow custom crate registries.

Name	Value
type	boolean
default	false
cli	--allow-custom-crate-registries
env	RENOVATE_ALLOW_CUSTOM_CRATE_REGISTRIES

allowPlugins

Set this to true if repositories are allowed to run install plugins.

Name	Value
type	boolean
default	false
cli	--allow-plugins
env	RENOVATE_ALLOW_PLUGINS

allowScripts

Set this to true if repositories are allowed to run install scripts.

Name	Value
type	boolean
default	false
cli	--allow-scripts
env	RENOVATE_ALLOW_SCRIPTS

allowedCommands

A list of regular expressions that decide which commands are allowed in post-upgrade tasks.

Name	Value
type	array
subType	string
cli	--allowed-commands
env	RENOVATE_ALLOWED_COMMANDS

A list of regular expressions that decide which commands in postUpgradeTasks are allowed to run.

If you are using a template command, the regular expression should match the final resolved value. If this list is empty then no tasks will be executed.

For example:

{
  "allowedCommands": ["^tslint --fix$", "^tslint --[a-z]+$"]
}

This configuration option was formerly known as allowedPostUpgradeCommands.

allowedEnv

List of allowed patterns for environment variable names in repository env config.

Name	Value
type	array
subType	string
mergeable	true
cli	--allowed-env
env	RENOVATE_ALLOWED_ENV

Bot administrators can allow users to configure custom environment variables within repo config. Only environment variables matching the list will be accepted in the env configuration.

Examples:

renovate.json

{
  "env": {
    "SOME_ENV_VARIABLE": "some_value",
    "EXTRA_ENV_NAME": "value"
  }
}

The above would require allowedEnv to be configured similar to the following:

config.js

module.exports = {
  allowedEnv: ['SOME_ENV_*', 'EXTRA_ENV_NAME'],
};

allowedEnv values can be exact match header names, glob patterns, or regex patterns. For more details on the syntax and supported patterns, see Renovate's String Pattern Matching documentation.

allowedHeaders

List of allowed patterns for header names in repository hostRules config.

Name	Value
type	array
default	["X-*"]
subType	string
cli	--allowed-headers
env	RENOVATE_ALLOWED_HEADERS

allowedHeaders can be useful when a registry uses a authentication system that's not covered by Renovate's default credential handling in hostRules. By default, all headers starting with "X-" are allowed. If needed, you can allow additional headers with the allowedHeaders option. Any set allowedHeaders overrides the default "X-" allowed headers, so you should include them in your config if you wish for them to remain allowed. The allowedHeaders config option takes an array of minimatch-compatible globs or re2-compatible regex strings. For more details on this syntax see Renovate's string pattern matching documentation.

Examples:

Example header	Kind of pattern	Explanation
/X/	Regex	Any header with x anywhere in the name
!/X/	Regex	Any header without X anywhere in the name
X-*	Global pattern	Any header starting with X-
X	Exact match glob	Only the header matching exactly X

{
  "hostRules": [
    {
      "matchHost": "https://domain.com/all-versions",
      "headers": {
        "X-Auth-Token": "secret"
      }
    }
  ]
}

Or with custom allowedHeaders:

config.js

module.exports = {
  allowedHeaders: ['custom-header'],
};

autodiscover

Autodiscover all repositories.

Name	Value
type	boolean
default	false
cli	--autodiscover
env	RENOVATE_AUTODISCOVER

When you enable autodiscover, by default, Renovate runs on every repository that the bot account can access. You can limit which repositories Renovate can access by using the autodiscoverFilter config option.

autodiscoverFilter

Filter the list of autodiscovered repositories.

Name	Value
type	array
subType	string
cli	--autodiscover-filter
env	RENOVATE_AUTODISCOVER_FILTER

You can use this option to filter the list of repositories that the Renovate bot account can access through autodiscover. The pattern matches against the organization/repo path.

This option supports an array of minimatch-compatible globs or RE2-compatible regex strings. For more details on this syntax see Renovate's string pattern matching documentation.

If you set multiple filters, then the matches of each filter are added to the overall result.

If you use an environment variable or the CLI to set the value for autodiscoverFilter, then commas , within filters are not supported. Commas will be used as delimiter for a new filter.

# DO NOT use commas inside the filter if your are using env or cli variables to configure it.
RENOVATE_AUTODISCOVER_FILTER="/MyOrg/{my-repo,foo-repo}"


# in this example you can use regex instead
RENOVATE_AUTODISCOVER_FILTER="/MyOrg\/(my|foo)-repo/"

Minimatch:

The configuration:

{
  "autodiscoverFilter": ["my-org/*", "!my-org/old-*"]
}

Glob patterns are case-insensitive.

Regex:

All text inside the start and end / will be treated as a regular expression. If using negations, all repositories except those who match the regex are added to the result:

{
  "autodiscoverFilter": ["/project/.*/", "!/project/old-/"]
}

autodiscoverNamespaces

Filter the list of autodiscovered repositories by namespaces.

Name	Value
type	array
subType	string
supportedPlatforms	forgejo, gitea, gitlab
cli	--autodiscover-namespaces
env	RENOVATE_AUTODISCOVER_NAMESPACES

You can use this option to autodiscover projects in specific namespaces (a.k.a. groups/organizations/workspaces). In contrast to autodiscoverFilter the filtering is done by the platform and therefore more efficient.

For example:

{
  "platform": "gitlab",
  "autodiscoverNamespaces": ["a-group", "another-group/some-subgroup"]
}

Note

On Gitea/Forgejo, you can't use autodiscoverTopics together with autodiscoverNamespaces because both platforms do not support this. Topics are preferred and autodiscoverNamespaces will be ignored when you configure autodiscoverTopics on Gitea/Forgejo.

autodiscoverProjects

Filter the list of autodiscovered repositories by project names.

Name	Value
type	array
subType	string
supportedPlatforms	bitbucket
cli	--autodiscover-projects
env	RENOVATE_AUTODISCOVER_PROJECTS

You can use this option to filter the list of autodiscovered repositories by project names. This feature is useful for users who want Renovate to only work on repositories within specific projects or exclude certain repositories from being processed.

Example for Bitbucket

{
  "platform": "bitbucket",
  "autodiscoverProjects": ["a-group", "!another-group/some-subgroup"]
}

The autodiscoverProjects config option takes an array of minimatch-compatible globs or RE2-compatible regex strings. For more details on this syntax see Renovate's string pattern matching documentation.

autodiscoverRepoOrder

The order method for autodiscover server side repository search.

Name	Value
type	string
allowedValues	asc, desc
supportedPlatforms	forgejo, gitea
cli	--autodiscover-repo-order
env	RENOVATE_AUTODISCOVER_REPO_ORDER

The order method for autodiscover server side repository search.

If multiple autodiscoverTopics are used resulting order will be per topic not global.

autodiscoverRepoSort

The sort method for autodiscover server side repository search.

Name	Value
type	string
allowedValues	alpha, created, updated, size, id
supportedPlatforms	forgejo, gitea
cli	--autodiscover-repo-sort
env	RENOVATE_AUTODISCOVER_REPO_SORT

The sort method for autodiscover server side repository search.

If multiple autodiscoverTopics are used resulting order will be per topic not global.

autodiscoverTopics

Filter the list of autodiscovered repositories by topics.

Name	Value
type	array
subType	string
supportedPlatforms	forgejo, gitea, github, gitlab
cli	--autodiscover-topics
env	RENOVATE_AUTODISCOVER_TOPICS

Some platforms allow you to add tags, or topics, to repositories and retrieve repository lists by specifying those topics. Set this variable to a list of strings, all of which will be topics for the autodiscovered repositories.

For example:

{
  "autodiscoverTopics": ["managed-by-renovate"]
}

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
cli	--base-dir
env	RENOVATE_BASE_DIR
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.

For example:

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

bbUseDevelopmentBranch

Use the repository's development branch as the repository's default branch.

Name	Value
type	boolean
default	false
supportedPlatforms	bitbucket
inheritConfigSupport	true
cli	--bb-use-development-branch
env	RENOVATE_BB_USE_DEVELOPMENT_BRANCH

By default, Renovate will use a repository's "main branch" (typically called main or master) as the "default branch".

Configuring this to true means that Renovate will detect and use the Bitbucket development branch as defined by the repository's branching model.

If the "development branch" is configured but the branch itself does not exist (e.g. it was deleted), Renovate will fall back to using the repository's "main branch". This fall back behavior matches that of the Bitbucket Cloud web interface.

binarySource

Controls how third-party tools like npm or Gradle are called: directly, via Docker sidecar containers, or via dynamic install.

Name	Value
type	string
allowedValues	global, docker, install, hermit
default	"install"
cli	--binary-source
env	RENOVATE_BINARY_SOURCE

Renovate often needs to use third-party tools in its PRs, like npm to update package-lock.json or go to update go.sum.

Renovate supports four possible ways to access those tools:

• global: Uses pre-installed tools, e.g. npm installed via npm install -g npm.
• install (default): Downloads and installs tools at runtime if running in a Containerbase environment, otherwise falls back to global
• docker: Runs tools inside Docker "sidecar" containers using docker run.
• hermit: Uses the Hermit tool installation approach.

Starting in v36, Renovate's default Docker image (previously referred to as the "slim" image) uses binarySource=install while the "full" Docker image uses binarySource=global. If you are running Renovate in an environment where runtime download and install of tools is not possible then you should use the "full" image.

If you are building your own Renovate image, e.g. by installing Renovate using npm, then you will need to ensure that all necessary tools are installed globally before running Renovate so that binarySource=global will work.

The binarySource=docker approach should not be necessary in most cases now and binarySource=install is recommended instead. If you have a use case where you cannot use binarySource=install but can use binarySource=docker then please share it in a GitHub Discussion so that the maintainers can understand it. For this to work, docker needs to be installed and the Docker socket available to Renovate.

cacheDir

The directory where Renovate stores its cache. If left empty, Renovate creates a subdirectory within the baseDir.

Name	Value
type	string
cli	--cache-dir
env	RENOVATE_CACHE_DIR
default	null

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

The baseDir and cacheDir option may point to different directories. You can use one directory for the repo data, and another for the cache data.

For example:

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

cacheHardTtlMinutes

Maximum duration in minutes to keep datasource cache entries.

Name	Value
type	integer
default	10080
cli	--cache-hard-ttl-minutes
env	RENOVATE_CACHE_HARD_TTL_MINUTES

This experimental feature configures the physical lifetime of cache entries. Renovate internally uses two types of Time-to-Live (TTL) for its cache:

• Soft TTL (logical): When a cache entry's soft TTL expires, Renovate tries to refresh the data from the upstream source.
• Hard TTL (physical): When a cache entry's hard TTL expires, Renovate permanently removes the data from the cache.

This two-level cache expiry is used for:

1. HTTP caching with ETag, Last-Modified, and If-Modified-Since headers
2. getReleases and getDigest datasource methods, i.e. the package release data

If an upstream request fails, Renovate can still use stale data from the cache as long as its hard TTL has not expired.

The cacheHardTtlMinutes option lets you configure the hard TTL. Set this to a non-zero value, the recommended minimum is 60 (one hour).

If the soft TTL for a cache entry is longer than the hard TTL, Renovate uses the soft TTL value for both. The soft TTL is hard-coded but can be overridden with cacheTtlOverride.

Example:

The npm datasource has a default soft TTL of 15 minutes. When cacheHardTtlMinutes is set, for example to 60, Renovate will use the stale npm data in the following ways:

• The ETag from the cached result is used in new requests. If the upstream server returns a 304 Not Modified response, the cached data is revalidated and used.
• If an error occurs when querying the npmjs registry, Renovate will use the stale data from the cache as long as it has been cached for less than 60 minutes.

cachePrivatePackages

Cache private packages in the datasource cache. This is useful for self-hosted setups

Name	Value
type	boolean
default	false
cli	--cache-private-packages
env	RENOVATE_CACHE_PRIVATE_PACKAGES

In the self-hosted setup, use option to enable caching of private packages to improve performance.

cacheTtlOverride

An object that contains cache namespace TTL override values.

Name	Value
type	object
cli	--cache-ttl-override
env	RENOVATE_CACHE_TTL_OVERRIDE

Warning

For advanced use only! Use at your own risk!

Use this key-value map to override the default package cache TTL values for a specific namespace. This object contains pairs of namespaces and their corresponding TTL values in minutes.

Internally, Renovate has the notion of soft TTL and hard TTL. In some contexts they are equal, but when they differ, this option overrides the soft TTL. See cacheHardTtlMinutes for more information.

You can use:

• Exact matches: Direct namespace names
• Glob patterns: Wildcards like datasource-* or *
• Regex patterns: Regular expressions like /^datasource-/

Priority order:

1. Exact namespace matches take highest priority
2. If no exact match, the longest (most specific) matching pattern wins

Example:

{
  "cacheTtlOverride": {
    "datasource-rubygems": 120,
    "datasource-*": 60,
    "datasource-{crate,go}": 90,
    "/^changelog-/": 45,
    "*": 30
  }
}

In this example:

• datasource-rubygems gets 120 minutes (exact match - highest priority)
• datasource-crate and datasource-go get 90 minutes (matches datasource-{crate,go} - longest pattern)
• datasource-hex gets 60 minutes (matches datasource-* - shorter pattern)
• changelog-github-release gets 45 minutes (matches /^changelog-/ regex)
• preset gets 30 minutes (matches * wildcard - shortest pattern)

Namespaces of special interest follow the pattern datasource-releases-{datasource}. When releases for a datasource are fetched, they are stored in this namespace. Whether caching is enabled for a particular datasource depends on whether it's private or caching is forced with cachePrivatePackages.

Other valid cache namespaces are as follows:

• changelog-bitbucket-notes@v2
• changelog-bitbucket-release
• changelog-bitbucket-server-notes@v2
• changelog-bitbucket-server-release
• changelog-forgejo-notes@v2
• changelog-forgejo-release
• changelog-gitea-notes@v2
• changelog-gitea-release
• changelog-github-notes@v2
• changelog-github-release
• changelog-gitlab-notes@v2
• changelog-gitlab-release
• datasource-artifactory
• datasource-aws-machine-image
• datasource-aws-rds
• datasource-aws-eks-addon
• datasource-azure-bicep-resource
• datasource-azure-pipelines-tasks
• datasource-bazel
• datasource-bitbucket-tags
• datasource-bitbucket-server-tags
• datasource-bitrise
• datasource-buildpacks-registry
• datasource-cdnjs
• datasource-conan
• datasource-conda
• datasource-cpan
• datasource-crate-metadata
• datasource-crate
• datasource-deb
• datasource-deno
• datasource-docker-architecture
• datasource-docker-hub-cache
• datasource-docker-digest
• datasource-docker-hub-tags
• datasource-docker-imageconfig
• datasource-docker-labels
• datasource-docker-releases-v2
• datasource-docker-tags
• datasource-dotnet-version
• datasource-endoflife-date
• datasource-forgejo-releases
• datasource-forgejo-tags
• datasource-galaxy-collection
• datasource-galaxy
• datasource-git-refs
• datasource-git-tags
• datasource-git
• datasource-gitea-releases
• datasource-gitea-tags
• datasource-github-release-attachments
• datasource-gitlab-packages
• datasource-gitlab-releases
• datasource-gitlab-tags
• datasource-glasskube-packages
• datasource-go-direct
• datasource-go-proxy
• datasource-go
• datasource-golang-version
• datasource-gradle-version
• datasource-helm
• datasource-hermit
• datasource-hex
• datasource-hexpm-bob
• datasource-java-version
• datasource-jenkins-plugins
• datasource-jsr
• datasource-maven:cache-provider
• datasource-maven:postprocess-reject
• datasource-node-version
• datasource-npm:cache-provider
• datasource-nuget-v3
• datasource-orb
• datasource-packagist
• datasource-pod
• datasource-python-version
• datasource-repology
• datasource-rpm
• datasource-ruby-version
• datasource-rubygems
• datasource-sbt-package
• datasource-terraform-module
• datasource-terraform-provider
• datasource-terraform
• datasource-typst:cache-provider
• datasource-typst:releases
• datasource-unity3d
• datasource-unity3d-packages
• github-releases-datasource-v2
• github-tags-datasource-v2
• merge-confidence
• preset
• terraform-provider-hash
• url-sha256

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

checkedBranches

A list of branch names to mark for creation or rebasing as if it was selected in the Dependency Dashboard issue.

Name	Value
type	array
subType	string
cli	--checked-branches
env	RENOVATE_CHECKED_BRANCHES

This array will allow you to set the names of the branches you want to rebase/create, as if you selected their checkboxes in the Dependency Dashboard issue.

It has been designed with the intention of being run on one repository, in a one-off manner, e.g. to "force" the rebase of a known existing branch. It is highly unlikely that you should ever need to add this to your permanent global config.

Example: renovate --checked-branches=renovate/chalk-4.x renovate-reproductions/checked will rebase the renovate/chalk-4.x branch in the renovate-reproductions/checked repository.`

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

configFileNames

List of filenames where repository config will be stored.

Name	Value
type	array
subType	string
inheritConfigSupport	true

A list of filenames where repository config can be stored.

This list doesn't replace the existing list of default config filenames used internally, instead these filenames are prepended to the list.

Example:

{
  "configFileNames": ["myrenovate.json"]
}

Note

If you want renovate to use a custom filename for the onboarding branch you also need to change the onboardingConfigFileName.

containerbaseDir

The directory where Renovate stores its containerbase cache. If left empty, Renovate creates a subdirectory within the cacheDir.

Name	Value
type	string
cli	--containerbase-dir
env	RENOVATE_CONTAINERBASE_DIR
default	null

This directory is used to cache downloads when binarySource=docker or binarySource=install.

Use this option if you need such downloads to be stored outside of Renovate's regular cache directory (cacheDir).

customEnvVariables

Custom environment variables for child processes and sidecar Docker containers.

Name	Value
type	object
cli	--custom-env-variables
env	RENOVATE_CUSTOM_ENV_VARIABLES

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

Warning

Do not configure any secret values directly into customEnvVariables because they may be logged to stdout. Instead, configure them into secrets first so that they will be redacted in logs.

If configuring secrets in to customEnvVariables, take this approach:

{
  secrets: {
    SECRET_TOKEN: process.env.SECRET_TOKEN,
  },
  customEnvVariables: {
    SECRET_TOKEN: '{{ secrets.SECRET_TOKEN }}',
  },
}

The above configuration approach will mean the values are redacted in logs like in the following example:

         "secrets": {"SECRET_TOKEN": "***********"},
         "customEnvVariables": {"SECRET_TOKEN": "{{ secrets.SECRET_TOKEN }}"},

deleteAdditionalConfigFile

If set to true, Renovate tries to delete the additional self-hosted config file after reading it.

Name	Value
type	boolean
default	false
cli	--delete-additional-config-file
env	RENOVATE_DELETE_ADDITIONAL_CONFIG_FILE

If set to true Renovate tries to delete the additional self-hosted config file after reading it.

The process that runs Renovate must have the correct permissions to delete the additional config file.

Tip

You can tell Renovate where to find your config file with the RENOVATE_ADDITONAL_CONFIG_FILE environment variable.

deleteConfigFile

If set to true, Renovate tries to delete the self-hosted config file after reading it.

Name	Value
type	boolean
default	false
cli	--delete-config-file
env	RENOVATE_DELETE_CONFIG_FILE

If set to true Renovate tries to delete the self-hosted config file after reading it.

The process that runs Renovate must have the correct permissions to delete the config file.

Tip

You can tell Renovate where to find your config file with the RENOVATE_CONFIG_FILE environment variable.

detectGlobalManagerConfig

If true, Renovate tries to detect global manager configuration from the file system.

Name	Value
type	boolean
default	false
cli	--detect-global-manager-config
env	RENOVATE_DETECT_GLOBAL_MANAGER_CONFIG

The purpose of this config option is to allow you (as a bot admin) to configure manager-specific files such as a global .npmrc file, instead of configuring it in Renovate config.

This config option is disabled by default because it may prove surprising or undesirable for some users who don't expect Renovate to go into their home directory and import registry or credential information.

Currently this config option is supported for the npm manager only - specifically the ~/.npmrc file. If found, it will be imported into config.npmrc with config.npmrcMerge set to true.

detectHostRulesFromEnv

If true, Renovate tries to detect host rules from environment variables.

Name	Value
type	boolean
default	false
cli	--detect-host-rules-from-env
env	RENOVATE_DETECT_HOST_RULES_FROM_ENV

The format of the environment variables must follow:

• RENOVATE_ prefix (at the moment this prefix optional, but usage of prefix will be required in the future)
• Datasource name (e.g. NPM, PYPI) or Platform name (only GITHUB)
• Underscore (_)
• matchHost (note: only domains or subdomains are supported - not https:// URLs or anything with forward slashes)
• Underscore (_)
• Field name (TOKEN, USERNAME, PASSWORD, HTTPSPRIVATEKEY, HTTPSCERTIFICATE, HTTPSCERTIFICATEAUTHORITY)

Hyphens (-) in datasource or host name must be replaced with double underscores (__). Periods (.) in host names must be replaced with a single underscore (_).

Note

You can't use these prefixes with the detectHostRulesFromEnv config option: npm_config_, npm_lifecycle_, npm_package_. In addition, platform host rules will only be picked up when matchHost is supplied.

npmjs registry token example

NPM_REGISTRY_NPMJS_ORG_TOKEN=abc123:

{
  "hostRules": [
    {
      "hostType": "npm",
      "matchHost": "registry.npmjs.org",
      "token": "abc123"
    }
  ]
}

GitLab Tags username/password example

GITLAB__TAGS_CODE__HOST_COMPANY_COM_USERNAME=bot GITLAB__TAGS_CODE__HOST_COMPANY_COM_PASSWORD=botpass123:

{
  "hostRules": [
    {
      "hostType": "gitlab-tags",
      "matchHost": "code-host.company.com",
      "username": "bot",
      "password": "botpass123"
    }
  ]
}

Datasource and credentials only

You can skip the host part, and use only the datasource and credentials.

DOCKER_USERNAME=bot DOCKER_PASSWORD=botpass123:

{
  "hostRules": [
    {
      "hostType": "docker",
      "username": "bot",
      "password": "botpass123"
    }
  ]
}

Platform with https authentication options

GITHUB_SOME_GITHUB__ENTERPRISE_HOST_HTTPSCERTIFICATE=certificate GITHUB_SOME_GITHUB__ENTERPRISE_HOST_HTTPSPRIVATEKEY=private-key GITHUB_SOME_GITHUB__ENTERPRISE_HOST_HTTPSCERTIFICATEAUTHORITY=certificate-authority:

{
  "hostRules": [
    {
      "hostType": "github",
      "matchHost": "some.github-enterprise.host",
      "httpsPrivateKey": "private-key",
      "httpsCertificate": "certificate",
      "httpsCertificateAuthority": "certificate-authority"
    }
  ]
}

dockerChildPrefix

Change this value to add a prefix to the Renovate Docker sidecar container names and labels.

Name	Value
type	string
default	"renovate_"
cli	--docker-child-prefix
env	RENOVATE_DOCKER_CHILD_PREFIX

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

For example, if you set dockerChildPrefix=myprefix_ then the final container created from the containerbase/sidecar is:

• called myprefix_sidecar instead of renovate_sidecar
• labeled myprefix_child instead of renovate_child

Note

Dangling containers are only removed when Renovate runs again with the same prefix.

dockerCliOptions

Pass CLI flags to docker run command when binarySource=docker.

Name	Value
type	string
cli	--docker-cli-options
env	RENOVATE_DOCKER_CLI_OPTIONS
default	null

You can use dockerCliOptions to pass Docker CLI options to Renovate's sidecar Docker containers.

For example, {"dockerCliOptions": "--memory=4g"} will add a CLI flag to the docker run command that limits the amount of memory Renovate's sidecar Docker container can use to 4 gigabytes.

Read the Docker Docs, configure runtime resource constraints to learn more.

dockerMaxPages

By default, Renovate fetches up to 20 pages of Docker tags from registries. But you can set your own limit with this config option.

Name	Value
type	integer
default	20
cli	--docker-max-pages
env	RENOVATE_DOCKER_MAX_PAGES

If set to an positive integer, Renovate will use this value as the maximum page number. Setting a different limit is useful for registries that ignore the n parameter in Renovate's query string and thus only return 50 tags per page.

dockerSidecarImage

Change this value to override the default Renovate sidecar image.

Name	Value
type	string
default	"ghcr.io/containerbase/sidecar:13.23.11"
cli	--docker-sidecar-image
env	RENOVATE_DOCKER_SIDECAR_IMAGE

By default Renovate pulls the sidecar Docker containers from ghcr.io/containerbase/sidecar. You can use the dockerSidecarImage option to override this default.

Say you want to pull a custom image from ghcr.io/your_company/sidecar. You would put this in your configuration file:

{
  "dockerSidecarImage": "ghcr.io/your_company/sidecar"
}

Now when Renovate pulls a new sidecar image, the final image is ghcr.io/your_company/sidecar instead of ghcr.io/containerbase/sidecar.

dockerUser

Set the UID and GID for Docker-based binaries if you use binarySource=docker.

Name	Value
type	string
cli	--docker-user
env	RENOVATE_DOCKER_USER
default	null

Override default user and group used by Docker-based tools. The user-id (UID) and group-id (GID) must 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.

Setting UID to 1001 and GID to 1002

{
  "dockerUser": "1001:1002"
}

If you use binarySource=docker|install read the section below.

If you need to change the Docker user please make sure to use the root (0) group, otherwise you'll get in trouble with missing file and directory permissions. Like this:

> export RENOVATE_DOCKER_USER="$(id -u):0" # 500:0 (username:root)

dryRun

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

Name	Value
type	string
allowedValues	extract, lookup, full
cli	--dry-run
env	RENOVATE_DRY_RUN

Use dryRun to preview the behavior of Renovate in logs, without making any changes to the repository files.

You can choose from the following behaviors for the dryRun config option:

• null: Default behavior - Performs a regular Renovate run including creating/updating/deleting branches and PRs
• "extract": Performs a very quick package file scan to identify the extracted dependencies
• "lookup": Performs a package file scan to identify the extracted dependencies and updates available
• "full": Performs a dry run by logging messages instead of creating/updating/deleting branches and PRs

Information provided mainly in debug log level.

encryptedWarning

Warning text to use if encrypted config is found.

Name	Value
type	string
cli	--encrypted-warning
env	RENOVATE_ENCRYPTED_WARNING
default	null

Warning

For advanced use only! Use at your own risk!

Use this if you want to stop supporting encrypted configuration capabilities but want to warn users first to migrate.

If set to a string value, Renovate will log warnings with the encryptedWarning text, meaning the message will be visible to users such as on the Dependency Dashboard.

endpoint

Custom endpoint to use.

Name	Value
type	string
cli	--endpoint
env	RENOVATE_ENDPOINT

executionTimeout

Default execution timeout in minutes for child processes Renovate creates.

Name	Value
type	integer
default	15
cli	--execution-timeout
env	RENOVATE_EXECUTION_TIMEOUT

Default execution timeout in minutes for child processes Renovate creates. If this option is not set, Renovate will fallback to 15 minutes.

exposeAllEnv

Set this to true to allow passing of all environment variables to package managers.

Name	Value
type	boolean
default	false
cli	--expose-all-env
env	RENOVATE_EXPOSE_ALL_ENV

To keep you safe, Renovate only passes a limited set of environment variables to package managers. If you must expose all environment variables to package managers, you can set this option to true.

Warning

Always consider the security implications of using exposeAllEnv! Secrets and other confidential information stored in environment variables could be leaked by a malicious script, that enumerates all environment variables.

Set exposeAllEnv to true only if you have reviewed, and trust, the repositories which Renovate bot runs against. Alternatively, you can use the customEnvVariables config option to handpick a set of variables you need to expose.

Setting this to true also allows for variable substitution in .npmrc files.

force

Any configuration set in this object will force override existing settings.

Name	Value
type	object
mergeable	true
env	RENOVATE_FORCE

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

Decides if CLI configuration options are moved to the force config section.

Name	Value
type	boolean
default	true
cli	--force-cli
env	RENOVATE_FORCE_CLI

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.

forkCreation

Whether to create forks as needed at runtime when running in "fork mode".

Name	Value
type	boolean
supportedPlatforms	github
default	true
cli	--fork-creation
env	RENOVATE_FORK_CREATION

This configuration lets you disable the runtime forking of repositories when running in "fork mode".

Usually you will need to keep this as the default true, and only set to false if you have some out of band process to handle the creation of forks.

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

forkOrg

The preferred organization to create or find forked repositories, when in fork mode.

Name	Value
type	string
supportedPlatforms	github
cli	--fork-org
env	RENOVATE_FORK_ORG
default	null

This configuration option lets you choose an organization you want repositories forked into when "fork mode" is enabled. It must be set to a GitHub Organization name and not a GitHub user account. When set, "allow edits by maintainers" will be false for PRs because GitHub does not allow this setting for organizations.

This can be used if you're migrating from user-based forks to organization-based forks.

If you've set a forkOrg then Renovate will:

1. Check if a fork exists in the preferred organization before checking it exists in the fork user's account
2. If no fork exists: it will be created in the forkOrg, not the user account

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

forkToken

Set a personal access token here to enable "fork mode".

Name	Value
type	string
supportedPlatforms	github
cli	--fork-token
env	RENOVATE_FORK_TOKEN
default	null

If this value is configured then Renovate:

• forks the target repository into the account that owns the PAT
• keep this fork's default branch up-to-date with the target

Renovate will then create branches on the fork and opens Pull Requests on the parent repository.

Note

Forked repositories will always be skipped when forkToken is set, even if includeForks is true.

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

gitNoVerify

Which Git commands will be run with the --no-verify option.

Name	Value
type	array
subType	string
allowedValues	commit, push
default	["commit", "push"]
cli	--git-no-verify
env	RENOVATE_GIT_NO_VERIFY

Controls when Renovate passes the --no-verify flag to git. The flag can be passed to git commit and/or git push. Read the documentation for git commit --no-verify and git push --no-verify to learn exactly what each flag does. To learn more about Git hooks, read the Pro Git 2 book, section on Git Hooks.

gitPrivateKey

PGP key to use for signing Git commits.

Name	Value
type	string
env	RENOVATE_GIT_PRIVATE_KEY
default	null

This is a private PGP or SSH key for signing Git commits.

For PGP, it should be an armored private key, so 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.

Note

The private key can't be protected with a passphrase if running in a headless environment. Renovate will not be able to handle entering the passphrase.

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

1. Run gpg import (if you haven't before) when using PGP
2. Run git config user.signingkey, git config commit.gpgsign true and git config gpg.format

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.

gitPrivateKeyPassphrase

Passphrase for the gitPrivateKey

Name	Value
type	string
env	RENOVATE_GIT_PRIVATE_KEY_PASSPHRASE
default	null

Passphrase for the gitPrivateKey when the private key is protected with a passphrase.

Currently supported for SSH keys only. When provided, Renovate will automatically decrypt the SSH private key during the signing process.

Note

Passphrases are not yet supported for GPG keys. If you provide a passphrase for a GPG key, it will be ignored and a warning will be logged.

Warning

Store this value securely as it provides access to decrypt your private key. Consider using environment variables or secure secret management systems rather than storing it in plain text configuration files.

gitTimeout

Configure the timeout with a number of milliseconds to wait for a Git task.

Name	Value
type	integer
default	0
cli	--git-timeout
env	RENOVATE_GIT_TIMEOUT

To handle the case where the underlying Git processes appear to hang, configure the timeout with the number of milliseconds to wait after last received content on either stdOut or stdErr streams before sending a SIGINT kill message.

gitUrl

Overrides the default resolution for Git remote, e.g. to switch GitLab from HTTPS to SSH-based.

Name	Value
type	string
supportedPlatforms	bitbucket-server, forgejo, gitea, gitlab
allowedValues	default, ssh, endpoint
default	"default"
cli	--git-url
env	RENOVATE_GIT_URL

Override the default resolution for Git remote, e.g. to switch GitLab from HTTPS to SSH-based.

Possible values:

• default: use HTTPS URLs provided by the platform for Git
• ssh: use SSH URLs provided by the platform for Git
• endpoint: ignore URLs provided by the platform and use the configured endpoint directly

githubTokenWarn

Display warnings about GitHub token not being set.

Name	Value
type	boolean
default	true
cli	--github-token-warn
env	RENOVATE_GITHUB_TOKEN_WARN

By default, Renovate logs and displays a warning when the RENOVATE_GITHUB_COM_TOKEN is not set. By setting githubTokenWarn to false, Renovate suppresses these warnings on Pull Requests, etc. Disabling the warning is helpful for self-hosted environments that can't access the github.com domain, because the warning is useless in these environments.

globalExtends

Configuration presets to use or extend for a self-hosted config.

Name	Value
type	array
subType	string
cli	--global-extends
env	RENOVATE_GLOBAL_EXTENDS

Unlike the extends field, which is passed through unresolved to be part of repository config, any presets in globalExtends are resolved immediately as part of global config. Use the globalExtends field if your preset has any global-only configuration options, such as the list of repositories to run against.

Use the extends field instead of this if, for example, you need the ability for a repository config (e.g. renovate.json) to be able to use ignorePresets for any preset defined in global config.

Warning

globalExtends presets can't be private. When Renovate resolves globalExtends it does not fully process the configuration. This means that Renovate does not have the authentication it needs to fetch private things.

httpCacheTtlDays

Maximum duration in days to keep HTTP cache entries.

Name	Value
type	integer
default	90
cli	--http-cache-ttl-days
env	RENOVATE_HTTP_CACHE_TTL_DAYS

This option sets the number of days that Renovate will cache HTTP responses. The default value is 90 days. Value of 0 means no caching.

Warning

When you set httpCacheTtlDays to 0, Renovate will remove the cached HTTP data.

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 the Mend Renovate App to self-hosted. An additional use case is for GitLab users of project or group access tokens who need to rotate them.

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.

Setting this field to true in Github or GitLab will also mean that all Issues will be fetched instead of only those by the bot itself.

includeMirrors

Whether to process repositories that are mirrors. By default, repositories that are mirrors are skipped.

Name	Value
type	boolean
default	false
supportedPlatforms	gitlab
cli	--include-mirrors
env	RENOVATE_INCLUDE_MIRRORS

By default, Renovate does not autodiscover repositories that are mirrors.

Change this setting to true to include repositories that are mirrors as Renovate targets.

inheritConfig

If true, Renovate will inherit configuration from the inheritConfigFileName file in inheritConfigRepoName.

Name	Value
type	boolean
default	false
cli	--inherit-config
env	RENOVATE_INHERIT_CONFIG

When you enable this option, Renovate will look for the inheritConfigFileName file in the inheritConfigRepoName repository before processing a repository, and read this in as config.

If the repository is in a nested organization or group on a supported platform such as GitLab, such as topGroup/nestedGroup/projectName then Renovate will look in topGroup/nestedGroup/renovate-config.

If inheritConfig is true but the inherited config file does not exist then Renovate will proceed without warning. If the file exists but cannot be parsed, then Renovate will raise a config warning issue and abort the job.

The inherited config may include all valid repository config and these config options:

• bbUseDevelopmentBranch
• onboarding
• onboardingBranch
• onboardingCommitMessage
• onboardingConfig
• onboardingConfigFileName
• onboardingNoDeps
• onboardingPrTitle
• onboardingRebaseCheckbox
• requireConfig

Note

The above list is prepared manually and may become out of date. Consult the self-hosted configuration docs and look for inheritConfigSupport values there for the definitive list.

This way organizations can change/control the default behavior, like whether configs are required and how repositories are onboarded.

We disabled inheritConfig in the Mend Renovate App to avoid wasting millions of API calls per week. This is because each 404 response from the GitHub API due to a missing org inherited config counts as a used API call. We will add a smart/dynamic approach in future, so that we can selectively enable inheritConfig per organization.

inheritConfigFileName

Renovate will look for this config file name in the inheritConfigRepoName.

Name	Value
type	string
default	"org-inherited-config.json"
cli	--inherit-config-file-name
env	RENOVATE_INHERIT_CONFIG_FILE_NAME

Change this setting if you want Renovate to look for a different file name within the inheritConfigRepoName repository. You may use nested files, for example: "some-dir/config.json".

inheritConfigRepoName

Renovate will look in this repo for the inheritConfigFileName.

Name	Value
type	string
default	"{{parentOrg}}/renovate-config"
cli	--inherit-config-repo-name
env	RENOVATE_INHERIT_CONFIG_REPO_NAME

Change this setting if you want Renovate to look in an alternative repository for the inherited config. The repository must be on the same platform and endpoint, and Renovate's token must have read permissions to the repository.

inheritConfigStrict

If true, any inheritedConfig fetch error will result in an aborted run.

Name	Value
type	boolean
default	false
cli	--inherit-config-strict
env	RENOVATE_INHERIT_CONFIG_STRICT

By default Renovate will silently (debug log message only) ignore cases where inheritConfig=true but no inherited config is found. When you set inheritConfigStrict=true then Renovate will abort the run and raise a config error if Renovate can't find the inherited config.

Warning

Only set this config option to true if every organization has an inherited config file and you want to make sure Renovate always uses that inherited config.

logContext

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

Name	Value
type	string
cli	--log-context
env	RENOVATE_LOG_CONTEXT

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.

mergeConfidenceDatasources

If set, Renovate will query the merge-confidence JSON API only for datasources that are part of this list.

Name	Value
allowedValues	go, maven, npm, nuget, packagist, pypi, rubygems
default	["go", "maven", "npm", "nuget", "packagist", "pypi", "rubygems"]
type	array
subType	string
cli	--merge-confidence-datasources
env	RENOVATE_MERGE_CONFIDENCE_DATASOURCES

This feature is applicable only if you have an access token for Mend's Merge Confidence API.

If set, Renovate will query the merge-confidence JSON API only for datasources that are part of this list. Otherwise, it queries all the supported datasources (check default value).

Example:

modules.exports = {
  mergeConfidenceDatasources: ['npm'],
};

mergeConfidenceEndpoint

If set, Renovate will query this API for Merge Confidence data.

Name	Value
type	string
default	"https://developer.mend.io/"
cli	--merge-confidence-endpoint
env	RENOVATE_MERGE_CONFIDENCE_ENDPOINT

Warning

For advanced use only! Use at your own risk!

This feature is applicable only if you have an access token for Mend's Merge Confidence API.

If set, Renovate will retrieve Merge Confidence data by querying this API. Otherwise, it will use the default URL, which is https://developer.mend.io/.

If you use the Mend Renovate Enterprise Edition (Renovate EE) and:

• have a static merge confidence token that you set via MEND_RNV_MC_TOKEN
• or set MEND_RNV_MC_TOKEN to auto

Then you must set this variable at the server and the workers.

But if you have specified the token as a matchConfidence packageRule, you only need to set this variable at the workers.

This feature is in private beta.

migratePresets

Define presets here which have been removed or renamed and should be migrated automatically.

Name	Value
type	object
additionalProperties	{"type": "string"}
cli	--migrate-presets
env	RENOVATE_MIGRATE_PRESETS

Use this if you have repositories that extend from a particular preset, which has now been renamed or removed. This is handy if you have a large number of repositories that all extend from a particular preset which you want to rename, without the hassle of manually updating every repository individually. Use an empty string to indicate that the preset should be ignored rather than replaced.

Example:

modules.exports = {
  migratePresets: {
    '@company': 'local>org/renovate-config',
  },
};

In the above example any reference to the @company preset will be replaced with local>org/renovate-config.

Tip

Combine migratePresets with configMigration if you'd like your config migrated by PR.

onboarding

Require a Configuration PR first.

Name	Value
type	boolean
inheritConfigSupport	true
cli	--onboarding
env	RENOVATE_ONBOARDING
default	true

Only set this to false 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 to override the default onboarding branch name.

Name	Value
type	string
default	"renovate/configure"
inheritConfigSupport	true
env	RENOVATE_ONBOARDING_BRANCH

Note

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 to override the default onboarding commit message.

Name	Value
type	string
inheritConfigSupport	true
env	RENOVATE_ONBOARDING_COMMIT_MESSAGE

If commitMessagePrefix or semanticCommits values are set 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 for onboarding PRs.

Name	Value
type	object
default	{"$schema": "https://docs.renovatebot.com/renovate-schema.json"}
inheritConfigSupport	true
mergeable	true
cli	--onboarding-config
env	RENOVATE_ONBOARDING_CONFIG

onboardingConfigFileName

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

Name	Value
type	string
default	"renovate.json"
inheritConfigSupport	true
env	RENOVATE_ONBOARDING_CONFIG_FILE_NAME

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.

Note

If you want renovate to use a custom filename for the onboarding branch you need add allow that filename using the configFileNames option.

onboardingNoDeps

Onboard the repository even if no dependencies are found.

Name	Value
type	string
default	"auto"
allowedValues	auto, enabled, disabled
inheritConfigSupport	true
cli	--onboarding-no-deps
env	RENOVATE_ONBOARDING_NO_DEPS

The default auto setting is converted to disabled if autodiscoverRepositories is true, or converted to enabled if false.

In other words, the default behavior is:

• If you run Renovate on discovered repositories then it will skip onboarding those without dependencies detected, but
• If you run Renovate on specific repositories then Renovate will onboard all such repositories even if no dependencies are found

onboardingPrTitle

Change this value to override the default onboarding PR title.

Name	Value
type	string
default	"Configure Renovate"
inheritConfigSupport	true
env	RENOVATE_ONBOARDING_PR_TITLE

If you have an existing Renovate installation and you change the onboardingPrTitle: then you may get onboarding PRs again for repositories with closed non-merged onboarding PRs. This is similar to what happens when you change the onboardingBranch config option.

onboardingRebaseCheckbox

Set to enable rebase/retry markdown checkbox for onboarding PRs.

Name	Value
type	boolean
default	false
supportedPlatforms	forgejo, gitea, github, gitlab
cli	--onboarding-rebase-checkbox
env	RENOVATE_ONBOARDING_REBASE_CHECKBOX

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.
To track this feature visit the following GitHub issue #17633.

optimizeForDisabled

Set to true to perform a check for disabled config prior to cloning.

Name	Value
type	boolean
default	false
cli	--optimize-for-disabled
env	RENOVATE_OPTIMIZE_FOR_DISABLED

When this option is true, Renovate will do the following during repository initialization:

1. Try to fetch the default config file (e.g. renovate.json)
2. Check if the file contains "enabled": false
3. If so, skip cloning and skip the repository immediately

If onboardingConfigFileName is set, that file name will be used instead of the default.

If the file exists and the config is disabled, Renovate will skip the repo without cloning it. Otherwise, it will continue as normal.

optimizeForDisabled can make initialization quicker in cases where most repositories are disabled, but it uses an extra API call for enabled repositories.

A second, advanced, use also exists when the bot global config has extends: [":disableRenovate"]. In that case, Renovate searches the repository config file for any of these configurations:

• extends: [":enableRenovate"]
• ignorePresets: [":disableRenovate"]
• enabled: true

If Renovate finds any of the above configurations, it continues initializing the repository. If not, then Renovate skips the repository without cloning it.

password

Password for authentication.

Name	Value
type	string
supportedPlatforms	azure, bitbucket, bitbucket-server
cli	--password
env	RENOVATE_PASSWORD
default	null

persistRepoData

If set to true: keep repository data between runs instead of deleting the data.

Name	Value
type	boolean
default	false
cli	--persist-repo-data
env	RENOVATE_PERSIST_REPO_DATA

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, codecommit, forgejo, gerrit, gitea, github, gitlab, local
default	"github"
cli	--platform
env	RENOVATE_PLATFORM

prCommitsPerRunLimit

Set the maximum number of commits per Renovate run. By default there is no limit.

Name	Value
type	integer
default	0
cli	--pr-commits-per-run-limit
env	RENOVATE_PR_COMMITS_PER_RUN_LIMIT

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.

presetCachePersistence

Cache resolved presets in package cache.

Name	Value
type	boolean
default	false
cli	--preset-cache-persistence
env	RENOVATE_PRESET_CACHE_PERSISTENCE

When this feature is enabled, resolved presets will be cached in Renovate's package cache, enabling reuse across multiple repositories.

TTL is 15 minutes by default, and it is adjustable in cacheTtlOverride.

Warning

Doing so improves efficiency because shared presets don't need to be reloaded/resolved for every repository, however it also means that private presets can be "leaked" between repositories. You should only enable this when all repositories are trusted, such as a corporate environment.

privateKey

Server-side private key.

Name	Value
type	string
replaceLineReturns	true
cli	--private-key
env	RENOVATE_PRIVATE_KEY
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 UI to encrypt values you can put the public key in a HTML page similar to https://app.renovatebot.com/encrypt.

To create the PGP key pair with GPG use the following commands:

• gpg --full-generate-key and follow the prompts to generate a key. Name and email are not important to Renovate, and do not configure a passphrase. Use a 4096bit key.

key generation log

❯ gpg --full-generate-key
gpg (GnuPG) 2.2.24; Copyright (C) 2020 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
  (14) Existing key from card
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (3072) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0)
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Renovate Bot
Email address: renovate@whitesourcesoftware.com
Comment:
You selected this USER-ID:
    "Renovate Bot <renovate@whitesourcesoftware.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

gpg: key 0649CC3899F22A66 marked as ultimately trusted
gpg: revocation certificate stored as '/Users/rhys/.gnupg/openpgp-revocs.d/794B820F34B34A8DF32AADB20649CC3899F22A66.rev'
public and secret key created and signed.

pub   rsa4096 2021-09-10 [SC]
      794B820F34B34A8DF32AADB20649CEXAMPLEONLY
uid                      Renovate Bot <renovate@whitesourcesoftware.com>
sub   rsa4096 2021-09-10 [E]

Note

If you use GnuPG v2.4 (or newer) to generate the key, then you must disable AEAD preferences. This is needed to allow Renovate to decrypt the encrypted values.

key edit log

❯ gpg --edit-key renovate@whitesourcesoftware.com
gpg> showpref
[ultimate] (1). Renovate Bot <renovate@whitesourcesoftware.com>
     Cipher: AES256, AES192, AES, 3DES
     AEAD: OCB, EAX
     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
     Compression: ZLIB, BZIP2, ZIP, Uncompressed
     Features: MDC, AEAD, Keyserver no-modify

gpg> setpref AES256 AES192 AES 3DES SHA512 SHA384 SHA256 SHA224 SHA1 ZLIB BZIP2 ZIP
Set preference list to:
     Cipher: AES256, AES192, AES, 3DES
     AEAD:
     Digest: SHA512, SHA384, SHA256, SHA224, SHA1
     Compression: ZLIB, BZIP2, ZIP, Uncompressed
     Features: MDC, Keyserver no-modify
Really update the preferences? (y/N) y
gpg> save

• Copy the key ID from the output (794B820F34B34A8DF32AADB20649CEXAMPLEONLY in the above example) or run gpg --list-secret-keys if you forgot to take a copy
• Run gpg --armor --export-secret-keys YOUR_NEW_KEY_ID > renovate-private-key.asc to generate an armored (text-based) private key file
• Run gpg --armor --export YOUR_NEW_KEY_ID > renovate-public-key.asc to generate an armored (text-based) public key file

The private key should then be added to your Renovate Bot global config (either using privateKeyPath or exporting it to the RENOVATE_PRIVATE_KEY environment variable). The public key can be used to replace the existing key in https://app.renovatebot.com/encrypt for your own use.

Base64 Encoding Support

Renovate supports base64-encoded private keys for easier handling in environment variables or configuration files. Simply provide the base64-encoded version of your private key, and Renovate will automatically detect and decode it. This works for both GPG and SSH private keys.

Any PGP-encrypted secrets must have a mandatory organization/group scope, and optionally can be scoped for a single repository only. The reason for this is to avoid "replay" attacks where someone could learn your encrypted secret and then reuse it in their own Renovate repositories. Instead, with scoped secrets it means that Renovate ensures that the organization and optionally repository values encrypted with the secret match against the running repository.

Note

You could use public key encryption with earlier versions of Renovate. We deprecated this approach and removed the documentation for it. If you're still using public key encryption then we recommend that you use private keys instead.

privateKeyOld

Secondary or old private key to try.

Name	Value
type	string
replaceLineReturns	true
cli	--private-key-old
env	RENOVATE_PRIVATE_KEY_OLD
default	null

Use this field if you need to perform a "key rotation" and support more than one keypair at a time. Decryption with this key will be tried after privateKey.

If you are migrating from the legacy public key encryption approach to use a PGP key, then move your legacy private key from privateKey to privateKeyOld and then put your new PGP private key in privateKey. Doing so will mean that Renovate will first try to decrypt using the PGP key but fall back to the legacy key and try that next.

You can remove the privateKeyOld config option once all the old encrypted values have been migrated, or if you no longer want to support the old key and let the processing of repositories fail.

Note

Renovate now logs a warning whenever repositories use non-PGP encrypted config variables.

privateKeyPath

Path to the Server-side private key.

Name	Value
type	string
cli	--private-key-path
env	RENOVATE_PRIVATE_KEY_PATH
default	null

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

privateKeyPathOld

Path to the Server-side old private key.

Name	Value
type	string
cli	--private-key-path-old
env	RENOVATE_PRIVATE_KEY_PATH_OLD
default	null

Used as an alternative to privateKeyOld, if you want the key to be read from disk instead.

processEnv

Environment variables to be used in global config only.

Name	Value
type	object
additionalProperties	{"type": "string"}
cli	--process-env
env	RENOVATE_PROCESS_ENV

Used to set environment variables through the configuration file instead of using actual environment variables.

Example:

{
  "processEnv": {
    "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
    "AWS_SECRET_ACCESS_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "AWS_DEFAULT_REGION": "us-west-2"
  }
}

Note

• All values must be provided as strings, e.g., "true" instead of true
• Only supported in file configuration (not via CLI or environment).

productLinks

Links which are used in PRs, issues and comments.

Name	Value
type	object
mergeable	true
default	{ "documentation": "https://docs.renovatebot.com/", "help": "https://github.com/renovatebot/renovate/discussions", "homepage": "https://github.com/renovatebot/renovate" }
additionalProperties	{"type": "string", "format": "uri"}
cli	--product-links
env	RENOVATE_PRODUCT_LINKS

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

redisPrefix

Key prefix for redis cache entries.

Name	Value
type	string
cli	--redis-prefix
env	RENOVATE_REDIS_PREFIX
default	null

If this value is set then Renovate will prepend this string to the name of all Redis cache entries used in Renovate. It's only used if redisUrl is configured.

redisUrl

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

Name	Value
type	string
cli	--redis-url
env	RENOVATE_REDIS_URL
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 changelogs) between repositories and runs.

For non encrypted connections,

Example URL structure: redis://[[username]:[password]]@localhost:6379/0.

For TLS/SSL-enabled connections, use rediss prefix

Example URL structure: rediss://[[username]:[password]]@localhost:6379/0.

Renovate also supports connecting to Redis clusters as well. In order to connect to a cluster, provide the connection string using the redis+cluster or rediss+cluster schema as appropriate.

Example URL structure: redis+cluster://[[username]:[password]]@redis.cluster.local:6379/0

reportPath

Path to where the file should be written. In case of s3 this has to be a full S3 URI.

Name	Value
type	string
cli	--report-path
env	RENOVATE_REPORT_PATH

reportPath describes the location where the report is written to.

If reportType is set to file, then set reportPath to a filepath. For example: /foo/bar.json.

If the value s3 is used in reportType, then use a S3 URI. For example: s3://bucket-name/key-name.

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

reportType

Set how, or if, reports should be generated.

Name	Value
type	string
allowedValues	logging, file, s3
cli	--report-type
env	RENOVATE_REPORT_TYPE

Defines how the report is exposed:

• <unset> If unset, no report will be provided, though the debug logs will still have partial information of the report
• logging The report will be printed as part of the log messages on INFO level
• file The report will be written to a path provided by reportPath
• s3 The report is pushed to an S3 bucket defined by reportPath. This option reuses s3Endpoint and s3PathStyle

This feature is flagged as experimental

Experimental features might be changed or even removed at any time.

repositories

List of Repositories.

Name	Value
type	array
subType	string
env	RENOVATE_REPOSITORIES

Elements in the repositories array can be an object if you wish to define more settings. Example:

{
  repositories: [{ repository: 'g/r1', bumpVersion: 'patch' }, 'g/r2'];
}

repositoryCache

This option decides if Renovate uses a JSON cache to speed up extractions.

Name	Value
type	string
allowedValues	disabled, enabled, reset
default	"disabled"
cli	--repository-cache
env	RENOVATE_REPOSITORY_CACHE

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.

repositoryCacheType

Set the type of renovate repository cache if repositoryCache is enabled.

Name	Value
type	string
default	"local"
cli	--repository-cache-type
env	RENOVATE_REPOSITORY_CACHE_TYPE

Set repositoryCacheType to an S3 URI to enable S3 backed repository cache

{
  repositoryCacheType: 's3://bucket-name';
}

Renovate uses the AWS SDK for JavaScript V3 to connect to the S3 instance. Therefore, Renovate supports all the authentication methods supported by the AWS SDK. Read more about the default credential provider chain for AWS SDK for JavaScript V3.

Tip

If you're storing the repository cache on Amazon S3 then you may set a folder hierarchy as part of repositoryCacheType. For example, repositoryCacheType: 's3://bucket-name/dir1/.../dirN/'.

Note

S3 repository is used as a repository cache (e.g. extracted dependencies) and not a lookup cache (e.g. available versions of dependencies). To keep the later remotely, define Redis URL.

requireConfig

Controls Renovate's behavior regarding repository config files such as renovate.json.

Name	Value
type	string
default	"required"
allowedValues	required, optional, ignored
inheritConfigSupport	true
cli	--require-config
env	RENOVATE_REQUIRE_CONFIG

By default, Renovate needs a Renovate config file in each repository where it runs before it will propose any dependency updates.

You can choose any of these settings:

• "required" (default): a repository config file must be present
• "optional": if a config file exists, Renovate will use it when it runs
• "ignored": config files in the repo will be ignored, and have no effect

This feature is closely related to the onboarding config option. The combinations of requireConfig and onboarding are:

	onboarding=true	onboarding=false
requireConfig=required	An onboarding PR will be created if no config file exists. If the onboarding PR is closed and there's no config file, then the repository is skipped.	Repository is skipped unless a config file is added manually.
requireConfig=optional	An onboarding PR will be created if no config file exists. If the onboarding PR is closed and there's no config file, the repository will be processed.	Repository is processed regardless of config file presence.
requireConfig=ignored	No onboarding PR will be created and repo will be processed while ignoring any config file present.	Repository is processed, any config file is ignored.

s3Endpoint

If set, Renovate will use this string as the endpoint when creating the AWS S3 client instance.

Name	Value
type	string
cli	--s3-endpoint
env	RENOVATE_S3_ENDPOINT
default	null

If set, Renovate will use this string as the endpoint when creating the AWS S3 client instance.

s3PathStyle

If set, Renovate will enable forcePathStyle when creating the AWS S3 client instance.

Name	Value
type	boolean
default	false
cli	--s3-path-style
env	RENOVATE_S3_PATH_STYLE

If set, Renovate will enable forcePathStyle when creating the AWS S3 client instance.

For example:

s3PathStyle	Path
off	https://bucket.s3.amazonaws.com/
on	https://s3.amazonaws.com/bucket/

Read the AWS S3 docs, Interface BucketEndpointInputConfig to learn more about path-style URLs.

secrets

Object which holds secret name/value pairs.

Name	Value
type	object
mergeable	true
additionalProperties	{"type": "string"}
cli	--secrets
env	RENOVATE_SECRETS

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": [
    {
      "matchHost": "google.com",
      "token": "{{ secrets.GOOGLE_TOKEN }}"
    }
  ]
}

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

token

Repository Auth Token.

Name	Value
type	string
cli	--token
env	RENOVATE_TOKEN
default	null

unicodeEmoji

Enable or disable Unicode emoji.

Name	Value
type	boolean
default	true
cli	--unicode-emoji
env	RENOVATE_UNICODE_EMOJI

If enabled emoji shortcodes are replaced with their Unicode equivalents. For example: :warning: will be replaced with ⚠️.

useCloudMetadataServices

If false, Renovate does not try to access cloud metadata services.

Name	Value
type	boolean
default	true
cli	--use-cloud-metadata-services
env	RENOVATE_USE_CLOUD_METADATA_SERVICES

Some cloud providers offer services to receive metadata about the current instance, for example AWS Instance metadata or GCP VM metadata. You can control if Renovate should try to access these services with the useCloudMetadataServices config option.

userAgent

If set to any string, Renovate will use this as the user-agent it sends with HTTP requests.

Name	Value
type	string
cli	--user-agent
env	RENOVATE_USER_AGENT

If set to any string, Renovate will use this as the user-agent it sends with HTTP requests. Otherwise, it will default to RenovateBot/${renovateVersion} (https://github.com/renovatebot/renovate).

username

Username for authentication.

Name	Value
type	string
supportedPlatforms	azure, bitbucket, bitbucket-server
cli	--username
env	RENOVATE_USERNAME
default	null

The only time where username is required is if using username + password credentials for the bitbucket platform. You don't need to configure username directly if you have already configured token. Renovate will use the token to discover its username on the platform, including if you're running Renovate as a GitHub App.

variables

Object which holds variable name/value pairs.

Name	Value
type	object
mergeable	true
additionalProperties	{"type": "string"}
cli	--variables
env	RENOVATE_VARIABLES

Variables may be configured by a bot admin in config.js, which will then make them available for templating within repository configs. This config option behaves exactly like secrets, except that it won't be masked in the logs. For example, to configure a SOME_VARIABLE to be accessible by all repositories:

module.exports = {
  variables: {
    SOME_VARIABLE: 'abc123',
  },
};

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

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

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

{
  "packageRules": [
    {
      "matchUpdateTypes": ["patch"],
      "addLabels": ["{{ variables.SOME_VARIABLE }}"]
    }
  ]
}

writeDiscoveredRepos

Writes discovered repositories to a JSON file and then exit.

Name	Value
type	string
cli	--write-discovered-repos
env	RENOVATE_WRITE_DISCOVERED_REPOS
default	null

By default, Renovate processes each repository that it finds. You can use this optional parameter so Renovate writes the discovered repositories to a JSON file and exits.

Known use cases consist, among other things, of horizontal scaling setups. See Scaling Renovate Bot on self-hosted GitLab.

Usage: renovate --write-discovered-repos=/tmp/renovate-repos.json

["myOrg/myRepo", "myOrg/anotherRepo"]