renovate/docs/configuration.md

28 KiB

Configuration

Configuration Methods

Configuration is supported via any or all of the below:

  • Configuration file
  • Environment
  • CLI
  • renovate.json in target repository
  • renovate field of package.json in target repository

The above are listed in reverse order of preference. i.e. package.json settings will override renovate.json settings, CLI, which overrides env, which overrides the config file, which overrides defaults.

Default Configuration

Default configuration values can be found in lib/config/definitions.js

Configuration File

You can override default configuration using a configuration file, with default name config.js in the working directory. If you need an alternate location or name, set it in the environment variable RENOVATE_CONFIG_FILE.

Using a configuration file gives you very granular configuration options. For instance, you can override most settings at the global (file), repository, or package level. e.g. apply one set of labels for backend/package.json and a different set for frontend/package.json in the same repository.

module.exports = {
  labels: ['upgrade'],
  depTypes: ['dependencies', 'devDependencies'],
  repositories: [
    {
      repository: 'singapore/repo1',
      packageFiles: [
        'package.json',
        {
          packageFile: 'frontend/package.json',
          labels: ['upgrade', 'frontend']
        },
      ],
    },
    {
      repository: 'singapore/repo2',
      depTypes: [
        'dependencies',
        'devDependencies',
        {
          depType: 'optionalDependencies',
          labels: ['renovate', 'optional'],
        },
      ],
      labels: ['renovate'],
    },
    'singapore/repo3',
  ],
  packages: [
    {
      package: 'jquery',
      labels: ['jquery', 'uhoh'],
    },
  ],
}

CLI

$ node renovate --help

To configure any <list> items, separate with commas. E.g. renovate --labels=renovate,dependency.

renovate.json

If you add a renovate.json file to the root of your repository, you can use this to override default settings. If you leave the packageFiles field empty then renovate will still auto-discover all package.json files in the repository.

package.json

If you add configuration options to your package.json then these will override any other settings above. Obviously, you can't set repository or package file location with this method.

"renovate": {
  "labels": [
    "upgrade",
    "bot"
  ]
}

Configuration Options

Name Description Type Default value Environment CLI
`extends` Configuration presets to use/extend list
[]
`RENOVATE_EXTENDS`
`description` Plain text description for a config or preset list
[]
`enabled` Enable or disable renovate boolean
true
`logLevel` Logging level string
"info"
`LOG_LEVEL` `--log-level`
`logFile` Log file path string
null
`RENOVATE_LOG_FILE` `--log-file`
`logFileLevel` Log file log level string
"debug"
`RENOVATE_LOG_FILE_LEVEL` `--log-file-level`
`onboarding` Require a Configuration PR first boolean
true
`RENOVATE_ONBOARDING` `--onboarding`
`renovateFork` Whether to renovate a forked repository or not. boolean
false
`RENOVATE_RENOVATE_FORK` `--renovate-fork`
`privateKey` Server-side private key string
null
`RENOVATE_PRIVATE_KEY` `--private-key`
`encrypted` A configuration object containing configuration encrypted with project key json
null
`RENOVATE_ENCRYPTED` `--encrypted`
`timezone` [IANA Time Zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string
null
`RENOVATE_TIMEZONE` `--timezone`
`schedule` Times of day/week to renovate list
[]
`updateNotScheduled` Whether to update (but not create) branches when not scheduled boolean
true
`RENOVATE_UPDATE_NOT_SCHEDULED` `--update-not-scheduled`
`onboarding` Require a Configuration PR first boolean
true
`RENOVATE_ONBOARDING` `--onboarding`
`platform` Platform type of repository string
"github"
`RENOVATE_PLATFORM` `--platform`
`endpoint` Custom endpoint to use string
null
`RENOVATE_ENDPOINT` `--endpoint`
`token` Repository Auth Token string
null
`RENOVATE_TOKEN` `--token`
`npmrc` String copy of npmrc file. Use \n instead of line breaks string
null
`RENOVATE_NPMRC` `--npmrc`
`yarnrc` String copy of yarnrc file. Use \n instead of line breaks string
null
`RENOVATE_YARNRC` `--yarnrc`
`ignoreNpmrcFile` Whether to ignore any .npmrc file found in repository boolean
false
`RENOVATE_IGNORE_NPMRC_FILE` `--ignore-npmrc-file`
`autodiscover` Autodiscover all repositories boolean
false
`RENOVATE_AUTODISCOVER` `--autodiscover`
`autodiscover` Autodiscover all repositories boolean
false
`RENOVATE_AUTODISCOVER` `--autodiscover`
`repositories` List of Repositories list
[]
`RENOVATE_REPOSITORIES`
`baseBranch` Base branch to target for Pull Requests. Otherwise default branch is used string
null
`packageFiles` Package file paths list
[]
`RENOVATE_PACKAGE_FILES` `--package-files`
`ignorePaths` Skip any package.json whose path matches one of these. Can be string or glob pattern list
["**/node_modules/**"]
`RENOVATE_IGNORE_PATHS` `--ignore-paths`
`dependencies` Configuration specifically for `package.json`>`dependencies` json
{"semanticPrefix": "fix(deps):"}
`RENOVATE_DEPENDENCIES`
`devDependencies` Configuration specifically for `package.json`>`devDependencies` json
{
  "pin": {
    "group": {
      "commitMessage": "Pin devDependencies",
      "prTitle": "Pin devDependencies"
    }
  }
}
`RENOVATE_DEV_DEPENDENCIES`
`optionalDependencies` Configuration specifically for `package.json`>`optionalDependencies` json
{}
`RENOVATE_OPTIONAL_DEPENDENCIES`
`peerDependencies` Configuration specifically for `package.json`>`peerDependencies` json
{"enabled": false}
`RENOVATE_PEER_DEPENDENCIES`
`ignoreDeps` Dependencies to ignore list
[]
`RENOVATE_IGNORE_DEPS` `--ignore-deps`
`packageRules` Rules for matching package names list
[]
`packageNames` Package names to match. Valid only within `packageRules` object list
[]
`excludePackageNames` Package names to exclude. Valid only within `packageRules` object list
[]
`packagePatterns` Package name patterns to match. Valid only within `packageRules` object. list
[]
`excludePackagePatterns` Package name patterns to exclude. Valid only within `packageRules` object. list
[]
`pinDigests` Whether to add digests to Dockerfile source images boolean
true
`RENOVATE_PIN_DIGESTS` `--pin-digests`
`pinVersions` Convert ranged versions to pinned versions boolean
null
`RENOVATE_PIN_VERSIONS` `--pin-versions`
`separateMajorReleases` If set to false, it will upgrade dependencies to latest release only, and not separate major/minor branches boolean
true
`RENOVATE_SEPARATE_MAJOR_RELEASES` `--separate-major-releases`
`separatePatchReleases` If set to true, it will separate minor and patch updates into separate branches boolean
false
`RENOVATE_SEPARATE_PATCH_RELEASES` `--separate-patch-releases`
`ignoreFuture` Ignore versions tagged as "future" boolean
true
`RENOVATE_IGNORE_FUTURE` `--ignore-future`
`ignoreUnstable` Ignore versions with unstable semver boolean
true
`RENOVATE_IGNORE_UNSTABLE` `--ignore-unstable`
`respectLatest` Ignore versions newer than npm "latest" version boolean
true
`RENOVATE_RESPECT_LATEST` `--respect-latest`
`branchPrefix` Prefix to use for all branch names string
"renovate/"
`RENOVATE_BRANCH_PREFIX` `--branch-prefix`
`major` Configuration to apply when an update type is major json
{}
`RENOVATE_MAJOR`
`minor` Configuration to apply when an update type is minor json
{}
`RENOVATE_MINOR`
`patch` Configuration to apply when an update type is patch. Only applies if `separatePatchReleases` is set to true json
{
  "branchName": "{{branchPrefix}}{{depNameSanitized}}-{{newVersionMajor}}.{{newVersionMinor}}.x"
}
`RENOVATE_PATCH`
`pin` Configuration to apply when an update type is pin. json
{
  "unpublishSafe": false,
  "recreateClosed": true,
  "groupName": "Pin Dependencies",
  "group": {
    "commitMessage": "Pin Dependencies",
    "prTitle": "{{groupName}}",
    "semanticPrefix": "refactor(deps):"
  }
}
`RENOVATE_PIN`
`digest` Configuration to apply when updating a Docker digest (same tag) json
{"semanticPrefix": "refactor(deps):"}
`RENOVATE_DIGEST`
`semanticCommits` Enable semantic commit prefixes for commits and PR titles boolean
null
`RENOVATE_SEMANTIC_COMMITS` `--semantic-commits`
`semanticPrefix` Prefix to use if semantic commits are enabled string
"chore(deps):"
`RENOVATE_SEMANTIC_PREFIX` `--semantic-prefix`
`recreateClosed` Recreate PRs even if same ones were closed previously boolean
false
`RENOVATE_RECREATE_CLOSED` `--recreate-closed`
`rebaseStalePrs` Rebase stale PRs (GitHub only) boolean
false
`RENOVATE_REBASE_STALE_PRS` `--rebase-stale-prs`
`unpublishSafe` Set a status check for unpublish-safe upgrades boolean
false
`RENOVATE_UNPUBLISH_SAFE` `--unpublish-safe`
`prCreation` When to create the PR for a branch. Values: immediate, not-pending, status-success. string
"immediate"
`RENOVATE_PR_CREATION` `--pr-creation`
`prNotPendingHours` Timeout in hours for when prCreation=not-pending integer
12
`RENOVATE_PR_NOT_PENDING_HOURS` `--pr-not-pending-hours`
`automerge` Whether to automerge branches/PRs automatically, without human intervention boolean
false
`RENOVATE_AUTOMERGE` `--automerge`
`automergeType` How to automerge - "branch-merge-commit", "branch-push" or "pr". Branch support is GitHub-only string
"pr"
`RENOVATE_AUTOMERGE_TYPE` `--automerge-type`
`requiredStatusChecks` List of status checks that must pass before automerging. Set to null to enable automerging without tests. list
[]
`branchName` Branch name template string
"{{branchPrefix}}{{depNameSanitized}}-{{newVersionMajor}}.x"
`RENOVATE_BRANCH_NAME`
`commitMessage` Commit message template string
"Update dependency {{depName}} to v{{newVersion}}"
`RENOVATE_COMMIT_MESSAGE`
`prTitle` Pull Request title template string
"{{#if isPin}}Pin{{else}}{{#if isRollback}}Roll back{{else}}Update{{/if}}{{/if}} dependency {{depName}} to {{#if isRange}}{{newVersion}}{{else}}{{#if isMajor}}v{{newVersionMajor}}{{else}}v{{newVersion}}{{/if}}{{/if}}"
`RENOVATE_PR_TITLE`
`prBody` Pull Request body template string
"This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request {{#if isRollback}}rolls back{{else}}updates{{/if}} dependency {{#if repositoryUrl}}[{{depName}}]({{repositoryUrl}}){{else}}`{{depName}}`{{/if}} from `{{#unless isRange}}{{#unless isPin}}v{{/unless}}{{/unless}}{{currentVersion}}` to `{{#unless isRange}}v{{/unless}}{{newVersion}}`{{#if isRollback}}. This is necessary and important because `v{{currentVersion}}` cannot be found in the npm registry - probably because of it being unpublished.{{/if}}\n{{#if releases.length}}\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n### Commits\n\n
\n{{githubName}}\n\n{{#each releases as |release|}}\n#### {{release.version}}\n{{#each release.commits as |commit|}}\n- [`{{commit.shortSha}}`]({{commit.url}}) {{commit.message}}\n{{/each}}\n{{/each}}\n\n
\n{{/if}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n- `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n- `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com)."
`RENOVATE_PR_BODY`
`lockFileMaintenance` Configuration for lock file maintenance json
{
  "enabled": false,
  "recreateClosed": true,
  "branchName": "{{branchPrefix}}lock-file-maintenance",
  "commitMessage": "Update lock file",
  "prTitle": "Lock file maintenance",
  "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request updates `package.json` lock files to use the latest dependency versions.\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n-   `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n-   `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com).",
  "schedule": ["before 5am on monday"],
  "groupName": null
}
`RENOVATE_LOCK_FILE_MAINTENANCE`
`lazyGrouping` Use group names only when multiple dependencies upgraded boolean
true
`RENOVATE_LAZY_GROUPING` `--lazy-grouping`
`groupName` Human understandable name for the dependency group string
null
`RENOVATE_GROUP_NAME` `--group-name`
`groupSlug` Slug to use for group (e.g. in branch name). Will be calculated from groupName if null string
null
`group` Config if groupName is enabled json
{
  "recreateClosed": true,
  "branchName": "{{branchPrefix}}{{groupSlug}}",
  "commitMessage": "Renovate {{groupName}} packages",
  "prTitle": "Renovate {{groupName}} packages",
  "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request renovates the package group \"{{groupName}}\".\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#each upgrades as |upgrade|}}\n-   {{#if repositoryUrl}}[{{upgrade.depName}}]({{upgrade.repositoryUrl}}){{else}}`{{depName}}`{{/if}}: from `{{upgrade.currentVersion}}` to `{{upgrade.newVersion}}`\n{{/each}}\n\n{{#unless isPin}}\n### Commits\n\n{{#each upgrades as |upgrade|}}\n{{#if upgrade.releases.length}}\n
\n{{upgrade.githubName}}\n{{#each upgrade.releases as |release|}}\n\n#### {{release.version}}\n{{#each release.commits as |commit|}}\n- [`{{commit.shortSha}}`]({{commit.url}}){{commit.message}}\n{{/each}}\n{{/each}}\n\n
\n{{/if}}\n{{/each}}\n{{/unless}}\n
\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n- `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n- `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com)." }
`labels` Labels to add to Pull Request list
[]
`RENOVATE_LABELS` `--labels`
`assignees` Assignees for Pull Request list
[]
`RENOVATE_ASSIGNEES` `--assignees`
`reviewers` Requested reviewers for Pull Requests (GitHub only) list
[]
`RENOVATE_REVIEWERS` `--reviewers`
`npm` Configuration object for npm package.json renovation json
{"enabled": true}
`RENOVATE_NPM` `--npm`
`meteor` Configuration object for meteor package.js renovation json
{"enabled": true}
`RENOVATE_METEOR` `--meteor`
`docker` Configuration object for Dockerfile renovation json
{
  "enabled": true,
  "branchName": "{{branchPrefix}}docker-{{depNameSanitized}}-{{newVersionMajor}}.x",
  "commitMessage": "Update {{depName}} to tag {{newTag}}",
  "prTitle": "Update Dockerfile {{depName}} image tag to {{newTag}}",
  "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request updates Docker base image `{{depName}}` from tag `{{currentTag}}` to new tag `{{newTag}}`.\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n-   `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n-   `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com).",
  "major": {"enabled": false},
  "minor": {"enabled": false},
  "patch": {"enabled": false},
  "digest": {
    "branchName": "{{branchPrefix}}docker-{{depNameSanitized}}-{{currentTag}}",
    "commitMessage": "Update {{depName}}:{{currentTag}} digest",
    "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request updates Docker base image `{{depName}}@{{currentTag}}` to the latest digest (`{{newDigest}}`).\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n-   `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n-   `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com).",
    "prTitle": "Update Dockerfile {{depName}} image {{currentTag}} digest ({{newDigestShort}})"
  },
  "pin": {
    "branchName": "{{branchPrefix}}docker-pin-{{depNameSanitized}}-{{currentTag}}",
    "prTitle": "Pin Dockerfile {{depName}}@{{currentTag}} image digest",
    "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request pins Docker base image `{{depName}}@{{currentTag}}` to use a digest (`{{newDigest}}`).\nThis digest will then be kept updated via Pull Requests whenever the image is updated on the Docker registry.\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n-   `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n-   `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com).",
    "groupName": "Pin Docker Digests",
    "group": {
      "prTitle": "Pin Docker digests",
      "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request pins Dockerfiles to use image digests.\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#each upgrades as |upgrade|}}\n-   {{#if repositoryUrl}}[{{upgrade.depName}}]({{upgrade.repositoryUrl}}){{else}}`{{depName}}`{{/if}}: `{{upgrade.newDigest}}`\n{{/each}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n-   `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n-   `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com)."
    }
  },
  "group": {
    "prTitle": "Update Docker {{groupName}} digests",
    "prBody": "This {{#if isGitHub}}Pull{{else}}Merge{{/if}} Request updates Dockerfiles to use image digests.\n\n{{#if schedule}}\n**Note**: This PR was created on a configured schedule (\"{{schedule}}\"{{#if timezone}} in timezone `{{timezone}}`{{/if}}) and will not receive updates outside those times.\n{{/if}}\n\n{{#each upgrades as |upgrade|}}\n-   {{#if repositoryUrl}}[{{upgrade.depName}}]({{upgrade.repositoryUrl}}){{else}}`{{depName}}`{{/if}}: `{{upgrade.newDigest}}`\n{{/each}}\n\n{{#if hasErrors}}\n\n---\n\n### Errors\n\nRenovate encountered some errors when processing your repository, so you are being notified here even if they do not directly apply to this PR.\n\n{{#each errors as |error|}}\n-   `{{error.depName}}`: {{error.message}}\n{{/each}}\n{{/if}}\n\n{{#if hasWarnings}}\n\n---\n\n### Warnings\n\nPlease make sure the following warnings are safe to ignore:\n\n{{#each warnings as |warning|}}\n-   `{{warning.depName}}`: {{warning.message}}\n{{/each}}\n{{/if}}\n\n---\n\nThis {{#if isGitHub}}PR{{else}}MR{{/if}} has been generated by [Renovate Bot](https://renovateapp.com)."
  }
}
`RENOVATE_DOCKER`