self-hosted-configuration.md

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

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.

allowCustomCrateRegistries

allowPlugins

allowPostUpgradeCommandTemplating

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

allowScripts

allowedPostUpgradeCommands

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.

e.g.

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

autodiscover

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

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.

Minimatch:

{
  "autodiscoverFilter": "project/*"
}

Regex:

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

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

You can negate the regex by putting a ! in front:

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

baseDir

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

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.

Renovate can instead use "sidecar" containers for third-party tools when binarySource=docker. 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.

Additionally, when Renovate is run inside a container built using containerbase/buildpack, such as the official Renovate images on Docker Hub, then binarySource=install can be used. This mode means that Renovate will dynamically install the version of tools available, if supported.

Supported tools for dynamic install are:

• composer
• flux
• jb
• npm

Unsupported tools will fall back to binarySource=global.

cacheDir

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

customEnvVariables

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

detectGlobalManagerConfig

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

This feature 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 capability is supported for the npm manager only - specifically the ~/.npmrc file. If found, it will be imported into config.npmrc with config.npmrcMerge will be set to true.

detectHostRulesFromEnv

The format of the environment variables must follow:

• Datasource name (e.g. NPM, PYPI)
• Underscore (_)
• matchHost
• Underscore (_)
• Field name (TOKEN, USERNAME, or PASSWORD)

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

!!! note The following prefixes cannot be supported for this functionality: npm_config_, npm_lifecycle_, npm_package_.

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 just the datasource and credentials.

DOCKER_USERNAME=bot DOCKER_PASSWORD=botpass123:

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

dockerChildPrefix

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

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

!!! note Dangling containers will only be removed when Renovate runs again with the same prefix.

dockerImagePrefix

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.

dockerUser

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

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

endpoint

executionTimeout

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