self-hosted-configuration.md

title: Self-Hosted configuration
description: Self-Hosted configuration usable in config file, CLI or environment variables

Self-Hosted configuration options

You can only use these configuration options when you're self-hosting Renovate.

Please also see Self-Hosted Experimental Options.

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

allowCustomCrateRegistries

allowPlugins

allowPostUpgradeCommandTemplating

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

module.exports = {
  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 needed because, by default, the installation of dependencies is skipped (see the skipInstalls global option).

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

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

If you wish to disable templating because of any security or performance concern, you may set allowPostUpgradeCommandTemplating to false. But before you disable templating completely, try the allowedPostUpgradeCommands config option to limit what commands are allowed to run.

allowScripts

allowedPostUpgradeCommands

A list of regular expressions that decide which commands in postUpgradeTasks are allowed to run. If this list is empty then no tasks will be executed.

For example:

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

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

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 or regex pattern.

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="/myapp/{readme.md,src/**}"

# in this example you can use regex instead
RENOVATE_AUTODISCOVER_FILTER="/myapp/(readme\.md|src/.*)/"

Minimatch:

{
  "autodiscoverFilter": ["project/*"]
}

The search for repositories is case-insensitive.

Regex:

All text inside the start and end / will be treated as a regular expression.

{
  "autodiscoverFilter": ["/project/.*/"]
}

You can negate the regex by putting an ! in front. Only use a single negation and don't mix with other filters because all filters are combined with or. If using negations, all repositories except those who match the regex are added to the result:

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

autodiscoverNamespaces

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

autodiscoverTopics

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

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

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

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

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

This experimental feature is used to implement the concept of a "soft" cache expiry for datasources, starting with npm. It should be set to a non-zero value, recommended to be at least 60 (i.e. one hour).

When this value is set, the npm datasource will use the cacheHardTtlMinutes value for cache expiry, instead of its default expiry of 15 minutes, which becomes the "soft" expiry value. Results which are soft expired are reused in the following manner:

• The etag from the cached results will be reused, and may result in a 304 response, meaning cached results are revalidated
• If an error occurs when querying the npmjs registry, then soft expired results will be reused if they are present

cacheTtlOverride

Utilize 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. For example, to override the default TTL of 60 minutes for the docker datasource "tags" namespace: datasource-docker-tags use the following:

{
  "cacheTtlOverride": {
    "datasource-docker-tags": 120
  }
}

checkedBranches

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

containerbaseDir

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

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

detectGlobalManagerConfig

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

The format of the environment variables must follow:

• Datasource name (e.g. NPM, PYPI) or Platform name (only GITHUB)
• Underscore (_)
• matchHost
• 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