# Renovate > Automated dependency updates. Configuration, usage, and development docs from the Renovate project. ## [Renovate](https://docharvest.github.io/docs/renovate/) Contents renovate Renovate Renovate Automated dependency updates. Configuration, usage, and development docs from the Renovate project. Automated dependency updates. Configuration, usage, and development docs from the Renovate project. - [Developmentdevelopment](/docs/renovate/development/) - [Usageusage](/docs/renovate/usage/) - [Adding A Package Managerdevelopment/adding-a-package-manager](/docs/renovate/development/adding-a-package-manager/) - [Best Practicesdevelopment/best-practices](/docs/renovate/development/best-practices/) - [Branches Commitsdevelopment/branches-commits](/docs/renovate/development/branches-commits/) - [Bug Handlingdevelopment/bug-handling](/docs/renovate/development/bug-handling/) - [Bump Node Majordevelopment/bump-node-major](/docs/renovate/development/bump-node-major/) - [Configurationdevelopment/configuration](/docs/renovate/development/configuration/) - [Creating Editing Renovate Presetsdevelopment/creating-editing-renovate-presets](/docs/renovate/development/creating-editing-renovate-presets/) - [Design Decisionsdevelopment/design-decisions](/docs/renovate/development/design-decisions/) - [Docs Sitedevelopment/docs-site](/docs/renovate/development/docs-site/) - [Help Us Help Youdevelopment/help-us-help-you](/docs/renovate/development/help-us-help-you/) - [Issue Labelingdevelopment/issue-labeling](/docs/renovate/development/issue-labeling/) - [Local Developmentdevelopment/local-development](/docs/renovate/development/local-development/) - [Major Releasedevelopment/major-release](/docs/renovate/development/major-release/) - [Minimal Reproductionsdevelopment/minimal-reproductions](/docs/renovate/development/minimal-reproductions/) - [New Package Manager Templatedevelopment/new-package-manager-template](/docs/renovate/development/new-package-manager-template/) - [Remote Developmentdevelopment/remote-development](/docs/renovate/development/remote-development/) - [Static Datadevelopment/static-data](/docs/renovate/development/static-data/) - [Style Guidedevelopment/style-guide](/docs/renovate/development/style-guide/) - [Triage Guidedevelopment/triage-guide](/docs/renovate/development/triage-guide/) - [Zoddevelopment/zod](/docs/renovate/development/zod/) - [About Ususage/about-us](/docs/renovate/usage/about-us/) - [Bazelusage/bazel](/docs/renovate/usage/bazel/) - [Bicepusage/bicep](/docs/renovate/usage/bicep/) - [Bot Comparisonusage/bot-comparison](/docs/renovate/usage/bot-comparison/) - [Community Toolsusage/community-tools](/docs/renovate/usage/community-tools/) - [Config Migrationusage/config-migration](/docs/renovate/usage/config-migration/) - [Config Overviewusage/config-overview](/docs/renovate/usage/config-overview/) - [Shareable Config Presetsusage/config-presets](/docs/renovate/usage/config-presets/) - [Config Validationusage/config-validation](/docs/renovate/usage/config-validation/) - [Configuration Optionsusage/configuration-options](/docs/renovate/usage/configuration-options/) - [Config Template Editingusage/configuration-templates](/docs/renovate/usage/configuration-templates/) - [Contributing To Renovateusage/contributing-to-renovate](/docs/renovate/usage/contributing-to-renovate/) - [Should you Pin your JavaScript Dependencies?usage/dependency-pinning](/docs/renovate/usage/dependency-pinning/) - [Dockerusage/docker](/docs/renovate/usage/docker/) - [Docker Build Processusage/docker-build-process](/docs/renovate/usage/docker-build-process/) - [Environment Variable Handlingusage/environment-variable-handling](/docs/renovate/usage/environment-variable-handling/) - [Frequently Asked Questions (FAQ)usage/faq](/docs/renovate/usage/faq/) - [GitLab bot securityusage/gitlab-bot-security](/docs/renovate/usage/gitlab-bot-security/) …and 55 more in the sidebar. [llms.txt](/docs/renovate/llms.txt) for agents ## [Renovate Developer Docs](https://docharvest.github.io/docs/renovate/development/) Contents renovate Development Renovate Development > \[!NOTE\] If you’re an end-user of Renovate, please read the [Renovate documentation](https://docs.renovatebot.com). The `docs/development` directory is for developers and contributors. The Markdown files explain how to work on Renovate’s code. If you need to get Renovate running locally, to contribute, or for some other reason, please read our [contributing guidelines](../../.github/contributing.md) to learn how. ## [Adding a Package Manager](https://docharvest.github.io/docs/renovate/development/adding-a-package-manager/) Contents renovate Adding A Package Manager Renovate Adding A Package Manager This document explains how to add a new package manager. ## Code structure Code for package managers goes in the `lib/modules/manager/*` directory. The package manager code is often tightly coupled to the datasource code in `lib/modules/datasource/*`. Versioning logic like Semver or PEP 440 goes in `lib/modules/versioning/*`. Common application logic for Renovate, not specific to particular managers, usually lives under `lib/workers/*`. ## Manager requirements The manager’s `index.ts` file supports the following values or functions: Value/function Optional Async `bumpPackageVersion` yes `extractPackageFile` yes `extractAllPackageFiles` yes yes `getRangeStrategy` yes `categories` yes `knownDepTypes` yes `supportsDynamicDepTypesNote` yes `supportsLockFileMaintenance` yes `updateArtifacts` yes yes `updateDependency` yes `updateLockedDependency` yes ### `bumpPackageVersion` (optional) Use this function to allow version bumps of updated packages. For example: - to increase the version of a Maven module if a package has been updated - to bump the Helm chart version, if a subchart version has been updated ### `extractPackageFile(content, packageFile, config)` (async, semi-mandatory) This function is mandatory, unless you use `extractAllPackageFiles` instead. It takes as arguments the file’s content and optionally the file’s full file pathname and config. The function returns an array of detected or extracted dependencies, including the: - dependency name - dependency type (dependencies, devDependencies, etc) - currentValue - versioning used (like SemVer, PEP 440) - a list of lock files ( `lockFiles` ) that are associated with this package file, if applicable The `extractPackageFile` function doesn’t need to fully _understand_ the file or syntax that it gets. It needs to understand enough to extract a correct list of dependencies. In general, we extract _all_ dependencies from each dependency file, even if they have values we don’t support. If the function reads parts of a dependency file that it can’t parse, it should give a `skipReason` message to the `extractPackageFile` function. Make sure the `skipReason` message is helpful to someone reading the logs. If `extractPackageFile` is passed a file which is a “false match”, so not a package file, or a file with no dependencies then it can return `null`. Downstream this results in the file being ignored and removed from the list of package files. ### `extractAllPackageFiles(packageFiles)` (async, optional) Normally a package manager parses or extracts all package files in _parallel_, and can thus use the `extractPackageFile` function. If the package manager you’re adding works in _serial_, use this function instead. For example the npm and Yarn package manager must process the `package.json` and `package-lock` or `yarn.lock` files together. This allows features like Workspaces to work. This means that for npm or Yarn we need to iterate through all package files after the initial parsing. As another example, in order for Gradle to extract dependencies Renovate must first call a command via a child process. The `extractAllPackageFiles` function takes an array of filenames as input. It returns an array of filenames and dependencies. If you implement `extractAllPackageFiles` the manager must export as well either `updateDependency` or `extractPackageFile`. ### `getRangeStrategy(config)` (optional) Write this optional function if you want the manager to support “auto” range strategies. For example, pinning or _not_ pinning a dependency, depending on other values in the package file. The `npm` manager uses the `getRangeStrategy` function to pin `devDependencies` but not `dependencies`, unless the package file is detected as an app. If left undefined, then a default `getRangeStrategy` will be used that always returns “replace”. ### `knownDepTypes` (optional) Use this to document any dependency types (`depType`) that the manager can extract. Only set the `prettyDepType` if the Manager sets it on the `Upgrade`. Use `description` to provide a human-readable description which will be found in the documentation for the Manager. This should be placed in `dep-types.ts`. ### `supportsDynamicDepTypesNote` (optional) Use this to provide a Markdown note about dynamically generated `depType` values that can’t be listed in `knownDepTypes`. This note will be rendered after the `knownDepTypes` table (regardless of whether any known `depTypes` are present). This should be placed in `dep-types.ts`. ### `supportsLockFileMaintenance` (optional) Set to `true` if this package manager needs to update lock files in addition to package files. ### `updateArtifacts` (async, optional) Use `updateArtifacts` to run binaries that in turn will update files. We often use `updateArtifacts` to update lock files indirectly. To _directly_ update dependencies in lock files: use `updateLockedDependency` instead. `updateArtifacts` gets triggered: - after a dependency update (for a package file), or - during `lockfileMaintenance` ### `updateDependency` (optional) Use `updateDependency` if _both_ conditions apply: - the manager can’t be updated to use the standard replacing mechanism - a custom replacement has to be provided ### `updateLockedDependency` (optional) Use `updateLockedDependency` to directly update dependencies in lock files. ## Package files and Lock files A special Renovate term is “package files”. Package files have human-readable dependency definitions, for example: - npm’s `package.json` file - Maven’s `pom.xml` file - Docker’s `Dockerfile` Some package managers may also have “lock files”, like npm’s `package-lock.json`. If a repository has a lock file, then Renovate _must_ update the package file _and_ the matching lock file in the same commit. This prevents creating “broken” updates for users and generating frustration with Renovate. ### Focus on getting lock file syncing working When you develop a new package manager, which supports lockfiles, focus on getting lock file synchronization working. Supporting lock file synchronization usually means that Renovate runs a third-party tool, like `npm` or `poetry`. The third-party tool then updates the lock file for Renovate. ### Avoid reverse engineering lock file formats Let a third-party package manager (`npm`, `poetry`, etc.) update the lockfile. Avoid “reverse engineering” lock file formats, where Renovate manually updates the lock file. Only “reverse engineer” lock file formats as a last resort. ### Add third-party tools to Containerbase first Add third-party package manager tools to [Containerbase](https://github.com/containerbase/base) first. Here are the various ways in approximate order in which lock file awareness should be added to a manager: ### Lock file maintenance The goal of lock file maintenance is to update all locked dependencies (including transitive dependencies) to the latest possible version, without changing ranges defined in package files. There are two ways to update lock files: - Call a command like ` update` to update all locked dependencies (plus transitive dependencies), updating the whole lock file where possible - Delete the lock file, then call a command like ` install` to create a new lockfile If you can, use the ` update` method, as that keeps platform-specific information. #### Keep platform-specific information Lock files may have platform-specific information (e.g. `amd64`, `arm64`). If you delete the lock file, and then create a new lock file with ` install`, the platform-specific information is lost. If you can, use the ` update` method instead! ### Lock file updating after a package file change Updating lock files after a package file changes is a fundamental feature. This means you often need to build it first, when adding new package manager to Renovate. Add a `updateArtifacts()` function, that “syncs” the lock file to the package file changes made by Renovate. This way, both files can be updated in the same commit. Usually, the flow is like this: 1. Renovate directly changes the version or constraint in the package file, 2. Renovate calls a tool command like ` install`, ` lock`, etc. 3. If the tool command changes the lock file (which it usually should!), then Renovate commits the changed lock file and the package file ### Locked version extracting and dependency pinning The next step is for the manager’s “extract” feature to return a `lockedVersion` for dependencies, whenever a lock file exists. To do this, the manager needs to: 1. Parse the lock file 2. Match each dependency from the package file to its entry in the lock file 3. Add the matched version as `lockedVersion` Once `lockedVersion` is provided, Renovate should be able to “pin” constraints/ranges into exact versions, if the user configures as such (e.g. `rangeStrategy=pin`), however Renovate _won’t_ automatically be able to make lockfile-only updates. ### Lock file-only updates #### updateArtifacts() End users often want, or need to: - preserve constraints in their package file (like `^1.0.0`) - and want Renovate to update their lock file when a new versions is available (e.g. updating from a locked value of `1.1.0` to `1.1.1`) In this case, the Renovate package manager must extract the `lockedVersion` as described above! #### Detect if updates satisfy `isLockFileUpdate=true` In addition to this, the manager needs to add logic to `updateArtifacts()` to detect if _any_ of the updates it has been passed satisfy `isLockFileUpdate=true`. If any lock file-only updates have been passed, then the manager typically needs to run specific commands to update/bump the locked version for one specific dependency only. This functionality is manager-specific, and depends heavily on the capabilities of the third-party tool. A mix of the following approaches are used in Renovate, from best to worst: - Renovate calls a tool command to specifically update the dependency in question to the specific version, e.g. ` update @` - Renovate manually updates the locked version in the lock file it needs updated, then calls a ` install` command to “fix” up the remaining parts (hashes, transitive dependencies, etc). This is good, if it works, but it is prone to breaking in future releases if the maintainers of the tool do not know people are using their package manager in this manner, even if it works unintentionally. - Renovate calls a tool command similar to the first approach, except the tool does not support specific versions, e.g. ` update `. This approach can be problematic because Renovate might _want_ to update to e.g. `v1.1.1` but instead the tool finds a newer `v1.1.2` and that’s what the user gets instead ##### Difficult cases A further complication is that sometimes: - dependencies must be upgraded together - there are peer dependency problems - or there is some other conflict In those cases it’s best if the tool supports creating a list of dependencies to update, and the tool then updates all dependencies at once. #### updateLockedDependency() The `updateLockedDependency()` method is optional for managers. But we recommend that any manager which supports `rangeStrategy=update-lockfile` also implements the `updateLockedDependency()` method. The goal of the `updateLockedDependency()` method is to return quickly if a dependency is already updated. This way, Renovate only runs tool commands when there is a dependency to update. The simplest logic for `updateLockedDependency()` is: 1. Parse the existing lock file 2. If the locked version of the dependency is already updated to the version specified: return `{ status: 'already-updated' }` 3. Else: return `{ status: 'unsupported' }` An example of this can be seen in [the `composer` manager source code for `updateLockedDependency()`](https://github.com/renovatebot/renovate/blob/da4964ac05952f9fe0543ba1174fcd62ad083d48/lib/modules/manager/composer/update-locked.ts#L7-L30). ## [Renovate Flow](https://docharvest.github.io/docs/renovate/development/assets/renovate-flow/) Contents renovate Renovate Flow Renovate ``` flowchart TB subgraph Start A[lib/renovate.ts] --> B[getConfig ordered by priority useBaseBranchConfig > Cli > ENV > file > default] A --> C[global initialize] A --> D[init platform] A --> E[set and ensure dir] A --> F[init cache limit commits] A --> G[init host rules] A --> H[validations] A --> I[auto discover repositories] end subgraph Repository J[workers/repository/index.ts, for each repository] J --> K[initRepo] J --> L[extractDependencies] J --> M[ensureOnboardingPr] J --> N[updateRepository] J --> O[finalize repository] end subgraph initializeRepository X[initRepo] X--> P[InitializeConfig] X--> Q[InitializeCaches] X--> R[initApis] X--> S[getRepoConfig] X--> T[checkIfConfigured] X--> U[applySecretsToConfig] X--> V[setUserRepoConfig] X--> W[detectVulnerabilityAlerts] end subgraph extractDependencies Z[repository/process/index.ts] Z --> AA[read dashboard body, put it into config] Z --> QM{if config.basebranches exists} QM --> |yes| AB[for each config.basebranches] AB --> AC[getBaseBranch and extract all dependencies from managers] AB --> AD[getBaseBranch and lookup new dependency versions] QM --> |no| AE[extract and lookup] end subgraph updateRepository BA[repository/process/write.ts] BA--> BB[for each update branch] BB --> BC[process branch] BC --> BD[do all validation] BC --> BF[schedules] BC --> BG[updates] BC --> BH[ensurePR] end Start ---> Repository K ---> initializeRepository L ----> extractDependencies N -----> updateRepository ``` ## [Best practices](https://docharvest.github.io/docs/renovate/development/best-practices/) Contents renovate Best Practices Renovate Best Practices This document explains our best practices. Follow these best practices when you’re working on our code. ## Git branch names Branch names should start with a [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) scope like `feat/` or `fix/`. If you’re closing an issue with your PR then put the issue number after the scope. Finally, describe the changes in the branch in a few words. Some good branch names: - `feat/13732-cacache-cleanup` - `fix/15431-gitea-automerge-strategy` - `refactor/vitest-reset-mocks` - `docs/rewrite-packageRules-section` Avoid branch names like `patch-1`. If you don’t know the correct Conventional Commit scope: give your branch a descriptive name like `issue-1-feature-foo`. If you forgot to pick a good branch name when you started work, then rename the branch before creating the pull request. Read the [GitHub Docs, renaming a branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/renaming-a-branch) to learn how to rename your branch on GitHub. ## General - Prefer full function declarations for readability and better stack traces, so avoid `const func = ():void => {}` - Prefer `interface` over `type` for TypeScript type declarations - Avoid [Enums](https://github.com/renovatebot/renovate/issues/13743), use unions or [immutable objects](https://github.com/renovatebot/renovate/blob/5043379847818ac1fa71ff69c098451975e95710/lib/modules/versioning/pep440/range.ts#L8-L20) instead - Always add unit tests for full code coverage - Only use [`v8` comments](https://github.com/AriPerkkio/ast-v8-to-istanbul?tab=readme-ov-file#ignore-hints) for unreachable code coverage that is needed for `codecov` completion - Use descriptive `v8` comments - Avoid cast or prefer `x as T` instead of `x` cast - Prefer `satisfies` operator over `as`, read the [TypeScript release notes for `satisfies` operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator) to learn more - Avoid `Boolean` instead use `is` functions from `@sindresorhus/is` package, for example: `is.string` ``` /* v8 ignore next -- can never happen */ ``` ### Functions - Use `function foo(){...}` to declare named functions - Use function declaration instead of assigning function expression into local variables (`const f = function(){...}`) (TypeScript already prevents rebinding functions) - Exception: if the function accesses the outer scope’s `this` then use arrow functions assigned to variables instead of function declarations - Regular functions _should not_ access `this`, but arrow functions and methods may access `this` - Only use nested functions when the [lexical scope](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures) is used #### Use arrow functions in expressions Avoid: ``` bar(function(){...}) ``` Use: ``` bar(() => { this.doSomething(); }); ``` Generally the `this` pointer _should not_ be rebound. Only use function expressions if you need to dynamically rebind `this`. Source: [Google TypeScript Style Guide, function declarations](https://google.github.io/styleguide/tsguide.html#function-declarations). ## Code style ### Write understandable code Write code that is easier to read, review and maintain. Avoid “clever” code that’s hard to understand. Prefer verbose code which is easier for others to read and maintain than concise code which may be hard or slower for others to understand. For example, Array `reduce()` functions are often hard to understand first time, and can be replaced with simpler `for` loops. A `for` loop is just as fast but is simpler to understand and maintain. #### Write single purpose functions Single purpose functions are easier to understand, test and debug. ``` function caller() { // ..code.. calculateUpdateAndPrint(data) // ..code.. } function calculateUpdateAndPrint(...) { /* code */ } ``` Simplified code: ``` function caller() { // code.. const res = calculate(data); update(res); print(res); // code.. } function calculate(...) { /* code */ } function update(...) { /* code */ } function print(...) { /* code */ } ``` #### Keep indentation level low Fail quickly. Nested code logic is hard to read and prone to logic mistakes. ``` function foo(str: string): boolean { let result = false; if (condition(str)) { const x = extractData(str); if (x) { // do something result = true; } } return result; } ``` Simplified code: ``` function foo(str: string): boolean { if (!condition(str)) { return false; } const x = extractData(str); if (!x) { return false; } // do something return true; } ``` ### Refactor one thing at a time Refactor the code _or_ refactor the tests. Avoid refactoring the code and tests at the same time, this can mask regression errors. ## Logging For `WARN`, `ERROR` and `FATAL` log messages use logger metadata. Also use logger metadata the result is a complex metadata object needing a multiple-line pretty stringification. For `INFO` and `DEBUG` log messages inline the metadata into the log message where feasible. It is OK to not inline metadata if it’s complex, but in that case first think whether that much information really needs to be logged. `WARN`, `ERROR` and `FATAL` messages are often used in metrics or error catching services. These log messages should have a static `msg` component, so they can be automatically grouped or associated. Good: ``` logger.debug({ config }, 'Full config'); logger.debug(`Generated branchName: ${branchName}`); logger.warn({ presetName }, 'Failed to look up preset'); ``` Avoid: ``` logger.debug({ branchName }, 'Generated branchName'); logger.warn(`Failed to look up preset ${presetName}`); ``` ## Array constructor Avoid the `Array()` constructor, with or without `new`, in your TypeScript code. It has confusing and contradictory usage. So you should avoid: ``` const a = new Array(2); // [undefined, undefined] const b = new Array(2, 3); // [2, 3]; ``` Instead, always use bracket notation to initialize arrays, or `from` to initialize an Array with a certain size. For example: ``` // [0, 0, 0, 0, 0] Array.from({ length: 5 }).fill(0); ``` [Source](https://google.github.io/styleguide/tsguide.html#array-constructor) ## Iterating objects & containers Use `for ( ... of ...)` loops instead of `[Array|Set|Map].prototype.forEach` and `for ( ... in ...)`. - Using `for ( ... in ...)` for objects is error-prone. It will include enumerable properties from the prototype chain - Using `for ( ... in ...)` to iterate over arrays, will counterintuitively return the array’s indices - Avoid `[Array|Set|Map].prototype.forEach`. It makes code harder to debug and defeats some useful compiler checks like reachability Only use `Array.prototype.map()` when the return value is used, otherwise use `for ( ... of ...)`. Source: [Google TypeScript Style Guide, iterating objects](https://google.github.io/styleguide/tsguide.html#iterating-objects) ## Exports Use named exports in all code. Avoid default `exports`. This way all `imports` follow the same pattern. Source: [Google TypeScript Style Guide, exports](https://google.github.io/styleguide/tsguide.html#exports) ## Imports Use [ES6 module](https://exploringjs.com/es6/ch_modules.html#sec_basics-of-es6-modules) syntax. For example: ``` import { square, diag } from 'lib'; // You may also use: import * as lib from 'lib'; ``` And avoid `require`: ``` import x = require('...'); ``` ## HTTP & RESTful API request handling Prefer using `Http` from `util/http` to simplify HTTP request handling and to enable authentication and caching, as our `Http` class will transparently handle host rules. For example: ``` import { Http } from '../../../util/http'; const http = new Http('some-host-type'); try { const body = (await http.getJson(url)).body; } catch (err) { ... } ``` ## Async functions Never use `Promise.resolve` in async functions. Never use `Promise.reject` in async functions, instead throw an `Error` class type. ## Dates and times Use the [`Luxon` package](https://www.npmjs.com/package/luxon) to handle dates and times. Use `UTC` to be time zone independent. [Example from our code](https://github.com/renovatebot/renovate/blob/5043379847818ac1fa71ff69c098451975e95710/lib/modules/versioning/distro.ts#L133-L134) : ``` if (end) { const now = DateTime.now().toUTC(); const eol = DateTime.fromISO(end, { zone: 'utc' }); return eol < now; } ``` ## Unit testing - Separate the _Arrange_, _Act_ and _Assert_ phases with newlines - Use `it.each` rather than `test.each` - Prefer [Tagged Template Literal](https://vitest.dev/api/#test-each) style for `it.each`, Prettier will help with formatting - See [Example](https://github.com/renovatebot/renovate/blob/768e178419437a98f5ce4996bafd23f169e530b4/lib/modules/platform/util.spec.ts#L8-L18) - Mock Date/Time when testing a Date/Time dependent module - For `Luxon` mocking see [Example](https://github.com/renovatebot/renovate/blob/5043379847818ac1fa71ff69c098451975e95710/lib/modules/versioning/distro.spec.ts#L7-L10) - Prefer `vi.spyOn` for mocking single functions, or mock entire modules - Avoid overwriting functions, for example: (`func = vi.fn();`) - Use plain `vi.mock('./module.ts', ()=>({ defaut: vi.fn(), some: vi.fn() }))` when only a few exports are touched, and stub them explicitly - Use `vi.mock('./module.ts', () => mockDeep())` only when the module is pulled in transitively and hand-stubbing every export is impractical - `mockDeep` returns a mock for any property access, so typos in mocked names won’t fail the test - Prefer `toEqual` - Use `toMatchObject` for huge objects when only parts need to be tested - Avoid `toMatchSnapshot`, only use it for: - huge strings like the Renovate PR body text - huge complex objects where you only need to test parts - Avoid exporting functions purely for the purpose of testing unless you really need to - Avoid cast or prefer `x as T` instead of `x` cast - Use `partial()` from `test/util` if only a partial object is required - Use `fakeSha(seed)` from `test/util` to generate deterministic, valid `LongCommitSha` values in tests ## Fixtures Where possible, reduce the test fixture to a size where an inline `codeBlock` is possible to use instead of a separate fixture file. Inline `codeBlock`s improve performance plus are more readable. ``` import { codeBlock } from 'common-tags'; const input = codeBlock` line one line two `; // → 'line one\nline two' ``` Use the `Fixture` class if loading fixtures from files. For example: ``` Fixture.get('./file.json'); // for loading string data Fixture.getJson('./file.json'); // for loading and parsing objects Fixture.getBinary('./file.json'); // for retrieving a buffer ``` ## Working with vanilla JS files (renovate/tools only) Declare types and function prototypes with [JSDoc](https://jsdoc.app/index.html). [Example](https://github.com/renovatebot/renovate/blob/5043379847818ac1fa71ff69c098451975e95710/tools/distro-json-generate.mjs#L7-L17) ## Classes - Use [Typescript getter setters (Accessors) when needed](https://google.github.io/styleguide/tsguide.html#properties-used-outside-of-class-lexical-scope). The getter must be a `pure function` i.e. - The function return values are identical for identical arguments - The function has no side effects [Source](https://en.wikipedia.org/wiki/Pure_function) - Omit constructors when defining Static classes - [No `#private` fields](https://google.github.io/styleguide/tsguide.html#private-fields), use TypeScript’s visibility annotations instead - Avoid underscore suffixes or prefixes like `_prop`, instead use [whole words](https://google.github.io/styleguide/tsguide.html#properties-used-outside-of-class-lexical-scope) as the suffix or prefix like `internalProp` ## regex Use [Named Capturing Groups](https://www.regular-expressions.info/named.html) when capturing groups. Prefer named groups even for a single capture — positional references (`match[1]`) break silently when the pattern changes. Non-capturing groups (`(?:...)`) are always fine and encouraged when the captured value is not needed. Always use the `regEx()` utility from `lib/util/regex.ts` instead of the `RegExp` constructor or regex literals. It transparently uses the RE2 engine when available for safer, denial-of-service-resistant matching. ``` import { regEx } from '~/lib/util/regex'; const pattern = regEx(/^(?\d+)\.(?\d+)(?:\.(?\d+))?$/); const match = pattern.exec(version); if (match?.groups) { const { major, minor, patch } = match.groups; } ``` ## Windows We recommend you set [`core.autocrlf = input`](https://git-scm.com/docs/gitattributes#_text) in your Git config. You can do this by running this Git command: ``` git config --global core.autocrlf input ``` This prevents the carriage return `\r\n` which may confuse Renovate. You can also set the line endings in your repository by adding `* text=auto eol=lf` to your `.gitattributes` file. ## [Branches and commits behavior](https://docharvest.github.io/docs/renovate/development/branches-commits/) Contents renovate Branches Commits Renovate Branches Commits ## Multiple files per branch Renovate can, and should, update multiple files in the same branch/PR. For example: - update the `package.json` and the `yarn.lock` file - update multiple package files in a monorepo, including different package managers ## One commit per branch Renovate always creates one commit per branch, even when updating multiple files. This keeps Renovate’s branches neat, so we can use the following logic: Last commit in branch made by Behavior Renovate Assume branch is clean Someone or something else Assume branch edited by user, do not push to branch anymore ### Updating branches We always want a single commit in Renovate’s branches. This means we let Renovate force-push a single new commit whenever it needs to. For example: 1. Renovate creates a `renovate/jest` branch to update the Jest package to `1.0.1` 2. Renovate later finds a newer `1.1.0` version 3. Renovate force-pushes a new commit for the `1.1.0` update into its `renovate/jest` branch ## [Bug report handling](https://docharvest.github.io/docs/renovate/development/bug-handling/) Contents renovate Bug Handling Renovate Bug Handling ## Start with a Discussion We use GitHub Discussions as a triaging stage for bug reports. Users should [create a new Request Help discussion](https://github.com/renovatebot/renovate/discussions/new?category=request-help) and choose from the options there. We often need more information to resolve your bug report. Maintainers may ask for such information directly, or use automated label comments, or both. Maintainers may close bug reports that lack the extra information, for example when keeping the Discussion open does not help other users anymore. We only create issues in this repository when we: - consider them to be actionable - are in a state where someone could work on it We often need a minimal reproduction or logs, or even _both_, to pinpoint the exact problem. Because we need enough information for a actionable bug report, we may close Discussions that lack the needed info, even if it’s highly likely the behavior is buggy. We have found that keeping Issues around that are not actionable just leads to them getting stale, and then closed. The Issues list is meant as a list of actionable things for a contributor or maintainer to pick up eventually. ## Discussion Resolution Bug reports are resolved in one of three ways: 1. Confirmed as a bug. The Discussion will be converted to an Issue, and then closed. Any future comments go to the Issue and _not_ the Discussion. 2. Closed as “behaving as designed” with no further action. The Discussion will be closed with a relevant note. 3. Rejected as not a _bug_, but accepted as a _feature request_. The Discussion will be closed with a note suggesting that the poster create a new “Suggest an Idea” Discussion instead, which can then be converted to an Issue once actionable. ## FAQ ### What’s your definition of bug? Bugs are behavior in Renovate which is _not_ as intended or documented. Missing functionality or partial support is not automatically a bug. For example, we’re probably missing at least one feature from each package manager that Renovate supports. If we labeled all those missing features as bugs, we lose sight of real bugs. ### Why can’t I create Bug Issues directly? It is really hard for users to decide if something is a bug. Only a fraction of the incoming bug reports are for things we consider proper bugs. A while ago, users were allowed to create Bug Issues. We ended up with many “bug, but not really” type issues, that polluted the repository. Those issues made it tricky for maintainers and users to see what’s really going on in the repository. We have since closed many old user-created bug Issues, and now only allow maintainers to create bug Issues. This way we do not end up in the same situation again. ### What if I disagree with your definition of bug? We are not interested in debating you, we prefer to spend our time helping users solve their problems. We are open to improve our approach to bugs, or this document, in good spirit. Please do _not_ post comments like these: - “How dare you block users from creating Issues?!” - “If the behavior was unexpected to me then that means it’s a bug.” Users who want to make our life difficult as maintainers will be blocked. Read our [Code of Conduct](https://github.com/renovatebot/renovate/blob/main/CODE_OF_CONDUCT.md) to learn more. ### Why do you close Bug discussions? It’s important to move relevant reports to the next step of an Issue, and focus our attention there. Bug reports that are not (going to be) an Issue, are marked as “not a bug”. This helps future users who browse or search the repository for similar terms, as they will not see any invalid Bug reports. If you are not sure if you have an _actual_ bug to report, please use the “Request Help” Discussion category. ### When will you fix my bug? There are no Service Level Agreements (SLAs) in Open Source. This means we are not required to respond to, or fix your problem within a certain time. If you are a paying Mend.io customer, please tell your support or customer contact that this bug is important to you. Please read our [Code of Conduct, how we prioritize work](https://github.com/renovatebot/renovate/blob/main/CODE_OF_CONDUCT.md#how-we-prioritize-work) to learn more. ## [How to bump Renovate to next NodeJS LTS release](https://docharvest.github.io/docs/renovate/development/bump-node-major/) Contents renovate Bump Node Major Renovate Bump Node Major ## When will Renovate update its support for LTS versions? - We will add a new LTS version as a supported version (in a minor release of Renovate) roughly ~1-2 weeks before the upcoming LTS becomes an official LTS - We will remove an LTS as a supported version (in a major release of Renovate): - when the LTS is no longer supported upstream by the Node.JS project - when we need new features that are only available in a newer LTS - when the maintenance burden of supporting multiple Node.JS versions is too high ## Add new NodeJS version - Add new version via `package.json>engines>node` - Update the node version in the [local-development](./local-development.md) docs - Update the node version in the GitHub Actions workflow files ## Remove old NodeJS version - Update `package.json>engines>node` - Mark PR as `BREAKING` by: - Adding the label `breaking` to the PR - Putting the text `feat!: require node v...` in the PR title ## [Configuration](https://docharvest.github.io/docs/renovate/development/configuration/) Contents renovate Configuration Renovate Configuration ## Configuration Methods Renovate global config can be defined via any of these methods: - Configuration file - Additional configuration file - Environment variables - CLI parameters The above are listed in **_reverse order_** of preference. e.g. CLI values will override environment values if they conflict. ### Default Configuration The default configuration values can be found in [lib/config/options/index.ts](../../lib/config/options/index.ts). Options which have `"globalOnly": true` are reserved only for bot global configuration and cannot be configured within repository config files. ### 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`. You can also add one more configuration file, with an additional config which overwrites the default config file. To use such a file, you need to set the env var `RENOVATE_ADDITIONAL_CONFIG_FILE` as this file does not have a default name. **Note:** `RENOVATE_CONFIG_FILE` and `RENOVATE_ADDITIONAL_CONFIG_FILE` must be provided with an explicit file extension. For example `RENOVATE_CONFIG_FILE=myconfig.js` or `RENOVATE_CONFIG_FILE=myconfig.json` and not `RENOVATE_CONFIG_FILE=myconfig`. If none is provided, or the file type is invalid, Renovate will fail. If you are in an ESM repo (`"type": "module"` in `package.json`) then you must use a `.cjs` extension and set `RENOVATE_CONFIG_FILE`. For example `RENOVATE_CONFIG_FILE=myconfig.cjs`. 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 of labels for `frontend/package.json` in the same repository. ``` module.exports = { npmrc: '//registry.npmjs.org/:_authToken=abc123', baseDir: '/tmp/renovate', forkProcessing: 'enabled', gradle: { enabled: false }, }; ``` ### CLI ``` node renovate --help ``` To configure any `` items, separate with commas. E.g. `renovate --labels=renovate,dependency`. To enable debug logging export `LOG_LEVEL=debug` to your environment. ### renovate.json If you add a `renovate.json` file to the root of your repository, you can use this to override default settings. ### package.json If you add configuration options to your `package.json` then these will override any other settings above. ``` { "renovate": { "labels": ["upgrade", "bot"] } } ``` ## Configuration Options Please read [our list of user-facing configuration options](https://docs.renovatebot.com/configuration-options/). For further options when running your own instance of Renovate, please see the full config options file at `lib/config/options/index.ts`. ## [Creating/editing Renovate presets](https://docharvest.github.io/docs/renovate/development/creating-editing-renovate-presets/) Contents renovate Creating Editing Renovate Presets Renovate Creating Editing Renovate Presets Renovate comes with default presets that you can find in the [`lib/config/presets/internal`](https://github.com/renovatebot/renovate/tree/main/lib/config/presets/internal) directory. You can suggest changes to the presets with a pull request. Follow the rules below to increase the chance that your pull request gets merged. ## General rules 1. Avoid creating presets for problems which can be fixed upstream 2. The internal preset should help a significant number of Renovate users ### Specific rules #### Group presets We have multiple kinds of `group:` presets, with different rules. ##### Rules for `group:monorepos` preset 1. Only group dependencies that _must_ be updated together ##### Rules for `group:recommended` presets 1. The `group:recommended` preset is for related dependencies which aren’t from a monorepo but which usually need to be updated together (as separate PRs may each break) ##### Rules for `group:*` presets 1. Finally, any other `group:*` presets can be added if they are beneficial to a wide number of users 2. They don’t need to be added to `group:recommended`, meaning that users will “opt in” to them one-by-one and _not_ get them automatically from `config:recommended`, which includes `group:monorepos` and `group:recommended` #### Rules for replacement presets 1. Replacement PRs should ideally propose a replacement only once the user is on a compatible version, by specifying a compatible `matchCurrentVersion` constraint 2. If no compatible replacement upgrade is possible, it’s acceptable to propose an incompatible one (e.g. a major version upgrade) 3. Replacements should update the user to the first recommended version of the new dependency and not include any new changes - whether breaking or not - if they can be avoided, in short: pin the new version If possible, replacement presets should give the user a replacement version that is _functionally identical_ to the _last version_ under the _old_ name. We only want a user’s tests to fail because of _broken references_ to the old package name, and not because the maintainer(s) changed the _behavior_ of the package. #### Rules for monorepo presets 1. The primary use case of monorepo presets is finding packages from the same origin source repository which should be updated together 2. Packages from the same repository which are developed and versioned independently do not need to be grouped as a monorepo, but in many cases we still do 3. Packages from separate repositories but which are released together and dependent on each other may also be added to the “monorepo” definitions even if not strictly true #### Rules for migrating presets 1. Removing a preset: Add the preset name to the `removedPresets` object in [`presets/common`](https://github.com/renovatebot/renovate/blob/main/lib/config/presets/common.ts#L1) and set its value to `null` 2. Renaming a preset: Add the old preset name to the `removedPresets` object in [`presets/common`](https://github.com/renovatebot/renovate/blob/main/lib/config/presets/common.ts#L1) and set its value to the new preset name 3. Renaming a monorepo preset: Add the old monorepo name to the `renamedMonorepos` object in [`presets/common`](https://github.com/renovatebot/renovate/blob/79f0888ebff8034ee80c905ceaca0811ddc1c8b8/lib/config/presets/common.ts#L50) and set its value to the new monorepo name ## [Design Decisions](https://docharvest.github.io/docs/renovate/development/design-decisions/) Contents renovate Design Decisions Renovate Design Decisions This file documents the design choices as well as configuration options. ## Intended use by end-users The Renovate repository/package is intended to be used as a CLI-based application. It should not be used downstream as a library, because it lacks a stable API. End users should only depend on the CLI or on the official hosted app. The Renovate npm package should only be used as a CLI tool. ## Stateless A key feature of Renovate is that it does not require any state storage (e.g. on disk or in a database). Instead, Renovate’s source of truth is the repository itself, e.g. branches, Issues and Pull Requests. Due to this design, it is possible to stop the script at any time without risking Renovate state being out of sync with repository state. ## Synchronous Operation The script processes repositories and branches within them synchronously. This has the following benefits: - Greatly reduces the chance of hitting simultaneous API rate limits - Simplifies logging ## Cascading Configuration We use a cascading configuration. This means that specific configuration options always override more general configuration options. From most specific to least specific: 1. Update type (e.g. `major`, `minor`, `patch`) 2. Package (e.g. `lodash`, `django`) 3. Manager (e.g. `npm`, `pypi`) 4. Repository config 5. Global configuration ## Automatic discovery of package file locations The default behavior is to auto-discover all package file (e.g. `package.json`) locations in a repository and process them all. Doing so means that “monorepos” are supported by default. This behavior can be overridden by the configuration option `includePaths`, where you list the file paths manually. You could limit Renovate to only update the `package.json` in the root of the repository and ignore `package.json` files in other directories. ## Separate Branches per dependency By default, `renovate` will maintain separate branches for each dependency. So if 20 dependencies need updating, there will be at least 20 branches/PRs. Although this may seem undesirable, it’s even less desirable if all 20 were in the same Pull Request and it’s very difficult to work out which upgrade caused the test failure. But you can override the default templates for branch name to get a single branch for all dependencies. The `groupName` configuration option can be used at a repository level (e.g. give it the value `All`) and then all dependency updates will be in the same branch/PR. ## Separate Minor and Major PRs `renovate` will create multiple branches/PRs if both major and minor branch upgrades are available. For example, if the current example is 1.6.0 and upgrades to 1.7.0 and 2.0.0 exist, then `renovate` will raise PRs for both the 1.x upgrade(s) and 2.x upgrade(s). Our reasons for separating minor and major PRs: - It’s often the case that projects can’t upgrade major dependency versions immediately - It’s also often the case that previous major versions continue receiving Minor or Patch updates - Projects should get Minor and Patch updates for their current Major release even if a new Major release exists This behavior can be overridden via the config option `separateMajorMinor`. ## Branch naming Branches have names like `renovate/webpack-1.x` instead of `renovate/webpack-1.2.0`. We do this because: - Branches often get updates (e.g. new patches) before they’re merged - Naming the branch like `1.x` means its name still makes sense if a `1.2.1` release happens Note: You can configure the branch names by using the string template `branchName` and/or its sub-templates `branchPrefix` and `branchTopic`. ## Pull Request Recreation By default, the script does not create a new PR if it finds a previously-closed PR with the same branch name and PR title (assuming the PR title has a version in it). This allows users to close unwelcome upgrade PRs and not worry about them being recreated every run. ## Rebasing Unmergeable Pull Requests With the default behavior of one branch per dependency, it’s often the case that a PR gets merge conflicts after an adjacent dependency update is merged. On most platforms you can use a web interface to resolve merge conflicts, but you’re still resolving the conflicts manually, which is annoying. `renovate` will rebase any unmergeable branches and add the latest necessary commit on top of the most recent `main` commit. Note: `renovate` will only do this if the original branch hasn’t been modified by anyone else. ## Suppressing string templates from CLI String templates (e.g. commit or PR name) are not configurable via CLI options, in order to not pollute the CLI help and make it unreadable. If you must configure via CLI, use an environment variable instead. e.g. ``` RENOVATE_BRANCH_NAME=foo renovate ``` Alternatively, consider using a Configuration File. ## Logging and error levels Renovate uses the following convention for log levels: - logger.error should only be used for problems that are likely to be a Renovate bug or require Renovate improvements. These are the types of errors that Renovate administrators should be alerted to immediately - logger.warn should be used for problems that might be a Renovate problem so should be checked periodically in batches - For _user_ problems (e.g. configuration errors), these should not warn or error on the server side and instead use logger.info ## [Docs site](https://docharvest.github.io/docs/renovate/development/docs-site/) Contents renovate Docs Site Renovate Docs Site The [Renovate docs site](https://docs.renovatebot.com) is built from this repository. The publishing process is triggered automatically on commits to `main`. If you have submitted a documentation PR and your changes are not published within a day feel free to ping the maintainers, on the PR that introduced the docs change. ## Fenced code blocks JSON code blocks will be validated to ensure that they are: - well-formed JSON - Renovate config which does not need config migration - valid Renovate configuration (with no warnings or errors) This is validated through `pnpm run doc-fence-check`. It is possible to completely ignore this validation check by using a `` comment before the code block. Where a JSON code block is _not_ Renovate config, you can specify: ```` ```json {configType=none} { "in": "valid" } ``` ```` By default, the validation treats a JSON code block as [Repository Config](../usage/configuration-options.md). When writing a JSON snippet for [Global Self-Hosted config](../usage/self-hosted-configuration.md), you will need to note that: ```` ```json {configType=global} { "allowedEnv": ["foo"] } ``` ```` It may be the case that there is a configuration warning that appears which may be safe to ignore, which can be done so with: ```` ```json {ignoreConfigWarnings=true} { "example-deprecated": true } ``` ```` ## [Help Us Help You](https://docharvest.github.io/docs/renovate/development/help-us-help-you/) Contents renovate Help Us Help You Renovate Help Us Help You This repository gets a lot of requests from the community every day, and we do our best to answer all of them. Please follow these points whenever interacting in this repo. ## Be positive and polite This project is open source, and has the work of a lot of contributors who are proud of it. Please avoid unnecessary criticism, especially if you are new to the project or have not contributed anything. You are welcome to make it better, and do not need to criticize the works of others first. ## Be considerate of the time of people helping you We ask that you respect the time of the contributors and maintainers who are helping you. This means accepting that sometimes a question might sit around for a bit before getting answered. This also means that features or bug fixes that you really want can take a long time to appear. ## Be respectful to competitors Even if you’re intending to express a compliment to Renovate from a good heart, try not to phrase it in a way which would be insulting to the developers of alternative tools like Dependabot. There are a lot of good bots out there, and while we’re happy if you like Renovate, we are friends with the creators and developers of other bots and want to keep things friendly. Objective, respectful comparisons or questions are always welcome too - including if you find Renovate missing something you’d like to see. ## Provide adequate descriptions Renovate maintainers and contributors spend many hours helping users, most of the time with problems which are the user’s own misconfiguration or misunderstanding. When you ask for help or are receiving it, please put effort into adequately describing your problem, what you’ve tried, and what you’re trying to do. If you describe a problem with too few details, and we ask you follow-up questions, and you continue to give short and incomplete descriptions, you’re likely to not get any further questions or help. You may get referred to this document though, to explain why! In other words, if someone’s taking the time to help you, “don’t be lazy”. ## Avoid complaining about docs after getting help If someone’s helped you get some functionality working, or successfully troubleshoot a problem, please try to do this: - Let us know which advice fixed your problem, if it’s unclear - If you’re feeling polite, thank the person who helped you - If you’re feeling helpful, submit a Pull Request to improve the relevant documentation Please don’t ruin a successful result with a criticism or complaint about the quality of the documentation. If you feel frustrated because better documentation would have prevented you from making the mistake in the first place then improve it with a PR for those who come after you! ## Avoid spamming issues Sometimes people appear to feel frustrated that their issue or discussion has not got enough attention, and they start commenting on other issues with text such as “I’m also having problems with Gradle! See issue #xyz”. Such comments appear intended to “pressure” Renovate maintainers into taking notice, and rarely do they help the people subscribed to the other, mostly-unrelated issues. Please do not do it. Instead, use the “Subscribe” button to follow issues. ## Reproduce repositories on github.com If you’ve been asked to provide a reproduction repository, please create it on github.com unless the reproduction itself is specific to another platform like GitLab. The Renovate maintainers can test and debug the quickest when using GitHub, and we also have a dedicated organization called [renovate-reproductions](https://github.com/renovate-reproductions/) where we fork reproductions into so that we have a copy in case the original creator removes theirs. ## Create reproductions with minimal config and dependencies We have documented what a “minimal” reproduction repository means, and request that you stick to it. The more config and the more dependencies in a reproduction, the slower it is to debug and solve the problem. Unless you’re planning to work on the feature or fix yourself, please be respectful of the person’s time who would need to do the work instead. ## Filter logs before sharing them If you’ve been asked to give us the logs in an issue or discussion, please don’t copy/paste the entire output and expect someone else to sort through thousands of lines to help you. A full log dump takes a lot of time to scroll through, and it is next to impossible to do so from mobile. Instead, please select the logs relevant to your problem and paste only the relevant logs. If it turns out there’s a need for the full dump, someone can ask you for it later. ## Avoid unjustified bug reports Don’t raise a bug report unless it’s definitely a bug. “I don’t like this” or “I didn’t expect this to happen” is not the same thing as a bug. Many unjustified bug reports are filed because people they think it will get them more attention. Instead, you may be wasting maintainer time because we have to reclassify your invalid bug report or convert it to a discussion, and you are much less likely to get the attention you’re hoping for. If in doubt, start a discussion instead. ## [Issue labeling](https://docharvest.github.io/docs/renovate/development/issue-labeling/) Contents renovate Issue Labeling Renovate Issue Labeling We try to keep issues well-classified through use of labels. Any repository collaborator can apply labels according to the below guidelines. The general idea is that we have: - manager (`manager:`) - versioning (`versioning:`) - datasource (`datasource:`) - platform (`platform:`) - core functionality (`core:`) The majority of issues should have at least one of those labels. These labels should also map approximately to our Conventional Commit scopes. ## Basic knowledge about Renovate You should know about platforms, package managers, datasources and versioning to label issues effectively. - To learn about platforms, read the [Renovate docs on Platforms](https://docs.renovatebot.com/modules/platform/) - To learn about managers, read the [Renovate docs on Managers](https://docs.renovatebot.com/modules/manager/) - To learn about datasources, read the [Renovate docs on Datasources](https://docs.renovatebot.com/modules/datasource/) - To learn more about versioning, read the [Renovate docs on Versioning](https://docs.renovatebot.com/modules/versioning/) Most issues should have a label relating to either a platform, manager, datasource, versioning or worker topic. ## Label categories ### Status Status of issue ``` status:requirements status:blocked status:in-progress ``` Use these to label the status of an issue. For example, use `status:requirements` to mean that an issue is not yet ready for development to begin. ### Type of issue Type of issue ``` type:bug type:docs type:feature type:refactor ``` Use these to label the type of issue. For example, use `type:bug` to label a bug type issue, and use `type:feature` for feature requests. Only use `type:refactor` for code changes, don’t use `type:refactor` for documentation type changes. All issues should have a `type:*` label. Use [this search](https://github.com/renovatebot/renovate/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+-label%3Atype%3Abug+-label%3Atype%3Afeature+-label%3Atype%3Adocs+-label%3Atype%3Arefactor+) to find issues without a `type:*` label. Add the `breaking` label for Issues or PRs which have changes that are not backwards compatible and require a major version bump. ### Priority Priority ``` priority-1-critical priority-2-high priority-3-medium priority-4-low ``` Use these to assign a priority level to an issue. Try to select the proper priority. Nothing bad will happen if you select a “wrong” priority. At a high level: critical = needs immediate fix, high = to be prioritized ahead of others, medium = default priority, low = trivial issue, or impacts a very small percentage of the user base. Use [this search](https://github.com/renovatebot/renovate/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+-label%3Apriority-1-critical+-label%3Apriority-2-high+-label%3Apriority-3-medium+-label%3Apriority-4-low) to find any issues which are missing a priority label. ### Platform Platform labels ``` platform:azure platform:bitbucket platform:bitbucket-server platform:codecommit platform:forgejo platform:gitea platform:github platform:gitlab ``` Use these to mark the platform that is affected by this issue. Keep in mind that an issue can be both affecting a platform and a self-hosted instance. ### Core Core labels ``` core:automerge core:autoreplace core:cache core:changelogs core:config core:dashboard core:git core:onboarding core:package-rules core:schedule core:vulnerabilities ``` The purpose of these labels is to allow browsing of open issues by the most commonly-used functionality, such as automerging or Dependency Dashboard. ### Manager “manager” is short for “package manager”. Add the relevant `manager:` labels to the issue. If there are multiple managers affected, add labels for all of them. ### Datasource Use a `datasource:` label when it is applicable specifically to particular datasources (for example, as defined in the docs list of datasources). ### Worker Worker ``` worker:branch worker:global worker:pr worker:repository ``` A worker is the “core” logic of Renovate. Use these labels to differentiate between the different internal Renovate working stages. ### New stuff New stuff ``` new datasource new package manager new platform new versioning ``` Apply these labels when somebody opens a `feature` type issue requesting a new datasource, package manager, platform, or new versioning scheme. ### Housekeeping Housekeeping ``` duplicate good first issue help wanted auto:bad-vibes auto:discussion-closed auto:discussion-first auto:format-code auto:logs auto:needs-details auto:no-coverage-ignore auto:no-done-comments auto:reproduction auto:retry-latest ``` Add a label `duplicate` to issues/PRs that are a duplicate of an earlier issue/PR. Add a label `good first issue` to issues that are small, easy to fix, and do-able for a newcomer. This label is sometimes picked up by tools or websites that try to encourage people to contribute to open source. Add the label `help wanted` to indicate that we need the original poster or someone else to do some work or it is unlikely to get done. Add a label `auto:bad-vibes` to any discussion containing rude comments such as excessive criticism or ungratefulness. Add a label `auto:discussion-closed` to close a discussion which had persistent or very bad vibes. Add a label `auto:discussion-first` to any PR which needs discussing first. Add a label `auto:format-code` to any Discussion which needs code formatting. Add a label `auto:logs` to indicate that there’s a problem with the logs, and the contributor needs to do one of these things: 1. Provide logs (if there are none yet) 2. Provide more logs (in case current logs are insufficient) 3. Format their logs properly Add a label `auto:needs-details` to discussions which need more details to move forward. Add a label `auto:no-coverage-ignore` if PR authors avoid needed unit tests by v8 ignoring code with the `/* v8 ignore ... */` comment. Add a label `auto:no-done-comments` if PR authors unnecessary “Done” comments, or type comments to ask for a review instead of requesting a new review through GitHub’s UI. Add a label `auto:reproduction` if nobody’s reproduced it in a public repo yet and such a reproduction is necessary before further work can be done. Add a label `auto:retry-latest` to any Discussion where the user should retry the latest version of Renovate to see if the problem persists. ### Self-hosted Self hosted ``` self-hosted ``` Apply the `self-hosted` label when an issue is applicable only to users who self-administer their own bot. ## Automated check for Issues with missing labels We have a GitHub Action (`find-issues-with-missing-labels.yml`) to find issues on our repository that are missing labels. Any Issues with missing labels will be put in a list in a new “error” Issue. The Action runs each week. ## Checking Module Label Coverage Run `pnpm labels:check` to check whether all datasource, manager, and platform modules have matching GitHub labels. Run `pnpm labels:show-commands` to print copy-pasteable `gh label create ...` commands for any missing labels. ### Apply the correct labels manually The Action will _not_ fix any badly labeled issues. This means that you, or we, must apply the correct labels to any affected Issue. ## [Local Development](https://docharvest.github.io/docs/renovate/development/local-development/) Contents renovate Local Development Renovate Local Development This document gives tips and tricks on how to run Renovate locally to add features or fix bugs. You can improve this documentation by opening a pull request. For example, if you think anything is unclear, or you think something needs to be added, open a pull request! ## Installation ### Prerequisites You need the following dependencies for local development: - Git `>=2.45.1` - Node.js `^24.11.0` - pnpm `^10.0.0` - C++ compiler For building the documentation, you also need: - Python `>=3.11` - PDM `>=2.26.0` #### Recommended: Mise We recommend [Mise](https://mise.jdx.dev/) to install and manage all of the tools above. After installing Mise, run `mise install` from the repository root. This installs the pinned versions of tools used in the project and triggers the installation of all dependencies. #### Linux You can use the following commands on Ubuntu. ``` curl -sL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get update sudo apt-get install -y git build-essential nodejs npm install -g pnpm ``` #### Nix To enter a development shell with the necessary packages, run `nix-shell --packages gcc gitFull nodejs` and then `npm install --global pnpm`. #### Windows Follow these steps to set up your development environment on Windows 10. If you already installed a part, skip the corresponding step. - Install [Git](https://git-scm.com/downloads). Make sure you’ve [configured your username and email](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) - Install [Node.js LTS](https://nodejs.org/en/download/) - In an Administrator PowerShell prompt, run `npm install --global npm` and then `npm --debug install --global windows-build-tools` - Install pnpm with: `npm install --global pnpm` You can see what versions you’re using like this: ``` PS C:\Windows\system32> git --version PS C:\Windows\system32> node --version PS C:\Windows\system32> pnpm --version ``` #### VS Code Dev Containers If you are using [VS Code](https://code.visualstudio.com/) you can skip installing [the prerequisites](#prerequisites) and work in a [development container](https://code.visualstudio.com/docs/devcontainers/containers) instead. - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [check its system requirements](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers#system-requirements) - Open the repository folder in VS Code - Choose “Reopen in Container” via the command palette or the small button in the lower left corner The VS Code [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal) is now running in the container and can be used to run more commands. To build inside the container: ``` pnpm build ``` #### Local Docker If, for some reason, you can’t run the relevant versions on your local machine, you can run everything from a Docker image. To build the correct Docker image: ``` docker build -f .devcontainer/Dockerfile -t renovatebot_local . ``` Starting from Docker Engine `23.0` and Docker Desktop `4.19`, Docker uses Buildx by default. So you must run the following command to get the image loaded to the Docker image store: ``` docker build -f .devcontainer/Dockerfile -t renovatebot_local --load . ``` Then you can run `pnpm` directly from Docker, for instance: ``` docker run -it --rm -v "${PWD}:/usr/src/app" -w /usr/src/app renovatebot_local pnpm install ``` ## Fork and Clone If you want to contribute to the project, you should first “fork” the main project using the GitHub website and then clone your fork locally. The Renovate project uses the [pnpm](https://github.com/pnpm/pnpm) package management system instead of npm. To ensure everything is working properly on your end, you must: !!! tip “Mise users” If you ran `mise install`, the `postinstall` hook already executed `pnpm install`. 1. Install all dependencies with `pnpm install` 2. Make a build with `pnpm build`, which should pass with no errors 3. Verify all tests pass and have 100% test coverage, by running `pnpm test` 4. Verify the installation by running `pnpm start`. You must see this error: `You must configure a GitHub personal access token` Do not worry about the token error for now, as you will be given instructions on how to configure the token a little later down in this document. You only need to do these steps once. Before you submit a pull request you should: 1. Install newer dependencies with `pnpm install` 2. Run the tests with `pnpm test` ## Platform Account Setup Although it’s possible to make small source code improvements without testing against a real repository, in most cases you should run a “real” test on a repository before you submit a feature or fix. It’s possible to do this against GitHub, GitLab or Bitbucket public servers. ### Register new account (optional) If you’re going to be doing a lot of Renovate development then we recommend that you set up a dedicated test account on GitHub or GitLab, so that you reduce the risk that you accidentally cause problems when testing out Renovate. e.g. if your GitHub username is “alex88” then maybe you register “alex88-testing” for use with Renovate. ### Generate platform token Once you have decided on your platform and account, log in and [generate a “Personal Access Token”](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) that can be used to authenticate Renovate. Select the **repo** scope when generating the token. ### Export platform token Although you can specify a token to Renovate using `--token=`, it can be inconvenient if you need to include this every time. You are better off to instead export the Environment Variable `RENOVATE_TOKEN` for this. ### Run against a real repo To make sure everything is working, create a test repository in your account, e.g. like `https://github.com/r4harry/testrepo1`. Now, add a file called `.nvmrc` with the content `20.0.0`. Now run against the test repo you created, e.g. `pnpm start r4harry/testrepo1`. If your token is set up correctly, you should find that Renovate created a “Configure Renovate” PR in the `testrepo1`. If this is working then in future you can create other test repos to verify your code changes against. ## Tests You can run `pnpm test` locally to test your code. We test all PRs using the same tests, run on GitHub Actions. `pnpm test` runs lint checks (`oxlint`, `biome`, `prettier`, etc.), a type check, and then all the unit tests using `vitest`. Refactor PRs should ideally not change or remove tests (adding tests is OK). ### Quick Local CI For fast iteration during development, use `pnpm check`, which runs lint and tests in parallel: ``` pnpm check pnpm check lib/util/http # scope to a directory pnpm check lib/util/hash.ts # scope to a file pnpm check --fix lib/util/http # auto-fix only ``` ### Vitest Run the Vitest unit tests with the `pnpm vitest` command. You can also run a subset of the Vitest tests using file matching, e.g. `pnpm vitest composer` or `pnpm vitest workers/repository/update/branch`. If you get a test failure due to a “snapshot” mismatch, and you are sure that you need to update the snapshot, then you can append `-u` to the end. e.g. `pnpm vitest composer -u` would update the saved snapshots for _all_ tests in `**/composer/**`. ### Coverage The Renovate project maintains 100% test coverage, so any Pull Request will fail if it does not have full coverage for code. Using `/* v8 ignore ... */` is not ideal, but can be a pragmatic solution if adding more tests wouldn’t really prove anything. To view the current test coverage locally, open up `coverage/index.html` in your browser. Do not let coverage put you off submitting a PR! Maybe we can help, or at least guide. Also, it can be good to submit your PR as a work in progress (WIP) without tests first so that you can get a thumbs up from others about the changes, and write tests after. ## Linting and formatting We use [Prettier](https://github.com/prettier/prettier) to format our code. If your code fails `pnpm test` due to a `prettier` rule then run `pnpm lint-fix` to fix it or most lint errors automatically before running `pnpm test` again. You usually don’t need to fix any Prettier errors by hand. If you’re only working on the documentation files, you can use the `pnpm doc-fix` command to format your work. ### IDE extensions We recommend installing the extensions listed in `.vscode/extensions.json`. VS Code will prompt you to install them when you open the project. For linting, we use [oxlint](https://oxc.rs) with type-aware analysis. To get real-time oxlint diagnostics, install the extension for your editor: - **VS Code**: [oxc](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode) - **Zed**: [oxc](https://github.com/zed-extensions/oxc) - **IntelliJ/WebStorm**: [Oxlint](https://plugins.jetbrains.com/plugin/25948-oxlint) - **Neovim**: [nvim-oxlint](https://github.com/soulsam480/nvim-oxlint) or via native LSP ## Documentation We use [MkDocs](https://www.mkdocs.org) to generate the documentation. To install the required dependency, use `uv sync`. You can run `pnpm build:docs` to generate the docs. Then use `pnpm mkdocs serve` to preview the documentation locally. The docs will update automatically when you run `pnpm build:docs` again, no need to stop the `pnpm mkdocs serve` command. Also, make sure to set the `GITHUB_TOKEN` in your environment as we use [gh cli](https://cli.github.com/manual/gh_issue_list) to fetch the issues. If you wish to skip fetching the issues, then set `SKIP_GITHUB_ISSUES` to `true` before building the docs. ## Keeping your Renovate fork up to date First of all, never commit to the `main` branch of your fork - always use a “feature” branch like `feat/1234-add-yarn-parsing`. Make sure your fork is up-to-date with the Renovate `main` branch, check this each time before you create a new branch. To do this, see these GitHub guides: - [Configuring a remote for a fork](https://help.github.com/articles/configuring-a-remote-for-a-fork/) - [Syncing a fork](https://help.github.com/articles/syncing-a-fork/) ## Tips and tricks ### Log files Usually the `debug` log level is good enough to troubleshoot most problems or verify functionality. It’s usually easier to have the logs in a file that you can open with a text editor. You can use a command like this to put the log messages in a file: ``` LOG_LEVEL=debug pnpm start myaccount/therepo > debug.log ``` The example command will redirect and save Renovate’s output to the `debug.log` file. Warning: the command will overwrite a existing `debug.log`! ### Adding configuration options We want stay backwards-compatible as much as possible, as well as make the code configurable. So most new functionality should be controllable via configuration options. Create your new configuration option in the `lib/config/options/index.ts` file. Also create documentation for the option in the `docs/usage/configuration-options.md` file. ### `Error: Cannot find module './build/Release/re2.node'` If you’re seeing errors related to `re2`, such as: ``` > renovate@0.0.0-semantic-release prepare:deps ... > node tools/prepare-deps.mjs Checking re2 ... Error: Cannot find module './build/Release/re2.node' Require stack: - .../renovate/node_modules/.pnpm/re2@1.24.0/node_modules/re2/re2.js - .../renovate/[eval] at Module._resolveFilename (node:internal/modules/cjs/loader:1475:15) at wrapResolveFilename (node:internal/modules/cjs/loader:1048:27) at defaultResolveImplForCJSLoading (node:internal/modules/cjs/loader:1072:10) at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1093:12) at Module._load (node:internal/modules/cjs/loader:1261:25) at wrapModuleLoad (node:internal/modules/cjs/loader:255:19) at Module.require (node:internal/modules/cjs/loader:1575:12) at require (node:internal/modules/helpers:191:16) at Object. (.../node_modules/.pnpm/re2@1.24.0/node_modules/re2/re2.js:3:13) at Module._compile (node:internal/modules/cjs/loader:1829:14) { code: 'MODULE_NOT_FOUND', requireStack: [ '.../node_modules/.pnpm/re2@1.24.0/node_modules/re2/re2.js', '.../[eval]' ] } Failed. ``` This is likely due to the version of `re2` being out-of-sync with your Node version. You can rebuild it with: ``` pnpm rebuild re2 ``` This will rebuild it for the current Node version in use. ## Debugging ### Chrome’s inspect tool You can debug Renovate with Chrome’s inspect tool. Here’s an example: 1. Open `chrome://inspect` in Chrome, then select “Open dedicated DevTools for Node” 2. Add a `debugger;` statement somewhere in the source code where you want to start debugging 3. Run Renovate using `pnpm debug ...` instead of `pnpm start ...` 4. Select “Resume script execution” in Chrome DevTools and wait for your break point to be triggered ### VS Code You can also debug Renovate with VS Code. Here’s an example: 1. In the configuration file, e.g. `config.js` in the root directory of the project, add `token` with your Personal Access Token 2. In the same configuration file, add `repositories` with the repository you want to test against. The file `config.js` would look something like this: ``` module.exports = { token: 'xxxxxxxx', repositories: ['r4harry/testrepo1'], }; ``` 3. Set a breakpoint somewhere in the source code and launch the application in debug mode with selected configuration as `debug` 4. Wait for your breakpoint to be triggered ## [Major Releases](https://docharvest.github.io/docs/renovate/development/major-release/) Contents renovate Major Release Renovate Major Release ## When will we push a major version? - There is no set schedule for major version releases - If we need to bump the **minor** (or major) version of Node.JS required to run Renovate - If we have a few breaking changes “piling up” - If we have a need to introduce something that will need wider visibility (i.e. some changes to `config:best-practices` ) ## Preparing - Determine what’s in the next release by looking at the [Milestones view](https://github.com/renovatebot/renovate/milestones) - Look through [breaking changes in the Issues backlog](https://github.com/renovatebot/renovate/issues?q=is%3Aissue%20state%3Aopen%20label%3Abreaking) or in [the PRs list](https://github.com/renovatebot/renovate/pulls?q=is%3Aopen+is%3Apr+label%3Abreaking) ### Draft release notes It is worthwhile drafting the release notes ahead of time, ideally on a GitHub Discussion or Issue, so you can preview what GitHub Flavoured Markdown would render as. For example see [how v42 release notes were drafted](https://github.com/renovatebot/renovate/discussions/38841#discussioncomment-14770478). ## Branching workflow When in the days before the release is ready to land: 1. Create a temporary branch for release, eg `next-major` (from `main`) - This should **not** be a protected branch (including `next`), as we will be rebasing it regularly 1. Create a PR from `next-major` to `main` 2. Add the `ci:fulltest` label to the PR 3. Note issues to close as part of each PR - Mark these as closed by the PR by setting them in the PR sidebar’s “Development - Successfully merging this pull request may close these issues.” 1. For each planned breaking change PR, rebase them + finalise the Git commit history - Adding the `Closes #...` isn’t necessary, as we’ve set this at a PR level 1. For each planned breaking change PR, change the base branch to `next-major` 2. For each planned breaking change PR, approve + merge them into the `next-major` branch - **NOTE** that you want to be merging changes that may lead to conflicts (large code changes, some dependency bumps) to the last possible opportunity 1. If required, rebase `next-major` on `main` and re-push back to `next-major` 2. Wait for CI ## Releasing 1. Once `main` is looking quiet, `next-major` is up-to-date, and CI is fully passing, you can proceed 2. Use `git` CLI to push all commits from release branch to main - **NOTE** that this is a “I’m going to `git push` and bypass branch protection requirements” rather than `git push --force` - This needs to be separate commits, so they each get their own note in the CHANGELOG - For v42 release, we: ``` git checkout main git pull # make sure we're using what's pushed # also, do not edit anything interactively at this point, as it will break the PR closing mechanism if the commits are different git rebase origin/next-major # NOTE THAT THIS DOES NOT REQUIRE A FORCE PUSH git push ``` 1. Wait for release 2. Take draft release notes, and prepend them to the autogenerated release notes from Semantic Release 3. Create a Maintainer Announcement with the release notes - And optionally add some additional commentary [i.e.](https://github.com/renovatebot/renovate/discussions/39133#discussioncomment-14890636) about the previous major release > \[!IMPORTANT\] The final `git push` to `main` can be performed by users with the Maintain role, which includes all Renovate maintainers. ## Post-release - Monitor Discussions for early insights about post-release bugs that need to be resolved - Update GitHub Action to next major - Approve and merge the major version bump from Renovate, which will release the next major of the GitHub Action - NOTE that you will only see 1 PR in the future, but in the last release, we saw 2: - [i.e.](https://github.com/renovatebot/github-action/pull/961) - [i.e.](https://github.com/renovatebot/github-action/pull/960) - Ensure that the Action’s new major version shows as default [in the marketplace](https://github.com/marketplace/actions/renovate-bot-github-action) - Update GitLab CI configuration to next major - [i.e.](https://gitlab.com/renovate-bot/renovate-runner/-/merge_requests/3334) - Add a copy of the JSON Schemas to Schema Store - Go to the last tagged release (of the last major version) and download `docs.tgz` - Copy the `renovate-schema.json`, `renovate-inherited-schema.json` and `renovate-global-schema.json` - See [schemastore#5294](https://github.com/SchemaStore/schemastore/pull/5294) as an example of what configuration may be needed to have the PR build pass - Close the Milestone for the release - After some time (usually when the Mend Developer Platform has been live with the new major), mark the previous major version as deprecated: ``` % npm deprecate renovate@"<44.0.0" "Renovate versions older than the latest major version are unsupported" ``` ## [About minimal reproductions](https://docharvest.github.io/docs/renovate/development/minimal-reproductions/) Contents renovate Minimal Reproductions Renovate Minimal Reproductions We may ask you to create a “minimal reproduction” repository. ## What is a minimal reproduction? A minimal reproduction is a repository with the _least_ amount of code and config that still triggers missing or wrong behavior. ### Example of a perfect reproduction The [`renovate-reproductions/12260` repository](https://github.com/renovate-reproductions/12260) shows a perfect reproduction, because it: - Only has the files/config needed to trigger the bug - Explains the current behavior and the expected behavior in the `readme.md` - Links to the Renovate Issue, or Discussion in the `readme.md` - Uses headings to organize information ## Creating a minimal reproduction Please read this section in full _before_ starting on your minimal reproduction. ### Ways to create a minimal reproduction There are two methods to create a reproduction, see the table for a comparison. Start point Method Benefits Drawbacks [our minimal reproduction template](https://github.com/renovatebot/minimal-reproduction-template) Copy files and config Minimal start point Crafting the bad config/setup from scratch Fork production repo Remove files and config Start with known bad config/setup May need to edit/delete many files Either method will work. We recommend you start from [our minimal reproduction template](https://github.com/renovatebot/minimal-reproduction-template). ### General steps _Always_ follow these steps: 1. Put your minimal reproduction repository on GitHub, only use GitLab or Bitbucket if needed 2. Use the fewest number of repository files and dependencies 3. Reduce your Renovate config to a minimum 4. Remove private or secret information 5. Create a `readme.md` file (or edit the template `readme.md`) and: - Explain the _Current behavior_ and _Expected behavior_ - Link to the Renovate Issue or Discussion - Use headings to organize the information 6. Set the repository visibility to `public` 7. Give us the link to the repository ### Host your reproduction on GitHub.com, if possible Please put your reproduction in a _public_ repository on GitHub.com, if possible. You may put the reproduction on another platform like GitLab or Bitbucket, _if_ the reproduction needs features/behavior of that platform. ### Tips You can find tips for specific situations here. #### Forcing Renovate to create a lot of pending updates Put an old version of a frequently updated dependency in your repository. Then set a high `minimumReleaseAge` for that dependency, for example: ``` { "extends": ["config:best-practices"], "packageRules": [ { "description": "Force lots of pending updates for the Prettier package", "matchPackageNames": ["prettier"], "minimumReleaseAge": "365 days" } ] } ``` You’ll get a lot of pending updates, which you can see on the Dependency Dashboard. ## How we use your minimal reproduction A minimal reproduction helps the Renovate developers: - confirm the problem is with Renovate, and _not_ with your environment, or your configuration settings - see where the bug or missing feature is - verify that the new code solves the problem, or correctly adds a feature - identify the root cause, or narrow down the possible causes - suggest workarounds for the problem - find where to look in our code to help you - step through the code with a debugger ## Why we will not use your production repository to debug You may think: > Why do you even need a minimal reproduction? I already have the reproduction on my production repository and it’s public. Why not use that to debug? This is because a production repository often has: - many dependencies - many custom rules in the Renovate configuration file - many files that are not relevant Lots of “moving parts” makes it hard to debug, as debug break points can trigger hundreds of times. When you have lots of custom config for Renovate, it’s hard for us to find the root cause of the behavior. Bugs are often caused by multiple features interacting. Reducing the config to a minimum helps us find exactly which config elements are needed to trigger the bug. ## Response to common objections Here are our responses to some common objections from users about creating a minimal reproduction. ### “It’s too much work to create a minimal reproduction” We know that it can be hard to create a minimal reproduction. The Renovate maintainers prioritize issues that have a minimal reproduction repository. If you do not create a minimal reproduction, the Renovate maintainers will probably work on other issues first. Discussions without a reproduction usually go stale. ### “I already described what you need in the issue” Thank you for describing your issue in detail. But we still need a minimal reproduction. Make sure your minimal reproduction matches your description and your expected behavior. ## [New package manager questionnaire](https://docharvest.github.io/docs/renovate/development/new-package-manager-template/) Contents renovate New Package Manager Template Renovate New Package Manager Template Did you read our documentation on adding a package manager? - I’ve read the [adding a package manager](adding-a-package-manager.md) documentation. ## Basics ### What’s the name of the package manager? ### What language(s) does this package manager support? ### How popular is this package manager? ### Does this language have other (competing?) package managers? - Yes (give names). - No. ### What are the big selling points for this package manager? Explain how this package manager is different from existing ones. ## Detecting package files ### What kind of package files, and names, does this package manager use? ### Which [`managerFilePatterns`](../usage/configuration-options.md#managerfilepatterns) pattern(s) should Renovate use? ### Do many users need to extend the [`managerFilePatterns`](../usage/configuration-options.md#managerfilepatterns) pattern for custom file names? - Yes, provide details. - No. ### Is the [`managerFilePatterns`](../usage/configuration-options.md#managerfilepatterns) pattern going to get many “false hits” for files that have nothing to do with package management? ## Parsing and Extraction ### Can package files have “local” links to each other that need to be resolved? ### Package file parsing method The package files should be: - Parsed together (in serial). - Parsed independently. ### Which format/syntax does the package file use? - JSON - TOML - YAML - Custom (explain below) ### How should we parse the package files? - Off the shelf parser. - Using regex. - Custom-parsed line by line. - Other. ### Does the package file have different “types” of dependencies? - Yes, production and development dependencies. - No, all dependencies are treated the same. ### List all the sources/syntaxes of dependencies that can be extracted ### Describe which types of dependencies above are supported and which will be implemented in future ## Versioning ### What versioning scheme does the package file(s) use? ### Does this versioning scheme support range constraints, like `^1.0.0` or `1.x`? - Supports range constraints (for example: `^1.0.0` or `1.x`), provide details. - No. ## Lookup ### Is a new datasource required? - Yes, provide details. - No. ### Will users want (or need to) set a custom host or custom registry for Renovate’s lookup? - Yes, provide details. - No. Where can Renovate find the custom host/registry? - No custom host or registry is needed. - In the package file(s), provide details. - In some other file inside the repository, provide details. - User needs to configure Renovate where to find the information, provide details. ### Are there any constraints in the package files that Renovate should use in the lookup procedure? - Yes, there are constraints on the parent language (for example: supports only Python `v3.x`), provide details. - Yes, there are constraints on the parent platform (for example: only supports Linux, Windows, etc.), provide details. - Yes, some other kind of constraint, provide details. - No constraints. ### Will users need the ability to configure language or other constraints using Renovate config? - Yes, provide details. - No. ## Artifacts ### Does the package manager use a lock file or checksum file? - Yes, uses lock file. - Yes, uses checksum file. - Yes, uses lock file _and_ checksum file. - No lock file or checksum. ### Is the locksum or checksum mandatory? - Yes, locksum is mandatory. - Yes, checksum is mandatory. - Yes, lock file _and_ checksum are mandatory. - No mandatory locksum or checksum. - Package manager does not use locksums or checksums. ### If lockfiles or checksums are used: what tool and exact commands should Renovate use to update one (or more) package versions in a dependency file? ### Package manager cache #### Does the package manager use a cache? - Yes, provide details. - No. #### If the package manager uses a cache, how can Renovate control the cache? - Package manager does not use a cache. - Controlled via command line interface, provide details. - Controlled via environment variables, provide details. #### Should Renovate keep a cache? - Yes, ignore/disable the cache. - No. ### Generating a lockfile from scratch Renovate can perform “lock file maintenance” by getting the package manager to generate a lockfile from scratch. Can the package manager generate a lockfile from scratch? - Yes, explain which command Renovate should use to generate the lockfile. - No, the package manager does _not_ generate a lockfile from scratch. - No, the package manager does not use lockfiles. ## Other ### What else should we know about this package manager? ## [Remote Development](https://docharvest.github.io/docs/renovate/development/remote-development/) Contents renovate Remote Development Renovate Remote Development This document gives tips and tricks on how to run Renovate in a remote container to add features or fix bugs. You can improve this documentation by opening a pull request. For example, if you think anything is unclear, or you think something needs to be added, open a pull request! ## First read the local development docs Read the [local development docs](./local-development.md) first. ## What’s remote development? When you work locally, you install the tooling and code editor on your computer. You are responsible for setting up the environment correctly. With remote development you use a container that’s hosted somewhere else. You’ll use the same code editor and have the same config as all other developers. ### Benefits - You only need a browser and internet - You don’t need to install development dependencies on your computer - Start work in a fresh environment every time - Reproducible development environment - Similar config for all developers - Use VS Code in the browser ### Drawbacks - Waiting for the remote container to start - If your internet is down you can’t work - If Codespaces is down you can’t work ## GitHub Codespaces The Renovate developers use [GitHub Codespaces](https://github.com/features/codespaces). The config files are in the `.devcontainer` folder in the repository. ## [Static Data](https://docharvest.github.io/docs/renovate/development/static-data/) Contents renovate Static Data Renovate Static Data Some data used by Renovate is stored in the repository and bundled with Renovate. This is either because the data changes infrequently or would be infeasible to parse on every run. ## Updating static data Static data is updated weekly with a [GitHub Actions workflow](https://github.com/renovatebot/renovate/actions/workflows/update-data.yml). You can also update it manually by running `pnpm run update-static-data`. ## [Renovate style guide](https://docharvest.github.io/docs/renovate/development/style-guide/) Contents renovate Style Guide Renovate Style Guide This document describes the correct style for user-facing text in the: - Documentation - Error and debug messages - Texts created by the bot in issues and pull requests ## Use American English Set your spell checker to the correct language. Guidelines: - Use `ize` instead of `ise` in words like customize and analyze - Drop the British `u` in words like behavior ## One sentence per line In Markdown files, use one sentence per line. Like this: ``` First sentence on one line. Second sentence on a new line. And so on. ``` ## Avoid contractions/possessives Avoid: ``` don't won't doesn't shouldn't wouldn't manager's file's ``` Do: ``` do not will not does not should not would not ``` Avoid possessives like `manager's` or `file's`, if needed rewrite the sentence. ## Avoid manually ordering numbered lists Avoid: ``` 1. First item 2. Second item 3. Third item ``` Do: ``` 1. First item 1. Second item 1. Third item ``` ## Avoid punctuation at the end of list items In Markdown files, avoid punctuation at the end of a list item. Like this: ``` - List item, no punctuation at the end ``` ## Use plain language Follow the [Plain language guidelines](https://www.plainlanguage.gov/guidelines/). ## Correct name for the GitHub app Refer to the GitHub app version of Renovate as “the Mend Renovate app”. ## [Triage guide](https://docharvest.github.io/docs/renovate/development/triage-guide/) Contents renovate Triage Guide Renovate Triage Guide ## What is triage? Triage means filtering the issues/discussions, and categorizing them with the proper labels. ## Triage workflows The general triage workflow is similar for bug reports and feature requests, but there are some small differences which are documented below. ### Triaging bug reports workflow Take the following steps on an incoming bug report: 1. Determine if this is a valid bug report at all, close and optionally delete obvious spam. 2. If poster is asking a configuration question, or has not made a convincing case that it’s really a bug, then convert to a “Ask a question” discussion, add either a response or at least a note that it’s been converted. 3. Determine if this is a duplicate of an open issue/discussion, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. 4. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. 5. Check if the _relevant_ logs are provided. If not apply the `auto:logs` label. ### Triaging feature requests workflow Take the following steps on an incoming feature request: 1. Determine if this is a valid feature request at all, close and optionally delete obvious spam. 2. If poster is asking a configuration question, or has not made a convincing case that it’s really a feature request, then convert to a “Ask a question” discussion, add either a response or at least a note that it’s been converted. 3. Determine if this is a duplicate of an open issue, if duplicate: link to earlier issue/discussion, apply `duplicate` label and close the issue/discussion. 4. Check what version of Renovate is used, if not on current major version: apply the `auto:retry-latest` label. This makes a bot comment to try again with a newer version of Renovate. 5. Make a best-effort judgement if this is a reasonable feature to put into Renovate. If in doubt, let the core maintainers decide. ## Creating new issues from discussions We want _actionable_ issues, so only _maintainers_ (and other approved users) may create them. In short: users create discussions, and when it’s clear what we need to do, the maintainers create the issue. ### Special labels for issues - If it’s an easy issue for somebody new to Renovate to help us with: apply the `good first issue` label - If we need outside help on the issue, apply the `help wanted` label ## What a triagist is allowed to do If you’ve been given triage rights, you are allowed to do the following things: - Apply labels to issues/discussions - Close, reopen, and assign all issues and pull requests - Mark duplicate issues and pull requests - Request pull request reviews - Lock and unlock discussions - Individually convert issues to discussions (do _not_ bulk convert issues) **Note:** We don’t use milestones or project boards. ## Guidelines for triage workflow The following are guidelines as we cannot cover all situations. Use common sense, do your best, and you’ll do all right. Don’t be afraid to ask for help. ### Apply labels to issues All issues should have labels attached to them. Read the [issue-labeling guide](./issue-labeling.md) to get all the necessary info. In general, make a good-faith effort to label issues correctly. ### Closing issues You can close an issue yourself if it’s: - Spam - Obviously fixed For really old issues, it’s a good idea to ask the maintainers to decide if they want to keep or close the issue. ### Closing pull requests You won’t need to close PRs very often, but you can certainly do it in case of spam or malicious content in the PR diff. ### Reopen issues Sometimes a bug is fixed with a PR that links to an issue. When the PR is merged, the issue is automatically closed. Sometimes the bug was not really fixed, and someone says: “Hey this is still broken for me.” In that case, re-open the issue only if it’s _definitely_ the same problem (users often associate different problems together incorrectly). Otherwise, ask the user to open a new issue if it seems like it is different. ### Assign issues You can assign an issue to yourself, or to somebody else, so that others know who’s going to work on the issue. GitHub allows issues to be assigned to: - any project collaborator, or - to any non-collaborator who has _created_ or _commented_ on the issue You can assign whoever makes sense. ### Mark duplicate issues and pull requests If you see an issue/discussion that’s an obvious duplicate: 1. Attach a `duplicate` label 2. Use the “Duplicate of” functionality [GitHub docs, about duplicate issues and pull requests](https://docs.github.com/en/free-pro-team@latest/github/managing-your-work-on-github/about-duplicate-issues-and-pull-requests) 3. Close the issue/discussion Follow the same workflow to mark duplicate PRs. ### Request PR reviews You can request a review from one of the maintainers, if needed, to get the PR review process rolling (again). ### Lock and unlock discussions Sometimes a discussion can go sour, like when people call each other names, or post spam, or veer off-topic. Ideally warn the user with an `auto:bad-vibes` label first, and then use the `auto:discussion-closed` label if problems persist. ### Going from `status:requirements` to actionable issue One of the most important non-code contributions people can do is help features and fixes go from `status:requirements` to a actionable issue. We use the label `status:requirements` to mean “more information or research is needed before someone could start coding this”. It can sometimes be an oversight of the maintainers, but more often it’s because there are requirements or edge cases to consider and the user hasn’t got an opinion or time to think about them and contribute enough. Sometimes it can be because there’s a need for some research and “design” decisions to be made, which may require maintainers to do, but it’s not high enough priority to justify the time yet. In a way `status:requirements` means “someone’s going to need to put more thought into this before it can move forward to development”. It can also mean “don’t start this now because you might do something which can’t be accepted into the code base”. ## [Zod schema guideline](https://docharvest.github.io/docs/renovate/development/zod/) Contents renovate Zod Renovate Zod ### Table of Contents - [Zod schema guideline](#zod-schema-guideline) - [When and where to use Zod](#when-and-where-to-use-zod) - [Technical guide](#technical-guide) - [Use `schema.ts` files for Zod schemas](#use-schemats-files-for-zod-schemas) - [Name schemas without any `Schema` suffix](#name-schemas-without-any-schema-suffix) - [Inferred types](#inferred-types) - [Specify only necessary fields](#specify-only-necessary-fields) - [Use `Json`, `Yaml` and `Toml` for string parsing](#use-json-yaml-and-toml-for-string-parsing) - [Use `.transform()` method to process validated data](#use-transform-method-to-process-validated-data) - [Rename and move fields at the top level transform](#rename-and-move-fields-at-the-top-level-transform) - [Stick to permissive behavior when possible](#stick-to-permissive-behavior-when-possible) - [Use `.catch()` to force default values](#use-catch-to-force-default-values) - [Use `LooseArray` and `LooseRecord` to filter out incorrect values from collections](#use-loosearray-and-looserecord-to-filter-out-incorrect-values-from-collections) - [Combining with `Result` class](#combining-with-result-class) - [Combining with `Http` class](#combining-with-http-class) We decided that Renovate should use [Zod](https://github.com/colinhacks/zod) for schema validation. So any new manager or datasource should use Zod as well. This document explains _how_ and _why_ you should use Zod features. When writing schema validation you want a balance between strictness of explicit contracts between separately developed systems, and the permissiveness of Renovate. We want Renovate to be only as strict as it _needs_ to be. Renovate should _not_ assume a field is always present, because that assumption may lead to run-time errors when a field turns out to be missing. For example: if Renovate assumes an _optional_ field from a public registry will always be used, it may run into trouble when a self-hosted implementation does not use this field. ## When and where to use Zod You should use Zod to validate: - Data received from external APIs and data sources, particularly the `lib/modules/datasource/*` section of Renovate - Data parsed from files in the repository, particularly the `lib/modules/manager/*` section of Renovate [The `cdnjs` datasource](https://github.com/renovatebot/renovate/blob/main/lib/modules/datasource/cdnjs/index.ts) is a good example of using Zod schema validations on API responses from external sources. [The `composer` manager](https://github.com/renovatebot/renovate/blob/main/lib/modules/manager/composer/schema.ts) is a good example of using Zod schema validation in a manager to validate parsed files in a repository. ## Technical guide ### Use `schema.ts` files for Zod schemas Following well-known refactoring principles, you should put Zod schema code in the correct place. The Zod schema usually goes in the `schema.ts` files, and the tests go in the `schema.spec.ts` files. You should write tests for Zod schemas. Creating or extending Zod schemas on the fly reduces Renovate’s performance. Only create or extend Zod schemas in this way if you _really_ need to. ### Name schemas without any `Schema` suffix Schema names must start with a capital letter: ``` const ComplexNumber = z.object({ re: z.number(), im: z.number(), }); ``` Do _not_ add `Schema` to the end of the schema name. Avoid names like `ComplexNumberSchema`. ### Inferred types Create inferred types after schemas if they’re needed somewhere in the code. Place such inferred types just after the schema definition using the same name. While IDEs may confuse schema and type name sometimes, it’s obvious which is which from the syntactic context. Example: ``` export const User = z.object({ firstName: z.string(), lastName: z.string(), }); export type User = z.infer; ``` ### Specify only necessary fields The external data that Renovate queries can be very complex, but Renovate may only need some of those fields. Avoid over-specifying schemas, only extract fields Renovate really needs. This reduces the surface of the contract between the external data source and Renovate, which means less errors to fix in the future. For example, say you want Renovate to know about the width, height and length of a box. You should _avoid_ code like this: ``` const Box = z.object({ width: z.number(), height: z.number(), length: z.number(), color: z.object({ red: z.number(), green: z.number(), blue: z.number(), }) weight: z.number(), }); const { width, height, length } = Box.parse(input); const volume = width * height * length; ``` The code above refers to the `color` and `weight` fields, which Renovate does _not_ need to do its job. Here’s the **correct** code: ``` const Box = z.object({ width: z.number(), height: z.number(), length: z.number(), }); const { width, height, length } = Box.parse(input); const volume = width * height * length; ``` ### Use `Json`, `Yaml` and `Toml` for string parsing You may need to perform extra steps like `JSON.parse()` before you can validate the data structure. Use the helpers in `schema-utils.ts` for this purpose. The **wrong** way to parse from string: ``` const ApiResults = z.array( z.object({ id: z.number(), value: z.string(), }), ); type ApiResults = z.infer; let results: ApiResults | null = null; try { const json = JSON.parse(input); results = ApiResults.parse(json); } catch (e) { results = null; } ``` The **correct** way to parse from string: ``` const ApiResults = Json.pipe( z.array( z.object({ id: z.number(), value: z.string(), }), ), ); const results = ApiResults.parse(input); ``` ### Use `.transform()` method to process validated data Schema validation helps to be more confident with types during downstream data transformation. If the validated data contains everything you need to transform it, you can apply transformations as the part of the schema itself. This is an example of **undesired** data transformation: ``` const Box = z.object({ width: z.number(), height: z.number(), length: z.number(), }); const { width, height, length } = Box.parse(input); const volume = width * height * length; ``` Instead, use the idiomatic `.transform()` method: ``` const BoxVolume = z .object({ width: z.number(), height: z.number(), length: z.number(), }) .transform(({ width, height, length }) => width * height * length); const volume = BoxVolume.parse({ width: 10, height: 20, length: 125, }); // => 25000 ``` #### Rename and move fields at the top level transform When you need to rename or move object fields, place the code to the top-level transform. The **wrong** way is to make cascading transformations: ``` const SourceUrl = z .object({ meta: z .object({ links: z.object({ Github: z.string().url(), }), }) .transform(({ links }) => links.Github), }) .transform(({ meta: sourceUrl }) => sourceUrl); ``` The **correct** way is to rename at the top-level: ``` const SourceUrl = z .object({ meta: z.object({ links: z.object({ Github: z.string().url(), }), }), }) .transform(({ meta }) => meta.links.Github); ``` ### Stick to permissive behavior when possible Zod schemas are strict, which means that if some field is wrong, or missing data, then the whole dataset is considered malformed. Because Renovate uses Zod, it would then abort processing, even if we want Renovate to continue processing! Remember: we want to make sure the incoming data is good enough for Renovate to work. We do _not_ need to validate that the data matches to any official specification. Here are some techniques to make Zod more permissive about the input data. #### Use `.catch()` to force default values ``` const Box = z.object({ width: z.number().catch(10), height: z.number().catch(10), }); const box = Box.parse({ width: 20, height: null }); // => { width: 20, height: 10 } ``` #### Use `LooseArray` and `LooseRecord` to filter out incorrect values from collections Suppose you want to parse a list of package releases, with elements that may (or may not) contain a `version` field. If the `version` field is missing, you want to filter out such elements. If you only use methods from the `zod` library, you would need to write something like this: ``` const Versions = z .array( z .object({ version: z.string(), }) .nullable() .catch(null), ) .transform((releases) => releases.filter((x): x is { version: string } => x !== null), ); ``` When trying to achieve permissive behavior, this pattern will emerge quite frequently, but filtering part of the code is not very readable. Instead, you should use the `LooseArray` and `LooseRecord` helpers from `schema-utils.ts` to write simpler code: ``` const Versions = LooseArray( z.object({ version: z.string(), }), ); ``` ### Use `Nullish` and `DeepNullish` to handle null as absent External APIs sometimes return `null` for fields that are conceptually absent rather than intentionally null. `Nullish` and `DeepNullish` normalise this by converting `null` (and `undefined`) to `undefined`, which Zod then treats as absent. #### `Nullish` — single field Wrap one field with `Nullish` when only that field needs to accept `null`: ``` const Release = z.object({ version: z.string(), releaseTimestamp: Nullish(z.string()), }); Release.parse({ version: '1.0.0', releaseTimestamp: null }); // => { version: '1.0.0' } (releaseTimestamp absent) ``` #### `DeepNullish` — whole schema at once When an API returns `null` in many optional fields, applying `Nullish` to each one individually is tedious. `DeepNullish` walks the schema at build time and replaces every `.optional()` field with `Nullish` semantics in one call. Prefer `DeepNullish` over manual `Nullish` wrapping when the schema has multiple optional fields: ``` const Release = DeepNullish( z.object({ version: z.string(), releaseTimestamp: z.string().optional(), gitRef: z.string().optional(), }), ); Release.parse({ version: '1.0.0', releaseTimestamp: null, gitRef: null }); // => { version: '1.0.0' } ``` `DeepNullish` also recurses into the **output side** of `pipe` / transform nodes, so it works directly with `Json.pipe(…)`: ``` const Release = DeepNullish( Json.pipe( z.object({ version: z.string(), releaseTimestamp: z.string().optional(), }), ), ); Release.parse('{"version":"1.0.0","releaseTimestamp":null}'); // => { version: '1.0.0' } ``` !!! note Intentional `.nullable()` fields are preserved — `null` is kept, not stripped. ### Combining with `Result` class The `Result` (and `AsyncResult`) class represents the result of an operation, like `Result.ok(200)` or `Result.err(404)`. It supports the `.transform()` method, which is similar to `zod`’s. It also supports `.onResult()` and `.onError()` methods for side-effectful result inspection. After all result manipulations are done, you may call `.unwrap()`, `.unwrapOrElse()` or `.unwrapOrThrow()` methods to get the underlying result value. You can wrap the schema parsing result into the `Result` class: ``` const { val, err } = Result.parse(url, z.string().url()) .transform((url) => http.get(url)) .onError((err) => { logger.warn({ err }, 'Failed to fetch something important'); }) .transform((res) => res.body); ``` You can use schema parsing in the middle of the `Result` transform chain: ``` const UserConfig = z.object({ /* ... */ }); const config = await Result.wrap(readLocalFile('config.json')) .transform((content) => Json.pipe(UserConfig).safeParse(content)) .unwrapOrThrow(); ``` ### Combining with `Http` class The `Http` class supports schema validation for the JSON results of methods like `.getJson()`, `.postJson()`, etc. Under the hood, `.parseAsync()` method is used (**important consequence**: in case of invalid data, it will throw). Provide schema in the last argument of the method: ``` const Users = z.object({ users: z.object({ id: z.number(), firstName: z.string(), lastName: z.string(), }), }); const { body: users } = await http.getJson( 'https://dummyjson.com/users', LooseArray(User), ); ``` For GET requests, use the `.getJsonSafe()` method which returns a `Result` instance: ``` const users = await http .getJsonSafe('https://dummyjson.com/users', LooseArray(User)) .onError((err) => { logger.warn({ err }, 'Failed to fetch users'); }) .unwrapOrElse([]); ``` ## [Renovate documentation](https://docharvest.github.io/docs/renovate/usage/) Contents renovate Usage Renovate Usage { loading=lazy } Automated dependency updates. Multi-platform and multi-language. ## Why use Renovate? - :octicons-git-pull-request-24:{ .lg .middle } **Automatic updates** * * * Get pull requests to update your dependencies and lock files. - :octicons-calendar-24:{ .lg .middle } **On your schedule** * * * Reduce noise by scheduling when Renovate creates PRs. - :octicons-package-24:{ .lg .middle } **Works out of the box** * * * Renovate finds relevant package files automatically, including in monorepos. - :octicons-goal-24:{ .lg .middle } **How you like it** * * * You can customize the bot’s behavior with configuration files. - :octicons-share-24:{ .lg .middle } **Share your configuration** * * * Share your configuration with ESLint-like config presets. - :octicons-sync-24:{ .lg .middle } **Out with the old, in with the new** * * * Get replacement PRs to migrate from a deprecated dependency to the community suggested replacement, works with _most_ managers, see [issue 14149](https://github.com/renovatebot/renovate/issues/14149) for exceptions. - :octicons-tools-24:{ .lg .middle } **Open source** * * * Renovate is licensed under the [GNU Affero General Public License](https://github.com/renovatebot/renovate/blob/main/license) (`AGPL-3.0-only`). ## Supported Platforms Renovate works on these platforms: - [Azure DevOps](./modules/platform/azure/index.md) - [AWS CodeCommit](./modules/platform/codecommit/index.md) - [Bitbucket Cloud](./modules/platform/bitbucket/index.md) - [Bitbucket Server](./modules/platform/bitbucket-server/index.md) - [Forgejo](./modules/platform/forgejo/index.md) - [Gerrit (experimental)](./modules/platform/gerrit/index.md) - [Gitea](./modules/platform/gitea/index.md) - [GitHub (.com and Enterprise Server)](./modules/platform/github/index.md) - [GitLab (.com and CE/EE)](./modules/platform/gitlab/index.md) ## Who Uses Renovate? A non-exhaustive list of companies and projects using Renovate can be seen below: { loading=lazy } List of companies and projects that use Renovate - Prisma - Netlify - Envoy - Condé Nast - Microsoft - Atlassian - Sourcegraph - Mozilla - Deloitte - Telus - Yarn - HashiCorp - Automattic - Algolia - eBay - Cypress - Red Hat - Financial Times - Uber - Buildkite ## Ways to run Renovate You can run Renovate as: - an [Open Source npm package](https://www.npmjs.com/package/renovate) - a [pre-built Open Source image on GitHub Container Registry](https://github.com/renovatebot/renovate/pkgs/container/renovate) - a [pre-built Open Source image on Docker Hub](https://hub.docker.com/r/renovate/renovate) Or you can use [the Mend Renovate App](https://github.com/marketplace/renovate) which is hosted by [Mend](https://www.mend.io/). [Install the Mend Renovate app for GitHub](https://github.com/marketplace/renovate){ .md-button .md-button–primary } [Check out our tutorial](https://github.com/renovatebot/tutorial){ .md-button } ## [About us](https://docharvest.github.io/docs/renovate/usage/about-us/) Contents renovate About Us Renovate About Us Renovate was created by [Mend](https://www.mend.io/) staff and they continue to work on Renovate. More than 1000 outside contributors helped improve Renovate. ## Special thanks We want to highlight the work of these awesome people. Thank you for your time and effort! ### Maintainers Renovate is maintained by: - [@viceice](https://github.com/viceice) - [@secustor](https://github.com/secustor) - [@jamietanna](https://github.com/jamietanna) ### Maintainers for features Next up, we have these people who help maintain parts of Renovate: - [@zharinov](https://github.com/zharinov) focused on parsing, Gradle and Maven - [@secustor](https://github.com/secustor) worked on Terraform and Helm - [@fgreinacher](https://github.com/fgreinacher) worked on NuGet - [@Turbo87](https://github.com/Turbo87) has helped in multiple areas, especially Cargo - [@Churro](https://github.com/Churro) worked on the `gradle` manager and added support for OSV vulnerabilities ### Valuable contributions We want to highlight these valuable contributions, even if they are one-offs. Some features made a lot of people happy, and efficient! - [@rarkins](https://github.com/rarkins) created Renovate and maintained it through to August 2025 - [@JamieMagee](https://github.com/JamieMagee) was an active maintainer for years, contributing many features - [@HonkingGoose](https://github.com/HonkingGoose) worked on the documentation and helped manage the community - [@ikesyo](https://github.com/ikesyo) regularly helpful - [@astellingwerf](https://github.com/astellingwerf) reviews PRs - [@danports](https://github.com/danports) worked on the Flux manager, and other managers. Feel free to ping `@danports` for any Flux-related issue or PR - [@shegox](https://github.com/shegox) worked on the Go manager, and improved our docs - [@setchy](https://github.com/setchy) focused on Bitbucket Cloud and replacement features - [@cgrindel](https://github.com/cgrindel) created the `bazel-module` manager - [@RahulGautamSingh](https://github.com/RahulGautamSingh) refactored a lot of code and worked on performance improvements like reduced cloning during updates and onboarding - [@Gabriel-Ladzaretti](https://github.com/Gabriel-Ladzaretti) S3 repo cache, child process refactoring, others - [@not7cd](https://github.com/not7cd) improved the `pip-compile` manager - [@squidfunk](https://github.com/squidfunk) for creating and maintaining the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) framework, that we use to build our docs, and for helping us with problems with the framework, or our docs - [The MkDocs project](https://www.mkdocs.org/) for making the static site generator, that we use to build our docs ## Renovate development The source code for Renovate is available on [GitHub at `renovatebot/renovate`](https://github.com/renovatebot/renovate). This is where we do most of the development. ### Getting more paid help If you need more assistance than what this project offers, you have two options: 1. Become a Mend.io customer, such as by buying Renovate Enterprise, or 2. Hire an experienced Renovate contributor privately for consulting. Mend.io staff do _not_ offer this service, but one of our volunteer maintainers, [`@secustor`](https://github.com/secustor), does ## About these docs The Renovate docs are built from Markdown files in our [`renovatebot/renovate` repository](https://github.com/renovatebot/renovate). Most of the source files can be found in the [`docs/usage/` directory](https://github.com/renovatebot/renovate/tree/main/docs/usage). We use [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to build our docs. ## [Bazel](https://docharvest.github.io/docs/renovate/usage/bazel/) Contents renovate Bazel Renovate Bazel Renovate upgrades dependencies in Bazel `WORKSPACE` files and `MODULE.bazel` files. ## How it works 1. Bazel support is enabled automatically 2. Renovate searches the repository for any `WORKSPACE` and `MODULE.bazel` files 3. Renovate extracts the dependencies it finds from the files (see below for the supported dependency declarations) 4. Renovate updates old dependencies to the latest version ## Bazel module (`MODULE.bazel`) support ### Bazel registry discovery Renovate searches [Bazel registries](https://bazel.build/external/registry) to find new Bazel module versions. You customize the registries your Bazel workspace uses by including [`--registry`](https://bazel.build/reference/command-line-reference#flag--registry) entries in your [`.bazelrc` files](https://bazel.build/run/bazelrc). Renovate checks the workspace’s `.bazelrc` files for custom registry entries. If no registries are found, Renovate defaults to the [Bazel Central Registry](https://bcr.bazel.build/). Here are some important points about Renovate’s Bazel registry searches. Renovate: - uses _all_ `--registry` values found in a workspace’s `.bazelrc` file - uses any files that are transitively imported by a `.bazelrc` file - only uses `--registry` values that are not associated with [a configuration](https://bazel.build/run/bazelrc#config) - queries the registries in the order that they are found in the `.bazelrc` file #### Example: multiple `.bazelrc` files In this example, there is a `.bazelrc` file which imports another file called `.registry.bazelrc`. Both files have `--registry` values: ``` import .registry.bazelrc build --registry=https://raw.githubusercontent.com/bazelbuild/bazel-central-registry/main ``` ``` build --registry=https://example.com/custom_registry ``` The final registry list is: 1. `` 2. `` #### Example: registry entries using Bazel configuration In this example, a `.bazelrc` file has registry values with and without a configuration: ``` build:ci --registry=https://internal.server/custom_registry build --registry=https://raw.githubusercontent.com/bazelbuild/bazel-central-registry/main ``` In this case the `https://internal.server/custom_registry` is ignored. The final registry list is: 1. `` ### Supported Bazel module declarations #### `bazel_dep` Renovate updates the `version` value for a [`bazel_dep`](https://bazel.build/rules/lib/globals/module#bazel_dep) declaration. ``` bazel_dep(name = "cgrindel_bazel_starlib", version = "0.15.0") ``` In the example above, Renovate evaluates the `0.15.0` version against the repository’s registries. If Renovate finds a newer version, it updates `0.15.0` to match that version. #### `git_override` If Renovate finds a [`git_override`](https://bazel.build/rules/lib/globals/module#git_override), it ignores the related `bazel_dep` entry and instead evaluates the `commit` value at the specified `remote`. When using `git_override`, the `version` parameter on the `bazel_dep` is optional. ``` bazel_dep(name = "cgrindel_bazel_starlib", version = "0.15.0") git_override( module_name = "cgrindel_bazel_starlib", commit = "fb47f0e9f7c376a7700fc9fe3319231ae57880df", remote = "https://github.com/cgrindel/bazel-starlib.git", ) bazel_dep(name = "rules_foo") git_override( module_name = "rules_foo", remote = "https://github.com/foo/rules_foo.git", commit = "8a1e9abe415eda7cd7f2a744fdac7499ce42cdca", ) ``` If the primary branch has a newer commit than in the list, Renovate updates the `commit` value. #### `single_version_override` The [`single_version_override`](https://bazel.build/rules/lib/globals/module#single_version_override) is a declaration with many purposes. Renovate only evaluates _two_ attributes from this declaration: `version` and `registry`. If a `version` is specified, it overrides the version in the `bazel_dep`. In the following example, Renovate notices that the version is pinned to `1.2.3`. This results in `rules_foo` being ignored for update evaluation. When using `single_version_override`, the `version` parameter on the `bazel_dep` is optional. ``` bazel_dep(name = "rules_foo", version = "1.2.4") single_version_override( module_name = "rules_foo", version = "1.2.3", ) bazel_dep(name = "rules_bar") single_version_override( module_name = "rules_bar", version = "1.2.3", ) ``` If a `registry` is specified, Renovate uses the specified registry URL to check for a new version. In the following example, Renovate only uses the `https://example.com/custom_registry` registry to discover `rules_foo` versions. Any registry values specified in the repository’s `.bazelrc` files are ignored for the `rules_foo` module. ``` bazel_dep(name = "rules_foo", version = "1.2.3") single_version_override( module_name = "rules_foo", registry = "https://example.com/custom_registry", ) ``` #### `archive_override` and `local_path_override` If Renovate finds an [`archive_override`](https://bazel.build/rules/lib/globals/module#archive_override) or a [`local_path_override`](https://bazel.build/rules/lib/globals/module#local_path_override), it ignores the related `bazel_dep`. Because these declarations lack versionable attributes, Renovate does not update them. When using `archive_override` and `local_path_override`, the `version` parameter on the `bazel_dep` is optional. ``` bazel_dep(name = "rules_foo", version = "1.2.3") archive_override( module_name = "rules_foo", urls = [ "https://example.com/archive.tar.gz", ], ) bazel_dep(name = "rules_bar") archive_override( module_name = "rules_bar", urls = [ "https://example.com/archive.tar.gz", ], ) ``` #### `multiple_version_override` Renovate ignores [`multiple_version_override`](https://bazel.build/rules/lib/globals/module#multiple_version_override). `multiple_version_override` does not affect the processing of version updates for a module. ### Lockfile support Renovate updates the `MODULE.bazel.lock` file after modifying dependencies in `MODULE.bazel`. When Renovate changes a `bazel_dep` version, it runs `bazel mod deps` to regenerate the lockfile. For this to work: 1. Your repository must already have a `MODULE.bazel.lock` file 2. [Bazelisk](https://github.com/bazelbuild/bazelisk) must be available in the environment, or Renovate must be configured to install tools via containerbase (`binarySource=install`) Renovate uses Bazelisk, which determines the correct Bazel version from the `.bazelversion` file in your repository. If no `MODULE.bazel.lock` file exists, Renovate skips the lockfile update step. ### `git_repository` If Renovate finds a [`git_repository`](https://bazel.build/rules/lib/repo/git#git_repository), it evaluates the `commit` value at the specified `remote`. `remote` is limited to github repos: `https://github.com//.git` ``` git_repository( name = "rules_foo", remote = "https://github.com/fooexample/rules_foo.git", commit = "8c94e11c2b05b6f25ced5f23cd07d0cfd36edc1a", ) ``` ## Legacy `WORKSPACE` files Renovate extracts dependencies from the following repository rules: - `container_pull` - `oci_pull` - `git_repository` - `go_repository` - `maven_install` - `http_archive` - `http_file` It also recognizes when these repository rule names are prefixed with an underscore. For example, `_http_archive` is treated the same as `http_archive`. ### `git_repository` (legacy) Renovate updates any `git_repository` declaration that has the following: 1. `name` 2. `remote` matching `https://github.com//.git` 3. `tag` using a valid SemVer e.g.: ``` git_repository( name = "build_bazel_rules_typescript", remote = "https://github.com/bazelbuild/rules_typescript.git", tag = "0.6.1", ) ``` Renovate uses the list of **tags** on the remote repository (GitHub) to detect a new version. ### `http_archive` and `http_file` Renovate updates any `http_archive` or `http_file` declaration that has the following: 1. `name` 2. `url` matching `https://github.com///releases/download//.tar.gz` 3. `sha256` e.g.: ``` http_archive( name = "io_bazel_rules_go", url = "https://github.com/bazelbuild/rules_go/releases/download/0.7.1/rules_go-0.7.1.tar.gz", sha256 = "341d5eacef704415386974bc82a1783a8b7ffbff2ab6ba02375e1ca20d9b031c", ) ``` Renovate uses the list of **releases** that it finds at the `url` to detect a new version. ### `maven_install` By default, Maven dependencies are extracted in the context of Gradle versioning scheme. To change it, configure `packageRules` like this: ``` { "packageRules": [ { "matchManagers": ["bazel"], "matchDatasources": ["maven"], "versioning": "maven" } ] } ``` ## Future work We welcome contributions or feature requests to support more patterns or use cases. ## [Bicep](https://docharvest.github.io/docs/renovate/usage/bicep/) Contents renovate Bicep Renovate Bicep Renovate supports upgrading API versions in `resource` references. Upgrading `module` versions is not supported. ## How it works 1. Renovate searches for `.bicep` files. 2. Renovate parses the files for `resource` types and API versions. 3. Renovate looks up the latest version in the [Azure/bicep-types-az](https://github.com/Azure/bicep-types-az) repository. ## Known issues API version updates of nested resources are not supported. The API version of the `blobServices` resource below for example, will not be upgraded: ``` resource storageAccount 'Microsoft.Storage/storageAccounts@2022-05-01' = { name: 'test' kind: 'StorageV2' sku: { name: 'Standard_LRS' } location: location resource blobServices 'blobServices@2022-05-01' = { name: 'default' } } ``` ## Future work - Support [versioned nested resource](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/child-resource-name-type#within-parent-resource) API version upgrades. - Support [module](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules) version upgrades. - [Public registry](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules#public-module-registry) module references. - [Private registry](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules#private-module-registry) module references. - [Template spec](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules#file-in-template-spec) module references. - [Module aliases](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-config-modules#aliases-for-modules) support. ## [Bot comparison](https://docharvest.github.io/docs/renovate/usage/bot-comparison/) Contents renovate Bot Comparison Renovate Bot Comparison This page explains the key differences between Renovate and Dependabot, to help you choose a bot. We’re trying to be as objective as possible, so this is not a “versus” or anti-Dependabot page. If you see anything wrong on this page, please let us know by creating a [Discussion](https://github.com/renovatebot/renovate/discussions), or edit this page with a PR. ## Table of features Feature Renovate Dependabot Dependency Dashboard Yes No Grouped updates Yes, use community-provided groups, or create your own Yes, create [`groups`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) manually or [handled automatically by dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-grouped-security-updates) Upgrades common monorepo packages at once Yes Yes Officially supported platforms Azure, Bitbucket, Forgejo, Gitea, GitHub, GitLab, SCM-Manager, see [full list](./index.md#supported-platforms) GitHub and Azure DevOps Supported languages [List for Renovate](./modules/manager/index.md) [List for Dependabot](https://docs.github.com/en/code-security/dependabot/ecosystems-supported-by-dependabot/supported-ecosystems-and-repositories#supported-ecosystems-and-repositories) Show changelogs Yes Yes Compatibility score badges Four badges showing: Age, Adoption, Passing, Confidence One badge with overall compatibility score Built-in to GitHub No, requires app or self-hosting Yes Scheduling By default, Renovate runs as often as it is allowed to, read [Renovate scheduling](./key-concepts/scheduling.md) to learn more Yes: `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `yearly` or `cron` License [GNU Affero General Public License](https://github.com/renovatebot/renovate/blob/main/license) [MIT License](https://github.com/dependabot/dependabot-core/blob/main/LICENSE) Programming language of project TypeScript Ruby Project pulse [`renovatebot/renovate` pulse](https://github.com/renovatebot/renovate/pulse) [`dependabot-core` pulse](https://github.com/dependabot/dependabot-core/pulse) Contributor graph [`renovatebot/renovate` contributor graph](https://github.com/renovatebot/renovate/graphs/contributors) [`dependabot-core` contributor graph](https://github.com/dependabot/dependabot-core/graphs/contributors) ## Hosted app This section explains the key differences between the Mend Renovate app and the GitHub-native Dependabot. Even if you’re going to self-host a bot, read the hosted app section first, because many features and concepts are similar. Then read the self-hosted section. ### Dependency Dashboard One big feature of Renovate is the Dependency Dashboard, which is enabled by default. Read the [Key concepts, Dependency Dashboard](./key-concepts/dashboard.md) page to learn more. Dependabot does not have a similar feature. ### Grouped updates Renovate comes with community-provided groupings of dependencies. So Renovate groups common dependencies into a single PR, out-of-the-box. Dependabot can group dependencies into a single PR too, but you must set your own [`groups`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) first. ### Upgrades common monorepo packages at once Renovate has a [`group:monorepos`](./presets-group.md#groupmonorepos) preset, that upgrades common monorepo packages in a single PR. Dependabot does not update common monorepo packages in a single PR. ### Supported platforms Platform means the Git-hosting site or program, for example GitHub, GitLab or Azure. Renovate works on multiple platforms, including GitHub. Read the [list of Renovate platforms](./modules/platform/index.md) to learn more. The _official_ Dependabot program only works on GitHub. If you’re an advanced user, you may use the [`dependabot-core` repository](https://github.com/dependabot/dependabot-core) as a base to build your own Dependabot, which you can run on other platforms. ### Supported languages - [Renovate’s supported managers](./modules/manager/index.md) - [Dependabot’s supported repositories and ecosystems](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystems) ### Show changelogs Feature Renovate Dependabot Link to GitHub release Yes, to specific release tag Yes, to “releases landing page” Link to GitHub’s comparing changes UI Yes Yes Release notes Yes Yes Links to issues Yes Yes Upstream `CHANGELOG` file No Yes Recent commits No Yes Link to individual commits No Yes ### Compatibility score badges Renovate shows four _Merge Confidence_ badges in its PRs: - **Age**: The age of the package - **Adoption**: The percentage of this package’s users (within Renovate) which are using this release - **Passing**: The percentage of updates which have passing tests for this package - **Confidence**: The confidence level for this update Read the [Merge Confidence badges](./merge-confidence.md) page to learn more. Dependabot shows one compatibility score badge in its PRs. This score tells you how many other repositories have passing CI tests for the proposed update. Read the [GitHub Docs, Dependabot’s compatibility scores](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates#about-compatibility-scores) to learn more about Dependabot’s badge. ### Built-in to GitHub vs app Renovate needs app installation or self-hosting. Dependabot is built-in to GitHub. ### Scheduling You can set a schedule for Renovate, per dependency, manager, or even a global schedule. Read [Renovate scheduling](./key-concepts/scheduling.md) to learn more. Dependabot has four options that apply at a language level: - [`schedule.interval`](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#interval) - [`schedule.day`](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#day) - [`schedule.time`](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#time) - [`schedule.timezone`](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#timezone) ### License Renovate uses the [GNU Affero General Public License](https://github.com/renovatebot/renovate/blob/main/license). Dependabot uses the [MIT License](https://github.com/dependabot/dependabot-core/blob/main/LICENSE). Neither license is relevant to the end user though if consuming through an App/SaaS. ### Programming language of project Renovate uses TypeScript. `dependabot-core` uses Ruby. ## Self-hosting a bot This section explains how to self-host each bot. ### Self-hosting Renovate You can self-host Renovate on all [officially supported platforms](./index.md#supported-platforms). If you decide to self-host Renovate, read the items from the [Self-hosting Renovate reading list](./reading-list.md#self-hosting-renovate). Available [Renovate distributions](./getting-started/running.md#available-distributions): - npm package (CLI) - Docker images - GitHub Action - GitLab Runner - Mend Renovate On-Premises - Mend Remediate (commercial offering) - Forking Renovate app ### Self-hosting Dependabot You can self-host Dependabot on other platforms than GitHub but none are officially supported. #### As a GitHub Actions workflow on GitHub You can run Dependabot as a GitHub Actions workflow on hosted and self-hosted runners. Learn more by reading the: - [GitHub Blog, Dependabot on GitHub Actions and self-hosted runners is now generally available](https://github.blog/news-insights/product-news/dependabot-on-github-actions-and-self-hosted-runners-is-now-generally-available/) - [GitHub Docs, About Dependabot on GitHub Actions runners](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/about-dependabot-on-github-actions-runners) #### `dependabot-core` If you want to customize Dependabot, or self-host on another platform, you can use [`dependabot-core`](https://github.com/dependabot/dependabot-core). Quote from the `dependabot-core` readme: > It \[`dependabot-core`\] currently supports opening Pull Requests against repositories hosted on GitHub, Github Enterprise, Azure DevOps, GitLab, BitBucket, and AWS CodeCommit. #### `dependabot-script` The Dependabot team has a community-maintained collection of scripts to start self-hosting Dependabot: [`dependabot-script`](https://github.com/dependabot/dependabot-script) but the repository has included a message warning that the scripts are broken since March 2023. #### `dependabot-gitlab/dependabot` There’s also a community-maintained Dependabot for GitLab: [`dependabot-gitlab/dependabot`](https://gitlab.com/dependabot-gitlab/dependabot). ## [Community Tools](https://docharvest.github.io/docs/renovate/usage/community-tools/) Contents renovate Community Tools Renovate Community Tools This page lists community-maintained tools that extend or complement Renovate. These tools are not officially supported by the Renovate team, but may be useful for your workflow. !!! note If you have a community tool you’d like to add to this page, please open a pull request. ## Renovate Operator (Kubernetes) The [Renovate Operator](https://github.com/mogenius/renovate-operator) lets you run Renovate on Kubernetes in a native way. It wraps the Renovate CLI in a Kubernetes operator and adds features like: - CRD-based scheduling with declarative cron syntax - Parallel execution with configurable concurrency control - Auto-discovery of repositories - Built-in web dashboard for monitoring and management - Webhook API for on-demand runs - Prometheus metrics and health checks ## `renovate-pretty-log-tui` [`renovate-pretty-log-tui`](https://gitlab.com/tanna.dev/renovate-pretty-log/) is a Terminal User Interface (TUI) to provide a richer, local-only view, for your Renovate debug logs. ## [Config Migration](https://docharvest.github.io/docs/renovate/usage/config-migration/) Contents renovate Config Migration Renovate Config Migration As part of continuous improvement and refinement, the Renovate maintainers often rename, remove or combine configuration options. When the Renovate maintainers change configuration options, they add “config migration” code. The migration code allows “legacy” config from users to keep working. Config migration works by migrating legacy config internally, before the config is used. If done right, config migration “just works” silently and legacy configs continue working indefinitely. The only sign that “config migration” is needed is the debug message in the Renovate logs, noting the old and newly migrated configs. ## Enabling config migration pull requests Even though Renovate allows you to keep using “legacy config”, we recommend you update the configuration names in your config regularly. Using the latest names: - makes it easier for you to understand the config - helps you find the documentation for the config Renovate can create a config migration Pull Request, to migrate legacy config in your configuration file. To get automated config migration Pull Requests from Renovate: set the [`configMigration`](./configuration-options.md#configmigration) config option to `true`. Config migration PRs are disabled by default. But we recommend you enable config migration PRs, because: - the config migration PR “tells” you something changed - up-to-date terms help you search the Renovate documentation - up-to-date terms help you, and us, debug problems quicker ## Config migration scenarios The scenarios for config migration are: - No config migration needed - Config migration needed, and enabled - Config migration needed, but disabled - Config migration needed, but there is a previously closed migration PR ### No config migration needed Renovate takes no action. ### Config migration needed, and enabled Renovate will: 1. Create a Config Migration PR 2. If the Dependency Dashboard issue is enabled, then Renovate puts a link to the Config Migration PR on the dashboard ### Config migration needed, but disabled If config migration is needed, but disabled then Renovate adds a checkbox to the Dependency Dashboard (if the dashboard exists). This is known as “on-demand” config migration, because migration PRs are only created at the request of the user by ticking the checkbox. The checkbox looks like this: ``` - [ ] Select this checkbox to let Renovate create an automated Config Migration PR. ``` When you select the checkbox: 1. Renovate creates a config migration PR 2. Renovate replaces the checkbox with a link to the Config Migration PR For example: ``` See Config Migration PR: #1. ``` ### Config migration needed, but there is a closed migration PR In this case, it does not matter if Config Migration is enabled, or not. Renovate will: - Add a checkbox to the Dependency Dashboard issue (if enabled) - When you select the checkbox on the dashboard, Renovate will: 1. Delete the _old_ config migration branch 2. Create a _new_ config migration PR 3. Replace the checkbox with a link to the _new_ PR in the Dependency Dashboard issue ## [Renovate configuration overview](https://docharvest.github.io/docs/renovate/usage/config-overview/) Contents renovate Config Overview Renovate Config Overview Each time Renovate runs on a repository it reads the configuration files listed below and creates a final config. This final config describes what Renovate will do during its run. The final config is internal to Renovate, and is _not_ saved or cached for a later run. But you can always find the final config in Renovate’s logs. Renovate reads the configuration files in this order (from top to bottom): 1. Default config 2. Global config - File config - Additional file config - Environment config - CLI config 3. Inherited config 4. Resolved presets referenced in config 5. Repository config Items with a higher number override items that have lower numbers. If the item has the `mergeable` property, it will merge with lower numbers instead. !!! note If you use a Mend-hosted app, please read [Mend-hosted Apps Configuration](mend-hosted/hosted-apps-config.md) _after_ reading this page. ## Types of config ### Default config Every Renovate config option has a default value/setting. That default value/setting may even be `null`. You can find the default values on the Renovate docs website. For example: - The default value for `onboarding` is `true` - The option `labels` lacks a default value, which means that no labels will be added to Renovate’s PRs The default config is loaded first, and may be superseded/overridden by the configuration types listed below. ### Global config Global config means: the config defined by the person or team responsible for running the bot. This is also referred to as “bot config”, because it’s the config passed to the bot by the person running it. Global config can contain config which is “global only” as well as any configuration options which are valid in Inherited config or Repository config. If you are an end user of Renovate, for example if you’re using the Mend Renovate App, then you don’t need to care as much about any global config. As a end-user you can not change some settings because those settings are global-only. If you are an end user, you can skip the rest of this “Global config” section and proceed to “Inherited config”. Global config can be read from a file, environment variable, or CLI parameters. You must configure at least one of these for Renovate to have the information it needs to run. For example: you may need to give Renovate the correct credentials. #### File config Renovate first tries to read the global config from a file. By default Renovate checks for a `config.js` file in the current working directory. But you can override this by defining `RENOVATE_CONFIG_FILE` in env, for example: `RENOVATE_CONFIG_FILE=/tmp/my-renovate-config.js`. By default Renovate allows the config file to be _missing_ and does not error if it cannot find it. But if you have configured `RENOVATE_CONFIG_FILE` and the path you specified is not found then Renovate will error and exit, because it assumes you have a configuration problem. If the file is found but cannot be parsed then Renovate will also error and exit. Global config files can be `.js` or `.json` files. You may use synchronous or asynchronous methods inside a `.js` file, including even to fetch config information from remote hosts. #### Additional file config Renovate tried to read an additional config file only if the env var `RENOVATE_ADDITIONAL_CONFIG_FILE` is set, for example: `RENOVATE_ADDITIONAL_CONFIG_FILE=/tmp/my-additional-renovate-config.js`. By default Renovate allows the config file to be _missing_ and does not error if it cannot find it. But if you have configured `RENOVATE_ADDITIONAL_CONFIG_FILE` and the path you specified is not found then Renovate will error and exit, because it assumes you have a configuration problem. If the file is found but cannot be parsed then Renovate will also error and exit. Global config files can be `.js` or `.json` files. You may use synchronous or asynchronous methods inside a `.js` file, including even to fetch config information from remote hosts. !!! warning Do not name the additional config file `config.js` as it is reserved for file config. #### Environment config Global config can be defined using environment variables. The config options that you can use in environment variables all have the prefix `RENOVATE_`. For example, `RENOVATE_PLATFORM=gitlab` is the same as setting `"platform": "gitlab"` in File config. Usually there’s a clear mapping from configuration option name to the corresponding Environment config name. But we recommend you still check the documentation for the field `env` for each option to make sure. If the configuration option lacks a `env` field, the config option also lacks a Environment config variable name. A special case for Environment config is the `RENOVATE_CONFIG` “meta” config option. The `RENOVATE_CONFIG` option accepts a stringified full config, for example: `RENOVATE_CONFIG={"platform":"gitlab","onboarding":false}`. Any additional Environment config variables take precedence over values in `RENOVATE_CONFIG`. ##### Environment variable examples !!! warning Make sure to escape any punctuation. Be extra careful if you’re passing stringified values. Boolean: - `RENOVATE_ONBOARDING=true` String: - `RENOVATE_BASE_DIR=/tmp/something` - `RENOVATE_BASE_DIR="/tmp/some thing"` Number: - `RENOVATE_PR_HOURLY_LIMIT=1` List with numbers or strings: - `RENOVATE_LABELS="abc,def,label with space"` Objects, or lists with objects: - `RENOVATE_CONFIG="{platform\":\"gitlab\",\"onboarding\":false}"` - `RENOVATE_PACKAGE_RULES="[{matchHost:\"gitlab\",token:\"$SOME_TOKEN\"}]"` !!! tip Use “stringify” ([Example online service](https://jsonformatter.org/json-stringify-online)) for strings and objects. ##### Experimental variables Renovate has “experimental” environment variables, which start with `RENOVATE_X_`. These variables are experimental, can be changed at any time, and are not parsed as part of regular configuration. Read the [Self-hosted experimental environment variables](./self-hosted-experimental.md) docs to learn more. ##### Logging variables Finally, there are some special environment variables that are loaded _before_ configuration parsing because they are used during logging initialization: - `LOG_CONTEXT`: a unique identifier used in each log message to track context - `LOG_FILE`: used to enable file logging and specify the log file path - `LOG_FILE_FORMAT`: defaults to “json”, but can be changed to a “pretty” human-readable output - `LOG_FILE_LEVEL`: log file logging level, defaults to `debug` - `LOG_FORMAT`: defaults to a “pretty” human-readable output, but can be changed to “json” - `LOG_LEVEL`: most commonly used to change from the default `info` to `debug` logging #### CLI config The final way to configure Global config is through CLI parameters. For example, the CLI parameter `--platform=gitlab` is the same as setting `"platform": "gitlab"` in File config or `RENOVATE_PLATFORM=gitlab` in Environment config. CLI config is read last and takes precedence over Environment and File config. For example, if you configure conflicting values in Environment, File config and CLI config, then the CLI config will be merged last and “win” if values conflict. It is important that you: - Always provide a value, even if the field is boolean (e.g. `--onboarding=true` and _not_ `--onboarding`), and - Prefer `=` notation over spaces, e.g. `--onboarding=true` instead of `--onboarding true` ### Inherited config #### Use cases The primary purpose of Inherited config is to allow for default settings of an organization/group. Two main use cases for Inherited config are: - Controlling onboarding settings within an org (e.g. disabling onboarding, making config optional) - Defining default config settings for repos within an org We recommend that organizations use shared presets instead of Inherited config, if possible. But default settings through Inherited config are useful if: - You want to avoid setting Repository config in each repo, or - You onboarded many repos prior to having a shared org config, and don’t want to retrospectively edit each repo’s config #### How it’s found If `inheritConfig` is `true` in Global config then Renovate will look for Inherited config before processing each repository. The repository and file name which Renovate looks for can be configured using the other `inheritConfig*` settings documented in Global config. Default values are `{{parentOrg}}/renovate-config` for repository name (`inheritConfigRepoName`) and `org-inherited-config.json` for file name (`inheritConfigFileName`). Note: For Azure DevOps, `{{parentOrg}}` is the Project the repo belongs to, and for Bitbucket, the `{{parentOrg}}` is the Workspace of the repo, as shown in the table below. Repo Inherited config file location GitHub {parentOrg} / renovate-config / org-inherited-config.json Bitbucket {parentWorkspace} / renovate-config / org-inherited-config.json Azure DevOps {parentProject} / renovate-config / org-inherited-config.json If found, Inherited config will be merged on top (i.e. override) Global config. Avoid putting any global-only setting in a Inherited config, as doing so will result in an error. Inherited config may use all Repository config settings, and any Global config options which have the “supportsInheritConfig” property in the docs. For information on how the Mend Renovate App supports Inherited config, see the dedicated “Mend Renovate App Config” section toward the end of this page. #### Presets handling If the inherited config contains `extends` presets, then Renovate will: 1. Resolve the presets 2. Add the resolved preset config to the beginning of the inherited config 3. Merge the presets on top of the global config ##### You can not ignore presets from inherited config You can _not_ use `ignorePresets` in your repository config to ignore presets _within_ inherited config. This is because inherited config is resolved _before_ the repository config. ### Repository config Repository config is the config loaded from a config file in the repository. Alternative file names are supported, but the default is `renovate.json`. If Renovate finds more than one configuration file in the same repository, then Renovate will use the _first_ configuration file it finds and ignores the other(s). ### Config precedence Once Repository config is loaded, it is merged over the top of the previously loaded Global and Inherited config, meaning it takes precedence over them. Presets referenced with an “extends” config are resolved first and take lower precedence over regular/raw config in the same file or config object. ## Onboarding When Renovate processes a repository, one of the first decisions it makes is “Does this repository need to be onboarded?”. By default, Renovate will create an “Onboarding PR” with a default config if a repository does not have a Repository config file committed to the default branch. ### Onboarding Config When Renovate creates an Onboarding PR it will propose a Repository config file to be merged. By default, it is essentially an empty config with only the Renovate JSON schema referenced, but you can change this behavior if desired. If you configure `onboardingConfig` in either Global config or Inherited config then Renovate will use that config directly instead of the default. If you self-host Renovate in GitLab using [`renovate-runner`](https://gitlab.com/gitlab-com/gl-infra/renovate/renovate-runner), the CI will contain a default [RENOVATE\_ONBOARDING\_CONFIG](https://gitlab.com/renovate-bot/renovate-runner/-/blob/main/templates/renovate.gitlab-ci.yml#L5) that will merge with your own configuration settings. For example, the CI by default contains: ``` RENOVATE_ONBOARDING_CONFIG: '{"$$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["config:recommended"] }' ``` If you want to change the `extends` in your own configuration, you need to override the variable in your own `.gitlab-ci.yml`: ``` variables: RENOVATE_ONBOARDING_CONFIG: '{"$$schema":"https://docs.renovatebot.com/renovate-schema.json","extends":["platform>organization/repo:renovate-config"]}' ``` Your `renovate.js` where you run Renovate cannot contain any `extends` definition, it will pick the `extends` from the `RENOVATE_ONBOARDING_CONFIG` variable. For example, your config can look like this: ``` module.exports = { ... onboardingConfig: { "argocd": { "fileMatch": [ "application\\.yaml$" ] }, }; ``` The resulting onboarding config will be: ``` { '$schema': 'https://docs.renovatebot.com/renovate-schema.json', 'argocd': { 'managerFilePatterns': ["/application\\.yaml$/"] }, 'extends': ['platform>organization/repo:renovate-config'], } ``` Alternatively if you follow Renovate’s naming convention for shared presets then it can automatically detect those instead. If the repository `{{parentOrg}}/renovate-config` has a `default.json` file then this will be treated as the organization’s default preset and included in the Onboarding config. Additionally for platforms which support nested Organization/Group hierarchies, Renovate will “hunt” up such hierarchies for a `renovate-config` repository with default config and stop when it finds the first. !!! note Renovate will also check for a `renovate.json` file if it cannot find a `default.json` file in a preset, however this option is deprecated and not recommended. If a default config is not found in a `renovate-config` repository within the Organization, Renovate will also check for the presence of a `renovate-config.json` file within a `.{{platform}}` repository parallel to the current repository. For example if the repository being onboarded is `abc/def` on a GitHub platform then Renovate will look for the existence of an `abc/.github` repository containing a `renovate-config.json` file. ### Changing default behavior Default onboarding behavior for an Organization can be changed either in Global or Inherited config. For example, if you set `onboarding=false` then Renovate will not onboard repositories, and skip any repositories without a Repository config. In other words, users need to manually push a valid Repository config file to activate Renovate on the repository. If you set `onboarding=false` plus `requireConfig=optional` then it means Renovate will skip onboarding and proceed to run on a repository, even if Renovate does not find any Repository config. ## Shared Presets ### Overview The concept of shared configuration is covered in detail on the [Presets](./key-concepts/presets.md) page, so please read that first. ### Use of Presets in Global config Presets should be used cautiously in Global config as they often lead to misunderstandings. #### globalExtends Sometimes you may not wish to put all settings within the Global config itself and instead commit it to a repository which is then referenced from the Global config. In such cases, use `globalExtends` instead of `extends` so that it is resolved immediately and used as part of Global config. #### extends If you use `extends` within Global config then it’s important to note that these are _not_ resolved/expanded during Global config processing and instead are passed through unresolved to be part of Repository config. Passing `extends` through to be part of Repository config has two major consequences: - It allows repository users to be able to use `ignorePresets` to ignore all or part of the `extends` presets, and - Presets defined within `extends` in Global config will take _higher_ precedence that “regular” Global config, because it’s resolved later ### Using a centralized config Using “centralized” configs through Renovate presets is important in order to be able to: - Save time by not repeating yourself in every repo with the same config, and - Being able to change settings across an entire Organization or groups of repositories in one place Once you’ve created a centralized preset config, there are multiple ways you can pass it through to repositories: - Defining it in Global config (either `globalExtends` or `extends`) - Using it as your Inherited config, or referencing it from Inherited config using `extends` - Ensuring it’s referenced in Onboarding config so that it’s committed as part of the Repository config The above possibilities go from least to most transparent when it comes to end users. Global config may be invisible to developers without log access, meaning they could be confused by any settings you apply - via presets or directly - within Global config. For example the developers wonder why Renovate is behaving differently to its documented default behavior and may even think it’s a bug. Inherited config is visible to developers (it’s within a repository they can see) although it’s _implicitly_ applied so without log access and if they’re not aware to look for an Inherited config repository then they may again be a little confused as to why default behavior has changed. The recommended approach for using a centralized preset is to explicitly “extend” it from every repository, which can be achieved easily if it’s part of your `onboardingConfig`. By having your centralized preset part of each Repository config `extends`, it has these two benefits: - You still have the ability to change shared settings in a single location - Any user viewing the repo can see the preset being extended and trace it back to understand which config is applied ## Other The below contains edge cases which you should avoid if possible, and likely don’t need to use. They are included here because they can cause “exceptions” to some of the previously mentioned rules of config. ### Optimize for Disabled The `optimizeForDisabled` option was designed for an edge case where a large percentage of repos are disabled by config. If this option is set to `true`, Renovate will use a platform API call to see if a `renovate.json` exists and if it contains `"enabled": false`. If so, the repository will be skipped without a clone necessary. If the file is not present or does not disable Renovate, then Renovate continues as before (having “wasted” that extra API call). ### Force config We recommend you avoid the `force` config option, if possible. It can be used to “force” config over the top of other config or rules which might be merged later, so at times can cause confusion - especially if it’s defined in Global config and overriding settings in Repository config. ## [Shareable Config Presets](https://docharvest.github.io/docs/renovate/usage/config-presets/) Contents renovate Shareable Config Presets Renovate Shareable Config Presets This page describes how to configure your shared presets. Read the [Key concepts, presets](./key-concepts/presets.md) page to learn more about presets in general. Shareable config presets must use the JSON, JSONC or JSON5 formats, other formats are not supported. !!! tip Describe what your preset does in the `"description"` field or add comments as Renovate supports `JSONC` syntax within its preset files. ## Extending from a preset To use a preset put it in an `extends` array within your Renovate config. Presets can be nested. ## Preset Hosting Presets should be hosted in repositories, which usually means the same platform host as Renovate is running against. Alternatively, Renovate can fetch preset files from an HTTP server. !!! warning We deprecated npm-based presets. We plan to drop the npm-based presets feature in a future major release of Renovate. You can set a Git tag (like a SemVer) to use a specific release of your shared config. ### Preset File Naming Presets are repo-hosted, and you can have one or more presets hosted per repository. If you omit a file name from your preset (e.g. `github>abc/foo`) then Renovate will look for a `default.json` file in the repo. If you wish to have an alternative file name, you need to specify it (e.g. `github>abc/foo//alternative-name.json5`). !!! warning We’ve deprecated using a `renovate.json` file for the default _preset_ file name in a repository. If you’re using a `renovate.json` file to share your presets, rename it to `default.json`. ### GitHub name example use preset resolves as filename Git tag GitHub default `github>abc/foo` `default` `https://github.com/abc/foo` `default.json` Default branch GitHub with preset name `github>abc/foo:xyz` `xyz` `https://github.com/abc/foo` `xyz.json` Default branch GitHub with preset name (JSONC) `github>abc/foo:xyz.jsonc` `xyz` `https://github.com/abc/foo` `xyz.jsonc` Default branch GitHub with preset name (JSON5) `github>abc/foo:xyz.json5` `xyz` `https://github.com/abc/foo` `xyz.json5` Default branch GitHub with preset name and path `github>abc/foo//path/xyz` `xyz` `https://github.com/abc/foo` `path/xyz.json` Default branch GitHub default with a tag `github>abc/foo#1.2.3` `default` `https://github.com/abc/foo` `default.json` `1.2.3` GitHub with preset name with a tag `github>abc/foo:xyz#1.2.3` `xyz` `https://github.com/abc/foo` `xyz.json` `1.2.3` GitHub with preset name and path with a tag `github>abc/foo//path/xyz#1.2.3` `xyz` `https://github.com/abc/foo` `path/xyz.json` `1.2.3` GitHub with subpreset name and tag `github>abc/foo:xyz/sub#1.2.3` `sub` `https://github.com/abc/foo` `xyz.json` `1.2.3` ### GitLab name example use preset resolves as filename Git tag GitLab default `gitlab>abc/foo` `default` `https://gitlab.com/abc/foo` `default.json` Default branch GitLab with preset name `gitlab>abc/foo:xyz` `xyz` `https://gitlab.com/abc/foo` `xyz.json` Default branch GitLab with preset name (JSONC) `gitlab>abc/foo:xyz.jsonc` `xyz` `https://gitlab.com/abc/foo` `xyz.jsonc` Default branch GitLab with preset name (JSON5) `gitlab>abc/foo:xyz.json5` `xyz` `https://gitlab.com/abc/foo` `xyz.json5` Default branch GitLab default with a tag `gitlab>abc/foo#1.2.3` `default` `https://gitlab.com/abc/foo` `default.json` `1.2.3` GitLab with preset name with a tag `gitlab>abc/foo:xyz#1.2.3` `xyz` `https://gitlab.com/abc/foo` `xyz.json` `1.2.3` GitLab with preset name and path with a tag `gitlab>abc/foo//path/xyz#1.2.3` `xyz` `https://gitlab.com/abc/foo` `path/xyz.json` `1.2.3` GitLab with subpreset name and tag `gitlab>abc/foo:xyz/sub#1.2.3` `sub` `https://gitlab.com/abc/foo` `xyz.json` `1.2.3` ### Gitea name example use preset resolves as filename Git tag Gitea default `gitea>abc/foo` `default` `https://gitea.com/abc/foo` `default.json` Default branch Gitea with preset name `gitea>abc/foo:xyz` `xyz` `https://gitea.com/abc/foo` `xyz.json` Default branch Gitea with preset name (JSON5) `gitea>abc/foo:xyz.json5` `xyz` `https://gitea.com/abc/foo` `xyz.json5` Default branch Gitea default with a tag `gitea>abc/foo#1.2.3` `default` `https://gitea.com/abc/foo` `default.json` `1.2.3` Gitea with preset name with a tag `gitea>abc/foo:xyz#1.2.3` `xyz` `https://gitea.com/abc/foo` `xyz.json` `1.2.3` Gitea with preset name and path with a tag `gitea>abc/foo//path/xyz#1.2.3` `xyz` `https://gitea.com/abc/foo` `path/xyz.json` `1.2.3` Gitea with subpreset name and tag `gitea>abc/foo:xyz/sub#1.2.3` `sub` `https://gitea.com/abc/foo` `xyz.json` `1.2.3` ### Forgejo name example use preset resolves as filename Git tag Forgejo default `forgejo>abc/foo` `default` `https://codeberg.org/abc/foo` `default.json` Default branch Forgejo with preset name `forgejo>abc/foo:xyz` `xyz` `https://codeberg.org/abc/foo` `xyz.json` Default branch Forgejo with preset name (JSON5) `forgejo>abc/foo:xyz.json5` `xyz` `https://codeberg.org/abc/foo` `xyz.json5` Default branch Forgejo default with a tag `forgejo>abc/foo#1.2.3` `default` `https://codeberg.org/abc/foo` `default.json` `1.2.3` Forgejo with preset name with a tag `forgejo>abc/foo:xyz#1.2.3` `xyz` `https://codeberg.org/abc/foo` `xyz.json` `1.2.3` Forgejo with preset name and path with a tag `forgejo>abc/foo//path/xyz#1.2.3` `xyz` `https://codeberg.org/abc/foo` `path/xyz.json` `1.2.3` Forgejo with subpreset name and tag `forgejo>abc/foo:xyz/sub#1.2.3` `sub` `https://codeberg.org/abc/foo` `xyz.json` `1.2.3` ### Self-hosted Git / current Git server !!! note If you’re self-hosting your platform, for instance a GitHub Enterprise Server instance, you’ll want to use `local>` to look up presets on the current Git server. You can also use `local>` if you’re running on `github.com`, and this will work as if you had written `github>`. This can make your presets more portable if you run across many different Git platforms. For instance, if you have `platform=github` and `endpoint=https://github.company.com`: name example use preset resolves as filename Git tag Local default `local>abc/foo` `default` `https://github.company.com/abc/foo` `default.json` Default branch Local with preset path `local>abc/foo:xyz` `xyz` `https://github.company.com/abc/foo` `xyz.json` Default branch Local with preset path (JSON5) `local>abc/foo:xyz.json5` `xyz` `https://github.company.com/abc/foo` `xyz.json5` Default branch Local with preset name and path `local>abc/foo//path/xyz` `xyz` `https://github.company.com/abc/foo` `path/xyz.json` Default branch Local default with a tag `local>abc/foo#1.2.3` `default` `https://github.company.com/abc/foo` `default.json` `1.2.3` Local with preset name with a tag `local>abc/foo:xyz#1.2.3` `xyz` `https://github.company.com/abc/foo` `xyz.json` `1.2.3` Local with preset name and path with a tag `local>abc/foo//path/xyz#1.2.3` `xyz` `https://github.company.com/abc/foo` `path/xyz.json` `1.2.3` Local with subpreset name and tag `local>abc/foo:xyz/sub#1.2.3` `sub` `https://github.company.com/abc/foo` `xyz.json` `1.2.3` !!! tip You can’t combine the path and sub-preset syntaxes. This means that anything in the form `provider>owner/repo//path/to/file:subsubpreset` is not supported. One workaround is to use distinct files instead of sub-presets. ## Example configs An example of a small rule is `:preserveSemverRanges`, which has the description “Preserve (but continue to upgrade) any existing SemVer ranges.”. It simply sets the configuration option `rangeStrategy` to `replace`. An example of a full config is `config:recommended`, which is Renovate’s default configuration. It mostly uses Renovate config defaults but adds a few smart customizations such as grouping monorepo packages together. !!! note The `:xyz` naming convention (with `:` prefix) is shorthand for the `default:` presets. For example: `:xyz` is the same as `default:xyz`. ## How to Use Preset Configs By default, Renovate App’s onboarding PR suggests the `["config:recommended"]` preset. If you’re self hosting, and want to use the `config:recommended` preset, then you must add `"onboardingConfig": { "extends": ["config:recommended"] }` to your bot’s config. Read the [Full Config Presets](./presets-config.md) page to learn more about our `config:` presets. A typical onboarding `renovate.json` looks like this: ``` { "extends": ["config:recommended"] } ``` Here’s an example of using presets to change Renovate’s behavior. You’re happy with the `config:recommended` preset, but want Renovate to create PRs when you’re not at the office. You look at our `schedule:` presets, and find the `schedule:nonOfficeHours` preset. You put `schedule:nonOfficeHours` in the `extends` array of your `renovate.json` file, like this: ``` { "extends": ["config:recommended", "schedule:nonOfficeHours"] } ``` ## Preset Parameters If you browse the “default” presets, you will see some that have parameters, e.g.: ``` { "labels": { "description": "Apply labels {{arg0}} and {{arg1}} to PRs", "labels": ["{{arg0}}", "{{arg1}}"] }, "assignee": { "description": "Assign PRs to {{arg0}}", "assignees": ["{{arg0}}"] } } ``` Here is how you would use these in your Renovate config: ``` { "extends": [":labels(dependencies,devops)", ":assignee(renovate-tests)"] } ``` In short, the number of `{{argx}}` parameters in the definition is how many parameters you need to provide. Parameters must be strings, non-quoted, and separated by commas if there are more than one. If you find that you are repeating config a lot, you might consider publishing one of these types of parameterized presets yourself. Or if you think your preset would be valuable for others, please contribute a PR to the Renovate repository, see [Contributing to presets](#contributing-to-presets). Also, the entire parameter string is available as `{{args}}`. It includes everything between parentheses, verbatim, without the parentheses themselves. If you want to include a comma in the parameter value, you need to use `{{args}}` instead of `{{arg0}}`. ## GitHub-hosted Presets To host your preset config on GitHub: - Create a new repository. Normally you’d call it `renovate-config` but it can be named anything - Add configuration files to this new repo for any presets you want to share. For the default preset, `default.json` will be checked. For named presets, `.json` will be loaded. For example, loading preset `library` would load `library.json`. No other files are necessary. - In other repos, reference it in an extends array like `"github>owner/name"`, for example: ``` { "extends": ["github>renovate-tests/renovate-config"] } ``` From then on Renovate will use the Renovate config from the preset repo’s default branch. You do not need to add it as a devDependency or add any other files to the preset repo. ## GitLab-hosted Presets For a private GitLab repository Renovate requires at least `Reporter` level access. To host your preset config on GitLab: - Create a new repository on GitLab. Normally you’d call it `renovate-config` but it can be named anything - Add a `default.json` to this new repo containing the preset config. No other files are necessary - In other repos, reference it in an extends array like `"gitlab>owner/name"`, e.g. `"gitlab>renovate-tests/renovate-config"` ## Gitea-hosted Presets To host your preset config on Gitea: - Create a new repository on Gitea. Normally you’d call it `renovate-config` but you can use any name you want - Add a `default.json` to this new repository containing the preset config. No other files are necessary - In other repositories, reference it in an extends array like `"gitea>owner/name"`, e.g. `"gitea>renovate-tests/renovate-config"` ## Forgejo-hosted Presets To host your preset config on Forgejo: - Create a new repository on Forgejo. Normally you’d call it `renovate-config` but you can use any name you want - Add a `default.json` to this new repository containing the preset config. No other files are necessary - In other repositories, reference it in an extends array like `"forgejo>owner/name"`, e.g. `"forgejo>renovate-tests/renovate-config"` ## Local presets Renovate also supports local presets, e.g. presets that are hosted on the same platform as the target repository. This is especially helpful in self-hosted scenarios where public presets cannot be used. Local presets are specified either by leaving out any prefix, e.g. `owner/name`, or explicitly by adding a `local>` prefix, e.g. `local>owner/name`. Renovate will determine the current platform and look up the preset from there. ## Fetching presets from an HTTP server If your desired platform is not yet supported, or if you want presets to work when you run Renovate with `--platform=local`, you can specify presets using HTTP URLs: ``` { "extends": [ "http://my.server/users/me/repos/renovate-presets/raw/default.json?at=refs%2Fheads%2Fmain" ] } ``` Parameters are supported similar to other methods: ``` { "extends": [ "http://my.server/users/me/repos/renovate-presets/raw/default.json?at=refs%2Fheads%2Fmain(param)" ] } ``` ## Templating presets You can use [Handlebars](https://handlebarsjs.com/) templates to be flexible with your presets. This can be handy when you want to include presets conditionally. !!! note The template only supports a small subset of options, but you can extend them via `customEnvVariables`. Read the [templates](./templates.md) section to learn more. ### Example use-case The following example shows a self-hosted Renovate preset located in a GitLab repository called `renovate/presets`. ``` { "extends": ["local>renovate/presets"] } ``` Usually you want to validate the preset before you put it in your Renovate configuration Here is an example of how you can use templating to validate and load the preset on a branch level: ``` // config.js module.exports = { customEnvVariables: { GITLAB_REF: process.env.CI_COMMIT_REF_NAME || 'main', }, extends: ['local>renovate/presets#{{ env.GITLAB_REF }}'], }; ``` ## Contributing to presets Have you configured a rule that could help others? Please consider contributing it to the [Renovate repository](https://github.com/renovatebot/renovate/tree/main/lib/config/presets/internal) so that it gains higher visibility and saves others from reinventing the same thing. Create a [discussion](https://github.com/renovatebot/renovate/discussions) to propose your preset to the Renovate maintainers. The maintainers can also help improve the preset, and let you know where to put it in the code. If you are proposing a “monorepo” preset addition then it’s OK to raise a PR directly as that can be more efficient than a GitHub Discussion. ## Group/Organization level presets Whenever repository onboarding happens, Renovate checks for a a default config to extend. Renovate will check for a repository called `renovate-config` with a `default.json` file in the parent user/group/org of the repository. On platforms that support nested groups (e.g. GitLab), Renovate will check for this repository at each level of grouping, from nearest to furthest, and use the first one it finds. On all platforms, it will then look for a repository named like `.{{platform}}` (e.g. `.github`) with a `renovate-config.json`, under the same top-level user/group/org. If found, that repository’s preset will be suggested as the sole extended preset, and any existing `onboardingConfig` config will be ignored/overridden. For example the result may be: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["local>myorgname/.github:renovate-config"] } ``` ## npm-hosted presets !!! warning Using npm-hosted presets is deprecated, we recommend you do not follow these instructions and instead use a `local` preset. If you manage multiple repositories using Renovate and want the same custom config across all or most of them, then you might want to consider publishing your own preset config so that you can “extend” it in every applicable repository. That way when you want to change your Renovate configuration you can make the change in one location rather than having to copy/paste it to every repository individually. Let’s say that your username on npm and elsewhere is “fastcore”. In that case, you can choose between publishing your preset config package as `@fastcore/renovate-config` or `renovate-config-fastcore`. Let’s assume you choose `renovate-config-fastcore` as the package name. You then need to publish the `renovate-config-fastcore` package where the `package.json` has the field `renovate-config` and then put your config under the field `default`. For example: ``` { "name": "renovate-config-fastcore", "version": "0.0.1", "renovate-config": { "default": { "extends": ["config:recommended", "schedule:nonOfficeHours"] } } } ``` Then in each of your repositories you can add your Renovate config like: ``` { "extends": ["fastcore"] } ``` Any repository including this config will then adopt the rules of the default `library` preset but schedule it on weeknights or weekends. If you prefer to publish using the namespace `@fastcore/renovate-config` then you would use the `@` prefix instead: ``` { "extends": ["@fastcore"] } ``` ## [Config Validation](https://docharvest.github.io/docs/renovate/usage/config-validation/) Contents renovate Config Validation Renovate Config Validation You can check your Renovate configuration with a standalone program called `renovate-config-validator`. All [`renovate` distributions](getting-started/running.md#available-distributions) include this program. ## Default behavior When you run `renovate-config-validator` with no arguments it will check: - all [default locations](configuration-options.md) (if files exist) - the `RENOVATE_CONFIG_FILE` environment variable For example: ``` $ npx --yes --package renovate -- renovate-config-validator INFO: Validating renovate.json INFO: Config validated successfully ``` If you want to run `renovate-config-validator` while using a custom filename for your renovate config file, you will need to pass the filename as cli argument. ### Strict mode By default, the validator program fails with a non-zero exit code if there are any validation warnings or errors. You can pass the `--strict` flag to make it fail if a scanned config needs migration: ``` $ npx --yes --package renovate -- renovate-config-validator --strict INFO: Validating renovate.json WARN: Config migration necessary "oldConfig": { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": [ "config:base" ] }, "newConfig": { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": [ "config:recommended" ] }, ``` ### Pass file to check as CLI arguments You can pass the file you want to check to the `renovate-config-validator` program with a CLI argument. This can be handy to check a config file with a non-default name, like when you’re using preset repositories. For example: ``` $ npx --yes --package renovate -- renovate-config-validator first_config.json INFO: Validating first_config_.json INFO: Config validated successfully ``` !!! note If you specify the filename, `renovate-config-validator` treats the file(s) as global self-hosted configuration instead of repo-level configuration. If this isn’t intentional - for instance if you’re validating a [shared config preset](./config-presets.md) or a non-standard filename - make sure you specify `--no-global`, i.e. `renovate-config-validator --no-global go-presets.json`. ### Providing global configuration If `renovate-config-validator` detects a `config.js`, or any [global self-hosed environment variables](./self-hosted-configuration.md), they will be set as global configuration. For instance, if you had a `config.js`: ``` module.exports = { // to mirror the Mend-hosted Renovate globalExtends: ['global:safeEnv'], }; ``` And a `renovate.json`: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "env": { "GONOSUMDB": "off" } } ``` The `renovate-config-validator` would allow this to pass. ## Validate your config automatically You can create a [pre-commit](https://pre-commit.com) hook to validate your configuration automatically. Go to the [`renovatebot/pre-commit-hooks` repository](https://github.com/renovatebot/pre-commit-hooks) for more information. ### Validation of Renovate config change PRs !!! tip Using the Mend-hosted apps? Push a branch to `renovate/reconfigure` for feedback (via status check), and if there’s a PR, Renovate will add comments to it! Renovate can validate configuration changes in Pull Requests when you use a special branch name. Follow these steps to validate your configuration: 1. Create a new Git branch that matches the `{{branchPrefix}}reconfigure` pattern. For example, if you’re using the default prefix `renovate/`, your branch name must be `renovate/reconfigure`. 2. Commit your updated Renovate config file to this branch, and push it to your Git hosting platform. The next time Renovate runs on that repo it will: 1. Search for a branch that matches the special reconfigure pattern. 2. Check for a config file in the reconfigure branch. Renovate can even find a renamed configuration file (compared to the config file in the default branch). 3. Add a passing or failing status to the branch, depending on the outcome of the config validation run. 4. If there’s an _open_ pull request with validation errors from the _reconfigure_ branch then Renovate comments in the PR with details. 5. Validate each commit the next time Renovate runs on the repository, until the PR is merged. !!! note The reconfigure branch **must** be pushed to the source repository that Renovate runs against, not a fork. ## [Configuration Options](https://docharvest.github.io/docs/renovate/usage/configuration-options/) Contents renovate Configuration Options Renovate Configuration Options This document describes all the configuration options you may use in a Renovate configuration file. Any config you define applies to the whole repository (e.g. if you have a monorepo). A `subtype` in the configuration table specifies what type you’re allowed to use within the main element. If a config option has a `parent` defined, it means it’s only allowed to configure it within an object with the parent name, such as `packageRules` or `hostRules`. When an array or object configuration option is `mergeable`, it means that values inside it will be added to any existing object or array that existed with the same name. !!! tip This documentation corresponds with the JSON schema in [`docs.renovatebot.com/renovate-schema.json`](renovate-schema.json). !!! note Config options with `type=string` are always non-mergeable, so `mergeable=false`. ## Locations for configuration filenames You can store your Renovate configuration file in one of these locations: Also, be sure to check out Renovate’s [shareable config presets](./config-presets.md) to save yourself from reinventing any wheels. Shareable config presets work with JSON and JSON5 file formats. If you have any questions about the config options, or want to get help/feedback about a config, go to the [discussions tab in the Renovate repository](https://github.com/renovatebot/renovate/discussions) and start a [new “Request Help” discussion](https://github.com/renovatebot/renovate/discussions/new?category=request-help). We will do our best to answer your question(s). Or in a custom file present within the [`configFileNames`](./self-hosted-configuration.md#configfilenames). When Renovate runs on a repository, it tries to find the configuration files in the order listed above. Renovate first checks all the files in the `configFileNames` array before checking from the above file list. Renovate stops the search after it finds the first match. !!! warning Storing the Renovate configuration in a `package.json` file is deprecated and support may be removed in the future. !!! note Renovate supports `JSONC` for `.json` files and any config files without file extension (e.g. `.renovaterc`). We also recommend you prefer using a `.jsonc` file if you want to add comments to your configuration, instead of a `.json5` file. Using an explicit `.jsonc` file is preferred over using a `.json` file with comments, as it can cause issues with editors and syntax highlighting. Renovate always uses the config from the repository’s default branch, even if that configuration specifies `baseBranchPatterns`. Renovate does not read/override the config from within each base branch if present. * * * ## `abandonmentThreshold` The `abandonmentThreshold` option allows Renovate to flag packages as abandoned when they haven’t received updates for a specified period of time. Renovate adds an `isAbandoned` boolean property to the package lookup result when: - `abandonmentThreshold` is defined (not `null`) - The package has a `mostRecentTimestamp` timestamp available from the datasource The `mostRecentTimestamp` timestamp represents the release date of the highest version, but only if that version also has the most recent timestamp among all releases. This ensures abandonment detection is based on normal package release patterns. If a package’s most recent release date plus the `abandonmentThreshold` duration is in the past, the package is marked as abandoned (`isAbandoned: true`). This option accepts time duration strings like `1 year`, `6 months`, `90 days`, etc. Example usage: ``` { "abandonmentThreshold": "2 years" } ``` You can also apply this setting selectively using `packageRules`: ``` { "packageRules": [ { "matchDatasources": ["npm"], "abandonmentThreshold": "1 year" } ] } ``` ## `addLabels` The `labels` field is non-mergeable, meaning that any config setting a list of PR labels will replace any existing list. If you want to append labels for matched rules, then define an `addLabels` array with one (or more) label strings. All matched `addLabels` strings will be attached to the PR. Consider this example: ``` { "labels": ["dependencies"], "packageRules": [ { "matchPackageNames": ["/eslint/"], "labels": ["linting"] }, { "matchDepTypes": ["optionalDependencies"], "addLabels": ["optional"] } ] } ``` With the above config: - Optional dependencies will have the labels `dependencies` and `optional` - ESLint dependencies will have the label `linting` - All other dependencies will have the label `dependencies` If you want to use dynamic labels, you can use [templates](./templates.md) such as this example using `depName` for `addLabels`: ``` { "addLabels": ["{{depName}}"] } ``` !!! note Keep your labels within the maximum character limit for your Git hosting platform. Renovate usually truncates labels to 50 characters, except for GitLab, which has a 255 character limit. ## `additionalBranchPrefix` By default, the value for this config option is an empty string. Normally you don’t need to set this config option. Here’s an example where `additionalBranchPrefix` can help you. Say you’re using a monorepo and want to split pull requests based on the location of the package definition, so that individual teams can manage their own Renovate pull requests. This can be done with this configuration: ``` { "additionalBranchPrefix": "{{parentDir}}-" } ``` ## `additionalReviewers` This option _adds_ to the existing reviewer list, rather than _replacing_ it like `reviewers`. Use `additionalReviewers` when you want to add to a preset or base list, without replacing the original. For example, when adding focused reviewers for a specific package group. Please note that Reviewers are only added during creation of a PR, but are not modified afterwards. ## `assignAutomerge` By default, Renovate will not assign reviewers and assignees to an automerge-enabled PR unless it fails status checks. By configuring this setting to `true`, Renovate will instead always assign reviewers and assignees for automerging PRs at time of creation. ## `assignees` Must be valid usernames on the platform in use. This setting is following the same convention as [`reviewers`](#reviewers) for platform-specific behaviors such as Github teams. ## `assigneesFromCodeOwners` If enabled Renovate tries to determine PR assignees by matching rules defined in a CODEOWNERS file against the changes in the PR. Read the docs for your platform for details on syntax and allowed file locations: - [GitHub Docs, About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) - [GitLab, Code Owners](https://docs.gitlab.com/ee/user/project/codeowners/) - [Bitbucket, Set up and use code owners](https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-use-code-owners/) ## `assigneesSampleSize` If configured, Renovate will take a random sample of given size from assignees and assign them only, instead of assigning the entire list of `assignees` you have configured. ## `autoApprove` Setting this to `true` will automatically approve the PRs. You can also configure this using `packageRules` if you want to use it selectively (e.g. per-package). ## `autoReplaceGlobalMatch` Setting this to `false` will replace only the first match during replacements updates. Disabling this is useful for situations where values are repeated within the dependency string, such as when the `currentVersion` is also featured somewhere within the `currentDigest`, but you only want to replace the first instance. Consider this example: ``` FROM java:8@sha256:0e8b2a860 ``` ``` { "packageRules": [ { "matchPackageNames": ["java"], "replacementName": "eclipse-temurin", "replacementVersion": "11" } ] } ``` With the above replacement scenario, the current dependency has a version of `8`, which also features several times within the digest section. When using the default `autoReplaceGlobalMatch` configuration, Renovate will try to replace all instances of `8` within the dependency string with the `replacementVersion` value of `11`. This will replace more than is intended and will be caught during replacement validation steps, resulting in the replacement PR to not be created. When setting `autoReplaceGlobalMatch` configuration to `false`, Renovate will only replace the first occurrence of `8` and will successfully create a replacement PR. ## `automerge` By default, Renovate raises PRs but leaves them to someone or something else to merge them. By configuring this setting, you allow Renovate to automerge PRs or even branches. Using automerge reduces the amount of human intervention required. Usually you won’t want to automerge _all_ PRs, for example most people would want to leave major dependency updates to a human to review first. You could configure Renovate to automerge all but major this way: ``` { "packageRules": [ { "matchUpdateTypes": ["minor", "patch", "pin", "digest"], "automerge": true } ] } ``` Also note that this option can be combined with other nested settings, such as dependency type. So for example you could choose to automerge all (passing) `devDependencies` only this way: ``` { "packageRules": [ { "matchDepTypes": ["devDependencies"], "automerge": true } ] } ``` !!! note Branches creation follows [`schedule`](#schedule) and the automerge follows [`automergeSchedule`](#automergeschedule). !!! note On Azure there can be a delay between a PR being set as completed by Renovate, and Azure merging the PR / finishing its tasks. Renovate tries to delay until Azure is in the expected state, but it will continue if it takes too long. In some cases this can result in a dependency not being merged, and a fresh PR being created for the dependency. !!! note By default, Renovate will not assign reviewers and assignees to an automerge-enabled PR unless it fails status checks. By configuring [`assignAutomerge`](#assignautomerge) setting to `true`, Renovate will instead always assign reviewers and assignees for automerging PRs at time of creation. **Automerge and GitHub branch protection rules** You must select at least one status check in the _Require status checks to pass before merging_ section of your branch protection rules on GitHub, if you match all three conditions: - `automerge=true` - `platformAutomerge=true`, Renovate defaults to `true` - You use GitHub’s _Require status checks to pass before merging_ branch protection rule If you don’t select any status check, and you use platform automerge, then GitHub might automerge PRs with failing tests! ## `automergeComment` Use this only if you configure `automergeType="pr-comment"`. Example use: ``` { "automerge": true, "automergeType": "pr-comment", "automergeComment": "bors: r+" } ``` ## `automergeSchedule` Use the `automergeSchedule` option to define times of week or month during which Renovate may automerge its PRs. The default value for `automergeSchedule` is “at any time”, which functions the same as setting a `null` schedule. To configure this option refer to [`schedule`](#schedule) as the syntax is the same. !!! warning When `platformAutomerge` is enabled, Renovate enqueues the platform PR automerge at time of creation, so the schedule specified in `automergeSchedule` cannot be followed. If it’s essential that automerging only happens within the specific `automergeSchedule` time window, then you need to set `platformAutomerge` to `false` and instead rely on Renovate’s automerge instead of the platform one. ## `automergeStrategy` The automerge strategy defaults to `auto`, so Renovate decides how to merge pull requests as best it can. If possible, Renovate follows the merge strategy set on the platform itself for the repository. If you’ve set `automerge=true` and `automergeType=pr` for any of your dependencies, then you may choose what automerge strategy Renovate uses by setting the `automergeStrategy` config option. If you’re happy with the default behavior, you don’t need to do anything. You may choose from these values: - `auto`, Renovate decides how to merge - `fast-forward`, “fast-forwarding” the main branch reference, no new commits in the resultant tree - `merge-commit`, create a new merge commit - `rebase`, rewrite history as part of the merge, but usually keep the individual commits - `rebase-merge`, create a new merge commit, but rebase the commits prior merging (azure-only) - `squash`, flatten the commits that are being merged into a single new commit Platforms may only support _some_ of these merge strategies. If the chosen automerge strategy is not supported on your platform then Renovate stops automerging. In that case you’ll have to set a supported automerge strategy. ## `automergeType` This setting is only applicable if you opt in to configure `automerge` to `true` for any of your dependencies. Automerging defaults to using Pull Requests (`automergeType="pr"`). In that case Renovate first creates a branch and associated Pull Request, and then automerges the PR on a subsequent run once it detects the PR’s status checks are “green”. If by the next run the PR is already behind the base branch it will be automatically rebased, because Renovate only automerges branches which are up-to-date and green. If Renovate is scheduled for hourly runs on the repository but commits are made every 15 minutes to the main branch, then an automerge like this will keep getting deferred with every rebase. !!! tip If you have no tests but still want Renovate to automerge, you need to add `"ignoreTests": true` to your configuration. If you prefer that Renovate more silently automerge _without_ Pull Requests at all, you can configure `"automergeType": "branch"`. In this case Renovate will: - Create the branch, wait for test results - Rebase it any time it gets out of date with the base branch - Automerge the branch commit if it’s: (a) up-to-date with the base branch, and (b) passing all tests - As a backup, raise a PR only if either: (a) tests fail, or (b) tests remain pending for too long (default: 24 hours) The final value for `automergeType` is `"pr-comment"`, intended only for users who already have a “merge bot” such as [bors-ng](https://github.com/bors-ng/bors-ng) and want Renovate to _not_ actually automerge by itself and instead tell `bors-ng` to merge for it, by using a comment in the PR. If you’re not already using `bors-ng` or similar, don’t worry about this option. ## `azureWorkItemId` When creating a PR in Azure DevOps, some branches can be protected with branch policies to [check for linked work items](https://learn.microsoft.com/azure/devops/repos/git/branch-policies#check-for-linked-work-items). Creating a work item in Azure DevOps is beyond the scope of Renovate, but Renovate can link an already existing work item when creating PRs. ## `baseBranchPatterns` This configuration option was formerly known as `baseBranches`. By default, Renovate will detect and process only the repository’s default branch. For most projects, this is the expected approach. Renovate also allows users to explicitly configure `baseBranchPatterns`, e.g. for use cases such as: - You wish Renovate to process only a non-default branch, e.g. `dev`: ``` { "baseBranchPatterns": ["dev"] } ``` - You have multiple release streams you need Renovate to keep up to date, e.g. in branches `main` and `next`: ``` { "baseBranchPatterns": ["main", "next"] } ``` - You want to update your main branch and consistently named release branches, e.g. `main` and `release/`: ``` { "baseBranchPatterns": ["main", "/^release\\/.*/"] } ``` It’s possible to add this setting into the `renovate.json` file as part of the “Configure Renovate” onboarding PR. If so then Renovate will reflect this setting in its description and use package file contents from the custom base branch(es) instead of default. Also, check [useBaseBranchConfig](#usebasebranchconfig) if you want to configure different configuration for each base branch. The simplest approach is exact matches, e.g. `["main", "dev"]`. `baseBranchPatterns` also supports Regular Expressions that must begin and end with `/`, e.g.: ``` { "baseBranchPatterns": ["main", "/^release\\/.*/"] } ``` You can negate the regex by prefixing it with `!`. Only use a single negation and do not mix it with other branch names, since all branches are combined with `or`. With a negation, all branches except those matching the regex will be added to the result: ``` { "baseBranchPatterns": ["!/^pre-release\\/.*/"] } ``` You can also use the special `"$default"` string to denote the repository’s default branch, which is useful if you have it in an org preset, e.g.: ``` { "baseBranchPatterns": ["$default", "/^release\\/.*/"] } ``` !!! note Do _not_ use the `baseBranchPatterns` config option when you’ve set a `forkToken`. You may need a `forkToken` when you’re using the Forking Renovate app. ## `bbAutoResolvePrTasks` Configuring this to `true` means that Renovate will mark all PR Tasks as complete. ## `bbUseDefaultReviewers` Configuring this to `true` means that Renovate will detect and apply the default reviewers rules to PRs (Bitbucket only). ## `branchConcurrentLimit` By default, Renovate doesn’t enforce its own concurrent branch limit. However, it inherits the [prConcurrentLimit](#prconcurrentlimit), which defaults to 10. This effectively caps concurrent branches at 10, though in many repositories a lower limit, such as 3 or 5, tends to be more efficient. If you want the same limit for both concurrent branches and concurrent PRs, then set a value for `prConcurrentLimit` and it will be reused for branch calculations too. But if you want to allow more concurrent branches than concurrent PRs, you can configure both values (e.g. `branchConcurrentLimit=5` and `prConcurrentLimit=3`). This limit is enforced on a per-repository basis. Example config: ``` { "branchConcurrentLimit": 3 } ``` !!! warning Leaving PRs/branches as unlimited or as a high number increases the time it takes for Renovate to process a repository. If you find that Renovate is too slow when rebasing out-of-date branches, decrease the `branchConcurrentLimit`. If you have too many concurrent branches which rebase themselves each run, Renovate can take a lot of time to rebase. Solutions: - Decrease the concurrent branch limit (note: this won’t go and delete any existing, so won’t have an effect until you either merge or close existing ones manually) - Remove automerge and/or automatic rebasing (set `rebaseWhen` to `conflicted`). However if you have branch protection saying PRs must be up to date then it’s not ideal to remove automatic rebasing ## `branchName` If you truly need to configure this then it probably means either: - You are hopefully mistaken, and there’s a better approach you should use, so open a new “config help” discussion at the [Renovate discussions tab](https://github.com/renovatebot/renovate/discussions) or - You have a use case we didn’t expect, please open a discussion to see if we want to get a feature request from you ## `branchNameStrict` If `true`, Renovate removes special characters when slugifying the branch name: - all special characters are removed - only alphabetic characters are allowed - hyphens `-` are used to separate sections The default `false` behavior will mean that special characters like `.` and `/` may end up in the branch name. !!! note Renovate will not apply any search/replace to the `branchPrefix` part of the branch name. If you don’t want any `/` in your branch name then you will also need to change `branchPrefix` from the default `renovate/` value to something like `renovate-`. ## `branchPrefix` You can modify this field if you want to change the prefix used. For example if you want branches to be like `deps/eslint-4.x` instead of `renovate/eslint-4.x` then you configure `branchPrefix` = `deps/`. Or if you wish to avoid forward slashes in branch names then you could use `renovate_` instead, for example. `branchPrefix` must be configured at the root of the configuration (e.g. not within any package rule) and is not allowed to use template values. e.g. instead of `renovate/{{parentDir}}-`, configure the template part in `additionalBranchPrefix`, like `"additionalBranchPrefix": "{{parentDir}}-"`. !!! note This setting does not change the default _onboarding_ branch name, i.e. `renovate/configure`. If you wish to change that too, you need to also configure the field `onboardingBranch` in your global bot config. ## `branchPrefixOld` Renovate uses branch names as part of its checks to see if an update PR was created previously, and already merged or ignored. If you change `branchPrefix`, then no previously closed PRs will match, which could lead to Renovate recreating PRs in such cases. Instead, set the old `branchPrefix` value as `branchPrefixOld` to allow Renovate to look for those branches too, and avoid this happening. ## `branchTopic` This field is combined with `branchPrefix` and `additionalBranchPrefix` to form the full `branchName`. `branchName` uniqueness is important for dependency update grouping or non-grouping so be cautious about ever editing this field manually. This is an advanced field, and it’s recommend you seek a config review before applying it. ## `bumpVersion` Currently, this config option only works with these managers: - `cargo` - `helmv3` - `npm` - `nuget` - `maven` - `ocb` - `pep621` - `poetry` - `sbt` Raise a feature request if you want to use this config option with other package managers. Use `bumpVersion` if you want Renovate to update the `version` field in your package file when it updates the dependencies in that file. This can be handy when you have automated your package’s release, as you you don’t need extra steps after the Renovate upgrade, you can just release a new version. Configure this value to `"prerelease"`, `"patch"`, `"minor"` or `"major"` to have Renovate update the version in your edited package file. e.g. if you wish Renovate to always increase the target `package.json` version with a patch update, configure this to `"patch"`. For `npm` only you can also configure this field to `"mirror:x"` where `x` is the name of a package in the `package.json`. Doing so means that the `package.json` `version` field will mirror whatever the version is that `x` depended on. Make sure that version is a pinned version of course, as otherwise it won’t be valid. For `sbt` note that Renovate will update the version string only for packages that have the version string in their project’s `built.sbt` file. ## `bumpVersions` The `bumpVersions` option allows Renovate to update semantic version strings in your code when dependencies are updated. This is useful for files or version fields that Renovate does not natively support or for custom versioning needs. The option is an array of rules, each specifying how and where to bump versions. Each rule includes the following fields: - `filePatterns`: A list of regex patterns to match file names. These patterns follow Renovate’s [string pattern matching syntax](./string-pattern-matching.md). Templates can also be used for dynamic patterns. - `matchStrings`: An array of regex patterns to locate version strings within the matched files. Any of the regexes can match the content. Each pattern must include a named capture group `version` to extract the version string. - `bumpType`: Specifies the type of version bump which defaults to `patch`. This field supports templates for conditional logic. Supported values are documented in the [bumpVersions.bumpType section](#bumpversionsbumptype). - `name` (optional): A descriptive name for the rule, which is used in logs for easier identification. !!! tip You can use templates in `filePatternTemplates`, `bumpType`, and `matchStrings`. This way you can leverage the power of Renovate’s templating engine to change based on the context of the upgrade. Here is an example of a `bumpVersions` configuration: ``` { "bumpVersions": [ { "name": "Updating release version file", "filePatterns": [".release-version"], "bumpType": "minor", "matchStrings": ["^(?.+)$"] } ] } ``` In this example: - Renovate scans files named `.release-version`. - It matches the entire file content as the version string. - It bumps the version to the next minor release. **Conditional Bumping with `packageRules`:** You can use `packageRules` to apply `bumpVersions` conditionally. For example, to bump versions only for updates in the `charts/` directory: ``` { "packageRules": [ { "matchFileNames": ["charts/**"], "bumpVersions": [ { "filePatterns": ["{{packageFileDir}}/Chart.{yaml,yml}"], "matchStrings": ["version:\\s(?[^\\s]+)"], "bumpType": "{{#if isPatch}}patch{{else}}minor{{/if}}" } ] } ] } ``` In this configuration: - If Renovate updates dependencies in the `charts/` directory check the `Chart.yaml` file next to the updated file. - The version string is extracted from lines matching `version: `. - The `bumpType` is dynamically set to `patch` for if the dependency update is a patch update and `minor` otherwise. **debugging `bumpVersions`** Use [`logLevelRemap`](#loglevelremap) to remap, `trace` log level messages to a higher level e.g. `debug`. All messages are prefixed with `bumpVersions` or `bumpVersions()` to help you filter them in the logs. ``` { "logLevelRemap": [ { "matchMessage": "/bumpVersions/", "newLogLevel": "debug" } ] } ``` **short versions** It’s possible to bump short versions: - `1` → `2` (major) - `1.1` → `2.0` (major) - `1.2` → `1.3` (minor) ### `bumpVersions.bumpType` The `bumpType` field specifies the type of version bump to apply. Supported values are: - `prerelease` - `patch` - `minor` - `major` - `sync` This field supports templates for conditional logic. For example: ``` { "bumpType": "{{#if isPatch}}patch{{else}}minor{{/if}}" } ``` In this example, the bump type is set to `patch` for patch updates and `minor` for all other cases. **Using `sync` to sync with dependency updates** The `sync` type is special: it uses the same version as the dependency manager update that triggered the branch. This is useful when you want to keep version files in sync with actual dependency updates. For example, if you have a `.release-version` file that should always match the version of a specific dependency: ``` { "bumpVersions": [ { "filePatterns": [".release-version"], "bumpType": "sync", "matchStrings": ["^(?.+)$"] } ] } ``` When Renovate updates a dependency to version `2.5.3`, it will also update the `.release-version` file to `2.5.3`. !!! note When using `bumpType: "sync"`, Renovate uses the `newVersion` from the first upgrade in the branch. If no upgrades are found in the branch, the version bump will be skipped and a debug message will be logged. ### `bumpVersions.filePatterns` The `filePatterns` field defines which files should be scanned for version strings. It accepts one or more patterns following Renovate’s [string pattern matching syntax](./string-pattern-matching.md). Templates can also be used for dynamic patterns. See [Templates](./templates.md) for more information. For example: ``` { "filePatterns": ["**/version.txt", "{{packageFileDir}}/Chart.yaml"] } ``` This configuration matches files named `version.txt` in any directory and `Chart.yaml` files in specific package directories. * * * ### `bumpVersions.matchStrings` Use `matchStrings` within `bumpVersions` to define patterns to match version strings in files. See [`customManagers.matchStrings`](#custommanagersmatchstrings) for full documentation. ### `bumpVersions.name` The `name` field is an optional identifier for the bump version rule. It is used in logs to help identify which rule is being applied. For example: ``` { "name": "Update release version" } ``` This name will appear in Renovate logs, making it easier to debug or trace specific rules. ## `cloneSubmodules` Enabling this option will mean that detected Git submodules will be cloned at time of repository clone. By default all will be cloned, but this can be customized by configuring `cloneSubmodulesFilter` too. Submodules are always cloned recursively. Important: private submodules aren’t supported by Renovate, unless the underlying `ssh` layer already has the correct permissions. ## `cloneSubmodulesFilter` Use this option together with `cloneSubmodules` if you wish to clone only a subset of submodules. This config option supports regex and glob filters, including negative matches. For more details on this syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). ## `commitBody` Configure this if you wish Renovate to add a commit body, otherwise Renovate uses a regular single-line commit. For example, To add `[skip ci]` to every commit you could configure: ``` { "commitBody": "[skip ci]" } ``` Another example would be if you want to configure a DCO sign off to each commit. If you want Renovate to sign off its commits, add the [`:gitSignOff` preset](./presets-default.md#gitsignoff) to your `extends` array: ``` { "extends": [":gitSignOff"] } ``` ## `commitBodyTable` ## `commitHourlyLimit` This config option limits the number of commits Renovate pushes in an hour. It includes commits pushed while creating a new branch or rebasing an existing one. Use `commitHourlyLimit` to strictly control the rate at which Renovate triggers CI runs. Both branch creation and rebasing trigger CI runs, so limiting these operations helps you control your CI load. For example, with `commitHourlyLimit: 2`, in a given hour Renovate might: - Create 2 new branches (triggering 2 CI runs), then stop until the next hour, or - Create 1 new branch and rebase 1 existing branch (2 CI runs total), then stop This limit is enforced on a per-repository basis and per hourly period (`:00` through `:59`). This setting differs from `prHourlyLimit` in an important way: - `prHourlyLimit` only limits PR _creation_. Renovate can still rebase existing branches, which triggers additional CI runs - `commitHourlyLimit` limits both branch creation _and_ automatic rebasing, giving you stricter control over CI usage If you want strict control over CI load, use `commitHourlyLimit`. If you only want to limit the rate of _new_ PRs, use [prHourlyLimit](#prhourlylimit). !!! tip Manual rebases (requested via checkbox, Dependency Dashboard, or rebase label) always bypass this limit. ## `commitMessage` ## `commitMessageAction` This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. Actions may be like `Update`, `Pin`, `Roll back`, `Refresh`, etc. Check out the default value for `commitMessage` to understand how this field is used. ## `commitMessageExtra` This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string. The “extra” is usually an identifier of the new version, e.g. “to v1.3.2” or “to tag 9.2”. ## `commitMessageLowerCase` With `semanticCommits` pr- and commit-titles will by default (`"auto"`) be converted to all-lowercase. Set this to `"never"` to leave the titles untouched, allowing uppercase characters in semantic commit titles. ## `commitMessagePrefix` This is used to alter `commitMessage` and `prTitle` (which also affects how it’s displayed in the Dependency Dashboard) without needing to copy/paste the whole string. The “prefix” is usually an automatically applied semantic commit prefix, but it can also be statically configured. ## `commitMessageSuffix` This is used to add a suffix to commit messages. Usually left empty except for internal use (multiple base branches, and vulnerability alerts). ## `commitMessageTopic` You can use `commitMessageTopic` to change the `commitMessage` and `prTitle` without copy/pasting the whole string. The “topic” usually refers to the dependency being updated, for example: `"dependency react"`. We recommend you use `matchManagers` and `commitMessageTopic` in a `packageRules` array to set the commit message topic, like this: ``` { "packageRules": [ { "matchManagers": ["github-actions"], "commitMessageTopic": "{{depName}}" } ] } ``` ## `composerIgnorePlatformReqs` By default, Renovate will ignore Composer platform requirements as the PHP platform used by Renovate most probably won’t match the required PHP environment of your project as configured in your `composer.json` file. Composer `2.2` and up will be run with `--ignore-platform-req='ext-*' --ignore-platform-req='lib-*'`, which ignores extension and library platform requirements but not the PHP version itself and should work in most cases. Older Composer versions will be run with `--ignore-platform-reqs`, which means that all platform constraints (including the PHP version) will be ignored by default. This can result in updated dependencies that are not compatible with your platform. To customize this behavior, you can explicitly ignore platform requirements (for example `ext-zip`) by setting them separately in this array. Each item will be added to the Composer command with `--ignore-platform-req`, resulting in it being ignored during its invocation. Note that this requires your project to use Composer V2, as V1 doesn’t support excluding single platform requirements. The used PHP version will be guessed automatically from your `composer.json` definition, so `php` should not be added as explicit dependency. If an empty array is configured, Renovate uses its default behavior. Set to `null` (not recommended) to fully omit `--ignore-platform-reqs/--ignore-platform-req` during Composer invocation. This requires the Renovate image to be fully compatible with your Composer platform requirements in order for the Composer invocation to succeed, otherwise Renovate will fail to create the updated lock file. The Composer output should inform you about the reasons the update failed. ## `confidential` If enabled, all issues created by Renovate are set as confidential, even in a public repository. !!! note The Dependency Dashboard issue will also be confidential. By default issues created by Renovate are visible to all users. !!! note This option is applicable to GitLab only. ## `configMigration` If enabled, Renovate raises a pull request when it needs to migrate the Renovate config file. Renovate only performs `configMigration` on `.json` and `.json5` files. We’re adding new features to Renovate bot often. Often you can keep using your Renovate config and use the new features right away. But sometimes you need to update your Renovate configuration. To help you with this, Renovate will create config migration pull requests, when you enable `configMigration`. Example: After we changed the [`baseBranchPatterns`](#basebranchpatterns) feature, the Renovate configuration migration pull request would make this change: ``` { - "baseBranch": "main" + "baseBranchPatterns": ["main"] } ``` !!! warning The `configMigration` feature writes plain JSON for `.json` files, and JSON5 for `.json5` files. Renovate may downgrade JSON5 content to plain JSON. When downgrading JSON5 to JSON Renovate may also remove the JSON5 comments. This can happen because Renovate wrongly converts JSON5 to JSON, thus removing the comments. For more details, read the [config migration documentation](./config-migration.md). ## `configWarningReuseIssue` If no existing issue is found, Renovate’s default behavior is to create a new Config Warning issue. Accordingly, you’ll get a new issue each time you have a Config Warning, although never more than one open at a time. Configure this option to `true` if you prefer Renovate to reopen any found matching closed issue whenever there is a config warning. The downside of this is that you may end up with a very old issue getting “recycled” each time and it will sort older than others. ## `constraints` Constraints are used in package managers which use third-party tools to update “artifacts” like lock files or checksum files. Typically, the constraint is detected automatically by Renovate from files within the repository and there is no need to manually configure it. Constraints are also used to manually restrict which _datasource_ versions are possible to upgrade to based on their language support. For now this datasource constraint feature only supports `python`, other compatibility restrictions will be added in the future. ``` { "constraints": { "python": "2.7" } } ``` If you need to _override_ constraints that Renovate detects from the repository, wrap it in the [global self-hosted configuration’s `force` object](./self-hosted-configuration.md#force) like so: ``` module.exports = { force: { constraints: { node: '< 15.0.0', }, }, }; ``` The following `constraints` are available to specify which package managers/language constraints/tools Renovate will install for your repository: !!! note When using [`binarySource=global`](./self-hosted-configuration.md#binarysource), the `constraints` options do not take effect. Additionally, there are several additional constraints that can be specified: !!! note Make sure not to mix this up with the term `compatibility`, which Renovate uses in the context of version releases, e.g. if a Docker image is `node:12.16.0-alpine` then the `-alpine` suffix represents `compatibility`. ## `constraintsFiltering` This option controls whether Renovate filters new releases based on configured or detected `constraints`. Renovate supports two options: - `none`: No release filtering (all releases allowed) - `strict`: If the release’s constraints match the package file constraints, then it’s included More advanced filtering options may come in future. There must be a `constraints` object in your Renovate config, or constraints detected from package files, for this to work. Additionally, the “datasource” within Renovate must be capable of returning `constraints` values about each package’s release. This feature is limited to the following datasources: - `crate` - `go` - `jenkins-plugins` - `npm` - `packagist` - `pub` - `pypi` - `rubygems` Sometimes when using private registries they may omit constraints information, which then is another reason such filtering may not work even if the datasource and corresponding default public registry supports it. !!! warning Enabling this feature may result in many package updates being filtered out silently. See below for a description of how it works. !!! warning Enabling this feature when using [`binarySource=global`](./self-hosted-configuration.md#binarysource) can lead to situations where Renovate suggests updates that it cannot then update, as it does not have the right tool versions installed. When `constraintsFiltering=strict`, the following logic applies: - Are there `constraints` for this repository, either detected from source or from config? - Does this package’s release declare constraints of its own (e.g. `engines` in Node.js)? - If so, filter out this release unless the repository constraint is a _subset_ of the release constraint Here are some examples: Your repo engines.node Dependency release engines.node Result `18` `16 || 18` allowed `^18.10.0` `>=18` allowed `^16.10.0 || >=18.0.0` `>= 16.0.0` allowed `>=16` `16 || 18` filtered `16` `^16.10.0` filtered When using with `npm`, we recommend you: - Use `constraintsFiltering` on `dependencies`, not `devDependencies` (usually you do not need to be strict about development dependencies) - Do _not_ enable `rollbackPrs` at the same time (otherwise your _current_ version may be rolled back if it’s incompatible) ## `constraintsVersioning` Use `constraintsVersioning` to override the versioning scheme used when filtering releases by specific constraint names with [`constraintsFiltering`](#constraintsfiltering). !!! note Each key must be an [additional constraint name](#constraints) (i.e. not a tool name), and each value must be a valid versioning scheme ID. Datasources that support constraints filtering may set sensible defaults for their constraints. You can override these defaults in your Renovate config. For example, to use a SemVer-style versioning scheme when defining the `rubygems` constraint: ``` { "constraints": { "rubygems": "^1.3" }, "constraintsVersioning": { "rubygems": "semver-coerced" } } ``` ## `customDatasources` Use `customDatasources` to fetch releases from APIs or statically hosted sites and Renovate has no own datasource. These datasources can be referred by `customManagers` or can be used to overwrite default datasources. For more details see the [`custom` datasource documentation](modules/datasource/custom/index.md). ### `customDatasources.defaultRegistryUrlTemplate` This field is used to build a `registryUrl` for the dependency. It is not needed if either: - The dependency can be found with the default `registryUrls` of the datasource (e.g. npmjs registry if the datasource is `npm`), or - The matching groups you specified as part of the matching already include a `registryUrl` group As this is a template it can be dynamically set. E.g. add the `packageName` as part of the URL: ``` { customDatasources: { foo: { defaultRegistryUrlTemplate: 'https://example.foo.bar/v1/{{ packageName }}', }, }, } ``` ### `customDatasources.format` Defines which format the API is returning. Currently `json` or `plain` are supported, see the `custom` [datasource documentation](modules/datasource/custom/index.md) for more information. ### `customDatasources.transformTemplates` `transformTemplates` is a list of [jsonata rules](https://docs.jsonata.org/simple) which get applied serially. Use this if the API does not return a Renovate compatible schema. ## `customManagers` Use `customManagers`(previously `regexManagers`) entries to configure the custom managers in Renovate. You can define custom managers to handle: - Proprietary file formats or conventions - Popular file formats not yet supported as a manager by Renovate Renovate has two custom managers: Custom manager Matching engine `regex` Regular Expression, with named capture groups. `jsonata` JSONata query. To use a custom manager, you must give Renovate this information: 1. `managerFilePatterns`: regex/glob pattern of the file to extract deps from 2. `matchStrings`: `regex` patterns or `jsonata` queries used to process the file The `matchStrings` must capture/extract the following three fields: - `datasource` - `depName` and / or `packageName` - `currentValue` Alternatively, you could also use corresponding templates (e.g. `depNameTemplate`) for these fields. But, we recommend you use only _one_ of these methods, or you’ll get confused. Also, we recommend you explicitly set which `versioning` Renovate should use. Renovate defaults to `semver-coerced` versioning if _both_ condition are met: - The `versioning` field is missing in the custom manager config - The Renovate datasource does _not_ set its own default versioning For more details and examples regarding each custom manager, see our documentation for the [`regex` manager](modules/manager/regex/index.md) and the [`JSONata` manager](modules/manager/jsonata/index.md). For template fields, use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. !!! tip Look at our [Custom Manager Presets](./presets-customManagers.md), they may have what you need. ### `customManagers.autoReplaceStringTemplate` Allows overwriting how the matched string is replaced. This allows for some migration strategies. E.g. moving from one Docker image repository to another one. ``` # The image of the service //: image: my.old.registry/aRepository/andImage:1.18-alpine ``` ``` { "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/values.yaml$/"], "matchStrings": [ "image:\\s+(?my\\.old\\.registry/aRepository/andImage):(?[^\\s]+)" ], "depNameTemplate": "my.new.registry/aRepository/andImage", "autoReplaceStringTemplate": "image: {{{depName}}}:{{{newValue}}}", "datasourceTemplate": "docker" } ] } ``` This will lead to following update where `1.21-alpine` is the newest version of `my.new.registry/aRepository/andImage`: ``` # The image of the service //: image: my.new.registry/aRepository/andImage:1.21-alpine ``` !!! note Can only be used with the custom regex manager. ### `customManagers.currentValueTemplate` If the `currentValue` for a dependency is not captured with a named group then it can be defined in config using this field. It will be compiled using Handlebars and the regex `groups` result. ### `customManagers.customType` It specifies which custom manager to use. There are two available options: `regex` and `jsonata`. Example: ``` { "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/values.yaml$/"], "matchStrings": [ "ENV .*?_VERSION=(?.*) # (?.*?)/(?.*?)\\s" ] } ] } ``` ``` { "customManagers": [ { "customType": "jsonata", "fileFormat": "json", "managerFilePatterns": ["/file.json/"], "matchStrings": [ "packages.{ \"depName\": package, \"currentValue\": version }" ], "datasourceTemplate": "github-tags" } ] } ``` ### `customManagers.datasourceTemplate` If the `datasource` for a dependency is not captured with a named group, then it can be defined in config using this field. It will be compiled using Handlebars and the regex `groups` result. ### `customManagers.depNameTemplate` If `depName` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field. It will be compiled using Handlebars and the regex `groups` result. ### `customManagers.depTypeTemplate` If `depType` cannot be captured with a named capture group in `matchString` then it can be defined manually using this field. It will be compiled using Handlebars and the regex `groups` result. ### `customManagers.extractVersionTemplate` If `extractVersion` cannot be captured with a named capture group in `matchString`, then it can be defined manually using this field. It will be compiled using Handlebars and the regex `groups` result. ### `customManagers.fileFormat` !!! note Can only be used with the custom jsonata manager. It specifies the syntax of the package file that’s managed by the custom `jsonata` manager. This setting helps the system correctly parse and interpret the configuration file’s contents. Only the `json`, `toml` and `yaml` formats are supported. `yaml` files are parsed as multi document YAML files. ``` { "customManagers": [ { "customType": "jsonata", "fileFormat": "json", "managerFilePatterns": ["/.renovaterc/"], "matchStrings": [ "packages.{ 'depName': package, 'currentValue': version }" ], "datasourceTemplate": "github-tags" } ] } ``` ``` { "customManagers": [ { "customType": "jsonata", "fileFormat": "yaml", "managerFilePatterns": ["/file.yml/"], "matchStrings": [ "packages.{ 'depName': package, 'currentValue': version }" ], "datasourceTemplate": "github-tags" } ] } ``` ``` { "customManagers": [ { "customType": "jsonata", "fileFormat": "toml", "managerFilePatterns": ["/file.toml/"], "matchStrings": [ "packages.{ 'depName': package, 'currentValue': version }" ], "datasourceTemplate": "github-tags" } ] } ``` ### `customManagers.matchStrings` Each `matchStrings` must be one of the following: 1. A valid regular expression, which may optionally include named capture groups (if using `customType=regex`) 2. Or, a valid, escaped [JSONata](https://docs.jsonata.org/overview.html) query (if using `customType=json`) Example: ``` { "matchStrings": [ "ENV .*?_VERSION=(?.*) # (?.*?)/(?.*?)\\s" ] } ``` ``` { "matchStrings": [ "packages.{ \"depName\": package, \"currentValue\": version }" ] } ``` !!! note You do not need to add leading and trailing slashes in `matchStrings`. ### `customManagers.matchStringsStrategy` `matchStringsStrategy` controls behavior when multiple `matchStrings` values are provided. Three options are available: - `any` (default) - `recursive` - `combination` !!! note `matchStringsStrategy` can only be used in a custom regex manager config! #### any Each provided `matchString` will be matched individually to the content of the `packageFile`. If a `matchString` has multiple matches in a file each will be interpreted as an independent dependency. As example the following configuration will update all three lines in the Dockerfile. ``` { "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/^Dockerfile$/"], "matchStringsStrategy": "any", "matchStrings": [ "ENV [A-Z]+_VERSION=(?.*) # (?.*?)/(?.*?)(\\&versioning=(?.*?))?\\s", "FROM (?\\S*):(?\\S*)" ], "datasourceTemplate": "docker" } ] } ``` ``` FROM amd64/ubuntu:24.04 ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node ``` #### recursive If using `recursive` the `matchStrings` will be looped through and the full match of the last will define the range of the next one. This can be used to narrow down the search area to prevent multiple matches. But the `recursive` strategy still allows the matching of multiple dependencies as described below. All matches of the first `matchStrings` pattern are detected, then each of these matches will be used as basis for the input for the next `matchStrings` pattern, and so on. If the next `matchStrings` pattern has multiple matches then it will split again. This process will be followed as long there is a match plus a next `matchingStrings` pattern is available. Matched groups will be available in subsequent matching layers. This is an example how this can work. The first custom manager will only upgrade `grafana/loki` as looks for the `backup` key then looks for the `test` key and then uses this result for extraction of necessary attributes. But the second custom manager will upgrade both definitions as its first `matchStrings` matches both `test` keys. ``` { "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/^example.json$/"], "matchStringsStrategy": "recursive", "matchStrings": [ "\"backup\":\\s*{[^}]*}", "\"test\":\\s*\\{[^}]*}", "\"name\":\\s*\"(?.*)\"[^\"]*\"type\":\\s*\"(?.*)\"[^\"]*\"value\":\\s*\"(?.*)\"" ], "datasourceTemplate": "docker" }, { "customType": "regex", "managerFilePatterns": ["/^example.json$/"], "matchStringsStrategy": "recursive", "matchStrings": [ "\"test\":\\s*\\{[^}]*}", "\"name\":\\s*\"(?.*)\"[^\"]*\"type\":\\s*\"(?.*)\"[^\"]*\"value\":\\s*\"(?.*)\"" ], "datasourceTemplate": "docker" } ] } ``` ``` { "backup": { "test": { "name": "grafana/loki", "type": "docker", "value": "1.6.1" } }, "setup": { "test": { "name": "python", "type": "docker", "value": "3.9.0" } } } ``` #### combination You may use this option to combine the values of multiple lines inside a file. You can combine multiple lines with `matchStringStrategy` values, but the `combination` approach is less susceptible to white space or line breaks stopping a match. `combination` can only match _one_ dependency per file. To update multiple dependencies with `combination` you must define multiple custom managers. Matched group values will be merged to form a single dependency. ``` { "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/^main.yml$/"], "matchStringsStrategy": "combination", "matchStrings": [ "prometheus_image:\\s*\"(?.*)\"\\s*//", "prometheus_version:\\s*\"(?.*)\"\\s*//" ], "datasourceTemplate": "docker" }, { "customType": "regex", "managerFilePatterns": ["/^main.yml$/"], "matchStringsStrategy": "combination", "matchStrings": [ "thanos_image:\\s*\"(?.*)\"\\s*//", "thanos_version:\\s*\"(?.*)\"\\s*//" ], "datasourceTemplate": "docker" } ] } ``` ``` prometheus_image: "prom/prometheus" // a comment prometheus_version: "v2.21.0" // a comment ------ thanos_image: "prom/prometheus" // a comment thanos_version: "0.15.0" // a comment ``` In the above example, each custom manager will match a single dependency each. ### `customManagers.packageNameTemplate` `packageName` is used for looking up dependency versions. It will be compiled using Handlebars and the regex `groups` result. It will default to the value of `depName` if left unconfigured/undefined. ### `customManagers.registryUrlTemplate` If the `registryUrls` for a dependency is not captured with a named group then it can be defined in config using this field. It will be compiled using Handlebars and the regex `groups` result. ### `customManagers.versioningTemplate` If the `versioning` for a dependency is not captured with a named group then it can be defined in config using this field. It will be compiled using Handlebars and the regex `groups` result. ## `customizeDashboard` You may use the `customizeDashboard` object to customize the Dependency Dashboard. Supported fields: - `repoProblemsHeader`: This field will replace the header of the Repository Problems in the Dependency Dashboard issue. ## `defaultRegistryUrls` Override a datasource’s default registries with this config option. The datasources’s `customRegistrySupport` value must be `true` for the config option to work. Default registries are only used when both: - The manager did not extract any `registryUrls` values, and - No `registryUrls` values have been applied via config, such as `packageRules` Think of `defaultRegistryUrls` as a way to specify the “fallback” registries for a datasource, for use when no `registryUrls` are extracted or configured. Compare that to `registryUrls`, which are a way to _override_ registries. ## `dependencyDashboard` Starting from version `v26.0.0` the “Dependency Dashboard” is enabled by default as part of the commonly-used `config:recommended` preset. To disable the Dependency Dashboard, add the preset `:disableDependencyDashboard` or set `dependencyDashboard` to `false`. ``` { "extends": ["config:recommended", ":disableDependencyDashboard"] } ``` Configuring `dependencyDashboard` to `true` will lead to the creation of a “Dependency Dashboard” issue within the repository. This issue has a list of all PRs pending, open, closed (unmerged) or in error. The goal of this issue is to give visibility into all updates that Renovate is managing. Examples of what having a Dependency Dashboard will allow you to do: - View all PRs in one place, rather than having to filter PRs by author - Rebase/retry multiple PRs without having to open each individually - Override any rate limiting (e.g. concurrent PRs) or scheduling to force Renovate to create a PR that would otherwise be suppressed - Recreate an unmerged PR (e.g. for a major update that you postponed by closing the original PR) !!! tip Enabling the Dependency Dashboard by itself does _not_ change the “control flow” of Renovate. Renovate still creates and manages PRs, and still follows your schedules and rate limits. The Dependency Dashboard gives you extra visibility and control over your updates. ## `dependencyDashboardApproval` This feature allows you to use Renovate’s Dependency Dashboard to force approval of updates before they are created. By setting `dependencyDashboardApproval` to `true` in config (including within `packageRules`), you can tell Renovate to wait for your approval from the Dependency Dashboard before creating a branch/PR. You can approve a pending PR by selecting the checkbox in the Dependency Dashboard issue. !!! tip When you set `dependencyDashboardApproval` to `true` the Dependency Dashboard issue will be created automatically, you do not need to turn on `dependencyDashboard` explicitly. You can configure Renovate to wait for approval for: - all package upgrades - major, minor, patch level upgrades - specific package upgrades - upgrades coming from specific package managers If you want to require approval for _all_ upgrades, set `dependencyDashboardApproval` to `true`: ``` { "dependencyDashboardApproval": true } ``` If you want to require approval for _major_ updates, set `dependencyDashboardApproval` to `true` within a `major` object: ``` { "major": { "dependencyDashboardApproval": true } } ``` If you want to approve _specific_ packages, set `dependencyDashboardApproval` to `true` within a `packageRules` entry where you have defined a specific package or pattern. ``` { "packageRules": [ { "matchPackageNames": ["/^@package-name/"], "dependencyDashboardApproval": true } ] } ``` ## `dependencyDashboardAutoclose` You can configure this to `true` if you prefer Renovate to close an existing Dependency Dashboard whenever there are no outstanding PRs left. ## `dependencyDashboardCategory` You can use this to categorize updates on the Dependency Dashboard. For example, to visually distinguish between production and dev updates, or to split between teams or logical parts of a monorepo. In practice this means it introduces an extra level of hierarchy/heading in the Dashboard’s markdown. To create a category for all CI/CD updates, you can configure a package rule like this: ``` { "packageRules": [ { "matchCategories": ["cd", "ci"], "dependencyDashboardCategory": ":hammer_and_wrench: Continuous Integration & Continuous Deployment" } ] } ``` When you configure categories, updates that do not match any of the configured categories will be grouped under the “Other” category. Some sections in the Dependency Dashboard also contain an action that applies to all updates in that section, such as to approve or rebase all updates. If there are categories in that section, the action will be put in an extra “All” category at the end of the section. This is to explicitly clarify that the action applies to all updates in the section, not to just a specific category. The Dependency Dashboard categories are only used to visually organize updates within the Dependency Dashboard issue. They do not impact grouping of updates into a single update like how e.g. `branchName` and `groupName` do. ## `dependencyDashboardFooter` ## `dependencyDashboardHeader` ## `dependencyDashboardLabels` The labels only get updated when the Dependency Dashboard issue updates its content and/or title. It is pointless to edit the labels, as Renovate bot restores the labels on each run. ## `dependencyDashboardOSVVulnerabilitySummary` Use this option to control if the Dependency Dashboard lists the OSV-sourced CVEs for your repository. You can choose from: - `none` (default) do not list any CVEs - `unresolved` list CVEs that have no fixes - `all` list all CVEs You will only get OSV-based vulnerability alerts for direct dependencies. This feature is independent of the `osvVulnerabilityAlerts` option. The source of these CVEs is [OSV.dev](https://osv.dev/). ## `dependencyDashboardReportAbandonment` Controls whether abandoned packages are reported in the dependency dashboard. When enabled (default), Renovate will display a collapsible section in the dependency dashboard listing packages that have been identified as abandoned based on the `abandonmentThreshold` configuration. This helps you identify dependencies that may need attention due to lack of maintenance. Set this to `false` if you prefer not to see abandoned packages in your dependency dashboard. ## `dependencyDashboardTitle` Configure this option if you prefer a different title for the Dependency Dashboard. ## `description` The description field can be used inside any configuration object to add a human-readable description of the object’s config purpose. A description field embedded within a preset is also collated as part of the onboarding description unless the preset only consists of presets itself. Presets which consist only of other presets have their own description omitted from the onboarding description because they will be fully described by the preset descriptions within. ## `digest` Add to this object if you wish to define rules that apply only to PRs that update digests. ## `draftPR` If you want the PRs created by Renovate to be considered as drafts rather than normal PRs, you could add this property to your `renovate.json`: ``` { "draftPR": true } ``` This option is evaluated at PR/MR creation time. !!! note Forgejo, Gitea and GitLab implement draft status by checking if the PR’s title starts with certain strings. This means that `draftPR` on Forgejo, Gitea and GitLab are incompatible with the legacy method of triggering Renovate to rebase a PR by renaming the PR to start with `rebase!`. ## `enabled` The most common use of `enabled` is if you want to turn Renovate’s functionality off, for some reason. For example, if you wanted to disable Renovate completely on a repository, you could make this your `renovate.json`: ``` { "enabled": false } ``` !!! note When Renovate is disabled on a repository entirely (via `enabled=false`), if Renovate runs against the repo again, it will perform a one-time cleanup of the repository, closing open Issues, PRs and deleting any branches. To disable Renovate for all `eslint` packages, you can configure a package rule like: ``` { "packageRules": [ { "matchPackageNames": ["eslint**"], "enabled": false } ] } ``` To disable Renovate for npm `devDependencies` but keep it for `dependencies` you could configure: ``` { "packageRules": [ { "matchManagers": ["npm"], "matchDepTypes": ["devDependencies"], "enabled": false } ] } ``` ## `enabledManagers` This is a way to allow only certain package managers and implicitly disable all others. Example: ``` { "enabledManagers": ["dockerfile", "npm"] } ``` To enable custom managers you will need to add `custom.` prefix before their names Example: ``` { "enabledManagers": ["custom.regex"] } ``` For the full list of available managers, see the [Supported Managers](modules/manager/index.md#supported-managers) documentation. ## `encrypted` Before you put any secrets in your repository configuration, encrypt the secrets. You can encrypt secrets using either a HTML page, or the CLI. To encrypt secrets for the Mend Renovate App for github.com with a HTML page, go to [app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt) and complete the form. If you’re self-hosting Renovate, you may download and edit the form, to use your own PGP public key. You can also encrypt secrets from the CLI, using the `curl`, `echo`, `jq`, `gpg`, `grep` and `tr` CLI programs. Here is an example: ``` curl https://app.renovatebot.com/renovate.pgp --output renovate.pgp echo -n '{"o":"your-organization", "r":"your-repository (optional)", "v":"your-secret-value"}' | jq . -c | gpg --encrypt -a --recipient-file renovate.pgp | grep -v '^----' | tr -d '\n' ``` The above script uses: - `curl` to download the Mend Renovate hosted app’s public key - `echo` to echo a JSON object into `jq` - `jq` to validate the JSON and then compact it - `gpg` to encrypt the contents - `grep` and `tr` to extract the encrypted payload which we will use The `jq` step is optional, you can leave it out if you wish. Its primary value is validating that the string you echo to `gpg` is valid JSON, and compact. !!! note Encrypted secrets must have at least an org/group scope, and optionally a repository scope. This means that Renovate will check if a secret’s scope matches the current repository before applying it, and warn/discard if there is a mismatch. Encrypted secrets usually have a single organization. But you may encrypt a secret with more than one organization, for example: `org1,org2`. This way the secret can be used in both the `org1` and `org2` organizations. For more information on how to use secrets for private packages, read [Private package support](./getting-started/private-packages.md). ## `env` This option allows users to specify explicit environment variables values. It is valid only as a top-level configuration option and not, for example, within `packageRules`. !!! warning The bot administrator must configure a list of allowed environment names in the [`allowedEnv`](./self-hosted-configuration.md#allowedenv) config option, before users can use those allowed names in the `env` option. Behavior: - This option only applies when Renovate runs package manager commands (e.g. `npm install`), within the `updateArtifacts()` function - Values set in the `env` configuration override corresponding environment variables, including those from `customEnvVariables` and `process.env` ``` { "env": { "SOME_ENV_VARIABLE": "SOME_STRING_VALUE" } } ``` ## `excludeCommitPaths` Be careful you know what you’re doing with this option. The initial intended use is to allow the user to exclude certain dependencies from being added/removed/modified when “vendoring” dependencies. Example: ``` { "excludeCommitPaths": ["vendor/golang.org/x/text/**"] } ``` The above would mean Renovate would not include files matching the above glob pattern in the commit, even if it thinks they should be updated. ## `expandCodeOwnersGroups` If configured, Renovate will expand any matching `CODEOWNERS` groups into a full list of group members and assign them individually instead of the group. This is particularly useful when combined with `assigneesSampleSize` and `assigneesFromCodeOwners`, so that only a subset of the Codeowners are assigned instead of the whole group. ## `extends` See [shareable config presets](./config-presets.md) for details. Learn how to use presets by reading the [Key concepts, Presets](./key-concepts/presets.md#how-to-use-presets) page. ## `extractVersion` Only use this config option when the raw version strings from the datasource do not match the expected format that you need in your package file. You must define a “named capture group” called `version` like in the examples below. For example, to extract only the major.minor precision from a GitHub release, the following would work: ``` { "packageRules": [ { "matchPackageNames": ["foo"], "extractVersion": "^(?v\\d+\\.\\d+)" } ] } ``` The above will change a raw version of `v1.31.5` to `v1.31`, for example. Alternatively, to strip a `release-` prefix: ``` { "packageRules": [ { "matchPackageNames": ["bar"], "extractVersion": "^release-(?.*)$" } ] } ``` The above will change a raw version of `release-2.0.0` to `2.0.0`, for example. A similar one could strip leading `v` prefixes: ``` { "packageRules": [ { "matchPackageNames": ["baz"], "extractVersion": "^v(?.*)$" } ] } ``` ## `fetchChangeLogs` Use this config option to configure changelogs/release notes fetching. The available options are: - `off` - disable changelogs fetching - `branch` - fetch changelogs while creating/updating branch - `pr`(default) - fetches changelogs while creating/updating pull-request Avoid setting `fetchChangeLogs=branch`, because this slows down Renovate. But if you’re embedding changelogs in commit information, you may use `fetchChangeLogs=branch`. Renovate can fetch changelogs when they are hosted on one of these platforms: - Bitbucket Cloud - Bitbucket Server / Data Center - GitHub (.com and Enterprise Server) - GitLab (.com and CE/EE) If you are running on any platform except `github.com`, you need to [configure a Personal Access Token](./getting-started/running.md#githubcom-token-for-changelogs-and-tools) to allow Renovate to fetch changelogs notes from `github.com`. You may use [package rules](#packagerules) to override the value of `fetchChangeLogs` for matching depeendencies, with later rules overriding earlier ones. The following re-enables fetching of changelogs when creating pull-requests for lodash updates. ``` { "fetchChangeLogs": "off", "packageRules": [ { "matchSourceUrls": ["https://github.com/lodash/lodash"], "fetchChangeLogs": "pr" } ] } ``` The following disables fetching of changelogs for any package in aws-sdk-go-v2, which can be time-consuming due to the repository’s large number of tags: ``` { "packageRules": [ { "matchSourceUrls": ["https://github.com/aws/aws-sdk-go-v2{/**,}"], "fetchChangeLogs": "off" } ] } ``` !!! note Renovate can only show changelogs from some platforms and some package managers. We’re planning improvements so that Renovate can show more changelogs. Read [issue 14138 on GitHub](https://github.com/renovatebot/renovate/issues/14138) to get an overview of the planned work. ## `filterUnavailableUsers` When this option is enabled PRs are not assigned to users that are unavailable. This option only works on platforms that support the concept of user availability. For now, you can only use this option on the GitLab platform. ## `followTag` For `followTag` to work, the datasource must support distribution streams or tags, like for example npm does. The main use case is to follow a pre-release tag of a dependency, say TypeScripts’s `"insiders"` build: ``` { "packageRules": [ { "matchPackageNames": ["typescript"], "followTag": "insiders" } ] } ``` If you’ve set a `followTag` then Renovate skips its normal major/minor/patch upgrade logic and stable/unstable consistency logic, and instead keeps your dependency version synced _strictly_ to the version in the tag. Renovate follows tags _strictly_, this can cause problems when a tagged stream is no longer maintained. For example: you’re following the `next` tag, but later the stream you actually want is called `stable` instead. If `next` is no longer getting updates, you must switch your `followTag` to `stable` to get updates again. ## `forkModeDisallowMaintainerEdits` Use `forkModeDisallowMaintainerEdits` to disallow maintainers from editing Renovate’s pull requests when in fork mode. If GitHub pull requests are created from a [fork repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo), the PR author can decide to allow upstream repository to modify the PR directly. Allowing maintainers to edit pull requests directly is helpful when Renovate pull requests require more changes. The reviewer can simply push to the pull request without having to create a new PR. [More details here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). You may decide to disallow edits to Renovate pull requests in order to workaround issues in Renovate where modified fork branches are not deleted properly: [See this issue](https://github.com/renovatebot/renovate/issues/16657). If this option is enabled, reviewers will need to create a new PR if more changes are needed. !!! note This option is only relevant if you set `forkToken`. ## `forkProcessing` By default, Renovate skips any forked repositories when in `autodiscover` mode. It even skips a forked repository that has a Renovate configuration file, because Renovate doesn’t know if that file was added by the forked repository. **Process a fork in `autodiscover` mode** If you want Renovate to run on a forked repository when in `autodiscover` mode then: - Ensure a `renovate.json` config exists with `"forkProcessing": "enabled"` in your repository, - Or run the CLI command with `--fork-processing=enabled` **Process a fork in other modes** If you’re running Renovate in some other mode, for example when giving a list of repositories to Renovate, but want to skip forked repositories: set `"forkProcessing": "disabled"` in your _global_ config. **When using the Mend Renovate App** The behavior of `forkProcessing` depends on how you allow Renovate to run on your account. **Renovate runs on all repositories** If you allow Renovate to run on all your repositories, `forkProcessing` will be `"disabled"`. To run Renovate on a fork: add `"forkProcessing": "enabled"` to the forked repository’s `renovate.json` file. **Renovate runs on selected repositories** If you allow Renovate to run on “Selected” repositories, `forkProcessing` will be `"enabled"` for each “Selected” repository. **Allowed filenames** Only the `onboardingConfigFileName` (which defaults to `renovate.json`) is supported for `forkProcessing`. You can’t use other filenames because Renovate only checks the default filename when using the Git-hosting platform’s API. ## `gitAuthor` You can customize the Git author that’s used whenever Renovate creates a commit, although we do not recommend this. When this field is unset (default), Renovate will use its platform credentials (e.g. token) to learn/discover its account’s git author automatically. !!! note If running as a GitHub App and using `platformCommit`, GitHub itself sets the git author in commits so you should not configure this field. The `gitAuthor` option accepts a [RFC5322](https://datatracker.ietf.org/doc/html/rfc5322)\-compliant string. It’s recommended to include a name followed by an email address, e.g. ``` Development Bot ``` !!! danger We strongly recommend that the Git author email you use is unique to Renovate. Otherwise, if another bot or human shares the same email and pushes to one of Renovate’s branches then Renovate will mistake the branch as unmodified and potentially force push over the changes. ## `gitIgnoredAuthors` Specify commit authors ignored by Renovate. This field accepts [RFC5322](https://datatracker.ietf.org/doc/html/rfc5322)\-compliant strings. By default, Renovate will treat any PR as modified if another Git author has added to the branch. When a PR is considered modified, Renovate won’t perform any further commits such as if it’s conflicted or needs a version update. If you have other bots which commit on top of Renovate PRs, and don’t want Renovate to treat these PRs as modified, then add the other Git author(s) to `gitIgnoredAuthors`. Example: ``` { "gitIgnoredAuthors": ["some-bot@example.org"] } ``` ## `gitLabIgnoreApprovals` Ignore the default project level approval(s), so that Renovate bot can automerge its merge requests, without needing approval(s). Under the hood, it creates a MR-level approval rule where `approvals_required` is set to `0`. This option works only when `automerge=true` and either `automergeType=pr` or `automergeType=branch`. Also, approval rules overriding should not be [prevented in GitLab settings](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/settings.html#prevent-editing-approval-rules-in-merge-requests). ## `goGetDirs` By default, Renovate will run `go get -d -t ./...` to update the `go.sum`. If you need to modify this path, for example in order to ignore directories, you can override the default `./...` value using this option: ``` { "goGetDirs": ["./some-project/", "./tools/..."] } ``` ## `group` The default configuration for groups are essentially internal to Renovate and you normally shouldn’t need to modify them. But you may _add_ settings to any group by defining your own `group` configuration object. ## `groupName` There are multiple cases where it can be useful to group multiple upgrades together. Internally Renovate uses this for branches such as “Pin Dependencies”, “Lock File Maintenance”, etc. Another example used previously is to group together all related `eslint` packages, or perhaps `angular` or `babel`. To enable grouping, you configure the `groupName` field to something non-null. The `groupName` field allows free text and does not have any semantic interpretation by Renovate. All updates sharing the same `groupName` will be placed into the same branch/PR. For example, to group all non-major devDependencies updates together into a single PR: ``` { "packageRules": [ { "matchDepTypes": ["devDependencies"], "matchUpdateTypes": ["patch", "minor"], "groupName": "devDependencies (non-major)" } ] } ``` !!! note Replacement updates will never be grouped. Lock file maintenance will never be grouped with other dependency updates. ## `groupSingleUpdates` !!! note This option was [recently made opt-in, instead of opt-out](https://github.com/renovatebot/renovate/pull/44168). ## `groupSlug` By default, Renovate will “slugify” the groupName to determine the branch name. For example if you named your group “devDependencies (non-major)” then the branchName would be `renovate/devdependencies-non-major`. If you wished to override this then you could configure like this: ``` { "packageRules": [ { "matchDepTypes": ["devDependencies"], "matchUpdateTypes": ["patch", "minor"], "groupName": "devDependencies (non-major)", "groupSlug": "dev-dependencies" } ] } ``` As a result of the above, the branchName would be `renovate/dev-dependencies` instead. !!! note You shouldn’t usually need to configure this unless you really care about your branch names. ## `hashedBranchLength` Some code hosting systems have restrictions on the branch name lengths, this option lets you get around these restrictions. You can set the `hashedBranchLength` option to a number of characters that works for your system and then Renovate will generate branch names with the correct length by hashing `additionalBranchPrefix` and `branchTopic`, and then truncating the hash so that the full branch name (including `branchPrefix`) has the right number of characters. Example: If you have set `branchPrefix: "deps-"` and `hashedBranchLength: 12` it will result in a branch name like `deps-5bf36ec` instead of the traditional pretty branch name like `deps-react-17.x`. ## `hostRules` The primary purpose of `hostRules` is to configure credentials for host authentication. You tell Renovate how to match against the host you need authenticated, and then you also tell it which credentials to use. The lookup keys for `hostRules` are: `hostType` and `matchHost`, both of which are optional. Supported credential fields are `token`, `username`, `password`, `timeout`, `enabled` and `insecureRegistry`. Example for configuring `docker` auth: ``` { "hostRules": [ { "matchHost": "docker.io", "username": "", "password": "" } ] } ``` If multiple `hostRules` match a request, then they will be applied in the following order/priority: 1. rules with only `hostType` specified 2. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) 3. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) To disable requests to a particular host, you can configure a rule like: ``` { "hostRules": [ { "matchHost": "registry.npmjs.org", "enabled": false } ] } ``` A preset alternative to the above is: ``` { "extends": [":disableHost(registry.npmjs.org)"] } ``` To match specific ports you have to add a protocol to `matchHost`: ``` { "hostRules": [ { "matchHost": "https://domain.com:9118", "enabled": false } ] } ``` !!! warning Using `matchHost` without a protocol behaves the same as if you had set no `matchHost` configuration. !!! note Disabling a host is only 100% effective if added to self-hosted config. Renovate currently still checks its _cache_ for results first before trying to connect, so if a public host is blocked in your repository config (e.g. `renovate.json`) then it’s possible you may get cached _results_ from that host if another repository using the same bot has successfully queried for the same dependency recently. ### `hostRules.abortIgnoreStatusCodes` This field can be used to configure status codes that Renovate ignores and passes through when `abortOnError` is set to `true`. For example to also skip 404 responses then configure the following: ``` { "hostRules": [ { "abortOnError": true, "abortIgnoreStatusCodes": [404] } ] } ``` !!! tip This field is _not_ mergeable, so the last-applied host rule takes precedence. ### `hostRules.abortOnError` Use this field to configure Renovate to abort runs for custom hosts. By default, Renovate will only abort for known public hosts, which has the downside that transient errors for other hosts can cause autoclosing of PRs. To abort Renovate runs for HTTP failures from _any_ host: ``` { "hostRules": [ { "abortOnError": true } ] } ``` To abort Renovate runs for any `docker` datasource failures: ``` { "hostRules": [ { "hostType": "docker", "abortOnError": true } ] } ``` To abort Renovate for errors for a specific `docker` host: ``` { "hostRules": [ { "matchHost": "docker.company.com", "abortOnError": true } ] } ``` When this field is enabled, Renovate will abort its run if it encounters either (a) any low-level http error (e.g. `ETIMEDOUT`) or (b) gets a response _not_ matching any of the configured `abortIgnoreStatusCodes` (e.g. `500 Internal Error`); ### `hostRules.artifactAuth` You may use this field whenever it is needed to only enable authentication for a specific set of managers. For example, using this option could be used whenever authentication using Git for private composer packages is already being handled through the use of SSH keys, which results in no need for also setting up authentication using tokens. ``` { "hostRules": [ { "hostType": "gitlab", "matchHost": "gitlab.myorg.com", "token": "abc123", "artifactAuth": ["composer"] } ] } ``` Supported artifactAuth and hostType combinations: artifactAuth hostTypes `composer` `gitlab`, `packagist`, `github`, `git-tags` ### `hostRules.authType` You may use the `authType` option to create a custom HTTP `authorization` header. For `authType` to work, you must also set your own `token`. Do not set `authType=Bearer`: it’s the default setting for Renovate anyway. Do not set a username or password when you’re using `authType`, as `authType` doesn’t use usernames or passwords. An example for npm basic auth with token: ``` { "hostRules": [ { "matchHost": "npm.custom.org", "token": "", "authType": "Basic" } ] } ``` This will generate the following header: `authorization: Basic `. To use a bare token in the authorization header (required by e.g. Hex) - use the `authType` “Token-Only”: ``` { "hostRules": [ { "matchHost": "https://hex.pm/api/repos/private_repo/", "token": "", "authType": "Token-Only" } ] } ``` This will generate the header `authorization: `. ### `hostRules.concurrentRequestLimit` Usually the default setting is fine, but you can use `concurrentRequestLimit` to limit the number of concurrent outstanding requests. You only need to adjust this setting if a datasource is rate limiting Renovate or has problems with the load. The limit will be set for any host it applies to. Example config: ``` { "hostRules": [ { "matchHost": "api.github.com", "concurrentRequestLimit": 2 } ] } ``` Use an exact host for `matchHost` and not a domain (e.g. `api.github.com` as shown above and not `github.com`). Do not combine with `hostType` in the same rule or it won’t work. ### `hostRules.dnsCache` Enable got [dnsCache](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#dnsCache) support. It uses [`lru-cache`](https://github.com/isaacs/node-lru-cache) with the `max` option set to `1000`. ### `hostRules.enableHttp2` Enable got [http2](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#http2) support. ### `hostRules.headers` You can provide a `headers` object that includes fields to be forwarded to the HTTP request headers. By default, all headers starting with “X-” are allowed. A bot administrator may configure an override for [`allowedHeaders`](./self-hosted-configuration.md#allowedheaders) to configure more permitted headers. `headers` value(s) configured in the bot admin `hostRules` (for example in a `config.js` file) are _not_ validated, so it may contain any header regardless of `allowedHeaders`. For example: ``` { "hostRules": [ { "matchHost": "https://domain.com/all-versions", "headers": { "X-custom-header": "secret" } } ] } ``` ### `hostRules.hostType` `hostType` is another way to filter rules and can be either a platform such as `github` and `bitbucket-server`, or it can be a datasource such as `docker` and `rubygems`. You usually don’t need to configure it in a host rule if you have already configured `matchHost` and only one host type is in use for those, as is usually the case. `hostType` can help for cases like an enterprise registry that serves multiple package types and has different authentication for each, although it’s often the case that multiple `matchHost` rules could achieve the same thing. ### `hostRules.httpsCertificate` Specifies the [Certificate chains](https://en.wikipedia.org/wiki/X.509#Certificate_chains_and_cross-certification) in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) for mTLS authentication. ### `hostRules.httpsCertificateAuthority` By default, Renovate uses the curated list of well-known [CA](https://en.wikipedia.org/wiki/Certificate_authority)s by Mozilla. You may use another Certificate Authority instead, by setting it in the `httpsCertificateAuthority` config option. ### `hostRules.httpsPrivateKey` Specifies the private key in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) for mTLS authentication. !!! warning Do _not_ put your private key into this field, to avoid losing confidentiality completely. You must use [secrets](./self-hosted-configuration.md#secrets) to pass it down securely instead. ### `hostRules.insecureRegistry` Enable this option to allow Renovate to connect to an [insecure Docker registry](https://docs.docker.com/registry/insecure/) that is HTTP only. This is insecure and is not recommended. Example: ``` { "hostRules": [ { "matchHost": "reg.insecure.com", "insecureRegistry": true } ] } ``` ### `hostRules.keepAlive` If enabled, this allows a single TCP connection to remain open for multiple HTTP(S) requests/responses. ### `hostRules.matchHost` This can be a base URL (e.g. `https://api.github.com`) or a hostname like `github.com` or `api.github.com`. If the value starts with `http(s)` then it will only match against URLs which start with the full base URL. Otherwise, it will be matched by checking if the URL’s hostname matches the `matchHost` directly or ends with it. When checking the end of the hostname, a single dot is prefixed to the value of `matchHost`, if one is not already present, to ensure it can only match against whole domain segments. The `matchHost` URL must be the same as the `registryUrl` set in `.npmrc`, or you’ll get authentication issues when the artifacts are updated when yarn or npm runs. ``` { "hostRules": [ { "matchHost": "https://gitlab.myorg.com/api/v4/packages/npm/", "token": "abc123" } ] } ``` The above corresponds with an `.npmrc` like the following: ``` registry=https://gitlab.myorg.com/api/v4/packages/npm/ ``` !!! note Values containing a URL path but missing a scheme will be prepended with ‘https://’ (e.g. `domain.com/path` → `https://domain.com/path`) ### `hostRules.maxRequestsPerSecond` In addition to `concurrentRequestLimit`, you can limit the maximum number of requests that can be made per one second. It can be used to set minimal delay between two requests to the same host. Fractional values are allowed, e.g. `0.25` means 1 request per 4 seconds. Default value `0` means no limit. Example config: ``` { "hostRules": [ { "matchHost": "api.github.com", "maxRequestsPerSecond": 2 } ] } ``` ### `hostRules.maxRetryAfter` A remote host may return a `4xx` response with a `Retry-After` header value, which indicates that Renovate has been rate-limited. Renovate may try to contact the host again after waiting a certain time, that’s set by the host. By default, Renovate tries again after the `Retry-After` header value has passed, up to a maximum of 60 seconds. If the `Retry-After` value is more than 60 seconds, Renovate will abort the request instead of waiting. You can configure a different maximum value in seconds using `maxRetryAfter`: ``` { "hostRules": [ { "matchHost": "api.github.com", "maxRetryAfter": 25 } ] } ``` ### `hostRules.readOnly` If the `readOnly` field is being set to `true` inside the host rule, it will match only against the requests that are known to be read operations. Examples are `GET` requests or `HEAD` requests, but also it could be certain types of GraphQL queries. This option could be used to avoid rate limits for certain platforms like GitHub or Bitbucket, by offloading the read operations to a different user. ``` { "hostRules": [ { "matchHost": "api.github.com", "readOnly": true, "token": "********" } ] } ``` If more than one token matches for a read-only request then the `readOnly` token will be given preference. ### `hostRules.timeout` Use this figure to adjust the timeout for queries. The default is 60s, which is quite high. To adjust it down to 10s for all queries, do this: ``` { "hostRules": [ { "timeout": 10000 } ] } ``` ## `ignoreDeprecated` By default, Renovate won’t update a dependency version to a deprecated release unless the current version was _itself_ deprecated. The goal of this is to make sure you don’t upgrade from a non-deprecated version to a deprecated one, only because it’s higher than the current version. If for some reason you wish to _force_ deprecated updates with Renovate, you can configure `ignoreDeprecated` to `false`, which we do not recommend for most situations. ## `ignoreDeps` The `ignoreDeps` configuration field allows you to define a list of dependency names to be ignored by Renovate. Currently it supports only “exact match” dependency names and not any patterns. e.g. to ignore both `eslint` and `eslint-config-base` you would add this to your config: ``` { "ignoreDeps": ["eslint", "eslint-config-base"] } ``` The above is the same as if you wrote this package rule: ``` { "packageRules": [ { "matchPackageNames": ["eslint", "eslint-config-base"], "enabled": false } ] } ``` ## `ignorePaths` Renovate will extract dependencies from every file it finds in a repository, unless that file is explicitly ignored. With this setting you can selectively ignore package files that would normally be “autodiscovered” and updated by Renovate. For instance if you have a project with an `"examples/"` directory you wish to ignore: ``` { "ignorePaths": ["**/examples/**"] } ``` Renovate’s default ignore is `node_modules` and `bower_components` only. If you are extending from the popular `config:recommended` preset then it adds ignore patterns for `vendor`, `examples`, `test(s)` and `fixtures` directories too. ## `ignorePlugins` Set this to `true` if running plugins causes problems. Applicable for Composer only for now. ## `ignorePresets` Use this if you are extending a complex preset but don’t want to use every “sub preset” that it includes. For example, consider this config: ``` { "extends": ["config:recommended"], "ignorePresets": ["group:monorepos"] } ``` It would take the entire `"config:recommended"` preset - which has a lot of sub-presets - but ignore the `"group:monorepos"` rule. ## `ignoreReviewers` By default, Renovate does not add assignees or reviewers to PRs which are configured for automerge. If tests have failed, Renovate then does add them, but only if the assignees and reviewers list is empty. In the case that a user is automatically added as reviewer (such as Renovate Approve bot) and you want to ignore it for the purpose of this decision, add it to the `ignoreReviewers` list. ``` { "reviewers": ["foo"], "ignoreReviewers": ["renovate-approve"] } ``` Please note that Reviewers are only added during creation of a PR, but are not modified afterwards. ## `ignoreScripts` By default, Renovate will disable package manager scripts. Allowing packager manager scripts is a risk: - Untrusted or compromised repository users could use package manager scripts to exploit the system where Renovate runs, and - Malicious package authors could use scripts to exploit a repository and Renovate system, for example to exfiltrate source code and secrets **No script execution on free Mend-hosted Renovate** The Mend Renovate App does not allow scripts to run. We do not plan to let users on free tiers run scripts, because the risk of abuse is too high. **Renovate Enterprise Cloud can be configured to run scripts** Scripts can be enabled for paying customers on Mend.io hosted apps. Please ask Mend.io sales about “Renovate Enterprise Cloud”. **Allowing scripts if self-hosting Renovate** If you are self-hosting Renovate, and want to allow Renovate to run any scripts: 1. Set the self-hosted config option [`allowScripts`](./self-hosted-configuration.md#allowscripts) to `true` in your bot/admin configuration 2. Set `ignoreScripts` to `false` for the package managers you want to allow to run scripts (only works for the supportedManagers listed in the table above) ## `ignoreTests` Currently Renovate’s default behavior is to only automerge if every status check has succeeded. Setting this option to `true` means that Renovate will ignore _all_ status checks. You can set this if you don’t have any status checks but still want Renovate to automerge PRs. Beware: configuring Renovate to automerge without any tests can lead to broken builds on your base branch, please think again before enabling this! ## `ignoreUnstable` By default, Renovate won’t update any package versions to unstable versions (e.g. `4.0.0-rc3`) unless the current version has the same `major.minor.patch` and was _already_ unstable (e.g. it was already on `4.0.0-rc2`). Renovate will also not “jump” unstable versions automatically, e.g. if you are on `4.0.0-rc2` and newer versions `4.0.0` and `4.1.0-alpha.1` exist then Renovate will update you to `4.0.0` only. If you need to force permanent unstable updates for a package, you can add a package rule setting `ignoreUnstable` to `false`. In that case you will usually also want to set `respectLatest` to `false` so that Renovate considers versions ahead of `latest`. Also check out the `followTag` configuration option above if you wish Renovate to keep you pinned to a particular release tag. ## `includePaths` If you wish for Renovate to process only select paths in the repository, use `includePaths`. Alternatively, if you need to _exclude_ certain paths in the repository then consider `ignorePaths` instead. If you are more interested in including only certain package managers (e.g. `npm`), then consider `enabledManagers` instead. ## `internalChecksAsSuccess` By default, internal Renovate checks such as `renovate/stability-days` are not counted towards a branch being “green” or not. This is primarily to prevent automerge when the only check is a passing Renovate check. Internal checks will always be counted/considered if they are in pending or failed states. If there are multiple passing checks for a branch, including non-Renovate ones, then this setting won’t make any difference. Change this setting to `true` if you want to use internal Renovate checks towards a passing branch result. ## `internalChecksFilter` This setting determines whether Renovate controls when and how filtering of internal checks are performed, particularly when multiple versions of the same update type are available. Currently this applies to the `minimumReleaseAge` check only. - `none`: No filtering will be performed, and the highest release will be used regardless of whether it’s pending or not - `strict`: All pending releases will be filtered. PRs will be skipped unless a non-pending version is available - `flexible`: Similar to strict, but in the case where all versions are pending then a PR will be created with the highest pending version The `flexible` mode can result in “flapping” of Pull Requests, for example: a pending PR with version `1.0.3` is first released but then downgraded to `1.0.2` once it passes `minimumReleaseAge`. We recommend that you use the `strict` mode, and enable the `dependencyDashboard` so that you can see suppressed PRs. ## `keepUpdatedLabel` On supported platforms you may add a label to a PR so that Renovate recreates/rebases the PR when the branch falls behind the base branch. Adding the `keepUpdatedLabel` label to a PR makes Renovate behave as if `rebaseWhen` were set to `behind-base-branch`, but only for the given PR. Renovate does _not_ remove the label from the PR after it finishes rebasing. This is different from the `rebaseLabel` option, where Renovate _removes_ the label from the PR after rebasing. `keepUpdatedLabel` can be useful when you have approved certain PRs and want Renovate to keep the PRs up-to-date until you’re ready to merge them. The setting `keepUpdatedLabel` is best used in this scenario: - By default, you configure `rebaseWhen` to `never` or `conflicted` to reduce rebasing - Sometimes, you want Renovate to keep specific PRs up-to-date with their base branch (equivalent to `rebaseWhen=behind-base-branch`) ## `labels` By default, Renovate won’t add any labels to PRs. If you want Renovate to add labels to PRs it creates then define a `labels` array of one or more label strings. If you want the same label(s) for every PR then you can configure it at the top level of config. However you can also fully override them on a per-package basis. Consider this example: ``` { "labels": ["dependencies"], "packageRules": [ { "matchPackageNames": ["/eslint/"], "labels": ["linting"] } ] } ``` With the above config, every PR raised by Renovate will have the label `dependencies` while PRs containing `eslint`\-related packages will instead have the label `linting`. Behavior details: - On Forgejo, Gitea, GitHub and GitLab: Renovate will keep PR labels in sync with configured labels, provided that no other user or bot has made changes to the labels after PR creation. If labels are changed by any other account, Renovate will stop making further changes. - For other platforms, Renovate will add labels only at time of PR creation and not update them after that. The `labels` array is non-mergeable, meaning if multiple `packageRules` match then Renovate uses the last value for `labels`. If you want to add/combine labels, use the `addLabels` config option, which is mergeable. !!! note Keep your labels within the maximum character limit for your Git hosting platform. Renovate usually truncates labels to 50 characters, except for GitLab, which has a 255 character limit. ## `lockFileMaintenance` You can use `lockFileMaintenance` to refresh lock files to keep them up-to-date. When Renovate performs `lockFileMaintenance` it deletes the lock file and runs the relevant package manager. That package manager creates a new lock file, where all dependency versions are updated to the latest version. Renovate then commits that lock file to the update branch and creates the lock file update PR. Supported lock files: Support for new lock files may be added via feature request. By default, `lockFileMaintenance` is disabled. To enable `lockFileMaintenance` add this to your configuration: ``` { "lockFileMaintenance": { "enabled": true } } ``` To reduce “noise” in the repository, Renovate performs `lockFileMaintenance` `"before 4am on monday"`, i.e. to achieve once-per-week semantics. Depending on its running schedule, Renovate may run a few times within that time window - even possibly updating the lock file more than once - but it hopefully leaves enough time for tests to run and automerge to apply, if configured. ## `logLevelRemap` This option allows you to remap log levels for specific messages. Be careful with remapping `warn` or `error` messages to lower log levels, as it may hide important information. ``` { "logLevelRemap": [ { "matchMessage": "/^pip-compile:/", "newLogLevel": "info" }, { "matchMessage": "Package lookup error", "newLogLevel": "warn" }, { "matchMessage": "/^Please upgrade the version of Node.js/", "newLogLevel": "info" } ] } ``` ### `logLevelRemap.matchMessage` Use `matchMessage` to match the log message you want to remap. Accepts a string or regex pattern. ### `logLevelRemap.newLogLevel` For log level remapping, `newLogLevel` will set for the particular log message: ``` { "logLevelRemap": [ { "matchMessage": "/Error executing maven wrapper update command/", "newLogLevel": "warn" } ] } ``` ## `major` Add to this object if you wish to define rules that apply only to major updates. ## `maxMajorIncrement` This is particularly useful for preventing upgrades from [SemVer](https://semver.org/)\-based versions to [CalVer](https://calver.org/)\-based ones. For example, if you’re on version `19.0.0`, Renovate will upgrade to `22.0.0` but filter out versions like `999.0.0` and `2025.0.0`. You can use `packageRules` to customize this behavior for specific packages: ``` { "packageRules": [ { "description": "Allow to upgrade Home Assistant from 0.x to 2025.x", "matchPackageNames": ["homeassistant"], "maxMajorIncrement": 0 } ] } ``` The above allows unlimited major version upgrades by setting `maxMajorIncrement` to `0`. Alternatively, to limit major upgrades to within 10 versions: ``` { "packageRules": [ { "description": "Limit xmldoc major upgrades to within 10 versions", "matchPackageNames": ["xmldoc"], "maxMajorIncrement": 10 } ] } ``` ## `managerFilePatterns` Formerly known as `fileMatch`, which supported regex-only. `managerFilePatterns` supports both regex and glob patterns. Any existing config containing `fileMatch` patterns will be automatically migrated. Do not use the below guide for `fileMatch` if you are using an older version of Renovate. `managerFilePatterns` tells Renovate which repository files to parse and extract. Patterns in the user config are _added_ to the default values, they do not replace the default values. The default `managerFilePatterns` patterns can not be removed. If you need to include, or exclude, specific paths then use the [`ignorePaths`](#ignorepaths) or [`includePaths`](#includepaths) instead. Some managers have sensible defaults. For example, the Go manager looks for _any_ `go.mod` file by default, which covers most cases without extra configuration. At other times, the possible files is too vague for Renovate to have any default. For example, Kubernetes manifests can exist in any `*.yaml` file. We do not want Renovate to parse every YAML file in every repository, just in case _some_ of them have a Kubernetes manifest. Therefore Renovate’s default `managerFilePatterns` for the `kubernetes` manager is an empty array (`[]`). Because the array is empty, you as user must tell Renovate which directories/files to check. Finally, there are cases where Renovate’s default `managerFilePatterns` is good, but you may be using file patterns that a bot couldn’t possibly guess. For example, Renovate’s default `managerFilePatterns` for `Dockerfile` is `['/(^|/|\\.)([Dd]ocker|[Cc]ontainer)file$/', '/(^|/)([Dd]ocker|[Cc]ontainer)file[^/]*$/']`. This will catch files like `backend/Dockerfile`, `prefix.Dockerfile` or `Dockerfile-suffix`, but it will miss files like `ACTUALLY_A_DOCKERFILE.template`. Because `managerFilePatterns` is “mergeable”, you can add the missing file to the `filePattern` like this: ``` { "dockerfile": { "managerFilePatterns": ["/^ACTUALLY_A_DOCKERFILE\\.template$/"] } } ``` You must configure `managerFilePatterns` _inside_ a manager object. In the example above, the manager object is the `dockerfile`. For reference, here is a [list of supported managers](modules/manager/index.md#supported-managers). ## `milestone` If set to the number of an existing [GitHub milestone](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones), Renovate will add that milestone to its PR. Renovate will only add a milestone when it _creates_ the PR. ``` { "milestone": 12 } ``` ## `minimumGroupSize` If set to to a positive value x then branch creation will be postponed until x or more updates are available in the branch. This applies to both these scenarios: - Grouped updates with more than one dependency updated together, and - Branches with multiple updates of the same dependency (e.g. in multiple files) Example: ``` { "packageRules": [ { "description": "We need to update Node in two places - always wait until both upgrades are available", "matchDepNames": ["node"], "groupName": "Node.js", "minimumGroupSize": 3 } ] } ``` ## `minimumReleaseAge` `minimumReleaseAge` is a feature that requires Renovate to wait for a specified amount of time before suggesting a dependency update. !!! note Minimum Release Age has [a separate documentation page](./key-concepts/minimum-release-age.md) for more in-depth documentation about the functionality. This also includes documentation that was previously in this section, regarding how to specify release timestamps for custom registries. If `minimumReleaseAge` is set to a time duration _and_ the update has a release timestamp header, then Renovate will check if the set duration has passed. This behaviour can be changed using [`minimumReleaseAgeBehaviour`](#minimumreleaseagebehaviour). Note: Renovate will wait for the set duration to pass for each **separate** version. Renovate does not wait until the package has seen no releases for x time-duration(`minimumReleaseAge`). Do _not_ use `minimumReleaseAge` to slow down fast releasing project updates. Instead setup a custom `schedule` for that package, read [our selective-scheduling help](./noise-reduction.md#selective-scheduling) to learn how. When the time passed since the release is _less_ than the set `minimumReleaseAge`: Renovate adds a “pending” status check to that update’s branch. After enough days have passed: Renovate replaces the “pending” status with a “passing” status check. The datasource that Renovate uses must have a release timestamp for the `minimumReleaseAge` config option to work. Some datasources may have a release timestamp, but in a format Renovate does not support. In those cases a feature request needs to be implemented. You can confirm if your datasource supports the release timestamp by viewing [the documentation for the given datasource](./modules/datasource/index.md). !!! note Configuring this option will add a `renovate/stability-days` option to the status checks. !!! note As of Renovate 42.19.5, using `minimumReleaseAge=0 days` is treated the same as `minimumReleaseAge=null`. Examples of how you can use `minimumReleaseAge`: #### Suppress branch/PR creation for X days If you use `minimumReleaseAge=3 days`, `prCreation="not-pending"` and `internalChecksFilter="strict"` then Renovate only creates branches when 3 (or more days) have passed since the version was released. We recommend you set `dependencyDashboard=true`, so you can see these pending PRs. #### Prevent holding broken npm packages npm packages less than 72 hours (3 days) old can be unpublished from the npm registry, which could result in a service impact if you have already updated to it. Set `minimumReleaseAge` to `3 days` for npm packages to prevent relying on a package that can be removed from the registry: ``` { "packageRules": [ { "matchDatasources": ["npm"], "minimumReleaseAge": "3 days" } ] } ``` #### Await X time duration before Automerging If you enable `automerge` _and_ `minimumReleaseAge`, Renovate Renovate will create PRs immediately, but only automerge them when the `minimumReleaseAge` time-duration has passed. It’s recommended to also apply `prCreation="not-pending"` and `internalChecksFilter="strict"` to make sure that branches and PRs are only created after the `minimumReleaseAge` has passed. Renovate adds a “renovate/stability-days” pending status check to each branch/PR. This pending check prevents the branch going green to automerge before the time has passed. ## `minimumReleaseAgeBehaviour` When `minimumReleaseAge` is set to a time duration, the `minimumReleaseAgeBehaviour` will be used to control whether the release timestamp is required. When set to `timestamp-required`, this version is not treated stable unless there is release timestamp, and that release timestamp is past the [`minimumReleaseAge`](#minimumreleaseage). When set to `timestamp-optional`, Renovate will treat a release without a releaseTimestamp as stable. This only applies when used with [`minimumReleaseAge`](#minimumreleaseage). ## `minor` Add to this object if you wish to define rules that apply only to minor updates. ## `mode` This configuration option was created primarily for use with Mend’s hosted app, but can also be useful for some self-hosted use cases. It enables a new `silent` mode to allow repos to be scanned for updates _and_ for users to be able to request such updates be opened in PRs _on demand_ through the Mend UI, without needing the Dependency Dashboard issue in the repo. Although similar, the options `mode=silent` and `dryRun` can be used together. When both are configured, `dryRun` takes precedence, so for example PRs won’t be created. Configuring `silent` mode is quite similar to `dryRun=lookup` except: - It will bypass onboarding checks (unlike when performing a dry run on a non-onboarded repo) similar to `requireConfig=optional` - It can create branches/PRs if `checkedBranches` is set - It will keep any existing branches up-to-date (e.g. ones created previously using `checkedBranches`) When in `silent` mode Renovate will: - _not_ create or update any Issue: even the Dependency Dashboard or Config Warning Issues will stay as-is - _not_ prune or close any existing Issues - _not_ create any Config Migration PRs, even if you explicitly enabled Config Migration PRs in your Renovate config ## `npmToken` See [Private npm module support](./getting-started/private-packages.md) for details on how this is used. Typically you would encrypt it and put it inside the `encrypted` object. ## `npmrc` See [Private npm module support](./getting-started/private-packages.md) for details on how this is used. ## `npmrcMerge` This option exists to provide flexibility about whether `npmrc` strings in config should override `.npmrc` files in the repo, or be merged with them. In some situations you need the ability to force override `.npmrc` contents in a repo (`npmrcMerge=false`) while in others you might want to simply supplement the settings already in the `.npmrc` (`npmrcMerge=true`). A use case for the latter is if you are a Renovate bot admin and wish to provide a default token for `npmjs.org` without removing any other `.npmrc` settings which individual repositories have configured (such as scopes/registries). If `false` (default), it means that defining `config.npmrc` will result in any `.npmrc` file in the repo being overridden and its values ignored. If configured to `true`, it means that any `.npmrc` file in the repo will have `config.npmrc` prepended to it before running `npm`. ## `osvVulnerabilityAlerts` Renovate integrates with [OSV](https://osv.dev/), an Open Source vulnerability database, to check if extracted dependencies have known vulnerabilities. Set `osvVulnerabilityAlerts` to `true` to get pull requests with vulnerability fixes (once they are available). You will only get OSV-based vulnerability alerts for _direct_ dependencies. Renovate only queries the OSV database for dependencies that use one of these datasources: - [`crate`](./modules/datasource/crate/index.md) - [`go`](./modules/datasource/go/index.md) - [`hackage`](./modules/datasource/hackage/index.md) - [`hex`](./modules/datasource/hex/index.md) - [`maven`](./modules/datasource/maven/index.md) - [`npm`](./modules/datasource/npm/index.md) - [`nuget`](./modules/datasource/nuget/index.md) - [`packagist`](./modules/datasource/packagist/index.md) - [`pypi`](./modules/datasource/pypi/index.md) - [`rubygems`](./modules/datasource/rubygems/index.md) The entire database is downloaded locally by [osv-offline](https://github.com/renovatebot/osv-offline) and queried offline. #### Malicious package detection and protection !!! note This functionality is currently experimental, being actively worked on, and will soon be available for usage outside of `osvVulnerabilityAlerts`. If Renovate detects a malicious dependency using data from OSV, it will surface this in log warnings, and prevent PRs from being created. If you currently have a dependency that is using a malicious version, Renovate will report this via a warning log. If Renovate finds a dependency update available, and that dependency update is found to be malicious, Renovate will skip **any updates to the dependency**, marking it with `skipReason: malicious-update-proposed`, and report this via a warning log. ## `packageRules` `packageRules` is a powerful feature that lets you apply rules to individual packages or to groups of packages using regex pattern matching. `packageRules` is a collection of rules, that are **all** evaluated. If multiple rules match a dependency, configurations from matching rules will be merged together. The order of rules matters, because later rules may override configuration options from earlier ones, if they both specify the same option. The matching process for a package rule: - Each package rule must include at least one `match...` matcher. - If multiple matchers are included in one package rule, all of them must match. - Each matcher must contain at least one pattern. Some matchers allow both positive and negative patterns. - If a matcher includes any positive patterns, it must match at least one of them. - A matcher returns `false` if it matches _any_ negative pattern, even if a positive match also occurred. For more details on positive and negative pattern syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). Here is an example if you want to group together all packages starting with `eslint` into a single branch/PR: ``` { "packageRules": [ { "matchPackageNames": ["eslint**"], "groupName": "eslint packages" } ] } ``` Note how the above uses `matchPackageNames` with a prefix pattern. Here’s an example config to limit the “noisy” AWS SDK packages to weekly updates: ``` { "packageRules": [ { "description": "Schedule AWS SDK updates on Sunday nights (9 PM - 12 AM)", "matchPackageNames": ["@aws-sdk/*"], "schedule": ["* 21-23 * * 0"] } ] } ``` For Maven dependencies, the package name is ``, e.g. `"matchPackageNames": ["com.thoughtworks.xstream:xstream"]` Note how the above uses an exact match string for `matchPackageNames` instead of a pattern However you can mix together both patterns and exact matches in the same package rule and the rule will be applied if _either_ match. Example: ``` { "packageRules": [ { "matchPackageNames": ["neutrino", "@neutrino/**"], "groupName": "neutrino monorepo" } ] } ``` The above rule will group together the `neutrino` package and any package starting with `@neutrino/`. File name matches are convenient to use if you wish to apply configuration rules to certain package or lock files using patterns. For example, if you have an `examples` directory and you want all updates to those examples to use the `chore` prefix instead of `fix`, then you could add this configuration: ``` { "packageRules": [ { "matchFileNames": ["examples/**"], "extends": [":semanticCommitTypeAll(chore)"] } ] } ``` If you wish to limit Renovate to apply configuration rules to certain files in the root repository directory, you have to use `matchFileNames` with a `minimatch` glob (which can include an exact file name match) or RE2 regex. For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). For example you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: ``` { "packageRules": [ { "matchFileNames": ["package.json"], "dependencyDashboardApproval": true } ] } ``` !!! tip Order your `packageRules` so the least important rules are at the _top_, and the most important rules at the _bottom_. This way important rules override settings from earlier rules if needed. !!! warning Avoid nesting any `object`\-type configuration in a `packageRules` array, such as a `major` or `minor` block. ### `packageRules.allowedVersions` You can use `allowedVersions` - usually within a `packageRules` entry - to limit how far to upgrade a dependency. For example, if you want to upgrade to Angular v1.5 but _not_ to `angular` v1.6 or higher, you could set `allowedVersions` to `<= 1.5` or `< 1.6.0`: ``` { "packageRules": [ { "matchPackageNames": ["angular"], "allowedVersions": "<=1.5" } ] } ``` Renovate calculates the valid syntax for this at runtime, because it depends on the dynamic versioning scheme. You can also use the following template fields with `allowedVersions`: - `currentVersion` - `major` - `minor` - `patch` For example, if you want to upgrade to Angular to only the next major, you could set `allowedVersions` like this: ``` { "packageRules": [ { "matchPackageNames": ["angular"], "allowedVersions": "<={{add major 1}}" } ] } ``` !!! warning `allowedVersions` and `matchUpdateTypes` cannot be used in the same package rule. #### Using regular expressions You can use Regular Expressions in the `allowedVersions` config. You must _begin_ and _end_ your Regular Expression with the `/` character! For example, this config only allows 3 or 4-part versions, without any prefixes in the version: ``` { "packageRules": [ { "matchPackageNames": ["com.thoughtworks.xstream:xstream"], "allowedVersions": "/^[0-9]+\\.[0-9]+\\.[0-9]+(\\.[0-9]+)?$/" } ] } ``` Again: note how the Regular Expression _begins_ and _ends_ with the `/` character. #### Ignore versions with negated regex syntax You can use a special negated regex syntax to ignore certain versions. You must use the `!/ /` syntax, like this: ``` { "packageRules": [ { "matchPackageNames": ["chalk"], "allowedVersions": "!/java$/" } ] } ``` ### `packageRules.changelogUrl` Sometimes Renovate does not show the correct changelog for a package. As a workaround for this problem, you can give Renovate the URL to the changelog with the `changelogUrl` config option. When set, Renovate will put a _link_ to the changelogs in the Renovate PR body. Renovate does _not_ show the complete changelogs from the `changelogUrl` in its PR body text, you only get the URL from Renovate. To read the changelogs you must use the link. ``` { "packageRules": [ { "matchPackageNames": ["dummy"], "changelogUrl": "https://github.com/org/dummy" } ] } ``` `changelogUrl` supports template compilation. ``` { "packageRules": [ { "matchPackageNames": ["dummy"], "changelogUrl": "https://github.com/org/monorepo/blob/{{{sourceDirectory}}}/my-custom-changelog.txt" } ] } ``` !!! note Renovate can fetch changelogs from Bitbucket, Bitbucket Server / Data Center, Forgejo, Gitea, GitHub and GitLab platforms only, and setting the URL to an unsupported host/platform type won’t change that. For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). ### `packageRules.matchBaseBranches` Use this field to restrict rules to a particular branch. e.g. ``` { "baseBranchPatterns": ["main"], "packageRules": [ { "matchBaseBranches": ["main"], "matchPackageNames": ["!/^eslint/"], "enabled": false } ] } ``` This field also supports Regular Expressions if they begin and end with `/`. e.g. ``` { "baseBranchPatterns": ["main", "/^release\\/.*/"], "packageRules": [ { "matchBaseBranches": ["/^release/.*/"], "matchPackageNames": ["!/^eslint/"], "enabled": false } ] } ``` ### `packageRules.matchCategories` Use `matchCategories` to restrict rules to a particular language or group. Matching is done using “any” logic, i.e. “match any of the following categories”. The categories can be found in the [manager documentation](modules/manager/index.md). !!! note Rules with `matchCategories` are only applied _after_ extraction of dependencies. If you want to configure which managers are being extracted at all, use `enabledManagers` instead. ``` { "packageRules": [ { "matchCategories": ["python"], "addLabels": ["py"] } ] } ``` ### `packageRules.matchConfidence` !!! warning This configuration option needs a Mend API key, and is in private beta testing only. API keys are not available for free or via the `renovatebot/renovate` repository. ``` { "packageRules": [ { "matchConfidence": ["high", "very high"], "groupName": "high merge confidence" } ] } ``` ### `packageRules.matchCurrentAge` Use this field if you want to match packages based on the age of the _current_ (existing, in-repo) version. For example, if you want to group updates for dependencies where the existing version is more than 2 years old: ``` { "packageRules": [ { "matchCurrentAge": "> 2 years", "groupName": "old dependencies" } ] } ``` The `matchCurrentAge` string must start with one of `>`, `>=`, `<` or `<=`. Only _one_ date part is supported, so you _cannot_ do `> 1 year 1 month`. Instead you should do `> 13 months`. !!! note We recommend you only use the words hour(s), day(s), week(s), month(s) and year(s) in your time ranges. ### `packageRules.matchCurrentValue` This option is matched against the `currentValue` field of a dependency. `matchCurrentValue` supports Regular Expressions and glob patterns. For example, the following enforces that updates from `1.*` versions will be merged automatically: ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchCurrentValue": "1.*", "automerge": true } ] } ``` Regular Expressions must begin and end with `/`. ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchCurrentValue": "/^1\\./" } ] } ``` This field also supports a special negated regex syntax to ignore certain versions. Use the syntax `!/ /` like this: ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchCurrentValue": "!/^0\\./" } ] } ``` ### `packageRules.matchCurrentVersion` The `currentVersion` field will be one of the following (in order of preference): - locked version if a lock file exists - resolved version - current value Consider using instead `matchCurrentValue` if you wish to match against the raw string value of a dependency. `matchCurrentVersion` can be an exact version or a version range: ``` { "packageRules": [ { "matchCurrentVersion": ">=1.0.0", "matchPackageNames": ["angular"] } ] } ``` The syntax of the version range must follow the [versioning scheme](modules/versioning/index.md#supported-versioning) used by the matched package(s). This is usually defined by the [manager](modules/manager/index.md#supported-managers) which discovered them or by the default versioning for the package’s [datasource](modules/datasource/index.md). For example, a Gradle package would typically need Gradle constraint syntax (e.g. `[,7.0)`) and not SemVer syntax (e.g. `<7.0`). This field also supports Regular Expressions which must begin and end with `/`. For example, the following enforces that only `1.*` versions will be used: ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchCurrentVersion": "/^1\\./" } ] } ``` This field also supports a special negated regex syntax to ignore certain versions. Use the syntax `!/ /` like this: ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchCurrentVersion": "!/^0\\./" } ] } ``` ### `packageRules.matchDatasources` Use this field to restrict rules to a particular datasource. e.g. ``` { "packageRules": [ { "matchDatasources": ["orb"], "labels": ["circleci-orb!!"] } ] } ``` ### `packageRules.matchDepNames` This field behaves the same as `matchPackageNames` except it matches against `depName` instead of `packageName`. ### `packageRules.matchDepTypes` Use this field if you want to limit a `packageRule` to certain `depType` values. This matching can be an exact match, Glob match, or Regular Expression match. For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). Note that Glob matching (including exact name matching) is case-insensitive. Invalid if used outside of a `packageRule`. ### `packageRules.matchFileNames` Renovate will compare `matchFileNames` glob or RE2 regex matching against the dependency’s package file and also lock file if one exists. For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). The following example matches `package.json` but _not_ `package/frontend/package.json`: ``` { "packageRules": [ { "matchFileNames": ["package.json"], "labels": ["npm"] } ] } ``` The following example matches any `package.json`, including files like `backend/package.json`: ``` { "packageRules": [ { "description": "Group dependencies from package.json files", "matchFileNames": ["**/package.json"], "groupName": "All package.json changes" } ] } ``` The following example matches any file in directories starting with `app/`: ``` { "packageRules": [ { "description": "Group all dependencies from the app directory", "matchFileNames": ["app/**"], "groupName": "App dependencies" } ] } ``` The following example matches any `.toml` file in a `v1`, `v2` or `v3` directory: ``` { "packageRules": [ { "description": "Group all dependencies from legacy projects", "matchFileNames": ["/v[123]/.*\\.toml/"], "groupName": "Legacy project dependencies" } ] } ``` It is recommended that you avoid using “negative” globs, like `**/!(package.json)`, because such patterns might still return true if they match against the lock file name (e.g. `package-lock.json`). ### `packageRules.matchJsonata` Use the `matchJsonata` field to define custom matching logic using [JSONata](https://jsonata.org/) query logic. Renovate will evaluate the provided JSONata expressions against the passed values (`manager`, `packageName`, etc.). See [the JSONata docs](https://docs.jsonata.org/) for more details on JSONata syntax. Here are some example `matchJsonata` strings for inspiration: ``` $exists(deprecationMessage) $exists(vulnerabilityFixVersion) manager = 'dockerfile' and depType = 'final' updateType = 'major' and newVersionAgeInDays < 7 $detectPlatform(sourceUrl) = 'github' ``` `matchJsonata` accepts an array of strings, and will return `true` if any of those JSONata expressions evaluate to `true`. Renovate provides the following custom JSONata functions: - `$detectPlatform(url)` - Takes a URL string and returns the detected platform (`azure`, `bitbucket`, `bitbucket-server`, `forgejo`, `gitea`, `github`, `gitlab`) or `null`. ### `packageRules.matchManagers` Use this field to restrict rules to a particular package manager. e.g. ``` { "packageRules": [ { "matchPackageNames": ["node"], "matchManagers": ["dockerfile"], "enabled": false } ] } ``` ### `packageRules.matchNewValue` This option is matched against the `newValue` field of a dependency. `matchNewValue` supports Regular Expressions and glob patterns. For example, the following enforces that updates to `1.*` versions will be merged automatically: ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchNewValue": "1.*", "automerge": true } ] } ``` Regular Expressions must begin and end with `/`. ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchNewValue": "/^1\\./" } ] } ``` This field also supports a special negated regex syntax to ignore certain versions. Use the syntax `!/ /` like this: ``` { "packageRules": [ { "matchPackageNames": ["io.github.resilience4j**"], "matchNewValue": "!/^0\\./" } ] } ``` For more details on this syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). ### `packageRules.matchPackageNames` Use this field to match against the `packageName` field. This matching can be an exact match, Glob match, or Regular Expression match. For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). Note that Glob matching (including exact name matching) is case-insensitive. ``` { "packageRules": [ { "matchDatasources": ["npm"], "matchPackageNames": ["angular"], "rangeStrategy": "pin" } ] } ``` The above will configure `rangeStrategy` to `pin` only for the npm package `angular`. ``` { "packageRules": [ { "matchPackageNames": ["@angular/**", "!@angular/abc"], "rangeStrategy": "replace" } ] } ``` The above will set a replaceStrategy for any npm package which starts with `@angular/` except `@angular/abc`. ``` { "packageRules": [ { "matchDatasources": ["npm"], "matchPackageNames": ["/^angular/"], "groupName": "Angular" } ] } ``` The above will group together any npm package which starts with the string `angular`. ### `packageRules.matchRegistryUrls` Use this option to match packages based on their `registryUrls`. Any package whose `registryUrls` array contains at least one URL matching any of the provided patterns will be selected. Here’s an example of where you use this to disable updates from a specific private registry: ``` { "packageRules": [ { "matchRegistryUrls": ["https://private.registry.example.com/**"], "enabled": false } ] } ``` ### `packageRules.matchRepositories` ### `packageRules.matchSourceUrls` Here’s an example of where you use this to group together all packages from the Vue monorepo: ``` { "packageRules": [ { "matchSourceUrls": ["https://github.com/vuejs/vue"], "groupName": "Vue monorepo packages" } ] } ``` For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). ### `packageRules.matchUpdateTypes` Use `matchUpdateTypes` to match rules against types of updates. For example to apply a special label to `major` updates: ``` { "packageRules": [ { "matchUpdateTypes": ["major"], "labels": ["UPDATE-MAJOR"] } ] } ``` For more details on supported syntax see Renovate’s [string pattern matching documentation](./string-pattern-matching.md). !!! warning Packages that follow SemVer are allowed to make breaking changes in _any_ `0.x` version, even `patch` and `minor`. Check if you’re using any `0.x` package, and see if you need custom `packageRules` for it. When setting up automerge for dependencies, make sure to stop accidental automerges of `0.x` versions. Read the [automerge non-major updates](./key-concepts/automerge.md#automerge-non-major-updates) docs for a config example that blocks `0.x` updates. !!! warning `matchUpdateTypes` and `allowedVersions` cannot be used in the same package rule. Tokens can be configured via `hostRules` using the `"merge-confidence"` `hostType`: ``` { "hostRules": [ { "hostType": "merge-confidence", "token": "********" } ] } ``` ### `packageRules.overrideDatasource` If a particular `datasource`/`packageName` combination has a lookup problem, you may be able to fix it by _changing_ `datasource` and potentially also `packageName`. Here is an example: ``` { "packageRules": [ { "matchDatasources": ["docker"], "matchPackageNames": ["renovate/renovate"], "overrideDatasource": "npm", "overridePackageName": "renovate" } ] } ``` `overrideDatasource` does not support template compilation. Be cautious as using this setting incorrectly could break all lookups. ### `packageRules.overrideDepName` Be careful using this feature because it may cause undesirable changes such as to branch names. In Renovate terminology, `packageName` is the exact package name needing to be looked up on a registry, while `depName` is essentially the “pretty” name. For example, the `packageName` is `docker.io/library/node` while the `depName` might be `node` for short. `depName` is used in PR titles as well as branch names, so changes to `depName` will have effects on those. `overrideDepName` supports template compilation. Example: ``` { "packageRules": [ { "matchDatasources": ["docker"], "overrideDepName": "{{replace 'docker.io/library/' '' depName}}" } ] } ``` Be cautious as using this setting incorrectly could break all lookups. ### `packageRules.overridePackageName` See the [`packageRules.overrideDatasource`](#packagerulesoverridedatasource) documentation for an example of use. `overridePackageName` supports template compilation. Be cautious as using this setting incorrectly could break all lookups. ### `packageRules.prPriority` Sometimes Renovate needs to rate limit its creation of PRs, e.g. hourly or concurrent PR limits. By default, Renovate sorts/prioritizes based on the update type, going from smallest update to biggest update. Renovate creates update PRs in this order: 1. `pinDigest` 2. `pin` 3. `digest` 4. `patch` 5. `minor` 6. `major` If you have dependencies that are more or less important than others then you can use the `prPriority` field for PR sorting. The default value is 0, so setting a negative value will make dependencies sort last, while higher values sort first. Here’s an example of how you would define PR priority so that `devDependencies` are raised last and `react` is raised first: ``` { "packageRules": [ { "matchDepTypes": ["devDependencies"], "prPriority": -1 }, { "matchPackageNames": ["react"], "prPriority": 5 } ] } ``` ### `packageRules.replacementName` This config option only works with some managers. We’re working to support more managers, subscribe to issue [renovatebot/renovate#24883](https://github.com/renovatebot/renovate/discussions/24883) to follow our progress. Managers which do not support replacement: - `bazel` - `git-submodules` - `gomod` - `gradle` - `homebrew` - `regex` - `sbt` Use the `replacementName` config option to set the name of a replacement package. Can be used in combination with `replacementVersion`. You can suggest a new community package rule by editing [the `replacements.json` file on the Renovate repository](https://github.com/renovatebot/renovate/blob/main/lib/data/replacements.json) and opening a pull request. !!! note Replacement updates will never be grouped. Lock file maintenance will never be grouped with other dependency updates. ### `packageRules.replacementNameTemplate` !!! note `replacementName` will take precedence if used within the same package rule. Use the `replacementNameTemplate` config option to control the replacement name. Use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. For example, the following package rule can be used to replace the registry for `docker` images: ``` { "packageRules": [ { "matchDatasources": ["docker"], "matchPackageNames": ["docker.io/**"], "replacementNameTemplate": "{{{replace 'docker\\.io/' 'ghcr.io/' packageName}}}" } ] } ``` Or, to add a registry prefix to any `docker` images that do not contain an explicit registry: ``` { "packageRules": [ { "description": "official images", "matchDatasources": ["docker"], "matchPackageNames": ["/^[a-z-]+$/"], "replacementNameTemplate": "some.registry.org/library/{{{packageName}}}" }, { "description": "non-official images", "matchDatasources": ["docker"], "matchPackageNames": ["/^[a-z-]+/[a-z-]+$/"], "replacementNameTemplate": "some.registry.org/{{{packageName}}}" } ] } ``` ### `packageRules.replacementVersion` This config option only works with some managers. We’re working to support more managers, subscribe to issue [renovatebot/renovate#14149](https://github.com/renovatebot/renovate/issues/14149) to follow our progress. For a list of managers which do not support replacement read the `replacementName` config option docs. Use the `replacementVersion` config option to set the version of a replacement package. Must be used with `replacementName`. For example to replace the npm package `jade` with version `2.0.0` of the package `pug`: ``` { "packageRules": [ { "matchDatasources": ["npm"], "matchPackageNames": ["jade"], "replacementName": "pug", "replacementVersion": "2.0.0" } ] } ``` ### `packageRules.replacementVersionTemplate` !!! note `replacementVersion` will take precedence if used within the same package rule. Use the `replacementVersionTemplate` config option to control the replacement version. For example, the following package rule can be used to replace version with major-only version (17.0.1 → 17): ``` { "packageRules": [ { "matchPackageNames": ["dummy"], "replacementVersionTemplate": "{{ lookup (split currentValue '.') 0 }}" } ] } ``` ### `packageRules.sourceDirectory` Use this field to set the directory in which the package is present at the source of the package. ``` { "packageRules": [ { "matchPackageNames": ["dummy"], "sourceUrl": "https://github.com/bitnami/charts", "sourceDirectory": "bitnami/kube-prometheus" } ] } ``` !!! note `sourceDirectory` should be only be configured along with `sourceUrl`. ### `packageRules.sourceUrl` Use this field to set the source URL for a package, including overriding an existing one. Source URLs are necessary to link to the source of the package and in order to look up changelogs. The `sourceUrl` field supports template compilation, allowing you to dynamically construct URLs based on package information. ``` { "packageRules": [ { "matchPackageNames": ["dummy"], "sourceUrl": "https://github.com/org/dummy" } ] } ``` ``` { "packageRules": [ { "matchDatasources": ["terraform-provider"], "registryUrls": ["https://registry.opentofu.org"], "sourceUrl": "https://github.com/{{replace '/' '/terraform-provider-' packageName}}" } ] } ``` In the example above, a package name like `hashicorp/aws` will be transformed to `https://github.com/hashicorp/terraform-provider-aws`. ## `patch` Add to this object if you wish to define rules that apply only to patch updates. ## `pin` Add to this object if you wish to define rules that apply only to PRs that pin dependencies. ## `pinDigest` Add to this object if you wish to define rules that apply only to PRs that pin digests. ## `pinDigests` If enabled Renovate will pin Docker images or GitHub Actions by means of their SHA256 digest and not only by tag so that they are immutable. ## `platformAutomerge` !!! note If you use the default `platformAutomerge=true` then you should enable your Git hosting platform’s capabilities to enforce test passing before PR merge. If you don’t do this, the platform might merge Renovate PRs even if the repository’s tests haven’t started, are in still in progress, or possibly even when they have failed. On GitHub this is called “Require status checks before merging”, which you can find in the “Branch protection rules” section of the settings for your repository. [GitHub docs, about protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) [GitHub docs, require status checks before merging](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging) If you’re using another platform, search their documentation for a similar feature. !!! note If you mark `renovate/artifacts` as a required status check in your branch protection rules, you must also set [`statusCheckWhen.artifactError`](#statuscheckwhen) to `"always"`. The default `"failed"` only sets the check when artifact updates fail, so a required check rule would block every PR that has no artifact errors (the check would never appear). Setting it to `"always"` makes Renovate report green when there are no errors and red when there are, which is what branch protection requires. If you have enabled `automerge` and set `automergeType=pr` in the Renovate config, then leaving `platformAutomerge` as `true` speeds up merging via the platform’s native automerge functionality. On Bitbucket Server, GitHub and GitLab, Renovate re-enables the PR for platform-native automerge whenever it’s rebased. `platformAutomerge` will configure PRs to be merged after all (if any) branch policies have been met. This option is available for Azure, Bitbucket Server, Forgejo, Gitea, GitHub and GitLab. It falls back to Renovate-based automerge if the platform-native automerge is not available. You can also fine-tune the behavior by setting `packageRules` if you want to use it selectively (e.g. per-package). Note that the outcome of `rebaseWhen=auto` can differ when `platformAutomerge=true`. Normally when you set `rebaseWhen=auto` Renovate rebases any branch that’s behind the base branch automatically, and some people rely on that. This behavior is no longer guaranteed when `platformAutomerge` is `true` because the platform might automerge a branch which is not up-to-date. For example, GitHub might automerge a Renovate branch even if it’s behind the base branch at the time. Please check platform specific docs for version requirements. To learn how to use GitHub’s Merge Queue feature with Renovate, read our [GitHub Merge Queue](./key-concepts/automerge.md#github-merge-queue) docs. ## `platformCommit` Only use this option if you run Renovate as a [GitHub App](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps). It does not apply when you use a Personal Access Token as credential. When `platformCommit` is enabled, Renovate will create commits with GitHub’s API instead of using `git` directly. This way Renovate can use GitHub’s [Commit signing support for bots and other GitHub Apps](https://github.blog/2019-08-15-commit-signing-support-for-bots-and-other-github-apps/) feature. !!! note When using platform commits, GitHub determines the git author string to use and Renovate’s own gitAuthor is ignored. ## `postUpdateOptions` ### `bundlerConservative` Enable conservative mode for `bundler` (Ruby dependencies). This will only update the immediate dependency in the lockfile instead of all subdependencies. ### `composerNoMinimalChanges` Run `composer update` with no `--minimal-changes` flag (does not affect lock file maintenance, which will never use `--minimal-changes`). ### `composerWithAll` Run `composer update` with `--with-all-dependencies` flag instead of the default `--with-dependencies`. ### `dotnetWorkloadRestore` Run `dotnet workload restore` before `dotnet restore` commands. ### `goGenerate` Run `go generate ./...`. This will then commit any files which were added or modified by running `go generate`. Note this will not install any other tools as part of the process. See [Go Tool](https://tip.golang.org/doc/go1.24#tools) usage for how to incorporate these as part of your build process. This runs after vendoring, if vendoring was required. !!! note In order for this option to function, the global configuration option [`allowedUnsafeExecutions`](./self-hosted-configuration.md#allowedunsafeexecutions) must include `goGenerate`. ### `gomodMassage` Enable massaging `replace` directives before calling `go` commands. ### `gomodSkipVendor` Never run `go mod vendor` after Go module updates. ### `gomodTidy` Run `go mod tidy` after Go module updates. This is implicitly enabled for major module updates when `gomodUpdateImportPaths` is enabled. ### `gomodTidy1.17` Run `go mod tidy -compat=1.17` after Go module updates. ### `gomodTidyE` Run `go mod tidy -e` after Go module updates. ### `gomodUpdateImportPaths` Update source import paths on major module updates, using [mod](https://github.com/marwan-at-work/mod). ### `gomodVendor` Always run `go mod vendor` after Go module updates even if vendor files aren’t detected. ### `helmUpdateSubChartArchives` Update subchart archives in the `/charts` folder. ### `kustomizeInflateHelmCharts` Inflate updated helm charts referenced in the kustomization. ### `npmDedupe` Run `npm install` with `--prefer-dedupe` for npm >= 7 or `npm dedupe` after `package-lock.json` update for npm <= 6. ### `npmInstallTwice` Run `npm install` commands _twice_ to work around bugs where `npm` generates invalid lock files if run only once. ### `pnpmDedupe` Run `pnpm dedupe --ignore-scripts` after `pnpm-lock.yaml` updates. ### `yarnDedupeFewer` Run `yarn-deduplicate --strategy fewer` after `yarn.lock` updates. ### `yarnDedupeHighest` Run `yarn-deduplicate --strategy highest` (`yarn dedupe --strategy highest` for Yarn >=2.2.0) after `yarn.lock` updates. ## `postUpgradeTasks` Post-upgrade tasks are commands that are executed by Renovate after a dependency has been updated but before the commit is created. The intention is to run any other command line tools that would modify existing files or generate new files when a dependency changes. Post-upgrade tasks are blocked by default for security reasons, so the admin of Renovate needs to choose whether to allow specific commands or any commands to be run - it depends on how much they trust their users in repos. In Mend-hosted Renovate apps, commands remain blocked by default but can be allowed on-request for any paying (“Renovate Enterprise” or Mend Appsec) customers or trusted OSS repositories - please reach out if so. Each command must match at least one of the patterns defined in `allowedCommands` (a global-only configuration option) in order to be executed. If the list of allowed tasks is empty then no tasks will be executed. e.g. ``` { "postUpgradeTasks": { "commands": ["tslint --fix"], "fileFilters": ["yarn.lock", "**/*.js"], "executionMode": "update" } } ``` The `postUpgradeTasks` configuration consists of four fields: ### `postUpgradeTasks.commands` A list of commands that are executed after Renovate has updated a dependency but before the commit is made. You can use Handlebars templating in these commands. They will be compiled _prior_ to the comparison against [`allowedCommands`](./self-hosted-configuration.md#allowedcommands). !!! note Do not use `git add` in your commands to add new files to be tracked, add them by including them in your [`postUpgradeTasks.fileFilters`](#postupgradetasksfilefilters) instead. ### `postUpgradeTasks.dataFileTemplate` A template to create data file from. The template uses the same format as `commands`. The data file is created as a temporary file and the path to the data file is stored in the `RENOVATE_POST_UPGRADE_COMMAND_DATA_FILE` environment variable avaliable to each post-upgrade command. The primary purpose of the data file is to store some update information in a file which would be consumed from a post-upgrade command. This is particularly useful if a post-upgrade command needs to have a long line of arguments. Example: ``` { "postUpgradeTasks": { "commands": [ "my-script.py --data-file \"$RENOVATE_POST_UPGRADE_COMMAND_DATA_FILE\"" ], "dataFileTemplate": "[{{#each upgrades}}{\"depName\": \"{{{depName}}}\", \"currentValue\": \"{{{currentValue}}}\", \"newValue\": \"{{{newValue}}}\"}{{#unless @last}},{{\/unless}}{{\/each}}]" } } ``` !!! note `dataFileTemplate` is ignored if there is no `commands` configured. ### `postUpgradeTasks.executionMode` Defaults to `update`, but can also be set to `branch`. This sets the level the postUpgradeTask runs on, if set to `update` the postUpgradeTask will be executed for every dependency on the branch. If set to `branch` the postUpgradeTask is executed for the whole branch. ### `postUpgradeTasks.fileFilters` A list of glob-style matchers that determine which files will be included in the final commit made by Renovate. Dotfiles are included. Optional field which defaults to any non-ignored file in the repo (`**/*` glob pattern). Specify a custom value for this if you wish to exclude certain files which are modified by your `postUpgradeTasks` and you don’t want committed. ### `postUpgradeTasks.installTools` Whether to install any additional tools dynamically before executing the `commands`. The possible tool names that are known by [Containerbase](https://github.com/containerbase/base) are: !!! note When using [`binarySource=global`](./self-hosted-configuration.md#binarysource), the `installTools` options do not take effect. For example: ``` { "postUpgradeTasks": { "commands": ["make generate"], "installTools": { "golang": {} } } } ``` ``` { "constraints": { "node": "^18.0.0 || >=20.0.0" }, "postUpgradeTasks": { "commands": ["npm install", "npm run update-readme"], "installTools": { "node": {} } } } ``` !!! note The tool objects inside `installTools` currently do not expose any additional configurability. ### `postUpgradeTasks.workingDirTemplate` A template describing the working directory in which the commands should be executed, relative to the repository root. If the template evaluates to a false value, then the command will be executed from the root of the repository. Example: ``` { "postUpgradeTasks": { "commands": ["my-script.py"], "workingDirTemplate": "{{{packageFileDir}}}" } } ``` ## `prBodyColumns` Use this array to provide a list of column names you wish to include in the PR tables. ``` { "prBodyColumns": [ "Package", "Update", "Type", "New value", "Package file", "References" ] } ``` !!! note “Package file” is predefined in the default `prBodyDefinitions` object so does not require a definition before it can be used. ## `prBodyDefinitions` You can configure this object to either: - modify the template for an existing table column in PR bodies, or - _add_ a definition for a new/additional column. ``` { "prBodyDefinitions": { "Package": "`{{{depName}}}`" } } ``` ``` { "prBodyDefinitions": { "Sourcegraph": "[![code search for \"{{{depName}}}\"](https://sourcegraph.com/search/badge?q=repo:%5Egithub%5C.com/{{{repository}}}%24+case:yes+-file:package%28-lock%29%3F%5C.json+{{{depName}}}&label=matches)](https://sourcegraph.com/search?q=repo:%5Egithub%5C.com/{{{repository}}}%24+case:yes+-file:package%28-lock%29%3F%5C.json+{{{depName}}})" }, "prBodyColumns": [ "Package", "Update", "New value", "References", "Sourcegraph" ] } ``` !!! tip Columns must also be included in the `prBodyColumns` array in order to be used, so that’s why it’s included above in the example. ## `prBodyHeadingDefinitions` You can configure this object to modify the table headers present in the PR body. This can include Markdown or any other syntax that the platform supports. ``` { "prBodyHeadingDefinitions": { "Package": "📦 Package", "Age": "[Age](https://docs.renovatebot.com/merge-confidence)" }, "prBodyColumns": ["Package", "Age"] } ``` !!! tip Columns must also be included in the `prBodyColumns` array in order to be used, so that’s why it’s included above in the example. !!! note Templating is not supported for this option. ## `prBodyNotes` Use this field to add custom content inside PR bodies, including conditionally. ``` { "prBodyNotes": ["{{#if isMajor}}:warning: MAJOR MAJOR MAJOR :warning:{{/if}}"] } ``` ## `prBodyTemplate` The available sections are: - `header` - `table` - `warnings` - `notes` - `changelogs` - `configDescription` - `controls` - `footer` ## `prConcurrentLimit` This setting - if enabled - limits Renovate to a maximum of `x` concurrent PRs open at any time. This limit is enforced on a per-repository basis. !!! note Renovate always creates security PRs, even if the concurrent PR limit is already reached. Security PRs have `[SECURITY]` in their PR title. ## `prCreation` This setting tells Renovate _when_ to create PRs: - `immediate` (default): Renovate creates PRs immediately after creating the corresponding branch - `not-pending`: Renovate waits until status checks have completed (passed or failed) before raising the PR - `status-success`: Renovate only creates PRs if/when the the test pass - `approval`: Renovate creates branches for updates immediately, but creates the PR _after_ getting Dependency Dashboard approval When prCreation is set to `immediate`, you’ll get a Pull Request and possible associated notification right away when a new update is available. You’ll have to wait until the checks have been performed, before you can decide if you want to merge the PR. When prCreation is set to `not-pending`, Renovate creates the PR only once all tests have passed or failed. When you get the PR notification, you can take action immediately, as you have the full test results. If there are no checks associated, Renovate will create the PR once 24 hours have elapsed since creation of the commit. When prCreation is set to `status-success`, Renovate creates the PR only if all tests have passed. When a branch remains without PR due to a failing test: select the corresponding PR from the Dependency Dashboard, and push your fixes to the branch. When prCreation is set to `approval`, Renovate creates the PR only when approved via the Dependency Dashboard. Renovate still creates the _branch_ immediately. !!! note For all cases of non-immediate PR creation, Renovate doesn’t run instantly once tests complete. Instead, Renovate create the PR on its _next_ run after the relevant tests have completed, so there will be some delay. !!! warning If you set `prCreation=approval` you must _not_ use `dependencyDashboardApproval=true`! ## `prFooter` ## `prHeader` ## `prHourlyLimit` This config option slows down the _rate_ at which Renovate creates PRs. Slowing Renovate down can be handy when you’re onboarding a repository with a lot of dependencies. What may happen if you don’t set a `prHourlyLimit`: 1. Renovate creates an Onboarding PR 2. You merge the onboarding PR to activate Renovate 3. Renovate creates a “Pin Dependencies” PR (if needed) 4. You merge the “Pin Dependencies” PR 5. Renovate creates every single upgrade PR needed, which can be a lot The above may cause: - Renovate bot’s PRs to overwhelm your CI systems - a lot of test runs, because branches are rebased each time you merge a PR To prevent these problems you can set `prHourlyLimit` to a value like `1` or `2`. Renovate will only create that many PRs within each hourly period (`:00` through `:59`). You still get all the PRs in a reasonable time, perhaps over a day or so. Now you can merge the PRs at a do-able rate, once the tests pass. !!! tip The `prHourlyLimit` setting does _not_ limit the number of _concurrently open PRs_, only the _rate_ at which PRs are created. The `prHourlyLimit` setting is enforced on a per-repository basis. ## `prNotPendingHours` If you configure `prCreation=not-pending`, then Renovate will wait until tests are non-pending (all pass or at least one fails) before creating PRs. However there are cases where PRs may remain in pending state forever, e.g. absence of tests or status checks that are configure to pending indefinitely. This is why we configured an upper limit for how long we wait until creating a PR. !!! note If the option `minimumReleaseAge` is non-zero then Renovate disables the `prNotPendingHours` functionality. ## `prTitle` The PR title is important for some of Renovate’s matching algorithms (e.g. determining whether to recreate a PR or not) so ideally don’t modify it much. ## `prTitleStrict` There are certain scenarios where the default behavior appends extra context to the PR title. These scenarios include if a `baseBranch` or if there is a grouped update and either `separateMajorMinor` or `separateMinorPatch` is true. Using this option allows you to skip these default behaviors and use other templating methods to control the format of the PR title. ## `printConfig` This option is useful for troubleshooting, particularly if using presets. e.g. run `renovate foo/bar --print-config > config.log` and the fully-resolved config will be included in the log file. ## `pruneBranchAfterAutomerge` By default Renovate deletes, or “prunes”, the branch after automerging. Set `pruneBranchAfterAutomerge` to `false` to keep the branch after automerging. ## `pruneStaleBranches` By default, Renovate will “prune” any of its own branches/PRs which it thinks are no longer needed. Such branches are referred to as “stale”, and may be the result of Open, Merged, or Closed/Ignored PRs. It usually doesn’t _know_ why they’re there, instead it simply knows that it has no need for them. If a branch appears stale but has been modified by a different git author, then Renovate won’t delete the branch or autoclose any associated PR. Instead, it will update the title to append “ - abandoned“ plus add a comment noting that autoclosing is skipped. If a branch appears stale and hasn’t been modified, then: - If an Open PR exist for the branch, then Renovate will rename the PR to append “ - autoclosed“ before closing/abandoning it - Renovate will delete the branch You can configure `pruneStaleBranches=false` to disable deleting orphan branches and autoclosing PRs, but then you will be responsible for such branch/PR “cleanup” so it is not recommended. ## `rangeStrategy` Behavior: - `auto` = Renovate decides (this will be done on a manager-by-manager basis) - `pin` = convert ranges to exact versions, e.g. `^1.0.0` → `1.1.0` - `bump` = e.g. bump the range even if the new version satisfies the existing range, e.g. `^1.0.0` → `^1.1.0` - `replace` = Replace the range with a newer one if the new version falls outside it, and update nothing otherwise - `widen` = Widen the range with newer one, e.g. `^1.0.0` → `^1.0.0 || ^2.0.0` - `update-lockfile` = Update the lock file when in-range updates are available, otherwise `replace` for updates out of range. Works for `bundler`, `cargo`, `composer`, `gleam`, `npm`, `yarn`, `pnpm`, `terraform`, `poetry` and `uv` so far - `in-range-only` = Update the lock file when in-range updates are available, ignore package file updates Renovate’s `"auto"` strategy works like this for npm: 1. Widen `peerDependencies` 2. If an existing range already ends with an “or” operator like `"^1.0.0 || ^2.0.0"`, then Renovate widens it into `"^1.0.0 || ^2.0.0 || ^3.0.0"` 3. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` 4. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. By default, Renovate assumes that if you are using ranges then it’s because you want them to be wide/open. Renovate won’t deliberately “narrow” any range by increasing the semver value inside. For example, if your `package.json` specifies a value for `left-pad` of `^1.0.0` and the latest version on npmjs is `1.2.0`, then Renovate won’t change anything because `1.2.0` satisfies the range. If instead you’d prefer to be updated to `^1.2.0` in cases like this, then configure `rangeStrategy` to `bump` in your Renovate config. This feature supports caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`. The `in-range-only` strategy may be useful if you want to leave the package file unchanged and only do `update-lockfile` within the existing range. The `in-range-only` strategy behaves like `update-lockfile`, but discards any updates where the new version of the dependency is not equal to the current version. We recommend you avoid using the `in-range-only` strategy unless you strictly need it. Using the `in-range-only` strategy may result in you being multiple releases behind without knowing it. ## `rebaseLabel` On supported platforms it is possible to add a label to a PR to manually request Renovate to recreate/rebase it. By default this label is `"rebase"` but you can configure it to anything you want by changing this `rebaseLabel` field. ## `rebaseWhen` Possible values and meanings: - `auto`: Renovate will autodetect the best setting. It will use `behind-base-branch` if configured to automerge or repository has been set to require PRs to be up to date. Otherwise, `conflicted` will be used instead - `automerging`: Renovate will use `behind-base-branch` if configured to automerge, Otherwise, `never` will be used instead - `never`: Renovate will never rebase the branch or update it unless manually requested - `conflicted`: Renovate will rebase only if the branch is conflicted - `behind-base-branch`: Renovate will rebase whenever the branch falls 1 or more commit behind its base branch `rebaseWhen=conflicted` is not recommended if you have enabled Renovate automerge, because: - It could result in a broken base branch if two updates are merged one after another without testing the new versions together - If you have enforced that PRs must be up-to-date before merging (e.g. using branch protection on GitHub), then automerge won’t be possible as soon as a PR gets out-of-date but remains non-conflicted It is also recommended to avoid `rebaseWhen=never` as it can result in conflicted branches with outdated PR descriptions and/or status checks. Avoid setting `rebaseWhen=never` and then also setting `prCreation=not-pending` as this can prevent creation of PRs. ## `recreateWhen` This feature used to be called `recreateClosed`. By default, Renovate detects if it proposed an update to a project before, and will not propose the same update again. For example the Webpack 3.x case described in the [`separateMajorMinor`](#separatemajorminor) documentation. You can use `recreateWhen` to customize this behavior down to a per-package level. For example we override it to `always` in the following cases where branch names and PR titles must be reused: - Package groups - When pinning versions - Lock file maintenance You can select which behavior you want from Renovate: - `always`: Recreates all closed or blocking PRs - `auto`: The default option. Recreates only [immortal PRs](./key-concepts/pull-requests.md#immortal-prs) (default) - `never`: No PR is recreated, doesn’t matter if it is immortal or not We recommend that you stick with the default setting for this option. Only change this setting if you really need to. ## `registryAliases` You can use the `registryAliases` object to set registry aliases. Renovate applies _all_ `registryAliases` objects, from top to bottom. This feature works with the following managers: - [`ansible`](modules/manager/ansible/index.md) - [`bazel-module`](modules/manager/bazel-module/index.md) - [`bitbucket-pipelines`](modules/manager/bitbucket-pipelines/index.md) - [`circleci`](modules/manager/circleci/index.md) - [`crow`](modules/manager/crow/index.md) - [`docker-compose`](modules/manager/docker-compose/index.md) - [`dockerfile`](modules/manager/dockerfile/index.md) - [`droneci`](modules/manager/droneci/index.md) - [`fleet`](modules/manager/fleet/index.md) - [`flux`](modules/manager/flux/index.md) - [`github-actions`](modules/manager/github-actions/index.md) - [`gitlabci`](modules/manager/gitlabci/index.md) - [`helm-requirements`](modules/manager/helm-requirements/index.md) - [`helm-values`](modules/manager/helm-values/index.md) - [`helmfile`](modules/manager/helmfile/index.md) - [`helmv3`](modules/manager/helmv3/index.md) - [`kubernetes`](modules/manager/kubernetes/index.md) - [`terraform`](modules/manager/terraform/index.md) - [`woodpecker`](modules/manager/woodpecker/index.md) ``` { "registryAliases": { "jfrogecosystem": "some.jfrog.mirror", "jfrog.com": "some.jfrog.mirror" } } ``` ``` { "gitlabci": { "registryAliases": { "$HARBOR_HOST/$HARBOR_PROJECT": "registry.example.com/proxy", "$HARBOR_HOST/tools": "registry.example.com/tools" } } } ``` If you are using a pull-through cache (for instance on Amazon Elastic Container Registry (ECR)): ``` { "registryAliases": { "12345612312.dkr.ecr.us-east-1.amazonaws.com/public-images-go-here/ghcr.io": "ghcr.io", "12345612312.dkr.ecr.us-east-1.amazonaws.com/public-images-go-here/dockerhub": "docker.io" } } ``` ## `registryUrls` Usually Renovate is able to either (a) use the default registries for a datasource, or (b) automatically detect during the manager extract phase which custom registries are in use. In case there is a need to configure them manually, it can be done using this `registryUrls` field, typically using `packageRules` like so: ``` { "packageRules": [ { "matchDatasources": ["docker"], "registryUrls": ["https://docker.mycompany.domain"] } ] } ``` The field supports multiple URLs but it is datasource-dependent on whether only the first is used or multiple. ## `replacement` Add to this object if you wish to define rules that apply only to PRs that replace dependencies. ## `replacementApproach` For `npm` manager when `replacementApproach=alias` then instead of replacing `"foo": "1.2.3"` with `"@my/foo": "1.2.4"` we would instead replace it with `"foo": "npm:@my/foo@1.2.4"`. ``` { "replacementApproach": "alias" } ``` ## `respectLatest` Similar to `ignoreUnstable`, this option controls whether to update to versions that are greater than the version tagged as `latest` in the repository. By default, `renovate` will update to a version greater than `latest` only if the current version is itself past latest. !!! note By default, respectLatest will be set to `false` for Maven results if a `latest` tag is found. This is because many Maven registries don’t have a reliable `latest` tag - it just means whatever was last published. You need to override this to `respectLatest=true` in `packageRules` in order to use it. ## `reviewers` Must be valid usernames. **Required reviewers on Azure DevOps** To mark a reviewer as required on Azure DevOps, you must use the prefix `required:`. For example: if the username or team name is `bar` then you would set the config option like this: ``` { "reviewers": ["required:bar"] } ``` **Required reviewers on Forgejo** If you’re assigning a team to review on Forgejo, you must use the prefix `team:` and add the _last part_ of the team name. Say the full team name on Forgejo is `organization/foo`, then you’d set the config option like this: ``` { "reviewers": ["team:foo"] } ``` **Required reviewers on GitHub** If you’re assigning a team to review on GitHub, you must use the prefix `team:` and add the _last part_ of the team name. Say the full team name on GitHub is `@organization/foo`, then you’d set the config option like this: ``` { "reviewers": ["team:foo"] } ``` Please note that Reviewers are only added during creation of a PR, but are not modified afterwards. !!! note By default, Renovate will not assign reviewers and assignees to an automerge-enabled PR unless it fails status checks. By configuring [`assignAutomerge`](#assignautomerge) setting to `true`, Renovate will instead always assign reviewers and assignees for automerging PRs at time of creation. ## `reviewersFromCodeOwners` If enabled Renovate tries to determine PR reviewers by matching rules defined in a CODEOWNERS file against the changes in the PR. Read the docs for your platform for details on syntax and allowed file locations: - [GitHub Docs, About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) - [GitLab, Code Owners](https://docs.gitlab.com/ee/user/project/codeowners/) - [Bitbucket, Set up and use code owners](https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-use-code-owners/) Please note that Reviewers are only added during creation of a PR, but are not modified afterwards. ## `reviewersSampleSize` ## `rollback` Add to this object if you wish to define rules that apply only to PRs that roll back versions. ## `rollbackPrs` There are times when a dependency version in use by a project gets removed from the registry. For some registries, existing releases or even whole packages can be removed or “yanked” at any time, while for some registries only very new or unused releases can be removed. Renovate’s “rollback” feature exists to propose a downgrade to the next-highest release if the current release is no longer found in the registry. Renovate does not create these rollback PRs by default, so this functionality needs to be opted-into. We recommend you do this selectively with `packageRules` and not globally. ## `schedule` The `schedule` option allows you to define times of the day, week or month when you are willing to allow Renovate to create branches. Setting a `schedule` does not itself cause or trigger Renovate to run. It’s like putting a sign on your office which says “DHL deliveries only accepted between 9-11am”. Such a sign won’t _cause_ DHL to come to your office only at 9-11am, instead it simply means that if they come at any other time of the day then they’ll honor the sign and skip you. It also means that if they rarely attempt between 9-11am then you’ll often get no deliveries in a day. Similarly, if you set too restrictive of a Renovate `schedule` and the chance of Renovate running on your repo during those hours is low, then you might find your dependency updates regularly skipped. For this reason we recommend you allow a time window of at least 3-4 hours in any `schedule`, unless your instance of Renovate is expected to run more frequently than that. Renovate supports the standard [Cron syntax](https://crontab.guru/crontab.5.html), as well as deprecated support for a subset of [Later syntax](https://github.com/breejs/later). We recommend you always use Cron syntax, due to its superior testing and robustness. Config support questions are no longer accepted for Later syntax problems - you will be recommended to use Cron instead. The default value for `schedule` is “at any time”, which is functionally the same as declaring a `null` schedule or `* * * * *` with Cron. i.e. Renovate will create Pull Requests at any time of any day, as needed. The easiest way to define a schedule is to use a preset if one of them fits your requirements. See [Schedule presets](./presets-schedule.md) for details and feel free to request a new one in the source repository if you think it would help others. Here are some example schedules and their Cron equivalent: English description Supported by Later? Cron syntax every weekend Yes `* * * * 0,6` before 5:00am Yes `* 0-4 * * *` after 10pm and before 5am every weekday Yes `* 22-23,0-4 * * 1-5` on friday and saturday Yes `* * * * 5,6` every 3 months on the first day of the month Yes `* * 1 */3 *` !!! note For Cron schedules, you _must_ use the `*` wildcard for the minutes value, as Renovate doesn’t support minute granularity. And the cron schedule must have five comma separated parts. One example might be that you don’t want Renovate to run during your typical business hours, so that your build machines don’t get clogged up testing `package.json` updates. You could then configure a schedule like this at the repository level: ``` { "description": "Schedule on weekdays at night (10 PM - 4 AM) and anytime on weekends", "schedule": ["* 22-23,0-4 * * *", "* * * * 0,6"] } ``` This would mean that Renovate can run for 7 hours each night, plus all the time on weekends. Note how the above example makes use of the “OR” logic of combining multiple schedules in the array. !!! note If both the day of the week _and_ the day of the month are restricted in the schedule, then Renovate only runs when both the day of the month _and_ day of the week match! For example: `* * 1-7 * 4` means Renovate only runs on the _first_ Thursday of the month. It’s common to use `schedule` in combination with [`timezone`](#timezone). You should configure [`updateNotScheduled=false`](#updatenotscheduled) if you want the schedule more strictly enforced so that _updates_ to existing branches aren’t pushed out of schedule. You can also configure [`automergeSchedule`](#automergeschedule) to limit the hours in which branches/PRs are _automerged_ (if [`automerge`](#automerge) is configured). ## `semanticCommitScope` By default you will see Angular-style commit prefixes like `"chore(deps):"`. If you wish to change it to something else like `"package"` then it will look like `"chore(package):"`. You can also use `parentDir` or `baseDir` to namespace your commits for monorepos e.g. `"{{parentDir}}"`. ## `semanticCommitType` By default you will see Angular-style commit prefixes like `"chore(deps):"`. If you wish to change it to something else like “ci” then it will look like `"ci(deps):"`. ## `semanticCommits` If you are using a semantic prefix for your commits, then you will want to enable this setting. Although it’s configurable to a package-level, it makes most sense to configure it at a repository level. If configured to `enabled`, then the `semanticCommitScope` and `semanticCommitType` fields will be used for each commit message and PR title. Renovate autodetects if your repository is already using semantic commits or not and follows suit, so you only need to configure this if you wish to _override_ Renovate’s autodetected setting. ## `separateMajorMinor` Renovate’s default behavior is to create a separate branch/PR if both minor and major version updates exist (note that your choice of `rangeStrategy` value can influence which updates exist in the first place however). For example, if you were using Webpack 2.0.0 and versions 2.1.0 and 3.0.0 were both available, then Renovate would create two PRs so that you have the choice whether to apply the minor update to 2.x or the major update of 3.x. If you were to apply the minor update then Renovate would keep updating the 3.x branch for you as well, e.g. if Webpack 3.0.1 or 3.1.0 were released. If instead you applied the 3.0.0 update then Renovate would clean up the unneeded 2.x branch for you on the next run. It is recommended that you leave this option to `true`, because of the polite way that Renovate handles this. For example, let’s say in the above example that you decided you wouldn’t update to Webpack 3 for a long time and don’t want to build/test every time a new 3.x version arrives. In that case, simply close the “Update Webpack to version 3.x” PR and it _won’t_ be recreated again even if subsequent Webpack 3.x versions are released. You can continue with Webpack 2.x for as long as you want and get any updates/patches that are made for it. Then eventually when you do want to update to Webpack 3.x you can make that update to `package.json` yourself and commit it to the base branch once it’s tested. After that, Renovate will resume providing you updates to 3.x again! i.e. if you close a major upgrade PR then it won’t come back again, but once you make the major upgrade yourself then Renovate will resume providing you with minor or patch updates. This option also has priority over package groups configured by `packageRule`. So Renovate will propose separate PRs for major and minor updates of packages even if they are grouped. If you want to enforce grouped package updates, you need to set this option to `false` within the `packageRule`. ## `separateMinorPatch` By default, Renovate groups `patch` (`1.0.x`) and `minor` (`1.x.0`) releases into a single PR. For example: you are running version `1.0.0` of a package, which has two updates: - `1.0.1`, a `patch` type update - `1.1.0`, a `minor` type update By default, Renovate creates a single PR for the `1.1.0` version. If you want Renovate to create _separate_ PRs for `patch` and `minor` upgrades, set `separateMinorPatch` to `true`. Getting separate updates from Renovate can be handy when you want to, for example, automerge `patch` updates but manually merge `minor` updates. ## `separateMultipleMajor` Configure this to `true` if you wish to get one PR for every separate major version upgrade of a dependency. e.g. if you are on webpack@v1 currently then default behavior is a PR for upgrading to webpack@v3 and not for webpack@v2. If this setting is true then you would get one PR for webpack@v2 and one for webpack@v3. ## `separateMultipleMinor` Enable this for dependencies when it is important to split updates into separate PRs per minor release stream (e.g. `python`). For example, if you are on `python@v3.9.0` currently, then by default Renovate creates a PR to upgrade you to the latest version such as `python@v3.12.x`. By default, Renovate skips versions in between, like `python@v3.10.x`. But if you set `separateMultipleMinor=true` then you get separate PRs for each minor stream, like `python@3.9.x`, `python@v3.10.x` and `python@v3.11.x`, etc. ## `skipArtifactsUpdate` Use this option when automatic artifact updating fails, is incorrect, or not needed. This option was formerly known as `updateLockFiles`. When this option is set, Renovate won’t attempt to update artifacts such as lock files, so you will need to update them yourself, either manually or through secondary automation such as CI workflows. !!! note When this option is used in package rules, along with grouped upgrades, artifact updating will only be skipped if every upgrade in the grouped branch wants to skip it. !!! warning When artifact updates are skipped and the `packageManager` field in `package.json` is updated, the new version will not contain a hash. The hash is only applied when artifacts are updated. For example, a value of `packageManager: "yarn@3.0.0+sha224.deadbeef"` would be updated to just `packageManager: "yarn@3.1.0"` rather than `packageManager: "yarn@3.1.0+sha224.f0cacc1a"`. ## `skipInstalls` By default, Renovate will use the most efficient approach to updating package files and lock files, which in most cases skips the need to perform a full module install by the bot. If this is set to false, then a full install of modules will be done. This is currently applicable to `npm` only, and only used in cases where bugs in `npm` result in incorrect lock files being updated. ## `statusCheckNames` You can customize the name/context of status checks that Renovate adds to commits/branches/PRs. This option enables you to modify any existing status checks name/context, but adding new status checks this way is _not_ supported. Setting the value to `null` or an empty string, effectively disables or skips that status check. This option is mergeable, which means you only have to specify the status checks that you want to modify. ``` { "statusCheckNames": { "minimumReleaseAge": "custom/stability-days", "mergeConfidence": "custom/merge-confidence-level" } } ``` ## `statusCheckWhen` Control when each Renovate status check is set on branches. The keys match those available in [`statusCheckNames`](#statuschecknames). This option is mergeable, so you only need to specify the checks you want to change. Allowed values per key: - `always`: Renovate always sets the status check on every branch commit — green on success, red on failure. - `never`: Renovate never sets this status check. Use this to skip a check entirely. - `failed`: Renovate only sets the status check when there is a failure. Successes are silent (no green check). Default values: For example, to make `renovate/artifacts` a required check, set `artifactError` to `"always"` so it always reports green/red, allowing you to mark it as required in your branch protection rules. To skip a check entirely, set any key to `"never"` to suppress that status check. To only report failures for stability, set `minimumReleaseAge` to `"failed"` if you only care about the red/pending status. ``` { "statusCheckWhen": { "artifactError": "always", "mergeConfidence": "never" } } ``` ## `stopUpdatingLabel` This feature only works on supported platforms, check the table above. If you want Renovate to stop updating a PR, you can apply a label to the PR. By default, Renovate listens to the label: `"stop-updating"`. You can set your own label name with the `"stopUpdatingLabel"` field: ``` { "stopUpdatingLabel": "take-a-break-renovate" } ``` ## `suppressNotifications` Use this field to suppress various types of warnings and other notifications from Renovate. For example: ``` { "suppressNotifications": ["prIgnoreNotification"] } ``` The above config will suppress the comment which is added to a PR whenever you close a PR unmerged. ## `timezone` We recommend that you only configure the `timezone` option if _both_ of these are true: - you want to use the `schedule` feature - _and_ you want Renovate to evaluate the `schedule` in your timezone Please see the above link for valid timezone names. ## `toolSettings` When Renovate updates a dependency and needs to invoke processes leveraging Java, for example Gradle for [the `gradle`](./modules/manager/gradle/index.md) or [the `gradle-wrapper`](./modules/manager/gradle-wrapper/index.md) managers, the repository’s Gradle Wrapper will be invoked, if present. The JVM heap size for the Java invocations is 512m by default. This can be overridden using the following options. This option can be used on the repository level and in the [Renovate configuration](./self-hosted-configuration.md) using the following options. !!! note The JVM memory settings specified in the global self-hosted configuration set by the administrator in [`toolSettings.jvmMaxMemory`](./self-hosted-configuration.md) limits the memory settings for all repositories. The default limit for all repositories is 512m. !!! note The JVM memory settings are considered for the `gradle` and `gradle-wrapper` manager. ### `toolSettings.jvmMaxMemory` Maximum heap size in MB for Java VMs. Defaults to `512` for both the repository level and self-hosted configuration. To allow repositories to use _more_ than 512m of heap during any invocations of the Gradle Wrapper, configure the `jvmMaxMemory` option in the [`toolSettings.jvmMaxMemory`](./self-hosted-configuration.md). ### `toolSettings.jvmMemory` Initial heap size in MB for Java VMs. Must be less than or equal to `jvmMaxMemory`. Defaults to `jvmMaxMemory`. ### `toolSettings.nodeMaxMemory` !!! note This does not apply to _every_ Node process created by Renovate, only the managers noted above. ## `updateInternalDeps` Renovate defaults to skipping any internal package dependencies within monorepos. In such case dependency versions won’t be updated by Renovate. To opt in to letting Renovate update internal package versions normally, set this configuration option to true. ## `updateNotScheduled` When schedules are in use, it generally means “no updates”. However there are cases where updates might be desirable - e.g. if you have configured `prCreation=not-pending`, or you have `rebaseWhen=behind-base-branch` and the base branch is updated so you want Renovate PRs to be rebased. This defaults to `true`, meaning that Renovate will perform certain “desirable” updates to _existing_ PRs even when outside of schedule. If you wish to disable all updates outside of scheduled hours then configure this field to `false`. ## `updatePinnedDependencies` By default, Renovate will try to update all detected dependencies, regardless of whether they are defined using pinned single versions (e.g. `1.2.3`) or constraints/ranges (e.g. (`^1.2.3`). You can set this option to `false` if you wish to disable updating for pinned (single version) dependencies specifically. ## `useBaseBranchConfig` By default, Renovate will read config file from the default branch only and will ignore any config files in base branches. You can configure `useBaseBranchConfig=merge` to instruct Renovate to merge the config from each base branch over the top of the config in the default branch. The config file name in the base branch must be the same as in the default branch and cannot be `package.json`. This scenario may be useful for testing the config changes in base branches instantly. ## `userStrings` When a PR is closed, Renovate posts a comment to let users know that future updates will be ignored. If you want, you can change the text in the comment with the `userStrings` config option. You can edit these user-facing strings: - `artifactErrorWarning`: Text of the PR comment when artifact errors occur during updates. - `ignoreDigest`: Text of the PR comment for digest upgrades. - `ignoreMajor`: Text of the PR comment for major upgrades. - `ignoreOther`: Text of the PR comment for other (neither digest nor major) upgrades. - `ignoreTopic`: Topic of the PR comment. For example: ``` { "userStrings": { "artifactErrorWarning": "Custom text for artifact errors.", "ignoreTopic": "Custom topic for PR comment", "ignoreMajor": "Custom text for major upgrades.", "ignoreDigest": "Custom text for digest upgrades.", "ignoreOther": "Custom text for other upgrades." } } ``` ## `versionCompatibility` This option is used for advanced use cases where the version string embeds more data than just the version. It’s typically used with docker and tags datasources. Here are two examples: - The image tag `ghcr.io/umami-software/umami:postgresql-v1.37.0` embeds text like `postgresql-` as a prefix to the actual version to differentiate different DB types. - Docker image tags like `node:18.10.0-alpine` embed the base image as a suffix to the version. Here is an example of solving these types of cases: ``` { "packageRules": [ { "matchDatasources": ["docker"], "matchPackageNames": ["ghcr.io/umami-software/umami"], "versionCompatibility": "^(?.*)-(?.*)$", "versioning": "semver" }, { "matchDatasources": ["docker"], "matchPackageNames": ["node"], "versionCompatibility": "^(?[^-]+)(?-.*)?$", "versioning": "node" } ] } ``` This feature is most useful when the `currentValue` is a version and not a range/constraint. This feature _can_ be used in combination with `extractVersion` although that’s likely only a rare edge case. When combined, `extractVersion` is applied to datasource results first, and then `versionCompatibility`. `extractVersion` should be used when the raw version string returned by the `datasource` contains extra details (such as a `v` prefix) when compared to the value/version used within the repository. During the lookup phase, Renovate evaluates the `versionCompatibility` regex against the `currentValue` string. If there is a match, the version part is stored internally temporarily as `compareValue` and the compatibility part stored as `currentCompatibility`. Storing `currentCompatibility` allows Renovate to reuse this value later to filter for new versions with the same compatibility. Renovate applies this compatibility check to datasource lookup results by passing both the `versionCompatibility` and `currentCompatibility` strings to a filter. For a new version to be allowed, it must: - Satisfy the `versionCompatibility` regex, and - Have the same `compatibility` part as the `currentValue` At this point, Renovate’s core lookup logic is comparing versions to versions, and ignoring compatibility strings like `-jre8`. Finally, once updates are decided, Renovate restores the compatibility part to the `newValue` result. ## `versioning` Usually, each language or package manager has a specific type of “versioning”: JavaScript uses npm’s SemVer implementation, Python uses pep440, etc. Renovate also uses custom versioning, like `"docker"` to address the most common way people tag versions using Docker, and `"loose"` as a fallback that tries SemVer first. Otherwise Renovate does its best to sort and compare. By exposing `versioning` to config, you can override the default versioning for a package manager if needed. We do not recommend overriding the default versioning, but there are some cases such as Docker or Gradle where versioning is not strictly defined and you may need to specify the versioning type per-package. Renovate supports 4-part versions (1.2.3.4) in full for the NuGet package manager. Other managers can use the `"loose"` versioning fallback: the first 3 parts are used as the version, all trailing parts are used for alphanumeric sorting. A key characteristic of the `"docker"` versioning is that it attempts to preserve the precision of the current version string. For example, if your current version has two parts (e.g., 5.6), Renovate will propose updates that also have two parts (e.g., 5.7), rather than a three-part SemVer equivalent (e.g., 5.7.0). Example Use Case: “Floating Patch Versions” using 2 digits versioning You may want to use a 2-part version like 5.6 to indicate the minor version while automatically receiving the latest patch updates (a “floating patch”). At the same time, you still want Renovate to create merge requests for minor or major updates like 5.7 or 6.2. The default semver versioning would update 5.6 to a 3-part version like 5.6.1, which would break the floating patch behavior. In the below `renovate.json` extract example, Renovate will use the `docker` versioning for the `.gitlab-ci.yml` file, so you can pin the minor version while still receiving the latest patch updates. ``` { "packageRules": [ { "matchFileNames": [".gitlab-ci.yml"], "versioning": "docker" } ] } ``` When using this strategy, make sure that the package you’re referencing does support 2-part versions, e.g. that it has a version like `5.6` available in the registry in addition to `5.6.1` or `5.6.2`. ## `vulnerabilityAlerts` Renovate can read GitHub’s Vulnerability Alerts to customize its Pull Requests. For this to work, you must enable the [Dependency graph](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/enabling-the-dependency-graph), and [Dependabot alerts](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository). Follow these steps: 1. While logged in to GitHub, navigate to your repository 2. Select the “Settings” tab 3. Select “Advanced Security” in the sidebar 4. Enable the “Dependency graph” 5. Enable “Dependabot alerts” 6. If you’re running Renovate in app mode: make sure the app has `read` permissions for “Dependabot alerts”. If you’re the account administrator, browse to the app (for example [the Mend Renovate App](https://github.com/apps/renovate)), select “Configure”, and then scroll down to the “Permissions” section and make sure that `read` access to “Dependabot alerts” is mentioned Once the above conditions are met, and you got one or more vulnerability alerts from GitHub for this repository, then Renovate tries to raise fix PRs. You may use the `vulnerabilityAlerts` configuration object to customize vulnerability-fix PRs. ``` { "vulnerabilityAlerts": { "labels": ["security"], "automerge": true, "assignees": ["@renovate-tests"] } } ``` !!! warning There’s a small chance that a wrong vulnerability alert results in a flapping/looping vulnerability fix. If you allow Renovate to `automerge` vulnerability fixes, please check if the automerged fix is correct. !!! note When Renovate creates a `vulnerabilityAlerts` PR, it ignores settings like `branchConcurrentLimit`, `commitHourlyLimit`, `prConcurrentLimit`, `prHourlyLimit`, or `schedule`. This means that Renovate _always_ tries to create a `vulnerabilityAlerts` PR. In short: vulnerability alerts “skip the line”. To disable the vulnerability alerts feature, set `enabled=false` in a `vulnerabilityAlerts` config object, like this: ``` { "vulnerabilityAlerts": { "enabled": false } } ``` !!! note If you want to raise only vulnerability fix PRs, you may use the `security:only-security-updates` preset. ### `vulnerabilityAlerts.vulnerabilityFixStrategy` When a vulnerability fix is available, Renovate will default to picking the lowest fixed version (`vulnerabilityFixStrategy=lowest`). For example, if the current version is `1.0.0`, and a vulnerability is fixed in `1.1.0`, while the latest version is `1.2.0`, then Renovate will propose an update to `1.1.0` as the vulnerability fix. If `vulnerabilityFixStrategy=highest` is configured then Renovate will use its normal strategy for picking upgrades, e.g. in the above example it will propose an update to `1.2.0` to fix the vulnerability. ``` { "vulnerabilityAlerts": { "vulnerabilityFixStrategy": "highest" } } ``` ## [Config Template Editing](https://docharvest.github.io/docs/renovate/usage/configuration-templates/) Contents renovate Config Template Editing Renovate Config Template Editing This document describes how you can edit branch names, commit messages, PR titles and PR content. ## Branch Name The branch name is very important for Renovate because it helps determine “grouping” of updates, and also makes it efficient when an existing PR needs to be updated when a newer version of a package is released. If you change the `branchPrefix` while you have ignored some upgrades (closed PR without merging), you might get a duplicate PR after the new `branchPrefix` setting is picked up by the bot. `branchName` default value is `{{{branchPrefix}}}{{{additionalBranchPrefix}}}{{{branchTopic}}}`. The most common branch name you will see looks like this: `renovate/react-18.x`. In this example, the `branchPrefix` is the default `renovate/`, `additionalBranchPrefix` is empty, and `branchTopic` is `react-18.x`. Most users will be happy with the default `branchPrefix` of `renovate/`, but you can change this if you don’t like the default. Say you don’t want the forward slashes, in that case you would use `renovate-` as your `branchPrefix`. The onboarding PR will always use `renovate/configure`. `additionalBranchPrefix` is optional and by default is empty. `branchTopic` depends on the package manager and upgrade type, so you will see a lot of variety. This is probably a setting you want to change yourself. Be careful, and consider creating a new “config help” post at the [discussions tab in the Renovate repository](https://github.com/renovatebot/renovate/discussions) to get help from the Renovate team with your config. ## Commit Message Renovate uses one commit per branch. The `commitMessage` reflects the contents of the branch and is usually the same as the PR title. `commitMessage` has a default value of `{{{commitMessagePrefix}}} {{{commitMessageAction}}} {{{commitMessageTopic}}} {{{commitMessageExtra}}} {{{commitMessageSuffix}}}`, with the intention that you only edit some of those subcomponents. You usually don’t need to edit `commitMessagePrefix`, this option is used by Renovate if it needs to add a prefix to conform to the Semantic Commit convention. Avoid editing the commit message, unless you know what you’re doing. `commitMessageAction` is usually one word, like ‘Update’, ‘Pin’, ‘Refresh’, etc. You’re probably fine leaving this setting alone, though you can change it. e.g. if you prefer that Renovate uses the term ‘Upgrade’ instead of ‘Update’ then you could configure `"commitMessageAction": "Upgrade"`. `commitMessageTopic` is usually two to three words that show _what_ is being updated. e.g. it might be `dependency react` or `Docker image ubuntu`. You may want to edit this. If you think your new `commitMessageTopic` is helpful for others, please [open a PR](https://github.com/renovatebot/renovate/pulls). `commitMessageExtra` refers to the version being updated to. e.g. `to v18` for a major upgrade, or `to v18.0.2` for a patch update. It can be empty in some cases, like if the action/topic doesn’t change a package version, e.g. `Pin Docker digests`. `commitMessageSuffix` defaults to empty but is currently used in two cases: - Differentiating major from non-major groups - Differentiating between PRs from different base branches, maybe for `major` updates you always want the PR to end with `(MAJOR)`, for instance `commitBody` is used if you wish to add multi-line commit messages, such as for the `Signed-off-by` fields, or adding `[skip-ci]`, etc. It is appended to the generated `commitMessage`, separated by a newline. ## PR Title Because commit messages match with the PR title, the PR title template defaults to `null` and inherits/copies the value from `commitMessage`. If you have a requirement where `prTitle` should be different from `commitMessage`, then please [raise a feature request](https://github.com/renovatebot/renovate/issues) for discussion. ## PR Body You can change the PR body in the following ways: - Change the entire layout/flow by using `prBodyTemplate` (we do not recommend this) - Add a header by using `prHeader` - Add a footer by using `prFooter` - Add a note by using `prBodyNotes` - Edit the embedded table by using `prBodyDefinitions` and `prBodyColumns` ## [Contributing to Renovate](https://docharvest.github.io/docs/renovate/usage/contributing-to-renovate/) Contents renovate Contributing To Renovate Renovate Contributing To Renovate Thank you for thinking of contributing to Renovate! The [`docs/development/` directory of the `renovatebot/renovate` repository](https://github.com/renovatebot/renovate/tree/main/docs/development) has all the developer-facing documentation. ## I want to write code ### Read this first 1. [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) 2. [Best practices](https://github.com/renovatebot/renovate/blob/main/docs/development/best-practices.md) 3. [Local Development](https://github.com/renovatebot/renovate/blob/main/docs/development/local-development.md) or [Remote Development](https://github.com/renovatebot/renovate/blob/main/docs/development/remote-development.md) ### Creating/editing Renovate preset 1. [Creating/editing Renovate presets](https://github.com/renovatebot/renovate/blob/main/docs/development/creating-editing-renovate-presets.md) ### Adding a new package manager 1. [Adding a Package Manager](https://github.com/renovatebot/renovate/blob/main/docs/development/adding-a-package-manager.md) ### Background information 1. [Design Decisions](https://github.com/renovatebot/renovate/blob/main/docs/development/design-decisions.md) 2. [Zod schema guideline](https://github.com/renovatebot/renovate/blob/main/docs/development/zod.md) 3. [Branches and commits behavior](https://github.com/renovatebot/renovate/blob/main/docs/development/branches-commits.md) 4. [Configuration](https://github.com/renovatebot/renovate/blob/main/docs/development/configuration.md) 5. [Static Data](https://github.com/renovatebot/renovate/blob/main/docs/development/static-data.md) 6. [How to bump Renovate to next NodeJS LTS release](https://github.com/renovatebot/renovate/blob/main/docs/development/bump-node-major.md) ## I want to write documentation Read the [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md), and the [Renovate style guide](https://github.com/renovatebot/renovate/blob/main/docs/development/style-guide.md). ## I want to triage incoming discussions Start by reading: 1. [Contributing guide](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) 2. [Triage guide](https://github.com/renovatebot/renovate/blob/main/docs/development/triage-guide.md) 3. [Issue labeling](https://github.com/renovatebot/renovate/blob/main/docs/development/issue-labeling.md) You may need to direct a Renovate user to one of these pages: 1. [About minimal reproductions](https://github.com/renovatebot/renovate/blob/main/docs/development/minimal-reproductions.md) 2. [New package manager questionnaire](https://github.com/renovatebot/renovate/blob/main/docs/development/new-package-manager-template.md) 3. [Help Us Help You](https://github.com/renovatebot/renovate/blob/main/docs/development/help-us-help-you.md) ## [Should you Pin your JavaScript Dependencies?](https://docharvest.github.io/docs/renovate/usage/dependency-pinning/) Contents renovate Should you Pin your JavaScript Dependencies? Renovate Should you Pin your JavaScript Dependencies? Once you start using a tool/service like Renovate, probably the biggest decision you need to make is whether to “pin” your dependencies instead of using SemVer ranges. The answer is “It’s your choice”, but we can certainly make some generalizations/recommendations to help you. If you don’t want to read the in-depth discussion, you can skip ahead to our recommendations in the [“So what’s best?” section](#so-whats-best). ## What is Dependency Pinning? To ensure we’re all talking about the same thing, it’s important to define exactly what we mean by dependency “pinning”. Historically, projects use SemVer ranges in their `package.json`. For instance, if you run `npm install foobar` you will see an entry like `"foobar": "^1.1.0"` added to your `package.json`. Verbosely, this means “any foobar version greater than or equal to 1.1.0 but less than 2”. The project will automatically use `1.1.1` if it’s released, or `1.2.0`, or `1.2.1`, etc - meaning you will get not only patch updates but also feature (minor) releases too. Another alternative is ranges like `"foobar": "~1.1.0"` which means “any foobar version greater than or equal to 1.1.0 but less than 1.2”. This narrows the range to only patch updates to the 1.1 range. If instead you “pin” your dependencies rather than use ranges, it means you use exact entries like `"foobar": "1.1.0"` which means “use only foobar version 1.1.0 and no other”. ## Why use ranges? For projects of any type, the main reason to use ranges is so that you can “automatically” get updated releases - which may even include security fixes. By “automatically”, we mean that any time you run `npm install` you will get the very latest version matching your SemVer - assuming you’re not using a lock file, that is. ### Tilde vs Caret If you’re familiar with the theory of SemVer, you might think that you only need to use tilde ranges (e.g. `"~1.1.0"`) to get bug fixes, rather than caret ranges (e.g. `"^1.1.0"`). This is true in theory but not in practice. The reality is that for most projects, fixes are not “backported” to previous minor releases, and minor releases themselves may include fixes. So for example release `1.2.0` may include one new feature and one fix, so if you stick with `1.1.0` then you will miss out on the fix as there will never be a `1.1.1` once `1.2.0` is already released. This is the _reality_ of most open source packages. ### Ranges for Libraries A second reason for using ranges applies to “libraries” that are published as npm packages with the intention that they are used/`require()`’d by other packages. In this case, it is usually a bad idea to pin all your dependencies because it will introduce an unnecessarily narrow range (one release!) and cause most users of your package to bloat their `node_modules` with duplicates. For example, you might have pinned `foobar` to version `1.1.0` and another author pinned his/her `foobar` dependency to `1.2.2`. Any user of both your packages will end up with npm trying to install two separate versions of `foobar`, which might not even work. Even if both projects use a service like Renovate to keep their pinned dependencies up to date with the very latest versions, it’s still not a good idea - there will always be times when one package has updated/released before the other one and they will be out of sync. e.g. there might be a space of 30 minutes where your package specifies foobar `1.1.0` and the other one specifies `1.1.1` and your joint downstream users end up with a duplicate. ## Why pin dependencies? You mainly pin versions for certainty, and visibility. When you have a pinned version of each dependency in your `package.json`, you know exactly which version of each dependency is installed at any time. This benefits when upgrading versions as well as when rolling back in case of problems. !!! note We’ll cover lock files later, don’t worry. ### Upgrading pinned versions Let’s say that a “faulty” version `1.2.0` of `foobar` is released and it breaks one of your tests. If you were using default caret SemVer ranges, then your `main` branch is now “broken” because its `package.json` says that any version 1.x above 1.1.0 is acceptable, and npm will choose the latest (`1.2.0`). You would need to manually check and work out which dependency caused the failure (`foobar` may not have been the only dependency to have “automatically” upgraded since the last time your tests passed) and then you would need to pin the dependency yourself to stop `npm` installing `1.2.0`. Consider the same situation if instead you were _pinning_ dependency versions. Your `main` branch would not be broken because it’s pinned to `foobar@1.1.0` - instead you’d have a Pull Request for upgrading to `foobar@1.2.0` which would fail. You’d know not to merge it and can wait for `foobar@1.2.1` or later when it’s fixed. By pinning dependencies you know exactly what you’re running and you know exactly what failed. Now consider a similar theoretical scenario where `foobar@1.2.0` is faulty but it is _not_ caught by any of your automated tests. This is more common and more dangerous. If you were using SemVer ranges then this new version of `foobar` will likely be deployed to production automatically one day, sometime after which you notice errors and realize you need to fix it. Like before, you need to manually work out which dependency caused it - assuming you guess correctly that it was a new dependency version at fault - and pin it manually by editing `package.json` one dependency at a time. Alternatively, if you were instead pinning `foobar` then you would get a PR for `foobar@1.2.0` which awaits your approval. So first of all, you can choose to read the changelogs and/or visually inspect the branch yourself before merging, hopefully saving you from pushing this faulty code to production. If you did not catch the fault before merging, you are still better off with a pinned version. If you discover something wrong in production, you can easily “roll back” commits in your development environment until you find which rollback fixes the problem. Then you can simply revert that commit (reversing `foobar@1.1.0` → `foobar@1.2.0`) and push that to `main`. When the next release of `foobar` comes out (e.g. `1.2.1`) you will be prompted with a new PR and hopefully inspect it carefully this time before merge! As you can see in the above, pinning dependencies makes your build more consistent and predictable as a developer. ### Downside of pinned dependencies - upgrade “noise” The one major downside to your development workflow of pinning dependencies is the potential for increased “noise” in your repository. As mentioned above, you can expect to get Pull Requests whenever there is a new version of your dependencies available. Depending on how many repositories you maintain, and how many dependencies are in each, you may find this default approach to be overwhelming (e.g. waking up to 10 new Pull Requests each day). ## Reducing the “noise” of dependency updates The increased volume of Pull Requests for upgrading dependencies may be considered by some to be undesirable “noise” in their day. To some extent this is simply a trade-off for having your dependencies pinned and predictable, but there are also ways you can reduce this noise while still gaining the majority of the benefits: ### Pull Request automerging There are some dependencies that either (a) don’t have the potential to break something in production, or (b) are fully tested by your tests. For example, it’s very hard for `eslint` to break anything in production. If your build/tests pass, then you are fine. Consider enabling automerge for all lint packages to save yourself the work of manually approving the update each time. In this case you might wake up to 5/10 of your overnight Pull Requests having already merged themselves. Another example of a good candidate for automerging might be a database driver like `node-postgres` (`pg` on npm), if you have 100% test coverage of your API. In that case if the `pg` package has a minor or patch update and passes all tests then you may as well merge it automatically if you were not going to do a manual inspection anyway. ### Branch automerging In the above suggestion of Pull Request automerging, you might still find it annoying if you get GitHub Notifications for every PR that is created and merged. In that case, you could set `automergeType` to `branch`, which means Renovate will: - Create a new branch for testing - Wait until after tests have completed - Push the commit directly to `main` if tests pass, or - Raise a PR only if tests failed With this approach, updates will be essentially “silent” - causing no notifications - but you will be able to see each commit on `main` of course. ### Scheduling Although it can feel satisfying to get updates “immediately” when they’re available, the reality is that you usually don’t _need_ updates so frequently. And worse still, npm package versions that are less than 72 hours [can be unpublished](https://docs.npmjs.com/policies/unpublish), which would really break your build if you’ve pinned to a version that no longer exists. So to reduce the interruptions of automated dependency updates, consider putting Renovate on a schedule, such as: - Update only on weekends? This way you update packages at most once per week, _and_ your CI build runners are likely to be idle anyway - Update daily, but between midnight and 5am? This way developers aren’t bothered by notifications when they’re working, _and_ you’re keeping the build machines free for the developers To learn all about controlling Renovate’s schedule, read the [key concepts, scheduling](./key-concepts/scheduling.md) docs. ### Grouping related packages Although it’s good to isolate each dependency update for ease of troubleshooting, there are times when the extra noise isn’t worth it, or when packages naturally belong together anyway (such as all `babel` packages). You can add a package rule in our Renovate configuration to group these together and you’ll get one branch combined even if multiple packages have updates available. ## Pinning Dependencies and Lock Files Since both `yarn` and `npm@5` both support lock files, it’s a common question to ask “Why should I pin dependencies if I’m already using a lock file?”. It’s a good question! { loading=lazy } Lock files are a great companion to SemVer ranges _or_ pinning dependencies, because these files lock (pin) deeper into your dependency tree than you see in `package.json`. ### What a lock file will do for you When kept in sync with its associated `package.json`, a lock file will further lock down the exact dependencies and _sub_\-dependencies that your project uses, so that everyone running `npm install` or `yarn install` will install the exact same dependencies as the person or bot that last updated the lock file. To reuse an earlier example, this means that you could have `foobar@^1.1.0` in your `package.json` and be locked to `1.1.0` in your lock file, so that when the broken `foobar@1.2.0` is released, nobody on the team installs it. ### What a lock file doesn’t do for you If a lock file gets out of sync with its `package.json`, it can no longer be guaranteed to lock anything, and the `package.json` will be the source of truth for installs. The lock file has only delayed the inevitable problem, and provides much less visibility than `package.json`, because it’s not designed to be human readable and is quite dense. { loading=lazy } If the `package.json` has a range, and a new in-range version is released that would break the build, then essentially your `package.json` is in a state of “broken”, even if the lock file is still holding things together. The upside is that the lockfile will hold back `foobar` to `1.1.0` unless it’s forced to upgrade, so the break is postponed. The downside is _how_ you will discover the break eventually. The easiest case is if for some reason you _need_ to upgrade `foobar`, e.g. for a new feature it has, so you might run something like `yarn upgrade foobar`. Then you might either discover the break during your development or when you push your new development to CI for testing. In this case, hopefully you’ll guess it’s `foobar` that broke it and not your own code. Alternatively, maybe someone thinks “This lockfile is probably really out of date and might be missing some essential patches” and decides to `yarn upgrade` the whole thing in one go. No doubt the diff will be full of green and red as many direct and indirect dependencies will have changed versions. Then it’s pushed to CI for testing, fails, and you have to guess which of the changes caused it until you eventually narrow it down to `foobar`. This might require even manually looking through the lock file diffs line by line. Maybe dep `blahblah` also broke at the same time, to make it even harder. By ceding control of direct dependency versions to the lock file, you have lost the ability to _know_ when things are updated. You also may be missing out on really important patches you’re not even aware of, because they’re “in range” yet locked back to vulnerable or buggy versions in the lock file. Reconsider the same scenario if `foobar` had instead been pinned to `1.1.0` in `package.json`. The (broken) upgrade to `1.2.0` would have been explicitly proposed to you via a Renovate PR, you would see the break, and know that the version is bad. Meanwhile you could be upgrading all the other essential fixes of other dependencies without worrying about `foobar`. You could even be running `yarn upgrade` regularly to be getting _indirect_ package updates in the lockfile and seeing if everything still passes. So the lock file does not solve the same SemVer problems that pinning solves - but it compliments it. For this reason our usual recommendation is using a lock file regardless of whether you pin dependencies or not, and pinning even if you have a lock file. But you may also go ahead and configure however you want. Also, we’re open to ideas for how to make lock file updates more “visible” too. e.g. are you interested in a Renovate feature where you get a lockfile-only PR any time a direct dependency gets an in-range update? ## What about indirect/sub-dependencies? A good argument made by [@LinusU](https://github.com/LinusU) is: > Pinning will only protect you against breakage in a, in many cases, small percentage of your packages. If you for example have installed Express and pinned it, you will only protect yourself against a bad Express release, it will not help with the 30 dependencies that Express has. > > Because of this, I personally think that pinning dependencies just creates a false sense of security, and that using a lock file is superior in every way. It is true that pinning applies only to direct dependencies, and “indirect” dependencies typically count for a lot more in total in your lockfile than direct. e.g. those 30 ones that Express relies on. Does pinning give you “increased” security? Undeniably. The question is not whether it does, but whether that increased security comes at a cost (e.g. “noise”). But Linus also points out that a _false_ sense of security is a cost too. Don’t forget that there is some form of transitive trust too. You need to pick your direct dependencies carefully, and which versions of them you use. Hopefully in doing that you pick dependencies partly for how well _they_ look after their own dependencies and versions (e.g. do they have good enough test coverage, do they use something like Renovate to keep updated, etc?). So the reality is that even if 90% of the entries in your lock file are indirect dependencies, those are ones you have somewhat “delegated” responsibility for to your dependencies. e.g. I’d hope that Express are even better at watching their dependencies for breaks than I am, to use the example above. But certainly “does it give a false sense of security” is not a question we can really answer quantifiably. ## So what’s best? We recommend: 1. Any apps (web or Node.js) that aren’t `require()`’d by other packages should pin all types of dependencies for greatest reliability/predictability 2. Browser or dual browser/node.js libraries that are consumed/`required()`’d by others should keep using SemVer ranges for `dependencies` but can use pinned dependencies for `devDependencies` 3. Node.js-only libraries can consider pinning all dependencies, because application size/duplicate dependencies are not as much a concern in Node.js compared to the browser. Of course, don’t do that if your library is a micro one likely to be consumed in disk-sensitive environments 4. Use a lock file As noted earlier, when you pin dependencies then you will see an increase in the raw volume of dependency updates, compared to if you use ranges. If/when this starts bothering you, add Renovate rules to reduce the volume, such as scheduling updates, grouping them, or automerging “safe” ones. ## References This is a “living” document and we plan to update it whenever we think of something new or someone makes a valid point we’ve missed or misunderstood. Updated 2018-01-19 after [excellent feedback on lockfiles](https://github.com/commitizen/cz-conventional-changelog-default-export/pull/4#issuecomment-358038966) by [@LinusU](https://github.com/LinusU) ## [Docker](https://docharvest.github.io/docs/renovate/usage/docker/) Contents renovate Docker Renovate Docker Renovate supports upgrading dependencies in various types of Docker definition files: - Docker’s `Dockerfile` files - Docker Compose `docker-compose.yml`, `compose.yml` files - Visual Studio Code dev containers and GitHub Codespaces images and features - CircleCI config files - Kubernetes manifest files - Ansible configuration files ## How It Works 1. Renovate searches in each repository for any files matching each manager’s configured `managerFilePatterns` 2. Matching files are parsed, Renovate checks if the file(s) has any Docker image references (e.g. `FROM` lines in a `Dockerfile`) 3. If the image tag in use “looks” like a version (e.g. `myimage:1`, `myimage:1.1`, `myimage:1.1.0`, `myimage:1-onbuild`) then Renovate checks the Docker registry for upgrades (e.g. from `myimage:1.1.0` to `myimage:1.2.0`) ## Preservation of Version Precision By default, Renovate preserves the precision level specified in the Docker images. For example, if the existing image is pinned at `myimage:1.1` then Renovate only proposes upgrades to `myimage:1.2` or `myimage:1.3`. This means that you will not get upgrades to a more specific versions like `myimage:1.2.0` or `myimage:1.3.0`. Renovate does not yet support “pinning” an imprecise version to a precise version, e.g. from `myimage:1.2` to `myimage:1.2.0`, but it’s a feature we’d like to work on one day. ## Version compatibility Although suffixes in SemVer indicate pre-releases (e.g. `v1.2.0-alpha.2`), in Docker they typically indicate compatibility, e.g. `1.2.0-alpine`. By default Renovate assumes suffixes indicate compatibility, for this reason Renovate will not _change_ any suffixes. Renovate will update `1.2.0-alpine` to `1.2.1-alpine` but never updates to `1.2.1` or `1.2.1-stretch` as that would change the suffix. If this behavior does not suit a particular package you have, Renovate allows you to customize the `versioning` scheme it uses. For example, you have a Docker image `foo/bar` that sticks to SemVer versioning. This means that you need to tell Renovate that suffixes indicate pre-release versions, and not compatibility. You could then use this `packageRules` array, to tell Renovate to use `semver` versioning for the `foo/bar` package: ``` { "packageRules": [ { "matchDatasources": ["docker"], "matchPackageNames": ["foo/bar"], "versioning": "semver" } ] } ``` Another example is the official `python` image, which follows `pep440` versioning. ``` { "packageRules": [ { "matchDatasources": ["docker"], "matchPackageNames": ["python"], "versioning": "pep440" } ] } ``` If traditional versioning doesn’t work, try Renovate’s built-in `loose` `versioning`. Renovate will perform a best-effort sort of the versions, regardless of whether they have letters or digits. If both the traditional versioning, and the `loose` versioning do not give the results you want, try the `regex` `versioning`. This approach uses regex capture group syntax to specify which part of the version string is major, minor, patch, pre-release, or compatibility. See the docs for `versioning` for documentation and examples of `regex` versioning in action. ## Digest Pinning We recommend that you pin your Docker images to an exact digest. By pinning to a digest you make your Docker builds immutable, every time you do a `pull` you get the same content. If you work with dependencies in the JavaScript/npm ecosystem, you may be used to exact versions being immutable. For example, if you set a version like `2.0.1`, you and your colleagues always get the exact same “code”. Docker’s tags are not immutable versions, even if tags _look_ like a version. You probably expect `myimage:1` and `myimage:1.2` to change over time, but you might incorrectly assume that `myimage:1.2.0` never changes. Although it probably _shouldn’t_, the reality is that any Docker image tag _can_ change content, and potentially break. By replacing Docker tags with Docker digests as the image’s primary identifier you’ll get immutable builds. Working with strings like `FROM node@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e` is hard. Luckily Renovate can update the digests for you. When pinning a digest, Renovate retains the Docker tag in the `FROM` line for readability, like this: `FROM node:14.15.1@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`. ## Digest Updating If you follow our advice to replace a tag like `node:14` with a pinned digest like `node:14@sha256:d938c1761e3afbae9242848ffbb95b9cc1cb0a24d889f8bd955204d347a7266e`, you will get Renovate PRs whenever the `node:14` image is updated on Docker Hub. Previously this update would have been “invisible” to you - one day you pull code that represents `node:14.15.0` and the next day you pull code that represents `node:14.15.1`. But you can never be sure, especially as Docker caches. Maybe some of your colleagues, or worse still your build machine, are stuck on an older version with a security vulnerability. By pinning to a digest instead, you will get these updates via Pull Requests, or even committed directly to your repository if you enable branch automerge for convenience. This makes sure everyone on your team uses the latest versions. ## Version Upgrading Renovate also supports _upgrading_ versions in Docker tags, so from `myimage:1.2.0` to `myimage:1.2.1`, or from `myimage:1.2` to `myimage:1.3`. If a tag looks like a version, Renovate will upgrade it like a version. We recommend you use the `major.minor.patch` tagging scheme, so change `myimage:1` to `myimage:1.1.1` first. This way you can see the changes in Renovate PRs. You can see the difference between a PR that upgrades `myimage` from `1.1.1` to `1.1.2` and a PR that changes the contents of the version you already use (`1.1.1`). By default, Renovate will upgrade `minor` and `patch` versions, so from `1.2.0` to `1.2.1`, but _not_ upgrade `major` versions. If you wish to enable `major` versions: add the preset `docker:enableMajor` to the `extends` array in your `renovate.json` file. Renovate has some Docker-specific intelligence when it comes to versions. For example: ### Ubuntu codenames Renovate understands [Ubuntu release code names](https://wiki.ubuntu.com/Releases) and will offer upgrades to the latest LTS release. You must only use the _first_ term of the code name in _lowercase_. So use `noble` for the Noble Numbat release. For example, Renovate will offer to upgrade the following `Dockerfile` layer: ``` - FROM ubuntu:jammy + FROM ubuntu:noble ``` ### Debian codenames Renovate understands [Debian release code names and rolling updates schedule](https://wiki.debian.org/DebianReleases) and will offer upgrades to the latest stable release. For example from `debian:bullseye` to `debian:bookworm`. Renovate also supports dated container image versions for Debian, such as `debian:bookworm-20230816` or `debian:bullseye-20220101.2`. These are commonly used in Debian Docker images to pin to specific snapshots. The Debian codename must be in _lowercase_. For example, Renovate will offer to upgrade the following `Dockerfile` layer: ``` - FROM debian:bullseye + FROM debian:bookworm ``` Or for dated versions: ``` - FROM debian:bookworm-20230816 + FROM debian:bookworm-20230901 ``` ## Configuring/Disabling If you wish to make changes that apply to all Docker managers, then add them to the `docker` config object. This is not foolproof, because some managers like `circleci` and `ansible` support multiple datasources that do not inherit from the `docker` config object. If you wish to override Docker settings for one particular type of manager, use that manager’s config object instead. For example, to disable digest updates for Docker Compose only but leave them for other managers like `Dockerfile`, you would use this: ``` { "docker-compose": { "digest": { "enabled": false } } } ``` The following configuration options are applicable to Docker: ### Disable all Docker Renovation Add `"docker:disable"` to your `extends` array. ### Disable Renovate for only certain Dockerfiles Add all paths to ignore into the `ignorePaths` configuration field. e.g. ``` { "extends": ["config:recommended"], "ignorePaths": ["docker/old-files/"] } ``` ### Enable Docker major updates Add `"docker:enableMajor"` to your `extends` array. ### Disable digest pinning Add `"default:pinDigestsDisabled"` to your `extends` array. !!! note This preset only sets the global default for the [digest pinning flag](./configuration-options.md#pindigests) to `false`. If you have configured package rules that set `pinDigests` to `true`, those will still apply. This is also the case if you use the [`docker:pinDigests` preset](./presets-docker.md#dockerpindigests), which adds a package rule that sets `pinDigests` to `true` for all packages from the docker datasource. If you want to disable the `docker:pinDigests` preset (e.g. if you want to use `config:best-practices` but not have digest pinning enabled), ignore the preset like this: ``` { "extends": ["config:best-practices"], "ignorePresets": ["docker:pinDigests"] } ``` ### Automerge digest updates Add `"default:automergeDigest"` to your `extends` array. If you want Renovate to commit directly to your base branch without opening a PR first, add `"default:automergeBranchPush"` to the `extends` array. ### Registry authentication There are many different registries, and many ways to authenticate to those registries. We will explain how to authenticate for the most common registries. #### Docker Hub Here is an example of configuring a Docker username/password for Docker Hub in `config.js`. The Docker Hub password is stored in a process environment variable. ``` module.exports = { hostRules: [ { hostType: 'docker', matchHost: 'docker.io', username: '', password: process.env.DOCKER_HUB_PASSWORD, }, ], }; ``` You can add more host rules, read the [`hostRules` documentation](./configuration-options.md#hostrules) for more information. #### Self-hosted Docker registry Say you host some Docker images yourself, and use a password to access your self-hosted Docker images. In addition to self-hosting, you also pull images from Docker Hub, without a password. In this example you would configure a specific Docker host like this: ``` module.exports = { hostRules: [ { hostType: 'docker', matchHost: 'your.host.io', username: '', password: process.env.SELF_HOSTED_DOCKER_IMAGES_PASSWORD, }, ], }; ``` #### AWS ECR (Amazon Web Services Elastic Container Registry) ##### Using access key id & secret Renovate can authenticate with AWS ECR using AWS access key id & secret as the username & password, for example: ``` { "hostRules": [ { "hostType": "docker", "matchHost": "12345612312.dkr.ecr.us-east-1.amazonaws.com", "username": "AKIAABCDEFGHIJKLMNOPQ", "encrypted": { "password": "w...A" } } ] } ``` ##### Using `get-login-password` Renovate can also authenticate with AWS ECR using the output from the `aws ecr get-login-password` command as outlined in the [AWS documentation](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html#registry-auth-token). To make use of this authentication mechanism, specify the username as `AWS`: ``` { "hostRules": [ { "hostType": "docker", "matchHost": "12345612312.dkr.ecr.us-east-1.amazonaws.com", "username": "AWS", "encrypted": { "password": "w...A" } } ] } ``` #### Google Container Registry / Google Artifact Registry ##### Using Workload Identity To let Renovate authenticate with [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity), you must: - Configure Workload Identity - Give the Service Account the `artifactregistry.repositories.downloadArtifacts` permission ###### With Application Default Credentials (self-hosted only) To let Renovate authenticate with [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc), you must: - Configure ADC as normal - _Not_ provide a username, password or token Renovate will get the credentials with the [`google-auth-library`](https://www.npmjs.com/package/google-auth-library). ###### With short-lived access token / GitHub Actions (self-hosted only) ``` - name: authenticate to google cloud id: auth uses: google-github-actions/auth@v3.0.0 with: token_format: 'access_token' workload_identity_provider: ${{ env.WORKLOAD_IDENTITY_PROVIDER }} service_account: ${{ env.SERVICE_ACCOUNT }} - name: renovate uses: renovatebot/github-action@v46.1.17 env: RENOVATE_HOST_RULES: | [ { matchHost: "us-central1-docker.pkg.dev", hostType: "docker", username: "oauth2accesstoken", password: "${{ steps.auth.outputs.access_token }}" } ] with: token: ${{ secrets.RENOVATE_TOKEN }} configurationFile: .github/renovate.json5 ``` You can find a full GitHub Workflow example on the [renovatebot/github-action](https://github.com/renovatebot/github-action) repository. ##### Using long-lived service account credentials To access the Google Container Registry (deprecated) or the Google Artifact Registry, use the JSON service account with `Basic` authentication, and use the: - `_json_key` as username - full Google Cloud Platform service account JSON as password To avoid JSON-in-JSON wrapping, which can cause problems, encode the JSON service account beforehand. Google Container Registry does not natively support `_json_key_base64` and a base64 encoded service account. Google Artifact Registry supports `_json_key_base64` and a base64 encoded service account natively. If all your dependencies are on the Google Artifact Registry, you can base64 encode and use the service account directly: 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts 2. Base64 encode the service account credentials by running `cat service-account.json | base64` 3. Add the encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: ``` { "hostRules": [ { "matchHost": "europe-docker.pkg.dev", "username": "_json_key_base64", "password": "" } ] } ``` 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ``` { "hostRules": [ { "matchHost": "europe-docker.pkg.dev", "username": "_json_key_base64", "encrypted": { "password": "" } } ] } ``` If you have dependencies on Google Container Registry (and Artifact Registry) you need to use `_json_key` and a slightly different encoding: 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts 2. Open the file and prefix the content with `_json_key:`. The file should look like this: ``` _json_key:{ "type": "service_account", "project_id": "sample-project", "private_key_id": "5786ff7e615522b932a2a37b4a6f9645c4316dbd", "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDaOkxZut9uDUHV\n...\n/PWs0Wa2z5+IawMD7nO63+b6\n-----END PRIVATE KEY-----\n", "client_email": "renovate-lookup@sample-project.iam.gserviceaccount.com", "client_id": "115429165445403928973", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/renovate-lookup%40sample-project.iam.gserviceaccount.com" } ``` 3. Base64 encode the prefixed service account credentials by running `cat prefixed-service-account.json | base64` 4. Add the prefixed and encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: ``` { "hostRules": [ { "matchHost": "europe-docker.pkg.dev", "authType": "Basic", "token": "" } ] } ``` 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ``` { "hostRules": [ { "matchHost": "europe-docker.pkg.dev", "authType": "Basic", "encrypted": { "token": "" } } ] } ``` ##### Using short-lived access token / Gitlab CI / Google Cloud For this example, assume that you want to: - Run the GitLab CI in the Google Cloud - Store your Docker images in the Google Container Registry (GCR) ###### Accessing the Google Container Registry Accessing the GCR uses Bearer token based authentication. First, install the Google Cloud SDK. Then get the token by running: `gcloud auth print-access-token`. ###### Short-lived GCR Bearer tokens The GCR Bearer token expires after 60 minutes. This means you can _not_ re-use the token in a later build. Instead, _before_ Renovate starts in the GCR context, you must: 1. Fetch the Google access token 2. Inject the token into the `hostRules` configuration The following text explains one way to fetch the token, and inject it into Renovate. ###### Basic approach The basic approach is: 1. Create a custom image: fetch the GCR token, and inject the token into Renovate’s `config.js` file 2. Then run Renovate as one of the stages of your project ###### Independent runs To make the run independent of any user, use a [`Project Access Token`](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html). Give the Project Access Token these scopes: - `api` - `read_api` - `write_repository` Then use the Project Access Token as the `RENOVATE_TOKEN` variable for GitLab CI. For more (`gitlab-ci.yml`) configuration examples, see the [`renovate-runner` repository on GitLab](https://gitlab.com/renovate-bot/renovate-runner). ###### Create a custom image To access the token, you need a custom Renovate Docker image. Make sure to install the Google Cloud SDK into the custom image, as you need the `gcloud auth print-access-token` command later. For example: ``` FROM renovate/renovate:43.246.1 # Include the "Docker tip" which you can find here https://cloud.google.com/sdk/docs/install # under "Installation" for "Debian/Ubuntu" RUN ... ``` ###### Accessing the Google Container Registry (GCR) Renovate needs the current Google Access Token to access the Google Container Registry (GCR). Here’s an example of how to set that up: ``` hostRules: [ { matchHost: 'eu.gcr.io', token: 'MyReallySecretTokenThatExpiresAfter60Minutes', }, ]; ``` One way to give Renovate the short-lived Google Access Token is to: 1. Write a script that generates a `config.js` file, with the token, in your `gitlab-ci.yml` file 2. Run the `config.js` creation script just before you start Renovate For example: ``` script: - 'echo "module.exports = { hostRules: [ { matchHost: ''eu.gcr.io'', token: ''"$(gcloud auth print-access-token)"'' } ] };" > config.js' - renovate $RENOVATE_EXTRA_FLAGS ``` ## [Docker Build Process](https://docharvest.github.io/docs/renovate/usage/docker-build-process/) Contents renovate Docker Build Process Renovate The Renovate CLI is distributed for use in a few ways, one of which is as a pre-built container. As part of this build process, there are two key variants of this: - “slim” image (default) - “full” image ## Slim image (default) Renovate’s “slim” image is recommended as the minimal set of installed tools on a given container to be able to run Renovate. It uses [`binarySource=install`](./self-hosted-configuration.md#binarysource) to dynamically install tools as they’re needed. This keeps the base container quite lightweight (hence “slim”) but requires outbound network access at runtime. It is possible to make the “slim” container even more lightweight by removing some of the tools and packages - for instance to reduce the attack surface, or reduce the size of the resulting image - but that is left as an exercise to the reader. ## Full image Renovate’s “full” image is recommended for users who prefer to have most tools pre-installed, and not require any outbound access at runtime. It uses [`binarySource=global`](./self-hosted-configuration.md#binarysource) which only uses tools that are installed in the image. When using the “full” image, there are some tools and packages installed in the container that you may not be using. It is possible to remove these - for instance to reduce the attack surface, or reduce the size of the resulting image - but that is left as an exercise to the reader. ## Build process flow Renovate leverages [Containerbase](https://github.com/containerbase), a project maintained by the same maintainers as the Renovate CLI project itself, which provides base images and utilities for managing dependencies. This leads to a release process that requires multiple different container releases to result in the Renovate container image being updated. The full flow can be seen below: ``` flowchart TD Ubuntu --> ContainerbaseUbuntu ContainerbaseUbuntu --> ContainerbaseBase ContainerbaseBase --> ContainerbaseSidecar ContainerbaseSidecar --> RenovatebotBaseImage RenovatebotBaseImage --> RenovateSlim RenovatebotBaseImage --> RenovateFull Ubuntu[docker.io/library/ubuntu] ContainerbaseUbuntu[ghcr.io/containerbase/ubuntu] ContainerbaseBase[ghcr.io/containerbase/base] ContainerbaseSidecar[ghcr.io/containerbase/sidecar] RenovatebotBaseImage[ghcr.io/renovatebot/base-image] RenovateSlim[ghcr.io/renovatebot/renovate
docker.io/renovate/renovate] RenovateFull[ghcr.io/renovatebot/renovate:full
docker.io/renovate/renovate:full] ``` ## Tool support ### Adding new tools If you, as a user, are looking to extend the tool support that Renovate has, for instance to install it via [`constraints`](./configuration-options.md#constraints), then you will need to [request a new tool](https://github.com/containerbase/base/issues/new?template=new-tool.yml). !!! note In the future, there will be a [clearer guide](https://github.com/containerbase/base/issues/6570) for how to contribute tool support as a user. This tool will have its support added in `containerbase/base`, to allow Containerbase’s `install-tool` command-line tool to install the tool. Once `install-tool` support is implemented, the update to `ghcr.io/containerbase/base` will need to bubble up to the Renovate “slim” and “full” images before the tool can be used. ### Changing default tools If you, as a user, are looking to provide a tool installed by default (in the “slim” or “full” images), you will need to first make sure that the tool is supported (and if not, [add it](#adding-new-tools)). To add it to the default images, the [`renovatebot/base-image` image](https://github.com/renovatebot/base-image) will need to be amended to add this tool. !!! note Installed-by-default-tools will generally only be allowed for the “full” image. ## Building the Docker image locally Renovate’s Docker image can be built locally like so: ``` pnpm build pnpm build:docker # or to customize the build env OWNER=jamietanna pnpm build:docker build --platform linux/amd64 --version 0.0.0-local ``` ## [Environment Variable Handling](https://docharvest.github.io/docs/renovate/usage/environment-variable-handling/) Contents renovate Environment Variable Handling Renovate Environment Variable Handling ## For Renovate Renovate itself can be configured through a number of environment variables that correspond with [global self-hosted configuration options](./self-hosted-configuration.md), as well as some [repository configuration options](./configuration-options.md). These environment variables have the prefix with `RENOVATE_`. Renovate also has some [“experimental” variables that can be used with self-hosted deployments](./self-hosted-experimental.md). It is also possible to use the following configuration options to control Renovate’s environment variables: - [`processEnv`](./self-hosted-configuration.md#processenv): in a configuration file (i.e. `config.js`), allows specifying the values that Renovate will receive in its environment ## With child processes For security reasons, Renovate does not expose all environment variables to child processes. Instead, Renovate will use an allowlist of environment variables which it passes to any processes it calls. This is an intentional decision to protect against two key attack vectors: - an [“insider attack”](./security-and-permissions.md#execution-of-code-insider-attack) from a user of your self-hosted Renovate deployment - an [“outsider attack”](./security-and-permissions.md#execution-of-code-outsider-attack) from a malicious dependency By limiting the environment variables provided to child processes, we can reduce the risk of a malicious actor from receiving access to potentially sensitive information, such as authentication tokens. By default, Renovate will **always** pass the following environment variables to child processes: !!! note Some managers pass additional environment variables where necessary. For example, Renovate will convert Host Rules to the respective environment variables when calling `npm`, `pnpm` and `yarn`, including setting `GIT_CONFIG_` environment variables. This is not currently documented in full - you will need to review Renovate’s code to see the full list. As a self-hosted administrator, you can make it possible to specify other environment variables that repository owners can set, using: - [`allowedEnv`](./self-hosted-configuration.md#allowedenv): allows users to specify values for allowlisted environment variables in their repository configuration using [`env`](./configuration-options.md#env) - [`customEnvVariables`](./self-hosted-configuration.md#customenvvariables): administrator-defined environment variables, injected directly into every child process. Users cannot override these in their repository configuration - [`exposeAllEnv`](./self-hosted-configuration.md#exposeallenv): ⚠️ dangerously expose all environment variables from the Renovate process to all child processes - [`extends: ["global:safeEnv"]`](./presets-global.md#globalsafeenv): a curated list of commonly used environment variables that should be safe to allow users to configure with [`env`](./configuration-options.md#env). This is used by Mend-hosted Renovate With these option(s) configured, users will be able to set these environment variable(s) in their repository configuration using [`env`](./configuration-options.md#env), as well as [referencing them in any fields that support templating](#templating). ## Using environment variables for secrets Where possible, Renovate will try and redact secrets in its log messages, and the log output from any child processes. This relies on knowing whether the value is a secret for instance those configured through [`secrets`](./self-hosted-configuration.md#secrets) or in [`hostRules`](./configuration-options.md#hostrules). If specifying an environment variable - through the above - with a value that isn’t known to Renovate as a secret, this may lead to the secret being unknowingly exposed in the logs. ## Precedence When determining which environment variables Renovate should pass to a child process, Renovate merges with the following precedence order: ``` flowchart TD extraEnv["extraEnv
Manager-defined defaults/hints string value = default, null = inherit key only"] parentEnv["parentEnv
process.env filtered to basicEnvVars1 + string keys from extraEnv"] globalConfigEnv["globalConfigEnv
customEnvVariables set by self-hosted admin at startup"] userConfiguredEnv["userConfiguredEnv
env config in Renovate config file"] forcedEnv["forcedEnv
Hardcoded per exec-call by Renovate internals"] childProcess["Child Process"] exposeAllEnv["exposeAllEnv = true
Bypasses all layering, passes entire process.env"] processEnvConfig["processEnv
"] processEnv["process.env
The original process' process.env and processEnv"] allowedEnv["allowedEnv
Admin-controlled allowlist gates which environment variables repo owners may set"] extraEnv -->|"overridden by"| parentEnv parentEnv -->|"overridden by"| globalConfigEnv globalConfigEnv -->|"overridden by"| userConfiguredEnv userConfiguredEnv -->|"overridden by"| forcedEnv forcedEnv --> childProcess exposeAllEnv -.->|"short-circuits to"| childProcess processEnvConfig -.->|"merged into"| processEnv processEnv -.->|"filtered with basicEnvVars"| parentEnv allowedEnv -.->|"restricts"| userConfiguredEnv ``` 1: the list of environment variables [noted above](#with-child-processes) that are always passed to child processes ## Templating Allowlisted environment variables can be referenced in templates. See [templates and environment variables](./templates.md#environment-variables) for more details. ## [OpenTelemetry](https://docharvest.github.io/docs/renovate/usage/examples/opentelemetry/) Contents renovate Opentelemetry Renovate Opentelemetry Requirements: - docker-compose ## Prepare setup Create a `docker-compose.yaml` and `otel-collector-config.yml` file as seen below in a folder. ``` name: renovate-otel-demo services: # Jaeger for storing traces jaeger: image: jaegertracing/jaeger:2.19.0 ports: - '16686:16686' # Web UI - '4317' # OTLP gRPC - '4318' # OTLP HTTP # Prometheus for storing metrics prometheus: image: prom/prometheus:v3.12.0 ports: - '9090:9090' # Web UI - '4318' # OTLP HTTP command: - --web.enable-otlp-receiver # Mirror these flags from the Dockerfile, because `command` overwrites the default flags. # https://github.com/prometheus/prometheus/blob/5b5fee08af4c73230b2dae35964816f7b3c29351/Dockerfile#L23-L24 - --config.file=/etc/prometheus/prometheus.yml - --storage.tsdb.path=/prometheus otel-collector: # Using the Contrib version to access the spanmetrics connector. # If you don't need the spanmetrics connector, you can use the standard version image: otel/opentelemetry-collector-contrib:0.155.0 volumes: - ./otel-collector-config.yml:/etc/otelcol-contrib/config.yaml ports: - '4318:4318' # OTLP HTTP ( exposed to the host ) - '4317:4317' # OTLP gRPC ( exposed to the host ) depends_on: - jaeger - prometheus ``` ``` receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: otlp/jaeger: endpoint: jaeger:4317 tls: insecure: true otlphttp/prometheus: endpoint: http://prometheus:9090/api/v1/otlp debug: # verbosity: normal connectors: spanmetrics: histogram: exponential: dimensions: - name: http.method default: GET - name: http.status_code - name: http.host dimensions_cache_size: 1000 aggregation_temporality: 'AGGREGATION_TEMPORALITY_CUMULATIVE' exemplars: enabled: true processors: batch: extensions: health_check: pprof: zpages: service: extensions: [pprof, zpages, health_check] pipelines: traces: receivers: [otlp] exporters: - otlp/jaeger # Send traces to connector for metrics calculation - spanmetrics # Enable debug exporter to see traces in the logs #- debug processors: [batch] metrics: receivers: - otlp # Receive metrics from Renovate. - spanmetrics # Receive metrics calculated by the spanmetrics connector. processors: [batch] exporters: - otlphttp/prometheus # Enable debug exporter to see metrics in the logs # - debug ``` Start setup using this command inside the folder containing the files created in the earlier steps: ``` docker-compose up ``` This command will start: - an [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib) - an instance of [Jaeger for traces](https://www.jaegertracing.io/) - and [Prometheus](https://prometheus.io/) Jaeger will be now reachable under [http://localhost:16686](http://localhost:16686). ## Run Renovate with OpenTelemetry To start Renovate with OpenTelemetry enabled run following command, after pointing to your `config.js` config file: ``` docker run \ --rm \ --network renovate-otel-demo_default \ -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \ -v "/path/to/your/config.js:/usr/src/app/config.js" \ renovate/renovate:latest ``` You should now see `trace_id` and `span_id` fields in the logs. ``` INFO: Repository finished (repository=org/example) "durationMs": 5574, "trace_id": "f9a4c33852333fc2a0fbdc163100c987", "span_id": "4ac1323eeaee ``` ### Traces Open now Jaeger under [http://localhost:16686](http://localhost:16686). You should now be able to pick `renovate` under in the field `service` field. Select `Find Traces` to search for all Renovate traces and then select one of the found traces to open the trace view. You should be able to see now the full trace view which shows more information about what is happening, such as HTTP requests, execution of commands or Git operations, and how long Renovate takes to process a given branch: ### Metrics Additional to the received traces some metrics are calculated. This is achieved using the [spanmetrics connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector). The previously implemented setup will produce following metrics, which pushed to [Prometheus](http://localhost:9090): ``` ### Example of internal spans traces_span_metrics_calls_total{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 2 traces_span_metrics_calls_total{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="run", status_code="STATUS_CODE_UNSET"} 2 ### Example of http calls from Renovate to external services traces_span_metrics_calls_total{http_host="api.github.com:443", http_method="POST", http_status_code="200", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_CLIENT", span_name="POST", status_code="STATUS_CODE_UNSET"} 4 ### Example histogram metrics traces_span_metrics_duration_milliseconds_bucket{http_method="GET", job="renovatebot.com/renovate", le="8", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 0 ... traces_span_metrics_duration_milliseconds_bucket{http_method="GET", job="renovatebot.com/renovate", le="2000", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 0 traces_span_metrics_duration_milliseconds_bucket{http_method="GET", job="renovatebot.com/renovate", le="5000", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 1 traces_span_metrics_duration_milliseconds_bucket{http_method="GET", job="renovatebot.com/renovate", le="15000", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 1 traces_span_metrics_duration_milliseconds_bucket{http_method="GET", job="renovatebot.com/renovate", le="10000", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 1 traces_span_metrics_duration_milliseconds_bucket{http_method="GET", job="renovatebot.com/renovate", le="+Inf", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 1 traces_span_metrics_duration_milliseconds_sum{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 4190.694209 traces_span_metrics_duration_milliseconds_count{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repository", status_code="STATUS_CODE_UNSET"} 1 ``` The [spanmetrics connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector) creates two sets of metrics. #### Calls metric At first there are the `traces_span_metrics_calls_total` metrics. These metrics show how often _specific_ trace spans have been observed. For example: - `traces_span_metrics_calls_total{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repositories", status_code="STATUS_CODE_UNSET"} 2` signals that 2 repositories have been renovated. - `traces_span_metrics_calls_total{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="run", status_code="STATUS_CODE_UNSET"} 1` represents how often Renovate has been run. If we combine this using the PrometheusQueryLanguage ( PromQL ), we can calculate the average count of repositories each Renovate run handles. ``` traces_span_metrics_calls_total{span_name="repository",service_name="renovate"} / traces_span_metrics_calls_total{span_name="run",service_name="renovate"} ``` These metrics are generated for HTTP call spans too: ``` traces_span_metrics_calls_total{http_host="prometheus-community.github.io:443", http_method="GET", http_status_code="200", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_CLIENT", span_name="GET", status_code="STATUS_CODE_UNSET"} 5 ``` #### Latency buckets The second class of metrics exposed are the latency-focused buckets, that allow creating [heatmaps](https://grafana.com/docs/grafana/latest/basics/intro-histograms/#heatmaps). A request is added to a backed if the latency is bigger than the bucket value (`le`). `request_duration => le` As an example if we receive a request which need `1.533s` to complete get following metrics: ``` traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="0.1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="2"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="6"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="10"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="100"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="250"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="9.223372036854775e+12"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="+Inf"} 1 traces_span_metrics_duration_milliseconds_sum{http_host="api.github.com:443"} 1.533 traces_span_metrics_duration_milliseconds_count{http_host="api.github.com:443"} 1 ``` Now we have another request which this time takes 10s to complete: ``` traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="0.1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="2"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="6"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="10"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="100"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="250"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="9.223372036854775e+12"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="+Inf"} 2 traces_span_metrics_duration_milliseconds_sum{http_host="api.github.com:443"} 11.533 traces_span_metrics_duration_milliseconds_count{http_host="api.github.com:443"} 2 ``` More about the functionality can be found on the Prometheus page for [metric types](https://prometheus.io/docs/concepts/metric_types/#histogram). ## [Self-Hosting Examples](https://docharvest.github.io/docs/renovate/usage/examples/self-hosting/) Contents renovate Self Hosting Renovate Self Hosting !!! warning All self-hosted Renovate instances must operate under a trust relationship with the developers of the monitored repositories. Because of this, there are [security implications](../security-and-permissions.md#security-awareness-for-self-hosted-renovate-instances) when running a self-hosted Renovate instance, which you must consider carefully. !!! warning Most Open Source packages are hosted on github.com, including a number of tools that Renovate may pull at run-time. GitHub greatly rate limits unauthenticated API requests, so you need to configure credentials for `github.com` or the bot will get rate limited quickly.   Read [Running Renovate, GitHub.com token for changelogs](../getting-started/running.md#githubcom-token-for-changelogs-and-tools) to learn more. ## Installing Renovate OSS CLI ### npmjs ``` npm install -g renovate ``` Renovate does not embed `npm`, `pnpm` and `yarn` as its own dependencies. If you want to use these package managers to update your lockfiles, you must ensure that the correct versions are installed globally. ``` npm install -g yarn pnpm ``` The same goes for any other third-party binary tool like `gradle` or `poetry` - you need to make sure it is installed and the correct version before running Renovate. ### Docker Renovate is available for Docker via an automated build at [`renovate/renovate` on Docker Hub](https://hub.docker.com/r/renovate/renovate/). It builds `latest` based on the `main` branch and all SemVer tags are published too. ``` docker run --rm renovate/renovate docker run --rm renovate/renovate:43 docker run --rm renovate/renovate:43.246 docker run --rm renovate/renovate:43.246.1 ``` !!! warning Do not use the example tags listed above, as they will be out-of-date. Go to [the `renovate/renovate` tags on DockerHub](https://hub.docker.com/r/renovate/renovate/tags) to grab the latest tagged release from Renovate. If you want to configure Renovate using a `config.js` file then map it to `/usr/src/app/config.js` using Docker volumes. For example: ``` docker run --rm -v "/path/to/your/config.js:/usr/src/app/config.js" renovate/renovate ``` ### Kubernetes Renovate’s official Docker image is compatible with Kubernetes. The following is an example manifest of running Renovate against a GitHub Enterprise server. ``` apiVersion: batch/v1 kind: CronJob metadata: name: renovate spec: schedule: '@hourly' concurrencyPolicy: Forbid jobTemplate: spec: template: spec: containers: - name: renovate # Update this to the latest available and then enable Renovate on # the manifest image: renovate/renovate:43.246.1 args: - user/repo # Environment Variables env: - name: LOG_LEVEL value: debug envFrom: - secretRef: name: renovate-env restartPolicy: Never ``` And the `secret.yaml` that goes with it: ``` apiVersion: v1 kind: Secret metadata: name: renovate-env type: Opaque stringData: RENOVATE_GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs' # You can set RENOVATE_AUTODISCOVER to true to run Renovate on all repos you have push access to RENOVATE_AUTODISCOVER: 'false' RENOVATE_ENDPOINT: 'https://github.company.com/api/v3' RENOVATE_GIT_AUTHOR: 'Renovate Bot ' RENOVATE_PLATFORM: 'github' RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token' ``` A `config.json` file can be added to the manifest using a `ConfigMap` as shown in the following example (using a “dry run” in github.com): ``` --- apiVersion: v1 kind: ConfigMap metadata: name: renovate-config data: config.json: |- { "repositories": ["orgname/repo","username/repo"], "dryRun" : "full" } --- apiVersion: batch/v1 kind: CronJob metadata: name: renovate-bot spec: schedule: '@hourly' concurrencyPolicy: Forbid jobTemplate: spec: template: spec: containers: - image: renovate/renovate:43.246.1 name: renovate-bot env: # For illustration purposes, please use secrets. - name: RENOVATE_PLATFORM value: 'github' - name: RENOVATE_TOKEN value: 'some-token' - name: RENOVATE_AUTODISCOVER value: 'false' - name: RENOVATE_BASE_DIR value: '/tmp/renovate/' - name: RENOVATE_CONFIG_FILE value: '/opt/renovate/config.json' - name: LOG_LEVEL value: debug volumeMounts: - name: config-volume mountPath: /opt/renovate/ - name: work-volume mountPath: /tmp/renovate/ restartPolicy: Never volumes: - name: config-volume configMap: name: renovate-config - name: work-volume emptyDir: {} ``` ### CircleCI !!! warning The CircleCI configuration examples are for version `2` of `daniel-shuy/renovate`, which is outdated. Do you know how to get `daniel-shuy/renovate` version `3` working? Then please open a pull request to update the docs and close [Renovate issue #13428](https://github.com/renovatebot/renovate/issues/13428). If you are using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI. By default, the orb looks for the self-hosted configuration file in the project root, but you can specify another path to the configuration file with the `config_file_path` parameter. Secrets should be configured using environment variables (e.g. `RENOVATE_TOKEN`, `RENOVATE_GITHUB_COM_TOKEN`). [Configure environment variables in CircleCI Project Settings](https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project). To share environment variables across projects, use [CircleCI Contexts](https://circleci.com/docs/2.0/contexts/). ``` version: '2.1' orbs: renovate: daniel-shuy/renovate@2.2.0 workflows: renovate: jobs: - renovate/self-hosted: config_file_path: renovate-config.js nightly: triggers: - schedule: cron: 0 * * * * filters: branches: only: - main ``` #### Renovate config file validation when using CircleCI ``` version: '2.1' orbs: renovate: daniel-shuy/renovate@2.2.0 workflows: lint: jobs: - renovate/validate-config ``` ### GitLab CI/CD pipeline For GitLab pipelines we recommend you use the [`renovate-runner` project on GitLab](https://gitlab.com/renovate-bot/renovate-runner). We created some pipeline templates to help you run Renovate on pipeline schedules. You can also find the configuration steps there. For self-hosted GitLab clone/import the [`renovate-runner` project on GitLab](https://gitlab.com/renovate-bot/renovate-runner) project to your instance. ## File/directory usage By default, Renovate stores all files in the `renovate/` subdirectory of the operating system’s temporary directory, e.g. `/tmp/renovate/`. Repository data is copied or cloned into unique subdirectories under `repos/`, e.g. `/tmp/renovate/repos/github/owner1/repo-a/`. Renovate’s cache, and the caches(s) for npm, Yarn, Composer, and so on, are stored in `/tmp/renovate/cache`. ### Overriding the default directory If you don’t want to use the default `tmp/renovate` directory you can: - Set a value for `baseDir` in `config.js` - Use an environment variable `RENOVATE_BASE_DIR` - Use the CLI to pass a base directory: `--base-dir=` ### Overriding the default cache directory If you want to override the cache directory then set your own value for `cacheDir`. ## Usage The following example uses the Renovate CLI tool, which you can install by running `npm i -g renovate`. If running your own Renovate bot then you will need a user account that Renovate will run as. We recommend you create and use a dedicated account for the bot, e.g. name it `renovate-bot` if on your own instance. Create and save a PAT for this account. Create a Renovate config file, for example: ``` module.exports = { endpoint: 'https://self-hosted.gitlab/api/v4/', token: '**gitlab_token**', platform: 'gitlab', onboardingConfig: { extends: ['config:recommended'], }, repositories: ['username/repo', 'orgname/repo'], }; ``` Here change the `repositories` to something appropriate. Also replace `gitlab-token` value with the one created during the previous step. If you’re running against GitHub Enterprise Server, then change the `gitlab` values in the example to the equivalent GitHub ones. You can save this file as anything you want and then use the `RENOVATE_CONFIG_FILE` environment variable to tell Renovate where to find it. Most people use `cron` to schedule when Renovate runs, usually on an hourly schedule. ``` #!/bin/bash export PATH="/home/user/.yarn/bin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH" export RENOVATE_CONFIG_FILE="/home/user/renovate-config.js" export RENOVATE_TOKEN="**some-token**" # GitHub, GitLab, Azure DevOps export RENOVATE_GITHUB_COM_TOKEN="**github-token**" # Delete this if using github.com # Renovate renovate ``` Save the script file, and run the script manually. Only add the script to `cron` after you checked it works. !!! note The GitHub.com token as an environment variable is needed to fetch changelogs that are usually hosted on github.com. You don’t need to add it if you are already running the bot against github.com, but you do need to add it if you’re using GitHub Enterprise Server, GitLab, Azure DevOps, or Bitbucket. ## Kubernetes for GitLab, using Git over SSH This section describes how to use a Git binary with SSH for GitLab, to avoid API shortcomings. You need to first create a SSH key, then add the public part to GitLab (see this [guide](https://docs.gitlab.com/ee/ssh/)). Then, you need to create the secret to add the SSH key, and the following config to your container: ``` host gitlab.com HostName gitlab.com StrictHostKeyChecking no IdentityFile ~/.ssh/id_rsa User git ``` To easily create the secret, you can do the following (see [docs](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-pod-with-ssh-keys)). ``` kubectl create secret generic ssh-key-secret --from-file=config=/path/to/config --from-file=id_rsa=/path/to/.ssh/id_rsa --from-file=id_rsa.pub=/path/to/.ssh/id_rsa.pub ``` It creates something like this: ``` apiVersion: v1 data: config: aG9zdCBnaXRsYWIuY29tCiAgSG9zdE5hbWUgZ2l0bGFiLmNvbQogIFN0cmljdEhvc3RLZXlDaGVja2luZyBubwogIElkZW50aXR5RmlsZSB+Ly5zc2gvaWRfcnNhCiAgVXNlciBnaXQ= id_rsa: id_rsa.pub: kind: Secret metadata: name: ssh-key-secret namespace: ``` Then you need to add a Git author, and configure the mount volumes. The final configuration should look something like this: ``` --- apiVersion: v1 kind: Namespace metadata: name: --- apiVersion: v1 kind: Secret metadata: name: renovate-env namespace: type: Opaque stringData: RENOVATE_GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs' RENOVATE_AUTODISCOVER: 'false' RENOVATE_ENDPOINT: 'https://github.company.com/api/v3' RENOVATE_GIT_AUTHOR: 'Renovate Bot ' RENOVATE_PLATFORM: 'github' RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token' --- apiVersion: v1 data: config: aG9zdCBnaXRsYWIuY29tCiAgSG9zdE5hbWUgZ2l0bGFiLmNvbQogIFN0cmljdEhvc3RLZXlDaGVja2luZyBubwogIElkZW50aXR5RmlsZSB+Ly5zc2gvaWRfcnNhCiAgVXNlciBnaXQ= id_rsa: id_rsa.pub: kind: Secret metadata: name: ssh-key-secret namespace: --- apiVersion: batch/v1beta1 kind: CronJob metadata: name: renovate namespace: spec: schedule: '@hourly' concurrencyPolicy: Forbid jobTemplate: spec: template: spec: volumes: - name: ssh-key-volume secret: secretName: ssh-key-secret containers: - name: renovate # Update this to the latest available and then enable Renovate on the manifest image: renovate/renovate:43.246.1 volumeMounts: - name: ssh-key-volume readOnly: true mountPath: '/home/ubuntu/.ssh' args: - # Environment Variables envFrom: - secretRef: name: renovate-env restartPolicy: Never ``` ## Logging If you’re ingesting/parsing logs into another system then we recommend you set `LOG_LEVEL=debug` and `LOG_FORMAT=json` in your environment variables. Debug logging is usually needed for any debugging, while JSON format will mean that the output is parsable. ### About the log level numbers When you use `LOG_LEVEL=debug` and `LOG_FORMAT=json`, Renovate uses numbers in the `level` field. The logging level output is controlled by the Bunyan logging library. Level Meaning 10 trace 20 debug 30 info 40 warn 50 error 60 fatal ## Self-signed TLS/SSL certificates Renovate and invoked helper programs (like Git, or npm) use a secure TLS connection (e.g. HTTPS) to connect to remote source code and dependency hosts. If the remote hosts uses self-signed certificates or certificate authorities then Renovate must be told to trust them. ### Renovate Node.js app For the main Renovate Node.js application set the environment variable [`NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/self-signed-certificate.crt`](https://nodejs.org/api/cli.html#node_extra_ca_certsfile). The Renovate application now trusts the `self-signed-certificate.crt` file. This means Renovate can safely connect to systems using that certificate or certificates signed by this certificate authority. ### Helper programs like Git or npm Helper programs like Git and npm use the system trust store. For those programs to trust a self-signed certificate you must add it to the systems trust store. On Ubuntu/Debian and many Linux-based systems, this can be done by: 1. copying the self-signed certificate (e.g. `self-signed-certificate.crt`) to `/usr/local/share/ca-certificates/` 2. and running [`update-ca-certificates`](https://manpages.ubuntu.com/manpages/noble/man8/update-ca-certificates.8.html) to update the system trust store afterwards ### Renovate Docker image If you’re using the official [Renovate Docker image](#docker) then we recommend you add the self-signed certificate and build your own modified Docker image. ``` FROM renovate/renovate # Changes to the certificate authority require root permissions USER root # Copy and install the self signed certificate COPY self-signed-certificate.crt /usr/local/share/ca-certificates/ RUN update-ca-certificates # Change back to the Ubuntu user USER 12021 # OpenSSL ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt ``` ## Proxy Environment Variable Configuration If your environment uses an HTTP proxy configured via environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, and their lowercase variants), Renovate inherits these settings and prefers the lowercase variant. In some cases, you may need to adjust the `NO_PROXY` variable if Renovate encounters network or TLS errors when accessing internal or excluded domains. Renovate uses the [global-agent](https://github.com/gajus/global-agent) library to manage proxy connections. To exclude a domain and all its subdomains, you must use a wildcard — for example: ``` NO_PROXY=*.example.org ``` This configuration ensures that both `example.org` and `www.example.org` are accessed directly, bypassing the proxy for Renovate. If a tool that Renovate runs (such as git) still has proxy-related issues, note that different tools interpret NO\_PROXY formats differently. See [GitLab’s detailed explanation](https://about.gitlab.com/blog/we-need-to-talk-no-proxy/#no_proxy-format) for guidance on tool-specific behavior. To debug the proxy configuration behavior you can set the environment variable `ROARR_LOG=true` to enable log printing to stdout. ## [Frequently Asked Questions (FAQ)](https://docharvest.github.io/docs/renovate/usage/faq/) Contents renovate Frequently Asked Questions (FAQ) Renovate Frequently Asked Questions (FAQ) ## What is the default behavior? Renovate will: - Look for configuration options in a configuration file (e.g. `renovate.json`) and in each `package.json` file - Find and process all package files (e.g. `package.json`, `composer.json`, `Dockerfile`, etc) in each repository - Use separate branches/PR for each dependency - Use separate branches for each _major_ version of each dependency - Pin devDependencies to a single version, rather than use ranges - Pin dependencies to a single version if it appears not to be a library - Update `yarn.lock` or `package-lock.json` files, if found - Create Pull Requests immediately after branch creation ## Which Renovate versions are officially supported? Only the latest version of Renovate is supported by the Renovate maintainers. The Renovate team only fixes bugs in an older version if: - the Mend Renovate App needs to stay on that older major version for a short time, or - some critical bug needs to be fixed and the new major is blocked If you’re using the Mend Renovate App, you don’t need to do anything, as the Renovate maintainers update it regularly. If you’re self hosting Renovate, use the latest release if possible. ## Renovate core features not supported on all platforms Feature Platforms which lack feature See Renovate issue(s) Dependency Dashboard Azure, Bitbucket, Bitbucket Server, Gerrit, SCM-Manager [#9592](https://github.com/renovatebot/renovate/issues/9592) The Mend Renovate App Azure, Bitbucket Server, Forgejo, Gitea, GitLab, SCM-Manager ## Major platform features not supported by Renovate Some major platform features are not supported at all by Renovate. Feature name Platform See Renovate issue(s) Jira issues Bitbucket [#20568](https://github.com/renovatebot/renovate/issues/20568) Jira issues Bitbucket Server [#3796](https://github.com/renovatebot/renovate/issues/3796) Configurable merge strategy and message Only Bitbucket, Forgejo and Gitea for now [#10867](https://github.com/renovatebot/renovate/issues/10867) [#10869](https://github.com/renovatebot/renovate/issues/10869) [#10870](https://github.com/renovatebot/renovate/issues/10870) ## What is this `main` branch I see in the documentation? When you create a new repository with Git, Git creates a base branch for you. The default branch name that Git uses is `master` (this will be changed to `main` later). The Git-hosting ecosystem decided to use `main` instead of `master`. When you create a new repository on say GitHub or GitLab, you’ll get a `main` branch as your base branch. We replaced `master` with `main` in our documentation where possible. A branch name has no special meaning within the Git program, it’s only a name. The base branch could be called `trunk` or `mainline` or `prod`, and Git would work just as well. ## What if I need to .. ? ### Troubleshoot Renovate If you have problems with Renovate, or want to know where Renovate keeps the logging output then read our [troubleshooting documentation](./troubleshooting.md). ### Tell Renovate to ask for approval before creating a Pull Request By default, Renovate creates a pull request right away whenever there’s an update. But maybe you want Renovate to ask for your approval _before_ it creates a pull request. Use the “Dependency Dashboard approval” workflow to get updates for certain packages - or certain types of updates - only after you give approval via the Dependency Dashboard. The basic idea is that you create a new `packageRules` entry and describe what kind of package, or type of updates you want to approve beforehand. ``` { "packageRules": [ { "matchUpdateTypes": ["major"], "matchManagers": ["npm"], "dependencyDashboardApproval": true } ] } ``` ``` { "packageRules": [ { "matchPackageNames": ["jest"], "matchUpdateTypes": ["major"], "dependencyDashboardApproval": true } ] } ``` You may even configure Renovate bot to ask for approval for _all_ updates. The `dependencyDashboardApproval` config option is outside of a `packageRules` array, and so applies to all updates: ``` { "dependencyDashboardApproval": true } ``` Read our documentation on the [dependencyDashboardApproval](./configuration-options.md#dependencydashboardapproval) config option. ### Use an alternative branch as my Pull Request target Say your repository’s default branch is `main` but you want Renovate to use the `next` branch as its PR target. You can configure the PR target branch via the `baseBranchPatterns` option. Add this line to the `renovate.json` file that’s in the _default_ branch (`main` in this example). ``` { "baseBranchPatterns": ["next"] } ``` You can set more than one PR target branch in the `baseBranchPatterns` array. ### Support private npm modules See the dedicated [Private npm module support](./getting-started/private-packages.md) page. ### Control Renovate’s schedule To learn about controlling Renovate schedule, read the [key concepts, scheduling](./key-concepts/scheduling.md) docs. ### Disable Renovate for certain dependency types Define a `packageRules` entry which has the dependency type(s) in `matchDepTypes` and `"enabled": false`. ### Use a single branch/PR for all dependency upgrades Add a configuration for configuration option `groupName` set to value `"all"`, at the top level of your `renovate.json` or `package.json`. ### Use separate branches per dependency, but not one per major release Set configuration option `separateMajorMinor` to `false`. ### Keep using SemVer ranges, instead of pinning dependencies Set configuration option `rangeStrategy` to `"replace"`. ### Keep lock files (including sub-dependencies) up-to-date, even when `package.json` hasn’t changed By default, if you enable lock-file maintenance, Renovate will update the lockfile `["before 4am on monday"]`. If you want to update the lock file more often, set the `schedule` field inside the `lockFileMaintenance` object. ### Wait until tests have passed before creating the PR Set the configuration option `prCreation` to `"status-success"`. Branches with failing tests will remain in Git and get updated if needed. Renovate will only create a PR once the tests pass. ### Wait until tests have passed before creating a PR, but create the PR even if they fail Set the configuration option `prCreation` to `"not-pending"`. ### Assign PRs to specific user(s) Set the configuration option `assignees` to an array of usernames. ### Add labels to PRs Set the configuration option `labels` to an array of labels to use. ### Apply a rule, but only to package `abc`? 1. Add a `packageRules` array to your configuration 2. Create one object inside this array 3. Set field `matchPackageNames` to value `["abc"]` 4. Add the configuration option to the same object e.g. ``` { "packageRules": [ { "matchPackageNames": ["abc"], "assignees": ["importantreviewer"] } ] } ``` ### Apply a rule, but only for packages starting with `abc` Do the same as above, but instead of an exact match, use a glob prefix: ``` { "packageRules": [ { "matchPackageNames": "abc**", "assignees": ["importantreviewer"] } ] } ``` For more examples, see [String Pattern Matching, example glob patterns](./string-pattern-matching.md#example-glob-patterns). ### Group all packages starting with `abc` together in one PR As above, but apply a `groupName`: ``` { "packageRules": [ { "matchPackageNames": "abc**", "groupName": "abc packages" } ] } ``` ### Change the default values for branch name, commit message, PR title or PR description You can use the `branchName`, `commitMessage`, `prTitle` or `prBody` configuration options to change the defaults for those settings. ### Automatically merge passing Pull Requests Set the configuration option `automerge` to `true`. Nest it inside a `patch` or `minor` object if you only want to automerge certain types of updates. ### Separate patch releases from minor releases #### Renovate’s default behavior for major/minor releases By default, Renovate separates major and minor releases. Patch releases are treated as “minor”. Here’s an example: Say you’re using version `0.8.0` of the `foo` package. The `foo` maintainers release the following versions: - `0.8.1` (patch) - `0.9.0` (minor) - `1.0.0` (major) Renovate creates the following PRs: - Update dependency `foo` to `0.9.0` (minor) - Update dependency `foo` to `1.0.0` (major) Renovate groups the patch and minor versions into one PR. This means you only get a PR for the minor version, `0.9.0`. You can override this default behavior. To learn more read the section below. #### Overriding the default behavior for major/minor releases You can see in the example above that Renovate won’t normally create a PR for the `foo` patch release. You can tell Renovate to create a separate PR for the patch release by setting `separateMinorPatch` to `true`. In both cases, Renovate will open 3 PRs: - Update dependency `foo` to `0.8.1` (patch) - Update dependency `foo` to `0.9.0` (minor) - Update dependency `foo` to `1.0.0` (major) Usually you don’t want more PRs though. It can be nice to get patch PRs when you’re using automerge: - Get daily patch updates which are automerged once tests pass - Get weekly updates for minor and major updates This means you barely notice Renovate during the week, while you still get the benefits of patch level updates. ## What’s the difference between `depName` and `packageName`? Renovate uses two important config options to define a dependency’s name: `depName` and `packageName`. The `depName` is the short “pretty name” of the dependency. This is the user-facing name for the dependency. By default, Renovate uses the `depName`: - in the title of Pull Requests/Merge Requests - in commit messages - on the Dependency Dashboard The `packageName` is the full _exact_ name. Renovate uses the `packageName` to find the dependency in the package registry. Often `depName` and `packageName` are the same, but not always. Renovate uses the “pretty” `depName` in branch names and PR titles/content, because the `depName` is easier to read than the `packageName`. For instance, given the following Gradle plugin: ``` plugins { id("com.gradle.develocity").version("3.18.1") } ``` Renovate will give the dependency these properties: - `depName`: `com.gradle.develocity` - `packageName`: `com.gradle.develocity:com.gradle.develocity.gradle.plugin` Again, often the `depName` and `packageName` are equal. The names Renovate uses for the `depName` and `packageName` depend on the package manager (and package ecosystem naming conventions). For instance, `depName` and `packageName` may be different when you proxy Docker images. ## [Installing and onboarding Renovate into repositories](https://docharvest.github.io/docs/renovate/usage/getting-started/installing-onboarding/) Contents renovate Installing Onboarding Renovate Installing Onboarding ## About the security and privacy of installing Renovate Read the [Security and Permissions](../security-and-permissions.md) page to learn more about: - Renovate’s security stance - What to do if you need to use certified software - The security/disclosure process - Permissions - Privacy ## Repository installation Renovate administrators can configure Renovate to either “autodiscover” installed repositories, or configure a fixed list of repository names to operate on. If the administrator has configured a fixed list of repositories then the only way to “install” Renovate on a extra repository is for it to be manually added for the next run or restart. Otherwise, the process for adding new repositories to a Renovate installation can vary: - Most commonly, you run Renovate as a dedicated “bot user” with global config option `autodiscover` set to `true`, meaning that it will run on every repository which it’s been granted access to - If using a GitHub App (including the Mend Renovate App) then you can install the app into a user or organization account and select either “All repositories”, or “Select repositories” and pick them manually ### Hosted GitHub.com App Follow these steps to install and enable the Mend Renovate App: First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the Install button: { loading=lazy } The only choice you need to make is whether to run Renovate on all repositories or on selected repositories: { loading=lazy } Renovate will ignore any repositories that don’t have known package files, as well as any forks, so you can enable Renovate for all your repositories with no problems. That said, most people run Renovate on selected repositories. Unfortunately GitHub doesn’t offer a “select all except X, Y, Z” option, so you must select each repository where you want Renovate to run. Once you’re done selecting repositories for Renovate to run on, select the green Install button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. !!! note If you are using the Mend Renovate App then it has a custom behavior for forked repositories. If you choose “All repositories” when installing then forked repositories will be skipped by default, while if you choose “Select repositories” then they will be processed by Renovate even if they’re a fork. ### Hosted GitLab.com App Unfortunately Mend’s hosted GitLab app needed to be taken offline indefinitely until a viable security model for bots on GitLab.com is available. For more details on GitLab security for bots, please see the [GitLab Bot Security](../gitlab-bot-security.md) doc. ### Self-hosting on Windows We recommend you set [`core.autocrlf = input`](https://git-scm.com/docs/gitattributes#_text) in your Git config. You can do this by running this Git command: ``` git config --global core.autocrlf input ``` This prevents the carriage return `\r\n` which may confuse Renovate bot. You can also set the line endings in your repository by adding `* text=auto eol=lf` to your `.gitattributes` file. ## Repository onboarding Once you have enabled Renovate on a repository, you will get a “Configure Renovate” Pull Request looking something like this: { loading=lazy } !!! note If you self-host Renovate, and want to add the rebase/retry checkbox to Renovate’s onboarding PRs: enable the [`onboardingRebaseCheckbox` config option](../self-hosted-configuration.md#onboardingrebasecheckbox) first. ### No risk onboarding Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you _merge_ the onboarding Pull Request. If there is anything about the Pull Request that you don’t like or understand, take your time to read the [documentation](../index.md) or ask questions on the [discussions forum on GitHub](https://github.com/renovatebot/renovate/discussions) and merge the PR only once you’re satisfied with the result. You can edit your Renovate configuration **within the `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can work on the config until you’re satisfied with the results. If you wish to opt-out of having Renovate run for your repo, simply close the onboarding Pull Request without merging it. This action is reversible - you can re-request an onboarding PR by renaming the (closed) onboarding PR, or you can commit a Renovate configuration file to your default branch to manually onboard. ### Check for warnings If you have any Warnings or Errors listed, see if you need or want to make any changes to fix them. Warnings and errors should be fixed on the base branch (e.g. `main`) so that Renovate can recreate its Configure Renovate PR on its next cycle. ### Configuration location The “Configure Renovate” PR will include a `renovate.json` file in the root directory, with suggested default settings. If you don’t want a `renovate.json` file in your repository you can use one of the following files instead: - `renovate.json5` - `.github/renovate.json` - `.github/renovate.json5` - `.gitlab/renovate.json` - `.gitlab/renovate.json5` - `.renovaterc` - `.renovaterc.json` - `.renovaterc.json5` - `package.json` (deprecated) Or in a custom file present within the [`configFileNames`](../self-hosted-configuration.md#configfilenames). The bot first checks all the files in the `configFileNames` array before checking from the above file list. #### package.json !!! warning This approach has been deprecated and will be removed in a future release. You can add the same settings to a `"renovate"` section in your `package.json` file instead. The `package.json` file must be located at the root of your repository. This is handy if you are already using a `package.json` file anyway, e.g. when you’re working on a JavaScript project. The configuration in your `package.json` will apply to the whole project (this includes other, nested `package.json` files). ### Customized defaults Renovate provides a `renovate.json` file, with default settings that will work for most cases. Sometimes Renovate detects that an override to these defaults is needed, and will add this override automatically, such as: - Automatically enabling Angular-style semantic commits if your repository uses them - Determining whether to use dependency range pinning depending on the detected project type (app vs library) ### Common overrides Please check the docs on this website for an exhaustive Configuration Reference. To help you get started, here are some of the most commonly changed (overridden) configuration settings: - **rangeStrategy**: By default (with zero config) it’s `"replace"` but the `"config:recommended"` preset overrides it to `"auto"`. Some prefer `"bump"`. - **labels**: Labels to assign to Pull Requests - **assignees**: GitHub user(s) to assign the Pull Requests to Renovate will update your PR description each time it finds changes. ### Merge Once you’re done checking and configuring in your Configure Renovate PR, it’s time to merge it to enable the real Pull Requests to begin. ## Repository re-configuration There will be times when you need to change your Renovate config. There are two recommended approaches: - Reconfigure via PR - Nuke the config and re-onboard ### Reconfigure via PR If you want to make config edits directly, follow these steps: 1. Create a new branch named `renovate/reconfigure` 2. Edit your Renovate configuration file 3. Create a pull request from the `renovate/reconfigure` branch 4. Run renovate on your repository(if self-hosted), or wait for the hosted app to process the changes 5. Renovate will comment on your PR, outlining the expected changes from your modified configuration 6. You can continue to edit the configuration file in the same PR, and the bot will update its comment accordingly 7. If you only want to validate your configuration changes, check out: [Validate your config](../config-validation.md) ### Nuke config and re-onboard Perhaps you really liked the interactive onboarding PR and want to use it again. You can follow the steps below to nuke the config and get a new PR. Any existing Renovate PRs will be closed after you’ve completed these steps. 1. Find your original `Configure Renovate` PR 2. Rename the original PR to something else, e.g. `Configure Renovate - old` 3. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch Following these steps will trick Renovate into thinking that your repository was _never_ onboarded, and will trigger a new “Configure Renovate” PR. If you’re using the Mend Renovate App and you don’t get a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually. ## [Private package support](https://docharvest.github.io/docs/renovate/usage/getting-started/private-packages/) Contents renovate Private Packages Renovate Private Packages It’s a very common requirement to be able to support private module/dependency lookups. This page describes Renovate’s approach to authentication. First, a quick note on terminology: - The terms `module`, `package` and `dependency` can mostly be used interchangeably below - The terms `credentials`, `secrets` and `authentication` are also used interchangeably ## When does Renovate need credentials? By default, the only credentials Renovate has are those for the “platform”, i.e. GitHub, GitLab, etc. If the token used has sufficient permissions, this will enable Renovate to lookup dependencies located in alternative repositories on the same host or any hosted on any embedded package registry on the same host. It’s also quite common to need to look up packages on other protected hosts, including npmjs, Docker Hub, or private registries like Nexus or Artifactory. Any time you need Renovate to access such registries with credentials then you will need to provision them as part of your config. There are four times in Renovate’s behavior when it may need credentials: - Resolving private config presets - Looking up dependency versions - Looking up changelogs - Passing to package managers when updating lock files or checksums !!! note If you self-host Renovate, and have a self-hosted registry which _doesn’t_ require authentication to access, then such modules/packages are not considered “private” to Renovate. ## Private Config Presets Renovate supports config presets, including those which are private. Although npm presets were the first type supported, they are now deprecated and it is recommend that all users migrate to git-hosted “local” presets instead. However if you do still use them, private modules should work if you configure `hostRules` (recommended) or `npmrc` including token credentials in your bot global config. It is strongly recommended not to use private modules on a private registry and a warning will be logged if that is found. Credentials stored on disk (e.g. in `~/.npmrc`) are no longer supported. The recommended way of using local presets is to configure them using “local” presets, e.g. `"extends": ["local>myorg/renovate-config"]`, and ensure that the platform token has access to that repo. It’s not recommended that you use a private repository to host your config while then extending it from a public repository. If your preset doesn’t have secrets then you should make it public, while if it does have secrets then it’s better to split your preset between a public one which all repos extend, and a private one with secrets which only other private repos extend. In summary, the recommended approach to private presets is: - Host the presets on the same server/platform as other repositories - Make sure you install Renovate into the preset repository so that it has credentials to access it from other private repos - Use `local>....` syntax to refer to private presets ## Dependency Version Lookups Whenever Renovate detects that a project uses a particular dependency, it tries to look up that dependency to see if any new versions exist. If such a package is private, then Renovate must be configured with the relevant credentials. Renovate does not use any package managers for this step and performs all HTTP(S) lookups itself, including insertion of authentication headers. Configuring Renovate with credentials requires `hostRules`. Each host rule consists of a `hostType` value and/or a way to match against hosts using `matchHost`. `hostType` is not particularly important at this step unless you have different credentials for the same host, but it is sometimes useful in later steps so is good to include if you can. It can be either a “platform” name (e.g. `github`, `azure`, etc) or a “datasource” name (e.g. `npm`, `maven`, `github-tags`, etc). If you want to apply credentials only for a nested path within a host then write `matchHost` as a base URL like `https://registry.company.com/nested/path/`. If the same credentials apply to all paths on a host and not on any subdomains of it then configure `matchHost` with a protocol like `https://registry.company.com`. Finally, to apply credentials to all hosts within the domain, use a `matchHost` value with no `https://` prefix, e.g. `company.com` or `registry.company.com`, both of which would apply to a host like `beta.registry.company.com`. In addition to the above options to match against a host, you need to add the credentials. Typically they are either `token`, or `username` + `password`. Other credential terms are not supported yet. ``` { "hostRules": [ { "matchHost": "registry.npmjs.org", "token": "abc123" }, { "matchHost": "https://registry.company.com/pypi-simple/", "username": "engineering", "password": "abc123" } ] } ``` Renovate applies these `hostRules` to every HTTP(s) request which is sent, so they are largely independent of any platform or datasource logic. With `hostRules` in place, private package lookups should all work. ### GitHub (and Enterprise) repo scoped credentials If you need to use different credentials for a specific GitHub repo, then you can configure `hostRules` like one of the following: ``` { "hostRules": [ { "matchHost": "https://api.github.com/repos/org/repo", "token": "abc123" }, { "matchHost": "https://github.domain.com/api/v3/repos/org/repo", "token": "abc123" } ] } ``` Renovate will use those credentials for all requests to `org/repo`. #### Example for gomod Here’s an example for `gomod` with private `github.com` repos. Assume this config is used on the `github.com/some-other-org` repo: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "dependencyDashboard": true, "hostRules": [ { "matchHost": "https://gitlab.com", "token": "glpat-token_for_different_git_platform", "hostType": "gitlab" }, { "matchHost": "https://github.com/some-org", "token": "ghp_token_for_different_org", "hostType": "go" }, { "matchHost": "https://api.github.com/repos/some-org", "token": "ghp_token_for_different_org", "hostType": "github" } ], "customEnvVariables": { "GOPRIVATE": "github.com/some-org,github.com/some-other-org,gitlab.com/some-org", "GONOSUMDB": "github.com/some-org,github.com/some-other-org,gitlab.com/some-org", "GONOPROXY": "github.com/some-org,github.com/some-other-org,gitlab.com/some-org" }, "postUpdateOptions": ["gomodTidy"] } ``` ## Looking up changelogs When Renovate creates Pull Requests, its default behavior is to locate and embed release notes/changelogs of packages. These release notes are fetched from the source repository of packages and not from the registries themselves, so if they are private then they will require different credentials. When it comes to open source, most packages host their source on `github.com` in public repositories. GitHub greatly rate limits unauthenticated API requests, so you need to configure credentials for `github.com` or the bot will get rate limited quickly. It can be confusing for people who host their own source code privately to be asked to configure a `github.com` token but without it changelogs for most open source packages will be blocked. Currently the preferred way to configure `github.com` credentials for self-hosted Renovate is: - Create a read-only Personal Access Token (PAT) for a `github.com` account. This can be any GitHub account, but we recommend you create an “empty” account for this purpose. - Add the PAT to Renovate using the environment variable `RENOVATE_GITHUB_COM_TOKEN` !!! note `GITHUB_COM_TOKEN` is still parsed and takes precedence over `RENOVATE_GITHUB_COM_TOKEN`, but is considered deprecated and will be removed in a future major update. ## Package Manager Credentials for Artifact Updating In Renovate terminology, “artifacts” includes lock files, checksum files, and vendored dependencies. One way of understanding artifacts is: “everything else that needs to be updated when the dependency version changes”. Not all package managers supported by Renovate require artifact updating, because not all use lock or checksum files. But when such files need updating, Renovate does so by using the package managers themselves instead of trying to “reverse engineer” each package manager’s file formats and behavior. Importantly, such package managers are run via shell commands and do not understand Renovate’s `hostRules` objects, so Renovate needs to reformat the credentials into formats (such as environment variables or configuration files) which the package manager understands. Because of this need to convert `hostRules` credentials into a format which package managers understand, sometimes artifact updating can fail due to missing credentials. Sometimes this can be resolved by changing Renovate configuration, but other times it may be due to a feature gap. The following details the most common/popular manager artifacts updating and how credentials are passed: ### bundler `hostRules` with `hostType=rubygems` are converted into environment variables which Bundler supports. ### composer Any `hostRules` token for `github.com` or `gitlab.com` are found and written out to `COMPOSER_AUTH` in env for Composer to parse. Any `hostRules` with `hostType=packagist` are also included. For dependencies on `github.com` without a Packagist server: use a Personal Access Token for `hostRule` with `hostType=git-tags`, do not use an application token. Avoid adding a `hostRule` with `hostType=github` because: - it overrides the default Renovate application token for everything else - it causes unwanted side effects The repository in `composer.json` should have the `vcs` type with a `https` URL. For example: ``` { "repositories": [ { "type": "vcs", "url": "https://github.com/organization/private-repository" } ] } ``` ### gomod If a `github.com` token is found in `hostRules`, then it is written out to local [GIT\_CONFIG\_](https://git-scm.com/docs/git-config#Documentation/git-config.txt-GITCONFIGCOUNT) variables prior to running `go` commands. The environment variables used are: `GIT_CONFIG_KEY_0=url.https://${token}@github.com/.insteadOf GIT_CONFIG_VALUE_0=https://github.com/ GIT_CONFIG_COUNT=1`. ### helm Maybe you’re running your own ChartMuseum server to host your private Helm Charts. This is how you connect to a private Helm repository: ``` module.exports = { hostRules: [ { matchHost: 'your.host.io', hostType: 'helm', username: '', password: process.env.SELF_HOSTED_HELM_CHARTS_PASSWORD, }, ], }; ``` If you need to configure per-repository credentials then you can also configure the above within a repository’s Renovate config (e.g. `renovate.json`). ### npm The recommended approaches in order of preference are: 1. **Self-hosted hostRules**: Configure a hostRules entry in the bot’s `config.js` with the `hostType`, `matchHost` and `token` specified 2. **The Mend Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config 3. **The Mend Renovate App with a private registry**: Add an plaintext `npmrc` plus an encrypted `npmToken` in config These approaches are described in full below. #### Add hostRule to bots config Define `hostRules` like this: ``` module.exports = { hostRules: [ { hostType: 'npm', matchHost: 'registry.npmjs.org', token: process.env.NPMJS_TOKEN, }, { hostType: 'npm', matchHost: 'https://pkgs.dev.azure.com/{organization}/{project}/_packaging/{feed}/npm/registry/', username: 'VssSessionToken', password: process.env.AZURE_NPM_TOKEN, }, { // https://www.jfrog.com/confluence/display/JFROG/npm+Registry // Will be passed as `//artifactory.my-company.com/artifactory/api/npm/npm:_auth=` to `.npmrc` hostType: 'npm', matchHost: 'https://artifactory.my-company.com/artifactory/api/npm/npm/', token: process.env.ARTIFACTORY_NPM_TOKEN, authType: 'Basic', }, ], }; ``` !!! tip Remember to put a trailing slash at the end of your `matchHost` URL. #### Add npmrc string to Renovate config You can add an `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: ``` { "npmrc": "//some.registry.com/:_authToken=abcdefghi-1234-jklmno-aac6-12345567889" } ``` If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. If you wish for the values in your `config.npmrc` to be _merged_ (prepended) with any values found in repos then also set `config.npmrcMerge=true`. This merge approach is similar to how `npm` itself behaves if `.npmrc` is found in both the user home directory as well as a project. #### Add npmToken to Renovate config If you are using the main npmjs registry then you can configure only the `npmToken` instead: ``` { "npmToken": "abcdefghi-1234-jklmno-aac6-12345567889" } ``` #### Add an encrypted npm token to Renovate config If you don’t want all users of the repository to see the plaintext token, you can encrypt it with Renovate’s public key instead, so that only Renovate can decrypt it. Go to [https://app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt), paste in your npm token, select “Encrypt”, then copy the encrypted result. Paste the encrypted result inside an `encrypted` object like this: ``` { "encrypted": { "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" } } ``` If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. ``` { "encrypted": { "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" }, "npmrc": "registry=https://my.custom.registry/npm\n//my.custom.registry/npm:_authToken=${NPM_TOKEN}" } ``` Renovate will then use the following logic: 1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry 2. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token 3. If an `npmrc` string is present but doesn’t have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it #### Encrypted entire .npmrc file into config Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at [https://app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt). You will then get an encrypted string that you can substitute into your `renovate.json` instead. The end-result looks like this: ``` { "encrypted": { "npmrc": "WOTWu+jliBtXYz3CU2eI7dDyMIvSJKS2N5PEHZmLB3XKT3vLaaYTGCU6m92Q9FgdaM/q2wLYun2JrTP4GPaW8eGZ3iiG1cm7lgOR5xPnkCzz0DUmSf6Cc/6geeVeSFdJ0zqlEAhdNMyJ4pUW6iQxC3WJKgM/ADvFtme077Acvc0fhCXv0XvbNSbtUwHF/gD6OJ0r2qlIzUMGJk/eI254xo5SwWVctc1iZS9LW+L0/CKjqhWh4SbyglP3lKE5shg3q7mzWDZepa/nJmAnNmXdoVO2aPPeQCG3BKqCtCfvLUUU/0LvnJ2SbQ1obyzL7vhh2OF/VsATS5cxbHvoX/hxWQ==" } } ``` #### Automatically authenticate for npm package stored in private GitHub npm repository ``` { "hostRules": [ { "matchHost": "https://npm.pkg.github.com/", "hostType": "npm", "encrypted": { "token": "" } } ], "npmrc": "@organizationName:registry=https://npm.pkg.github.com/" } ``` #### Yarn 2+ Renovate doesn’t support reading `npmRegistries` and `npmScopes` from `.yarnrc.yml`, so `hostRules` (or `npmToken`) and `npmrc` should be configured like above. Renovate updates `npmRegistries` in `.yarnrc.yml` with resolved `hostRules` before running Yarn. For Renovate to overwrite existing `npmRegistries` entry, the key should match the `matchHost` minus the protocol (`http:` or `https:`) plus the trailing slash. For example, the Renovate configuration: ``` { "hostRules": [ { "matchHost": "https://npm.pkg.github.com/", "hostType": "npm", "encrypted": { "token": "" } } ] } ``` will update `.yarnrc.yml` as following: If no registry currently set ``` npmRegistries: //npm.pkg.github.com/: npmAuthToken: ``` If current registry key has protocol set: ``` npmRegistries: https://npm.pkg.github.com: npmAuthToken: ``` ### maven GitLab package registry can be authorized using `Authorization: Bearer `. In GitLab Pipelines authorization can be achieved using following config: ``` hostRules: [ { hostType: 'maven', matchHost: 'https://gitlab.host.com/api/v4', token: process.env.CI_JOB_TOKEN, }, ]; ``` ### nuget For each known NuGet registry, Renovate searches for `hostRules` with `hostType=nuget` and matching host. For those found, a command like the following is run: `dotnet nuget add source ${registryInfo.feedUrl} --configfile ${nugetConfigFile} --username ${username} --password ${password} --store-password-in-clear-text`. ``` hostRules: [ { matchHost: 'https://pkgs.dev.azure.com//', hostType: 'nuget', username: 'user', // doesn't matter for azure password: '', }, ]; ``` ### pip If a `requirements.txt` file has an index-url then Renovate follows that link, instead of following any link set in the `registryUrls` array. To override the URL found in `requirements.txt`, you must create a custom `packageRules` setting. This is because `packageRules` are applied _after_ package file extraction. For example: ``` { "packageRules": [ { "matchManagers": ["pip_requirements"], "registryUrls": ["https://docker.mycompany.domain"] } ] } ``` ### pipenv If a `Pipfile` contains a `source` with `USERNAME` or `PASSWORD` environment variables and there is a `hostRules` entry with a matching host plus `username` and `password` fields, then these variables would be passed to `pipenv lock`. For example: ``` [[source]] url = "https://$USERNAME:${PASSWORD}@mypypi.example.com/simple" verify_ssl = true name = "pypi" ``` ### pip-compile The pip-compile manager can extract these directives from the input file given to Renovate: - `--index-url` - `--extra-index-url` Renovate matches those URLs with credentials from matching `hostRules` blocks in the Renovate configuration. Then Renovate passes the information to `pip-compile` via environment variables. !!! warning “Put directives in the .in file, avoid the lockfile” You must put the `--[extra-]index-url` directive(s) in the `.in` file, for `pip-compile` to use during Renovate jobs. Do _not_ put the directive(s) in the lockfile, as this is _not_ supported. ``` --extra-index-url https://pypi.my.domain/simple private-package==1.2.3 ``` ``` { "pip-compile": { "managerFilePatterns": ["requirements.txt"] }, "hostRules": [ { "matchHost": "pypi.my.domain", "username": "myuser", "password": "mypassword" } ] } ``` #### Packages that Renovate needs Renovate relies on `pip`’s integration with the Python [keyring](https://pypi.org/project/keyring/) package along with the [keyrings.envvars](https://pypi.org/project/keyrings.envvars/) backend for this. ##### Self-hosting Renovate This section only applies to users who self-host Renovate. If you self-host and use Containerbase, or our Docker sidecar container, then Renovate can already access the packages it needs. But if you are self-hosting Renovate and: - _not_ running Renovate in a Containerbase environment - or, _not_ using the Docker sidecar container Then you must install the Python keyring package and the keyrings.envvars package into your self-hosted environment. ### poetry For every Poetry source, a `hostRules` search is done and then any found credentials are added to env like `POETRY_HTTP_BASIC_X_USERNAME` and `POETRY_HTTP_BASIC_X_PASSWORD`, where `X` represents the normalized name of the source in `pyproject.toml`. ``` module.exports = { hostRules: [ { matchHost: 'pypi.example.com', hostType: 'pypi', username: process.env.PYPI_USERNAME, password: process.env.PYPI_PASSWORD, }, ], }; ``` If you’re self-hosting Renovate via the [GitLab Runner](../getting-started/running.md#gitlab-runner) and want to access packages from private GitLab registries, you can use the GitLab CI job token for authentication: ``` module.exports = { hostRules: [ { matchHost: 'gitlab.example.com', hostType: 'pypi', username: 'gitlab-ci-token', password: process.env.CI_JOB_TOKEN, }, ], }; ``` ## Automatic hostRules credentials for platform-hosted registries ### GitHub Packages For GitHub Packages, Renovate will automatically provision hostRules for both `ghcr.io` (containers) and `*.pkg.github.com` (maven, npm, nuget, rubygems) using the GitHub platform token. This means that any private packages hosted on GitHub will be automatically authenticated if they are accessible using the same token by Renovate. If you wish to _override_ this authentication by providing a different token, then your rule must be _at least as specific_ as the automatic rule that Renovate generates. For example: ``` { "hostRules": [ { "matchHost": "npm.pkg.github.com", "hostType": "npm", "token": "some-personal-access-token" } ] } ``` ## Encryption and the Mend Renovate App Many users use [the Mend Renovate App](https://github.com/apps/renovate), which is hosted by Mend. If you are a user of this app, and have private modules, then the following is applicable. ### Private presets with public repositories If you have a preset in a private repo but reference (“extend”) it from a public repository then it won’t work. This is because public repositories are provided with a token scoped to only that particular repository, and not for all repositories within the organization. This is a security measure so that if a the token is accidentally leaked publicly, the damage is limited to the public repository it leaked to and not to every repository within the organization. The solution to this is that you should break your presets into public and private ones, and reference only the public ones from public repositories. ### Encrypting secrets It is strongly recommended that you avoid committing secrets to repositories, including private ones, and this includes secrets needed by Renovate to access private modules. The preferred approach to secrets is that the bot administrator configures them as `hostRules` which are then applied to all repositories which the bot accesses. !!! warning “Store secrets for your Mend-hosted app via the web UI” Mend no longer supports putting encrypted secrets in the Renovate config file on your repository. Going forward, all secrets must be stored in the App settings via the web UI. If you have encrypted secrets in your Renovate config, you must migrate them to the web UI. Read [Migrating Secrets from Repo Config to App Settings](../mend-hosted/migrating-secrets.md) to learn how. If you need to provide credentials to the Mend Renovate App, please do this: 1. Add each secret string in the Credentials section of Organisation or Repository settings in the web UI at [http://developer.mend.io](http://developer.mend.io). 2. Reference secrets inside your Renovate config files with notation: `{{ secrets.YOUR_SECRET }}`. ``` { "hostRules": [ { "matchHost": "github.com", "token": "{{ secrets.RENOVATE_GITHUB_COM_TOKEN }}" } ] } ``` For more details, see [Using Secrets with Mend Cloud Apps](../mend-hosted/credentials.md). ### Access to GitHub Actions Secrets The Mend Renovate App does not run using GitHub Actions, but such secrets would be a bad fit for the app anyway for the following reasons: - The app would be granted access to _all_ the repository/org secrets, not just the ones you want - If Renovate wants access to such secrets, it would need to ask for them from every user, not just the ones who want to use this approach (GitHub does not support the concept of optional permissions for Apps, so people do not have the option to decline) ## Admin/Bot config vs User/Repository config for Self-hosted users “Admin/Bot config” refers to the config which the Renovate Bot administrator provides at bot startup, e.g. using environment variables, CLI parameters, or the `config.js` configuration file. User/Repository config refers to the in-repository config file which defaults to `renovate.json` but has a large number of alternative filenames supported. If there is a need to supply custom rules for certain repository, it can still be done using the `config.js` file and the `repositories` array. If per-repository config must be done within the repository, it is still recommended against committing secrets directly (including e.g. `.npmrc` files with tokens) and instead encrypting them with a custom public key first. For instructions on this, see the above section on encrypting secrets for the Mend Renovate App but instead: - Save a copy of the [https://app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt) HTML file locally, or host it locally - Generate a public/private key pair for the app using the instructions in [privateKey](../self-hosted-configuration.md#privatekey) - Replace the existing public key in the HTML with the public key you generated in the step prior - Use the resulting HTML encrypt page to encrypt secrets for your app before adding them to user/repository config - Configure the app to run with `privateKey` set to the private key you generated above !!! note Encrypted values can’t be used in the “Admin/Bot config”. ### hostRules configuration using environment variables Self-hosted users can enable the option [`detectHostRulesFromEnv`](../self-hosted-configuration.md#detecthostrulesfromenv) to configure the most common types of `hostRules` via environment variables. ## [Running Renovate](https://docharvest.github.io/docs/renovate/usage/getting-started/running/) Contents renovate Running Renovate Running As end user, you can choose from these ways to run Renovate: - You use the Mend Renovate App - You self-administer/host your own Renovate instance - Someone else is hosting Renovate, and you install/configure it for the repositories you choose If you’re using the Mend Renovate App, or if someone else is hosting Renovate for you, skip ahead to the [installing & onboarding](./installing-onboarding.md) page. ## Self-Hosting Renovate When self-hosting Renovate you’re the “administrator” of the bot, this means you: - provide the infrastructure that Renovate runs on, - provision Renovate’s global config, - make sure Renovate bot runs regularly, - make sure Renovate bot itself is updated If you’re self-hosting Renovate on Windows, read [Self-hosting on Windows](./installing-onboarding.md#self-hosting-on-windows) to prevent line endings from confusing Renovate bot. If you’re running Renovate Community Edition or Renovate Enterprise Edition, refer to the documentation on the [`mend/renovate-ce-ee` GitHub repository](https://github.com/mend/renovate-ce-ee). ### Available distributions #### npm package (CLI) Renovate’s Open Source CLI is built and distributed as the npm package `renovate`. You can run this package in any Node.js environment - even via `npx` - and it will process all the repositories it is configured with, before exiting. When installing Renovate via npm you are responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc. The `renovate` npm package is compatible with all of Renovate’s supported platforms. #### Docker images Renovate is also distributed as Docker images on Docker Hub (`renovate/renovate`) and GitHub container registry (`ghcr.io/renovatebot/renovate`). These Docker images work on all the hosting platforms that Renovate supports. Both `linux/amd64` and `linux/arm64` architectures are supported, but you may still find some bugs in the `arm64` image. You can’t run the Docker images in a Windows or macOS container. In general, you can run Renovate natively on Windows as long as you have all tools it will need (e.g. `npm`, `pipenv`, etc.) preinstalled before you run Renovate. There are two Docker image flavors: - The default image, which installs required tools at runtime (default for `latest` tag), - The `-full` image, which comes with latest or very recent versions of every tool pre-installed ##### The default image (formerly `slim`) The default image only comes with the Node.js environment. Renovate will then install any needed tools when it runs. Read the `binarySource=install` documentation for more details. We recommend this default image for most users. Renovate supports a persistent cache for downloaded tools, so that it only needs to unpack the tools on later runs. Use the [`containerbaseDir` config option](../self-hosted-configuration.md#containerbasedir) to control where Renovate stores its containerbase cache. !!! warning The usage of `binarySource=docker` is deprecated, and [will be removed in the future](https://github.com/renovatebot/renovate/issues/40747). If you want, you can map the Docker socket into the container so that Renovate can dynamically invoke “sidecar” images when needed. You’ll need to set `binarySource=docker` for this to work. Read the [`binarySource` config option docs](../self-hosted-configuration.md#binarysource) for more information. ##### The full image The `-full` image comes with most package managers that Renovate supports, but not _all_ package managers. Update your Docker images regularly to keep the pre-installed tools up-to-date. The full image is for users who don’t want to download or install things at runtime. This image has some downsides, because it: - Comes pre-installed with _one_ version of each language/manager - usually the latest - Weighs several gigabytes #### GitHub Action Renovate’s npm tool is also provided as a GitHub Action on [`renovatebot/github-action`](https://github.com/renovatebot/github-action). Details on how to use it can be found in the repository. #### GitLab Runner The Renovate team provide a [“Renovate Runner”](https://gitlab.com/renovate-bot/renovate-runner/) project to make it easier to run Renovate as a CI pipeline job. This supports both `gitlab.com` and self-hosted GitLab. Details for how it works can be found in the project. #### Mend Renovate Self-Hosted (Community Edition / Enterprise Edition) Mend Renovate Self-Hosted Community Edition (sometimes “Renovate CE”/“CE”) and Enterprise Edition (sometimes “Renovate EE”/“EE”) are closed-source offerings of Renovate for self-hosted users. It is built similarly to the default “full” Renovate image described above, but with these differences: - It is a stateful app and does not exit after processing all repositories - It is installed as an App on GitHub, and behaves similarly on GitLab - for example responding to webhooks - It includes a priority job queue which prioritizes events like merged PRs over scheduled jobs - It is released every 2 weeks in a slightly slower and more stable cadence than Renovate OSS, which releases on every commit - It’s licensed using an end-user license agreement (EULA) and not the Affero General Public License (AGPL-3.0-only) Plus, the Enterprise Edition has: - Horizontal scaling to run multiple ‘worker’ containers - Dedicated support from Mend.io - Premium features, including Smart Merge Control Mend Renovate Self-Hosted CE and EE have support for GitHub.com, GitHub Enterprise Server, GitLab.com, GitLab Self-Managed, and Bitbucket Data Center. Go to the Mend.io website to learn more about [Renovate Enterprise Edition](https://www.mend.io/renovate-enterprise/). To learn how to configure Renovate CE or Renovate EE, read the documentation on the public GitHub repository [`mend/renovate-ce-ee`](https://github.com/mend/renovate-ce-ee). #### Mend Remediate [Mend Remediate](https://docs.mend.io/integrations/latest/mend-remediate-and-renovate) is part of Mend’s [Classic Repository Integrations](https://docs.mend.io/integrations/latest/mend-classic-repository-integrations) product which is for Mend commercial customers, with full enterprise support. It is integrated with Mend’s vulnerability detection capabilities and additionally supports the capability of “horizontal” scalability - the ability to configure many Renovate “worker” containers which share a common job queue in order to not conflict with each other. Mend Remediate supports GitHub Enterprise Server, GitLab self-hosted, and Bitbucket Server. #### Forking Renovate app “Forking Renovate” is the sister app to the Mend Renovate App. The difference is that Forking Renovate does not need `write` permissions to create branches within the repo, and instead submits PRs from its own fork. Because of how it works, it functions on public repositories only and additionally cannot support `automerge` capabilities. [Install Forking Renovate from GitHub App store](https://github.com/apps/forking-renovate). ##### Benefits Forking Renovate needs only `read` level access to the code of any repository it runs on. ##### Drawbacks If you use Forking Renovate, you’ll miss out on these features of the regular Renovate app: - Automerge - The `baseBranchPatterns` config option ### Hosting Renovate After deciding on a Renovate distribution, you need to decide where and how to run it. For the GitHub Action and GitLab Runner approaches, they will naturally run on their respective CI infrastructure. For the npm package approach or Docker images, you will need some form of VM or container infrastructure to run Renovate on. In all the above cases you must make sure that some form of cron-like capability exists to schedule when Renovate runs. We recommend that you run Renovate hourly, if possible. Mend Renovate On-Premises and Mend Remediate both run as long-lived containers, so they do not need any cron-like concept as it is built-in. ### Global config Renovate’s server-side/admin config is referred to as its “global” config, and can be set by using either: - a config file, or - an additional config file, or - environment variables, or - CLI parameters By default Renovate checks if a file named `config.js` is present. Any other (`*.js`, `*.ts`, `*.json`, `*.json5`, `*.yaml` or `*.yml`) file is supported, when you reference it with the `RENOVATE_CONFIG_FILE` environment variable (for example: `RENOVATE_CONFIG_FILE=config.yaml`). Renovate checks for the additional config file only if the `RENOVATE_ADDITIONAL_CONFIG_FILE` is set. Behaviour wise this config is similar to the file config, except that it has higher priority than the default config file. Some config is global-only, meaning that either it is only applicable to the bot administrator or it can only be controlled by the administrator and not repository users. Those are documented in [Self-hosted Configuration](../self-hosted-configuration.md). Your bot’s global config can include both global as well as non-global configuration options, while user/repo config can only include non-global options. We recommend that you keep as much of the non-global config as possible in repository config files. This way the Renovate end users can see as much of the bot’s configuration as possible. If you are configuring Renovate using environment variables, there are two possibilities: - Upper-cased, camel-cased, `RENOVATE_`\-prefixed single config options like `RENOVATE_TOKEN=abc123` or `RENOVATE_GIT_AUTHOR=a@b.com` - Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, for example: `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'` If you combine both of the above then any single config option in the environment variable will override what’s in `RENOVATE_CONFIG`. !!! note It’s also possible to change the default prefix from `RENOVATE_` using `ENV_PREFIX`. For example: `ENV_PREFIX=RNV_ RNV_TOKEN=abc123 renovate`. #### Using `config.js` If you use a `config.js`, it will be expected to export a configuration via `module.exports`. The value can be either a plain JavaScript object like in this example where `config.js` exports a plain object: ``` module.exports = { token: 'abcdefg', }; ``` `config.js` may also export a `Promise` of such an object, or a function that will return either a plain JavaScript object or a `Promise` of such an object. This allows one to include the results of asynchronous operations in the exported value. An example of a `config.js` that exports an `async` function (which is a function that returns a `Promise`) can be seen in a comment for [#10011: Allow autodiscover filtering for repo topic](https://github.com/renovatebot/renovate/issues/10011#issuecomment-992568583) and more examples can be seen in [`file.spec.ts`](https://github.com/renovatebot/renovate/blob/main/lib/workers/global/config/parse/file.spec.ts). #### Using TypeScript config files Renovate supports TypeScript config files (`.ts`, `.mts`, `.cts`) via Node.js’s built-in type stripping. Set the `RENOVATE_CONFIG_FILE` environment variable to point to your TypeScript config file: ``` RENOVATE_CONFIG_FILE=config.ts renovate ``` An example `config.ts`: ``` import type { AllConfig } from 'renovate/dist/config/types'; const config: AllConfig = { platform: 'github', token: process.env.RENOVATE_TOKEN, repositories: ['my-org/my-repo'], }; export default config; ``` TypeScript config files follow the same rules as JavaScript config files: they can export a plain object, a `Promise`, or a function. The `.mts` extension is always treated as an ES module, and `.cts` is always treated as CommonJS. ### Authentication Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token. We recommend you use `@renovate-bot` as username if you’re on a self-hosted server where you can set all usernames. We also recommend you configure `config.gitAuthor` with the same identity as your Renovate user, for example: `"gitAuthor": "Renovate Bot "`. !!! warning We recommend you use a single, dedicated username for your Renovate bot. Never share the Renovate username with your other bots, as this can cause flip-flopping. #### Docs Read the platform-specific docs to learn how to setup authentication on your platform: - [Azure DevOps](../modules/platform/azure/index.md) - [Bitbucket Cloud](../modules/platform/bitbucket/index.md) - [Bitbucket Server](../modules/platform/bitbucket-server/index.md) - [Forgejo](../modules/platform/forgejo/index.md) - [Gitea](../modules/platform/gitea/index.md) - [github.com and GitHub Enterprise Server](../modules/platform/github/index.md) - [GitLab](../modules/platform/gitlab/index.md) - [SCM-Manager](../modules/platform/scm-manager/index.md) ### GitHub.com token for changelogs (and tools) If you are running on any platform except github.com, you should also set the environment variable `RENOVATE_GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it. This account can be _any_ account on GitHub, and needs only `read-only` access. It’s used when fetching changelogs for repositories, as well as some Renovate-specific tools at runtime, in order to increase the hourly API limit. It’s also OK to configure the same as a host rule instead, if you prefer that. !!! note If you’re using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub), we highly recommend that you add a `github.com` PAT (classic). Otherwise you will exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies. ### Self-hosting examples For more examples on running Renovate self-hosted, read our [Self-hosted examples](../examples/self-hosting.md) page. ### Community tools There are also some [community-maintained tools](../community-tools.md) which may help running Renovate. ## [Use Cases](https://docharvest.github.io/docs/renovate/usage/getting-started/use-cases/) Contents renovate Use Cases Renovate Use Cases This page describes common use cases for Renovate. ## Development dependency updates The original use case, and the most popular one, is for developers to automate dependency updating in their software projects. ### Updating of package files We use the term “package file” to describe files which reference dependencies. Package files are managed by a “package manager”. Example package files include: - `package.json`, managed by npm or Yarn - `Gemfile`, managed by Bundler - `go.mod`, managed by `go` modules #### How Renovate updates a package file Renovate: 1. Scans your repositories to find package files and their dependencies 2. Checks if any newer versions exist 3. Raises Pull Requests for available updates The Pull Requests patch the package files directly, and include changelogs for the newer versions (if they are available). By default: - You’ll get separate Pull Requests for each dependency - Major updates are kept separate from non-major updates ### Package managers with lock files Many package managers support “lock files”, which “freeze” the entire dependency tree including transitive dependencies. npm, Yarn, Bundler, Composer, Poetry, Pipenv, and Cargo all support or use lock files. If you use a lock file then changes to your package file must come with a compatible change to the lock file. Renovate can patch/update package files directly, but can’t “reverse engineer” lock files. This is why Renovate lets the package manager do the lock file update. A simplified example: 1. The repository has a `package.json` and `package-lock.json` with version `1.0.0` of a dependency 2. Renovate sees that version `1.1.0` is available 3. Renovate patches the `package.json` to change the dependency’s version from `1.0.0` to `1.1.0` 4. Renovate runs `npm install` to let `npm` update the `package-lock.json` 5. Renovate commits the `package.json` and `package-lock.json` 6. Renovate creates the PR ### Custom dependency extraction Renovate supports 90+ types of package files. By default, Renovate finds most dependencies, but there are exceptions. This can be because: - The package manager/file format is not supported, or - The file format is not a standard or is proprietary If your dependencies are not found by default, you can use our `custom` manager to set your own custom patterns to extract dependencies. You configure the custom manager by telling it: - Which file pattern(s) to match - How to find the dependency name and version from within the file - Which datasource (e.g. Docker registry, npm registry, etc) to use to look up new versions The end result is that Renovate can keep dependencies in custom file formats up-to-date as long as the dependency datasource is known to Renovate. ## DevOps tooling Renovate is increasingly used for purposes which are traditionally described as DevOps instead of Developer. ### DevOps / Infrastructure as Code updates It’s common for repositories to have DevOps-related files like CI/CD configs, or “Infrastructure as Code” (IaC) files. Examples of IaC files are Docker, Kubernetes or Terraform files. Renovate handles IaC files as “package managers” and “package files” and can find and update them. #### Docker-compatible images Docker-compatible images are a key building block of modern software. These images are commonly found in CI/CD pipeline configs or referenced in IaC files. Renovate finds these IaC files and then searches Docker registries to see if there are newer tags or digests. #### Tag-based updating An example of tag-based updating are `node` images from Docker Hub. The `node` images use these tag formats: - `14.17.4` - `14.17.4-alpine3.11` Renovate understands both formats and raises updates like these: - From `14.17.4` to `14.17.5` - From `14.17.4-alpine3.11` to `14.17.5-alpine3.11` #### Docker digests You can check and update versions like `14.17.4` yourself. But looking up image digests like `341976f40d963a425d627a349a9b0034e1eafffbf4c82a173c1465ee403878d9` and updating them yourself doesn’t scale. So let Renovate update your Docker digests. You can even configure Renovate to “pin” your Docker digests. When you’re using tag+digest based images, you’ll have immutable builds. ### Internal package updates Your company typically has dozens of repositories, if not hundreds or thousands. These repositories often rely on other repositories and may have upstream or downstream internal dependencies. In such cases, it is best practice to: - Update downstream links as soon as possible, and - Keep internal version use as consistent as possible You can use Renovate to follow this best practice. Renovate finds and updates internal dependencies just like external or Open Source dependencies. #### Automerge internal dependencies Renovate’s automerge feature is really useful for internal dependencies where you can say “if it passes tests let’s merge it”. To learn more about “automerge” read the [key concepts, automerge](../key-concepts/automerge.md) documentation. #### Example of automerging internal dependencies We use these Renovate features to automerge an internal dependency: - [Git submodule support](../modules/manager/git-submodules/index.md) - [`automerge`](../configuration-options.md#automerge) set to `true` - [`automergeType`](../configuration-options.md#automergetype) set to `branch` ##### Background information We split our work over two repositories: 1. The [`renovatebot/renovate`](https://github.com/renovatebot/renovate) repository, which has the Renovate code, and most of the Markdown documentation files 2. The [`renovatebot/renovatebot.github.io`](https://github.com/renovatebot/renovatebot.github.io) repository, which has a submodule link to the `renovatebot/renovate` repository ##### Update process 1. We edit our documentation files on the main Renovate repository `renovatebot/renovate` 2. Renovate sees the change(s) to the `renovatebot/renovate` Git submodule, and creates an update branch on the _documentation build_ repository 3. If the tests pass Renovate automerges the update branch into the `main` branch. 4. A GitHub Actions workflow runs on `main` to build the documentation site and push the build live on our GitHub Pages domain ##### Benefits The way we’ve set things up means we avoid: - reviewing PRs - manually merging PRs In fact we don’t even get the update PR anymore! ## Advanced configuration The capabilities listed below are commonly needed for all the above use cases. ### Batched updates Renovate defaults to separating each dependency update into its own PR. But you may want to batch or “group” updates together. For example, group all patch updates into one PR or even all non-major updates together (patches and minor updates). You can configure batched updates by setting a [`groupName`](../configuration-options.md#groupname) as part of `packageRules`. To learn more about batched updates, see [Package grouping](../noise-reduction.md#package-grouping). ### Scheduled updates You may want to limit the times when Renovate is allowed to raise updates. This reduces “noise” during your working hours, and reduces the chance of CI contention. You can tell Renovate to “not bother you” during times when you’re using the CI resources, or want to focus on your work. You can set the time ranges during which Renovate creates updates in the `schedule` field. ### On-demand updates via Dependency Dashboard You can use Renovate’s “Dependency Dashboard” on platforms which support dynamic Markdown checkboxes: - Forgejo - Gitea - GitHub - GitLab When you enable the Dependency Dashboard, Renovate creates a “Dependency Dashboard” issue. This issue lists all updates which are pending, in progress, or were previously closed ignored. If you want to get an update ahead of schedule, or want to retry a previously closed update: select the update’s checkbox in the Dependency Dashboard. ### Dependency Dashboard Approval If you enable the Dependency Dashboard you can opt-in to a different workflow for some, or even all of your packages. We call this the “Dependency Dashboard Approval” workflow. Here’s how it works: - You tell Renovate which package updates need “Dashboard Approval” by setting a custom `packageRule` - Renovate only raises updates for packages that need “Dashboard Approval” after you select the corresponding checkbox on the dashboard #### Benefits of using Dependency Dashboard Approval - By not raising PRs automatically, it allows you to request updates on-demand when you’re ready, and - It offers you an alternative to permanently ignoring/disabling certain types of updates, like major updates When you use the Dependency Dashboard Approval workflow you have full visibility and control over your updates. ### Configuration presets You may run Renovate on many, or even all your repositories. This also means that you might want a similar config for all of your repositories. You can use configuration “presets” to avoid duplicating your configuration across your repositories. Configuration presets are JSON configuration files which are committed to repositories and then referenced from others. Renovate includes over 100 built-in presets, like the default recommended `config:recommended` preset. The typical workflow for a company is: - Create a dedicated repository to store the company’s default Renovate settings - Set that repository as the default `extends` value when onboarding new repositories This means that repositories get the centralized config by default, and any changes made to the centralized config repository are propagated to other repositories immediately. ## How others use Renovate You can learn a lot by seeing how others use Renovate. Check out the [Swissquote user story](../user-stories/swissquote.md). ## [GitLab bot security](https://docharvest.github.io/docs/renovate/usage/gitlab-bot-security/) Contents renovate GitLab bot security Renovate GitLab bot security Make sure you understand GitLab’s security model, before you run a “bot” service like Renovate on GitLab, particularly the pipeline credentials. !!! warning If you have any doubts or concerns about this content that could affect other users, please follow our [Security Policy](https://github.com/renovatebot/renovate/security/policy) and report them confidentially. ## `CI_JOB_TOKEN` permissions The concept of `CI_JOB_TOKEN` permissions was [overhauled in GitLab release 8.12](https://about.gitlab.com/releases/2016/09/22/gitlab-8-12-released/), jobs now run with the permissions of the user account which _triggered_ the pipeline. For security reasons the token was limited to read-only permissions and a limited set of API endpoints, but it’s been extended to allow [write access to the GitLab Package Registry](https://docs.gitlab.com/ee/api/index.html#gitlab-ci-job-token). Any pipeline triggered by a user account thus has permissions to: - read any repository which that account has access to - publish packages to them With the current GitLab CI permissions model, you should only commit to a project which you trust completely. Because that project could maliciously steal repository data, publish fake releases, or spam releases. ## Risks of hosting a Renovate GitLab app/bot/service With GitLab’s current security model, we find the risks of running a _public_ bot service like Renovate are too high. Therefore we stopped hosting Renovate on GitLab, and are waiting for a better security model. You should remember that when accounts are invited into projects or groups on GitLab, acceptance happens automatically. This was a useful feature to leverage for a shared service. If you are running a self-hosted Renovate service, we recommend you: - Run a shared service only within projects which have shared visibility/security within the users, or which have a low risk that a user would try to gain access to a private project they don’t otherwise have access to - If running with `autodiscover`, also configure a value for `autodiscoverFilter` so that the bot can’t be invited to projects or groups you don’t intend ## Security solutions and workarounds The following research notes may help you to assess the GitLab bot security risk. ### Public projects only If you only run a bot service on _public_ projects, the risk of unauthorized users accessing private project data is zero. But malicious users can still spoof or spam packages to any other public project they are not a member of, this rules out this approach for a public hosted service. A public-visibility-only bot service should be low risk for most self-hosted GitLab instances. But you _can’t stop users_ from inviting the bot into _private_ projects by accident, which is risky. ### Project Access Tokens [Project Access Tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) (PATs) are a recently added feature for GitLab. The main downsides to using PATs for a shared bot service are: - You can not [provision PATs through the API](https://gitlab.com/gitlab-org/gitlab/-/issues/238991), so project maintainers would need to provision a project bot account and then save it to Renovate manually and per-project - PATs are a paid-only feature for gitlab.com, which prevents users on the free plan from using them - At the time of writing, there are still some issues with getting PATs to trigger and authenticate CI - Any service using PATs would get MRs from a user like `@project_123_bot` instead of `@renovate-bot` The big benefit of PATs is their limited scope: users with write access to one project cannot read/write to other projects. ### Group Access Tokens Group Access Tokens are still in the planning stage, but may offer a more scalable way to manage a Renovate service. Tokens could be provisioned into Renovate per-group. Permissions and visibility _must_ be kept uniform throughout the group to prevent a privilege escalation. Many GitLab users _do not_ have uniform permissions and visibility throughout groups today, so this is a risk of Group Access Tokens in general. The [`gitlab-org` organization on GitLab](https://gitlab.com/gitlab-org) shows how common it is to mix project visibility within a same group. And the same as with PATs, if Group Access Tokens becomes a paid feature then users on a free plan can’t use the feature. ### Skipping CI The security problem described above is that if a user triggers a malicious pipeline then they can be exploited, so skipping CI altogether would seem to be a way to avoid that. If Renovate can _reliably_ force CI skipping for both (a) branch push, and (b) MR creation/updating then there should be no security exploit risk, but of course then there are no tests run instead. A possibility in future could be to combine this with a force push from a user or project token to trigger tests. The above solution/workaround will be actively researched in collaboration with GitLab. ### OAuth An alternative to a bot service running with a bot PAT would be to have it run using user OAuth tokens. In this scenario, an OAuth app would be needed to allow users to “install” the bot into projects with members they trust not to exploit them, and then commits and Merge Requests would appear to be authored by the _user_, not any bot. Bot services are better if they are provisioned with a “bot identity” so that users can quickly distinguish bot activity from real user activity. ## Recommended migration Until we can safely reactivate the hosted app, we recommend users migrate to use self-hosted pipelines to run Renovate. Read the [renovate-bot/renovate-runner README on GitLab](https://gitlab.com/renovate-bot/renovate-runner/-/blob/HEAD/README.md) to learn how. ## Status of the Renovate app for GitLab We’re trying to find a workable design for the GitLab app, so we can enable it safely again. If you have any ideas, please open a [discussion](https://github.com/renovatebot/renovate/discussions) and let us know! GitLab introduced Group Access Tokens & API for paid & self-hosted instances, but a good permission setup/flow is still not possible. Check out [GitLab issue #346298](https://gitlab.com/gitlab-org/gitlab/-/issues/346298). ## Acknowledgments Thank you to Nejc Habjan for bringing this security challenge to our attention, and also to his colleagues at Siemens for their help researching the risks. Thanks also to the GitLab security team for being responsive to our questions. ## [Automated Dependency Updates for Go Modules](https://docharvest.github.io/docs/renovate/usage/golang/) Contents renovate Go Modules Renovate Go Modules Renovate supports upgrading dependencies in `go.mod` files and associated `go.sum` checksums. If you’re self-hosting Renovate, you may use these environment variables: - `GOPROXY` - `GONOPROXY` - `GOPRIVATE` - `GOINSECURE` To learn what these variables do, read the [Go Modules Reference about the`GOPROXY` protocol](https://go.dev/ref/mod#module-proxy). ## How It Works 1. Renovate searches in each repository for any `go.mod` files 2. Renovate extracts existing dependencies from `require` statements 3. Renovate resolves the dependency’s source repository and checks for SemVer tags if found. Otherwise commits and `v0.0.0-....` syntax will be used 4. If Renovate finds an update, Renovate will update `go.mod` to the new value 5. Renovate runs `go get` to update the `go.sum` files (you can configure which directories are included using the `goGetDirs` option) 6. If the user has enabled the option `gomodUpdateImportPaths` in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) array, then Renovate uses [mod](https://github.com/marwan-at-work/mod) to update import paths on major updates, which can update any Go source file 7. If the user has any of the available `gomodTidy` options (e.g. `gomodTidy1.17`) in the [`postUpdateOptions`](./configuration-options.md#postupdateoptions), then Renovate runs `go mod tidy` with the respective options (multiple options are allowed). 8. `go mod vendor` is run if vendored modules are detected 9. A PR will be created with `go.mod`,`go.sum`, and any updated vendored files updated in the one commit 10. If the source repository has either a “changelog” file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR ## Enabling Go Modules Updating Renovate updates Go Modules by default. To install Renovate Bot itself, either enable the [Renovate App](https://github.com/apps/renovate) on GitHub, or check out [Renovate OSS](https://github.com/renovatebot/renovate) for self-hosted. ## Technical Details ### Replace massaging Renovate can massage `replace` statements it finds prior to running `go` commands, and then massage them back afterwards. This capability was added - and originally default behavior - because relative `replace` statements outside of the current repo will not work when Renovate clones the repo locally. On the other hand, this massaging of `replace` statements may lead to unexpected results, especially because `go mod tidy` may not fully tidy the `go.sum` if it is missing the `replace` directives in `go.mod`. It has therefore been disabled by default. To enable this replace massaging behavior, add `gomodMassage` to your `postUpdateOptions` array. ### Module Tidying Go Modules tidying is not enabled by default, and is opt-in via the [`postUpdateOptions`](./configuration-options.md#postupdateoptions) config option. The reason for this is that a `go mod tidy` command may make changes to `go.mod` and `go.sum` that are completely unrelated to the updated module(s) in the PR, and so may be confusing to some users. ### Module Vendoring Vendoring of Go Modules is done automatically if `vendor/modules.txt` is present. Renovate will commit all files changed within the `vendor/` folder. !!! note Renovate does not support vendoring major upgrades of Go modules. Follow issue [#21010](https://github.com/renovatebot/renovate/issues/21010). ### Go binary version By default, Renovate will keep up with the latest version of the `go` binary. You can force Renovate to use a specific version of Go by setting a constraint. ``` { "constraints": { "go": "1.23" } } ``` We do not support patch level versions for the minimum `go` version. This means you cannot use `go 1.23.3`, but you can use `go 1.23` as a constraint. ### Custom registry support, and authentication This example shows how you can use a `hostRules` configuration to configure Renovate for use with a custom private Go module source using Git to pull the modules when updating `go.sum` and vendored modules. All token `hostRules` with a `hostType` (e.g. `github`, `gitlab`, `bitbucket`, … ) and host rules without a `hostType` are setup for authentication. ``` module.exports = { hostRules: [ { matchHost: 'github.enterprise.com', token: process.env.GO_GITHUB_TOKEN, hostType: 'github', }, { matchHost: 'someGitHost.enterprise.com', token: process.env.GO_GIT_TOKEN, }, ], }; ``` ## [Java Dependency Updates](https://docharvest.github.io/docs/renovate/usage/java/) Contents renovate Java Versions Renovate Java Versions Renovate can update Gradle, Maven, and Ant dependencies. This includes libraries and plugins as well as the Gradle Wrapper. ## LTS releases The `config:recommended` preset includes the `workarounds:javaLTSVersions` preset. The workaround limits Renovate to upgrade to LTS versions of the Java runtime only. If you want Renovate to offer all `major` Java updates then add `workarounds:javaLTSVersions` to the `ignorePreset` array: ``` { "extends": ["config:recommended"], "ignorePresets": ["workarounds:javaLTSVersions"] } ``` ## Gradle Renovate detects versions that are specified in a string `'group:artifact:version'` and those specified in a map `(group:groupName, name:ArtifactName, version:Version)`. ### Gradle File Support Renovate can update: - `*.gradle`/`*.gradle.kts` files - Dependencies with version definitions in `gradle.properties` files - Gradle lockfiles stored in `*.lockfile` files - `*.versions.toml` files in any directory or `*.toml` files inside the `gradle` directory ([Gradle Version Catalogs docs](https://docs.gradle.org/current/userguide/platforms.html)) - `versions.props` and `versions.lock` from the [gradle-consistent-versions](https://github.com/palantir/gradle-consistent-versions) plugin - `gradle/verification-metadata.xml` signatures and checksums for [dependency verification](./modules/manager/gradle/index.md#dependency-verification) Renovate does not support: - Android projects that require extra configuration to run (e.g. setting the Android SDK) - Catalogs with version ranges - Catalog versions using `reject`, and `rejectAll` constraints - Catalog versions using more than one of `require`, `strictly`, `prefer` in a single declaration - Catalogs with custom names that do not end in `.toml` - Catalogs outside the `gradle` folder, whose names do _not_ end in `.versions.toml` (unless overridden via [`managerFilePatterns`](./configuration-options.md#managerfilepatterns) configuration) ### Gradle Plugin Support Renovate can also update [Gradle plugins](https://docs.gradle.org/current/userguide/plugins.html). It supports the `id()` syntax as well as the `kotlin()` shortcut for `id(org.jetbrains.kotlin.)`. For specifying `packageRules` it is important to know how `depName` and `packageName` are defined for a Gradle plugin: - The `depName` field is equal to `` - The `packageName` field is equal to `:.gradle.plugin` This is a direct consequence of the [Plugin Marker Artifact](https://docs.gradle.org/current/userguide/plugins.html#sec:plugin_markers) naming convention. ## Gradle Wrapper Renovate can update the [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) of a project. This includes the source declaration inside the `gradle/wrapper/gradle-wrapper.properties` as well as accompanied files such as `gradlew`, `gradlew.bat`, and `gradle/wrapper/gradle-wrapper.jar`. ### How It Works Renovate extracts the Gradle Wrapper version used from the `distributionUrl` inside the `gradle-wrapper.properties`. Once the version is determined, Renovate will look for newer versions from the `gradle-version` datasource. Renovate will then invoke the Gradle Wrapper to update itself, [as recommended by Gradle](https://docs.gradle.org/current/userguide/gradle_wrapper.html#sec:upgrading_wrapper). For the extraction to work, the `distributionUrl` must point to a file of type `.zip`, which includes the version in its name, and defines one of the official distribution types (bin, all). ### Support for mirrors and custom distributions As Renovate takes the `distributionUrl` defined inside the `gradle-wrapper.properties` as basis for its update, source declarations other than to the official Gradle Wrapper are supported. This can be used for hosting the official distributions with a proxy server, an offline mirror or even providing a custom distribution of the Gradle Wrapper, e.g. to provide a company-wide base configuration for all Gradle projects. But the `gradle-version` datasource is used to determine available versions. In case the available versions at the defined source differ from those available from Gradle or the [default datasource](https://services.gradle.org/versions/all) cannot be reached, e.g. due to network restrictions, the datasource may be reconfigured via a `packageRule`: ``` { "packageRules": [ { "matchDatasources": ["gradle-version"], "registryUrls": [ "https://domain.tld/repository/custom-gradle-wrapper/versions.json" ] } ] } ``` ## Maven Renovate can update dependency versions found in Maven `pom.xml` files. ### Maven File Support Renovate will search repositories for all `pom.xml` files and processes them independently. Renovate will also parse `settings.xml` files in the following locations: - `.mvn/settings.xml` - `.m2/settings.xml` - `settings.xml` Any repository URLs found within will be added as `registryUrls` to extracted dependencies. ## Custom registry support, and authentication The manager for Gradle makes use of the `maven` datasource. Renovate can be configured to access more repositories and access repositories authenticated. This example shows how you can use a `config.js` file to configure Renovate for use with Artifactory. We’re using environment variables to pass the Artifactory username and password to Renovate bot. ``` module.exports = { hostRules: [ { hostType: 'maven', matchHost: 'https://artifactory.yourcompany.com/', username: process.env.ARTIFACTORY_USERNAME, password: process.env.ARTIFACTORY_PASSWORD, }, ], }; ``` You can overwrite the repositories to use for version lookup through configuration. ``` module.exports = { packageRules: [ { matchDatasources: ['maven'], registryUrls: ['https://repo-a.tld/repo', 'https://repo-b.tld/repo'], }, ], }; ``` ### Google Artifact Registry There are multiple ways to configure Renovate to access Artifact Registry. #### Using Application Default Credentials / Workload Identity (Self-Hosted only) Configure [ADC](https://cloud.google.com/docs/authentication/provide-credentials-adc) or [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) as normal and _don’t_ provide a username, password or token. Renovate will automatically retrieve the credentials using the `google-auth-library`. #### Using long-lived service account credentials To access the Google Artifact Registry, use the JSON service account with `Basic` authentication, and use the: - `_json_key_base64` as username - full Google Cloud Platform service account JSON as password To avoid JSON-in-JSON wrapping, which can cause problems, encode the JSON service account beforehand. 1. Download your JSON service account and store it on your machine. Make sure that the service account has `read` (and only `read`) permissions to your artifacts 2. Base64 encode the service account credentials by running `cat service-account.json | base64` 3. Add the encoded service account to your configuration file 1. If you want to add it to your self-hosted configuration file: ``` { "hostRules": [ { "matchHost": "europe-maven.pkg.dev", "username": "_json_key_base64", "password": "" } ] } ``` 2. If you want to add it to your repository Renovate configuration file, [encrypt](./configuration-options.md#encrypted) it and then add it: ``` { "hostRules": [ { "matchHost": "europe-maven.pkg.dev", "username": "_json_key_base64", "encrypted": { "password": "" } } ] } ``` 4. Add the following to the `packageRules` in your repository Renovate configuration file: ``` { "packageRules": [ { "matchManagers": ["maven", "gradle"], "registryUrls": [ "https://europe-maven.pkg.dev//" ] } ] } ``` ## [JavaScript](https://docharvest.github.io/docs/renovate/usage/javascript/) Contents renovate JavaScript Renovate JavaScript Renovate supports upgrading JavaScript dependencies specified in `package.json` files. `npm`, `yarn`, `pnpm` and `bun` are all supported. ## [JSON Schema](https://docharvest.github.io/docs/renovate/usage/json-schema/) Contents renovate JSON Schema Renovate Renovate's JSON Schemas to describe possible configuration. Renovate provides [JSON Schemas](https://json-schema.org/) which can provide autocomplete, documentation and validation in your editor. Consult your editor’s documentation for how to configure this functionality. When Renovate creates an onboarding PR, it will automagically add the JSON Schema definition, like so: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", // ... } ``` As well as the `renovate-schema.json`, which covers repository configuration, Renovate also provides configuration for other types of configuration. The following JSON Schemas are available for use: - [`docs.renovatebot.com/renovate-schema.json`](renovate-schema.json) - [`docs.renovatebot.com/renovate-inherited-schema.json`](renovate-inherited-schema.json) - [`docs.renovatebot.com/renovate-global-schema.json`](renovate-global-schema.json) See below for more details on each of them. ## Repository configuration (`renovate-schema.json`) [`docs.renovatebot.com/renovate-schema.json`](renovate-schema.json) covers any [repository configuration options](./configuration-options.md) and is likely to be used in: - a repository onboarded to Renovate - any shared configuration presets - global self-hosted configuration (alongside configuration options only present in `renovate-global-schema.json` ## Repository + inherited configuration (`renovate-inherited-schema.json`) [`docs.renovatebot.com/renovate-inherited-schema.json`](renovate-inherited-schema.json) covers any [repository configuration options](./configuration-options.md), and any [inherited config options](./config-overview.md#inherited-config). It is only likely to be used if you create an `org-inherited-config.json` (or override the filename with [`inheritConfigFileName`](./self-hosted-configuration.md#inheritconfigfilename)) in your shared config repo. ## Global self-hosted configuration (`renovate-global-schema.json`) [`docs.renovatebot.com/renovate-global-schema.json`](renovate-global-schema.json) covers any [global self-hosted configuration](./self-hosted-configuration.md), and is likely to be used in: - a `config.js` - command-line arguments ### Usage with `config.js` Unfortunately - at time of writing - Language Server Protocol (LSP) servers do no yet provide a way to use a JSON Schema to provide type hints in a JavaScript file. ## Limitations The JSON Schema is autogenerated from the configuration options that Renovate holds. While we aim to provide relevant options, documentation and validation rules where possible, there may be times where there is a gap in the schema. Additionally, some of Renovate’s concepts _cannot_ be validated through JSON Schema, as they require more complex checks that only happen in Renovate’s codebase. Using the JSON Schema is recommended for early feedback (in your editor, or for your agent) but it is recommended to look at the [documentation around validating your config](./config-validation.md), for instance using `renovate-config-validator`, which will provide a more robust and accurate validation process. ## Previous majors The Renovate documentation site tracks the current release version of Renovate. If you are using the current major version of Renovate, but not the most up-to-date version of Renovate, you may find that the JSON Schema describes a configuration option you do not yet have access to. If you’re using a previous major version of Renovate, there will likely be many differences between what you have available in your version of Renovate. With this in mind, when Renovate releases a major version, we store an archive of the JSON Schema for the previous major version [in Schema Store](https://www.schemastore.org/). !!! note Previous major versions are only available since Renovate 39 (2025-04-29). For instance, if you are running Renovate 41, you will be able to use i.e. [`www.schemastore.org/renovate-41.json`](https://www.schemastore.org/renovate-41.json) for your JSON Schema. ## [Introduction](https://docharvest.github.io/docs/renovate/usage/key-concepts/automerge/) Contents renovate Automerge configuration and troubleshooting Renovate Automerge configuration and troubleshooting You can choose to automate some dependency updates by letting Renovate automerge its PR. Renovate will wait for the required tests to pass before it automerges. ## Renovate automerges take time Renovate automerges take time, so Renovate can’t automerge a PR the second it passes your required tests. Before you start troubleshooting, wait! Give Renovate about two hours, so Renovate can run in a state where your tests have passed, and the PR branch is up-to-date with the base branch. If you or others keep committing to the default branch then Renovate cannot find a suitable gap to automerge into! After Renovate automerges a branch, Renovate must calculate the “Git state” again, for all remaining branches. Merging one branch may result in another branch’s updates being changed, or even removed as no longer needed. Renovate requires automerging branches to be up-to-date with their target branch, _before_ automerging. As merging more than one branch in a row does not work _reliably_, Renovate will only automerge one branch/PR, per target branch, per run. Then you’ll have to wait for the next time Renovate runs. ## Recommendations from the Renovate maintainers In general, we recommend you enable automerge for any dependency update where you would select “merge” anyway. Keep automerge _disabled_ for updates where you want to read the changelogs or code before the merge. Automerge often works well for `devDependencies`. It can work for production `dependencies` too, but your project should have good test coverage. For example, if you have Jest or Mocha as a development dependency, and it has an upgrade with passing tests… automerge them! If you have a linter like ESLint or TSLint and its update passes… automerge them! If you have an API with 100% test coverage and Express is updated… automerge it! { loading=lazy } ## Configuration examples ### Automerge lock file maintenance The lowest risk type of update to automerge is probably `lockFileMaintenance`. When Renovate performs lock file maintenance, it leaves the project dependency definitions unchanged, but refreshes the lock file completely. This means Renovate installs the latest versions, that match the package file constraints. ``` { "lockFileMaintenance": { "enabled": true, "automerge": true } } ``` ### Automerge lint tool updates Automerging lint tool updates can be a real time-saver. Often a new lint tool version pass the updated tests, without any code changes on your end. If the tests pass you may as well automerge the PR. In cases where you need to make changes to your code, the Renovate PR will fail the linter check. You can then make the necessary code changes directly in the Renovate branch for that PR, confirm the tests pass with your changes, and manually merge the PR. ``` { "packageRules": [ { "matchDepTypes": ["devDependencies"], "matchPackageNames": ["lint", "prettier"], "automerge": true } ] } ``` ### Automerge non-major updates Non-major updates in SemVer ecosystems shouldn’t have breaking changes (if they follow the spec), so many users enable automerge for these too: ``` { "packageRules": [ { "matchUpdateTypes": ["minor", "patch"], "matchCurrentVersion": "!/^0/", "automerge": true } ] } ``` The `matchCurrentVersion` setting above is a rule to exclude any dependencies which are pre-1.0.0 because those can make breaking changes at _any_ time according to the SemVer spec. ### Automerge monorepo PRs Say you want to automerge `patch` and `minor` updates for packages in the `group:ionic-nativeMonorepo` preset: ``` { "packageRules": [ { "extends": ["monorepo:ionic-native"], "matchUpdateTypes": ["patch", "minor"], "automerge": true } ] } ``` ### Faster merges with platform-native automerge By default, Renovate uses platform-native automerge to speed up automerging. If you don’t want Renovate to use the platform-native automerge, then set `platformAutomerge` to `false`. ``` { "lockFileMaintenance": { "enabled": true, "automerge": true, "automergeType": "pr", "platformAutomerge": false } } ``` For more information read [`platformAutomerge`](../configuration-options.md#platformautomerge). ### GitHub Merge Queue Renovate supports GitHub’s Merge Queue. Read the [GitHub Docs, managing a merge queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) first. The steps to enable GitHub’s Merge Queue differ based on whether you use GitHub Actions or another CI provider. !!! tip “GitHub Merge Queue overview page” GitHub has a page that shows all the PRs in the Merge Queue. The page link follows this pattern: `https://github.com/organization-name/repository-name/queue/base-branch-name`. For example, here’s [Renovate’s main repository’s Merge Queue overview](https://github.com/renovatebot/renovate/queue/main). #### If you use GitHub Actions If you use GitHub Actions as your CI provider, follow these steps: Add the `on.merge_group` event to your GitHub Action `.yaml` files, for example: ``` on: pull_request: merge_group: ``` On `github.com`, go to your repository’s “homepage”, click on Settings, scroll down to the Pull Requests section and [enable the “Allow auto-merge” checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Then go to your repository’s branch protection rules for your base branch (usually `main`) and enable the “Require merge queue” setting. Confirm you’ve set the correct “required checks” for your base branch. Finally, allow Renovate to automerge by setting `automerge=true` in your Renovate config file, for example: ``` { "packageRules": [ { "description": "Automerge non-major updates", "matchUpdateTypes": ["minor", "patch"], "automerge": true } ] } ``` #### If you don’t use GitHub Actions If you _don’t_ use GitHub Actions as your CI provider, follow these steps: Update your CI provider’s configuration so it also runs tests on the temporary `gh-readonly-queue/{base_branch}` branches, read your CI providers’s documentation to learn how to do this. On `github.com`, go to your repository’s “homepage”, click on Settings, scroll down to the Pull Requests section and [enable the “Allow auto-merge” checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Go to your repository’s branch protection rules for your base branch (usually `main`) and enable the “Require merge queue” setting. Confirm you’ve set the correct “required checks” for your base branch. Finally, allow Renovate to automerge by setting `automerge=true` in your Renovate config file (see earlier example). ## Automerging and scheduling Automerging is particularly beneficial if you have configured a schedule, because Renovate on its own may be able to automerge the majority of your updates. And this is especially so if your repository needs rebasing, like when you use lock files. Let’s say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file. - At the start of the schedule, `Renovate` will create branches for `abc` and `xyz` upgrades, including `yarn.lock` updates - After `abc` passes tests, `Renovate` will automerge it into the base branch - The `xyz` branch has a `yarn.lock` conflict now - Renovate will immediately check all other branches and rebase them - The change to `xyz` branch will trigger another round of CI tests - After the updated `xyz` branch passes, Renovate will automerge it too This is a lot better than you waking up to two PRs and then having to deal with conflicts yourself after you merge the first one. ## Branch vs PR automerging Even if you automerge PRs, you are likely to still get notification noise - one when the PR is created and another when it is merged. For this reason we recommend you consider setting `automergeType=branch` which will mean: - Renovate first creates a branch and no PR - If tests pass, Renovate pushes a commit directly to the base branch without PR - If tests fail, Renovate raises a PR for you to review Add the `renovate/**` branch to your testing workflow files, or Renovate will not work properly with the `automergeType=branch` setting. The result is that passing updates are essentially “silent” - the only sign of them are the commits Renovate pushes to your base branch. If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this won’t work and you should stick with the default PR-based automerging instead. ## Assignees and Reviewers When automerge is enabled on a PR, Renovate will _not_ add assignees or reviewers at PR creation time, in order to decrease notifications noise a little. If tests subsequently _fail_, making automerge not possible, then Renovate will add the configured assignees and/or reviewers. Note: Renovate won’t add assignees and reviewers to a PR with failing checks if the PR already has assignees or reviewers present. If there are accounts you wish to ignore (i.e. add assignees and reviewers regardless) then add them to `ignoreReviewers` to specify those which should be filtered out in such consideration. ## Frequent problems and how to resolve them ### Automerge not enabled correctly in config Sometimes, the reason Renovate is not automerging a PR is because of a configuration mistake. You can confirm that Renovate knows you want it to automerge by checking if the PR body includes the text “Automerge: Enabled”. If you see “Automerge: Disabled by config” it means you need to make a config change for automerge to work. ### Absence of tests By default, Renovate will not automerge until it sees passing status checks / check runs for the branch. If you have no tests but still want Renovate to automerge, you need to add `"ignoreTests": true` to your configuration. !!! tip We strongly recommend you have tests in any project where you are regularly updating dependencies. ### Committer restrictions If you have protected your base branch with a list of allowed committers, and Renovate is not on that list, then naturally automerge can’t work. ### Pull Requests Required If you have configured your project to require Pull Requests before merging, it means that branch automerging is not possible, even if Renovate has rights to commit to the base branch. ### Required Pull Request reviews If you have mandatory Pull Request reviews then it means Renovate can’t automerge its own PR until such a review has happened. If you’re on `github.com` or GitHub Enterprise Server (`>=3.4`) you can let Renovate bypass the mandatory Pull Request reviews using the “[Allow specified actors to bypass required pull requests](https://github.blog/changelog/2021-11-19-allow-bypassing-required-pull-requests/)” option in your branch protection rules. Alternatively, if you use the Mend Renovate App, you can also install the helper apps [renovate-approve](https://github.com/apps/renovate-approve) and [renovate-approve-2](https://github.com/apps/renovate-approve-2) and they will mark all automerging Pull Requests by Renovate as approved. These approval helper apps are only available for GitHub. On Azure/Gerrit/Gitlab, you can activate the [`autoApprove` option](../configuration-options.md#autoapprove). ### Codeowners Depending on the platform, having a `CODEOWNERS` file could block automerging, because it means a code owner must review the PR. ### Overriding global automerge You might have setup a global configuration in a `.github` repository, that has a `renovate.json` file that turns on automerge for certain dependencies. It does not matter where you’ve put the global config, the important point in this example is that you’re extending from a global config that’s somewhere else. For this example we’ll assume you put your config in a repository on GitHub, called `.github`. Repositories in the organization all extend from this global configuration, and so they “inherit” the automerge settings as well. To turn off automerge for all dependencies of a selected repository, you need to make a config that overrides all `packageRules` in the repository’s `renovate.json` file, like this: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["local>org-name/.github:renovate-config"], "packageRules": [ { "matchPackageNames": ["*"], "automerge": false } ] } ``` ## [Renovate and changelogs](https://docharvest.github.io/docs/renovate/usage/key-concepts/changelogs/) Contents renovate Renovate and changelogs Renovate Learn how Renovate fetches changelogs This page explains how Renovate fetches changelogs, when it can display them, and more. ## How Renovate detects changelogs Renovate detects and populates changelogs by: 1. Identifying a source URL from the datasource response for a package, and saving that internally as `sourceUrl` if found 2. Checking if Renovate’s internal [_sourceUrl_ data](https://github.com/renovatebot/renovate/blob/main/lib/data/source-urls.json) for the package includes a source URL 3. Looking up the source URL, if it resides on a supported platform (e.g. GitHub) 4. Checking for both “Releases” metadata in the repository and any commonly known “changelog” file names 5. Filtering the found releases to only include those versions being updated by the current PR 6. Formatting and embedding the results into the PR body ## Changelogs for private packages For private packages, the algorithm is mostly the same as described above, with the additional considerations: - Renovate must be able to access the private package in the first place - The private registry must include the source URL in its response - Renovate must be able to detect and authenticate with whatever private repository corresponds to the source URL For more details, see [Private packages, looking up changelogs](../getting-started/private-packages.md#looking-up-changelogs). ## Relevant configuration options ### [`fetchChangeLogs`](../configuration-options.md#fetchchangelogs) Top-level configuration that controls when to fetch changelogs for addition to pull-request and branch commit-messages. If you want more finely-grained control over changelog fetching (disabling for specific packages, source repositories, etc), use [packageRules](../configuration-options.md#packagerules) to override the `fetchChangeLogs` value for matching packages. Set to `off` if changelog fetching is causing a problem. Set to `branch` if you have an advanced use case where you’re embedding changelogs in the Git commit itself, we don’t recommend this due to its potential size. ### [`changelogUrl`](../configuration-options.md#packageruleschangelogurl) This doesn’t help with _fetching_ the changelogs, but if you configure it then Renovate will include a link to this URL in the PR body, so users can click through to read the changelog. ## Platforms that Renovate can fetch changelogs from See the list of platforms in the [`fetchChangeLogs` config option docs](../configuration-options.md#fetchchangelogs). ### Running Renovate on a non-GitHub platform Most Open Source packages are hosted on github.com, which means most changelogs are hosted there too. Fetching changelogs from github.com requires a GitHub token because GitHub blocks unauthenticated GraphQL API use. This means that if you run Renovate on self-hosted GitHub Enterprise Server, or any non-GitHub platform which Renovate supports, then you need to configure a github.com Personal Access Token in Renovate in order to fetch changelogs. Read [Running Renovate, GitHub.com token for changelogs](../getting-started/running.md#githubcom-token-for-changelogs-and-tools) to learn more. ## Troubleshooting missing changelogs Follow these steps to find out why Renovate does not find a changelog: 1. The datasource for this package does not support sourceUrls. - If the registry fundamentally does not provide this data, then the only possibility is for it to be manually populated through PRs to Renovate’s source code - If the registry provides source URLs in its response but Renovate does not understand the required fields, then raise a feature request with examples, or better yet a Pull Request to implement support for the source URL parsing/mapping yourself - Sometimes self-hosted versions of registries don’t include the full metadata compared to what the public registries do 2. The package was published without source URL information being included. - For example, occasionally `npm` packages don’t have `repository` fields included - For example, Docker images regularly do not have the required `LABEL` entry 3. Renovate cannot access the source repository - This is typically a concern for private repositories only - Check if the token Renovate uses has access rights to the repository you need it to access 4. Renovate cannot detect the file names or release name convention within the repository - In this case an enhancement to Renovate might be needed to better detect the releases/formats, assuming the package/repository has a reasonable convention to follow 5. Renovate cannot detect the release version in the changelog file - Ensure the changelog header for the section contains the version being released, or in the case of a monorepo where this may not be the case, ensure the body has a line that contains both the package name and the version. - Otherwise an enhancement to Renovate might be needed to better detect the versions, assuming the package/repository has a reasonable convention to follow If none of this helps, search the Renovate issues and discussions to see if this is a known problem. ## Advice for package maintainers This section is for package maintainers that want to make sure Renovate can see their changelogs. There isn’t much information to add other than what’s already written above. Make sure that you have the required source URL in your package metadata, not just in your repository but also in the final data which the registry returns. For example, we have seen cases where the `repository` field in npm’s `package.json` is populated correctly in the repository, but stripped out as part of the publishing process. ### Let Renovate understand your versioning and changelogs In general, Renovate can understand your versions and changelogs best when you: - Use SemVer versioning, so `major.minor.patch` - Use the [`semantic-release` bot](https://github.com/semantic-release/semantic-release) to automate the release process Try to avoid things like: - Stripping out the trailing `.0` unnecessarily (e.g. having a package `3.1.0` on a registry but using only `3.1` in your changelogs) - Using “Release names” in a way which makes the actual version hard to discern (e.g. instead of `3.0.0` you title your release notes `Big news! v3 is here` ### npm package maintainers As maintainer, make sure the `package.json` has a filled in `repository` field, read the [npm Docs, configuring npm `repository` field](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#repository) to learn more. If your repository uses the monorepo pattern make sure _each_ `package.json` file has a `repository` field. ### maven package maintainers Read [`maven` datasource, making your changelogs fetchable](../modules/datasource/maven/index.md#making-your-changelogs-fetchable). ### Docker image maintainers Read the [Docker datasource](../modules/datasource/docker/index.md) docs. ### NuGet package maintainers See [Renovate issue #14128 about using NuGet’s changelogs](https://github.com/renovatebot/renovate/issues/14128). ## [Introduction](https://docharvest.github.io/docs/renovate/usage/key-concepts/dashboard/) Contents renovate Dependency Dashboard Renovate Dependency Dashboard Renovate has a Dependency Dashboard that shows an overview of the state of your repositories’ dependencies. When the Dependency Dashboard is enabled, Renovate will create a new issue in the repository. This issue has a “dashboard” where you can get an overview of the status of all updates. Having the Dependency Dashboard also enables the concept of an “approval” workflow for new upgrades, either for selected dependencies (recommended) or even for all. ## Supported platforms The Dependency Dashboard requires that the host platforms supports the concept of issues with dynamic Markdown checkboxes. Read [our FAQ, Renovate core features not supported on all platforms](../faq.md#renovate-core-features-not-supported-on-all-platforms) to see if your platform can use the Dependency Dashboard feature. ## How to enable the dashboard To turn on the Dashboard manually, add the `:dependencyDashboard` preset to your `extends` array in the Renovate configuration file: ``` { "extends": ["schedule:automergeDaily", ":dependencyDashboard"] } ``` Or set `dependencyDashboard` to `true`: ``` { "dependencyDashboard": true } ``` ## How to disable the dashboard To disable the Dependency Dashboard, add the preset `:disableDependencyDashboard` or set `dependencyDashboard` to `false`. ``` { "extends": ["config:recommended", ":disableDependencyDashboard"] } ``` ## Use cases This section explains some common use cases where having the Dependency Dashboard can help. ### Warnings for deprecated dependencies If Renovate finds: - packages flagged as deprecated on their registry, or - packages that have a community-sourced replacement PR available Then Renovate adds a prominent warning about these packages near the top of the Dependency Dashboard. Here is an example of how this can look: > The following dependencies are deprecated: Datasource Name Replacement? npm `airbnb-prop-types` npm `left-pad` #### Abandonment detection Renovate includes the `abandonments:recommended` preset (automatically included in `config:best-practices`) to help identify potentially abandoned packages. This preset: - Sets a default [`abandonmentThreshold`](../configuration-options.md#abandonmentthreshold) of `1 year` for all packages - Includes community-sourced overrides for packages that appear abandoned but are still maintained - Prevents updates to truly abandoned packages while allowing updates to packages with irregular release schedules **Usage:** ``` { "extends": ["abandonments:recommended"] } ``` You can contribute additional overrides by updating the [`abandonments.json`](https://github.com/renovatebot/renovate/blob/main/lib/data/abandonments.json) file. ### Visibility into rejected/deferred updates Renovate’s Dependency Dashboard shows an overview of all updates that are still “to do”. If you close an update PR from Renovate without merging, the Dashboard will list this update in the Closed/Ignored section. If you later change your mind about the update, you can get a new PR by selecting the corresponding checkbox on the dashboard. ### Dependency Dashboard Approval workflow Sometimes you want Renovate to wait for your approval before creating an update PR. You can customize this “wait for approval” behavior however you like best. At a high level the options are: - Require approval for _all_ updates - Require approval for a type of updates (`major` for example) - Require approval for specific packages You can mix and match these options as well. #### Require approval for all updates We do not recommend that you require approval for _all_ updates. When you require prior approval, you need to check the dashboard issue regularly to check for important updates. You’ll probably forget to check often enough, and out of sight means out of mind! Maybe you find Renovate too noisy, and want to opt-out of getting automatic updates whenever they’re ready. In this case, you can tell Renovate to wait for your approval before making any pull requests. This means that you have full control over when you get updates. But vulnerability remediation PRs will still get created immediately without requiring approval. To require manual approval for _all updates_, add the `:dependencyDashboardApproval` presets to the `extends` array in your Renovate configuration file: ``` { "extends": ["config:recommended", ":dependencyDashboardApproval"] } ``` #### Require approval for major updates Major updates often have breaking changes which require manual changes in your code before they can be merged. So maybe you only want to get major updates when you have sufficient time to check them carefully. Dependency Dashboard Approval is far superior to disabling major updates because at least you can fully see what’s pending on the dashboard, instead of updates being totally invisible. If you want to require approval for major updates, set `dependencyDashboardApproval` to `true` within a `major` object: ``` { "major": { "dependencyDashboardApproval": true } } ``` #### Require approval for specific packages Sometimes you only want to update specific packages when you say so. Maybe a package doesn’t follow Semantic Versioning, and has breaking changes on every new release, so you want to update on your terms. Or maybe you have a package that updates too rapidly for you to keep up with, and you want to update once in a while manually. If you want to approve specific packages, set `dependencyDashboardApproval` to `true` within a `packageRules` entry where you have defined a specific package or pattern. ``` { "packageRules": [ { "matchPackageNames": ["@somescope/**"], "dependencyDashboardApproval": true } ] } ``` ## [Introduction](https://docharvest.github.io/docs/renovate/usage/key-concepts/how-renovate-works/) Contents renovate How Renovate works Renovate How Renovate works Renovate usually performs these steps: - Cloning the repository - Scanning package files to extract dependencies - Looking up registries to check for updates - Applying any grouping rules defined - Pushing branches and raising Pull Requests Because Renovate must support a lot of dependency naming and versioning conventions, it has modules for each known convention. You can contribute your own modules, if you want. ## Modules Renovate’s modules are: - [datasource](../modules/datasource/index.md) - [manager](../modules/manager/index.md) - [platform](../modules/platform/index.md) - [versioning](../modules/versioning/index.md) Renovate uses these modules in order: 1. The platform module interacts with the source control platform and clones the repository 2. The manager module looks for files based on their name and extracts the dependencies (each dependency has a datasource) 3. The datasource module looks up versions of the dependency 4. The versioning module validates and sorts the returned versions For example: 1. The `gitlabci` manager finds a dependency: `python:3.10-alpine` which has the `docker` datasource 2. The `docker` datasource looks for versions and finds: `[python:3.9,python:3.9-alpine,python:3.10,python:3.10-alpine,python:3.11,python:3.11-alpine]` 3. The `docker` versioning returns `python:3.11-alpine`, because that version is compatible with `python:3.10-alpine` # Workflow Here’s an overview of the workflow: ``` flowchart TB subgraph INITIALIZATION direction TB MC[Merge configurations
most important to least:
cli > env > file > default] MC --> IP[Initialize platform] IP --> AD[Query the platform for repositories] AD --> NFIL[Narrow the list with filters] end subgraph REPOSITORY direction TB FER{{For each repository}} subgraph EXTRACTD[EXTRACT DEPENDENCIES] direction TB CLBRANCH[Extract base branches] CLBRANCH --> VULN[Check for vulnerabilities] VULN --> CC{{For each manager}} CC -->|manager A| CD["..."] CC -->|manager B| CCF["match files"] CCF --> CFEF{{For each file}} CFEF -->|file 1| CCD1[Extract dependency] CFEF -->|file 2| CCD2[...] end subgraph LOOKUP[LOOK UP UPDATES] direction TB UC{{For each manager}} UC -->|manager A| UD["..."] UC -->|manager B| UFEF{{For each file}} UFEF -->|file 1| FED{{For each dependency}} UFEF -->|file 2| FED2[...] FED -->|dep 1| D1[...] D1 -..-> CU FED -->|dep 2| D2[use datasource to
fetch versions] D2 --> J[use versioning to find
next valid update] FED2 -...-> CU UD -....-> CU J --> CU[Look up updates] end subgraph WRITEU[WRITE UPDATES] direction TB FEU{{For each update}} FEU --> AUCOND[Check if branch needed:
existing/rebase/concurrent amount] AUCOND --> AU[Create branch
Apply update
Create PR] end subgraph FINALIZE[FINALIZE] direction TB CM[Check for config migration] CM --> CSB[Clean stale branches] end FER --> IRPO[Initialize repository] IRPO --> EXTRACTD EXTRACTD --> LOOKUP LOOKUP --> WRITEU WRITEU --> FINALIZE end INITIALIZATION --> REPOSITORY ``` ## [Minimum Release Age](https://docharvest.github.io/docs/renovate/usage/key-concepts/minimum-release-age/) Contents renovate Minimum Release Age Renovate Minimum Release Age ## What is Minimum Release Age? `minimumReleaseAge` is a feature that requires Renovate to wait for a specified amount of time before suggesting a dependency update. The use of `minimumReleaseAge` is not to slow down fast releasing project updates, but to provide a means to reduce risk supply chain security risks. In other ecosystems and package managers, this may be referred to as a “dependency cooldown”. For example, `minimumReleaseAge=14 days` would ensure that a package update is not suggested by Renovate until 14 days after its release, which allows plenty of time to allow security researchers and automated security tools to catch malicious intent in packages. Note: Renovate will wait for the set duration to pass for each **separate** version. Renovate does not wait until the package has seen no releases for x time-duration(`minimumReleaseAge`). When the time passed since the release is _less_ than the set `minimumReleaseAge`: Renovate adds a “pending” status check to that update’s branch. After enough days have passed: Renovate replaces the “pending” status with a “passing” status check. ## Configuration options The following configuration options can be used to enable and tune the functionality of Minimum Release Age: - [`minimumReleaseAge`](../configuration-options.md#minimumreleaseage) (previously known as `stabilityDays`) - [`minimumReleaseAgeBehaviour`](../configuration-options.md#minimumreleaseagebehaviour) - [`internalChecksFilter`](../configuration-options.md#internalchecksfilter) ## FAQs ### Where does the release timestamp need to be set? To prevent supply-chain attacks, Renovate requires that the registry/datasource provides the timestamp. This ensures that a package maintainer cannot specify (maliciously or accidentally) a different timestamp to when the package was actually published. !!! warning For instance, a suggestion for the Docker ecosystem is to use the `org.opencontainers.image.created` image annotation. Unfortunately, the publisher controls this annotation, so could allow a maintainer to say that their image was published earlier than it had been to bypass Minimum Release Age restrictions. As long as the registry/datasource provides the release timestamp, Renovate will add support for it. ### My package manager has support for minimum release age, how does Renovate work with that? Do I need to set it in both? We recommend specifying minimum release age in **both** your Renovate and package manager configuration. Renovate’s concept of `minimumReleaseAge` is set independently to your package manager’s configuration, and is used by Renovate to decide whether to suggest dependency updates. Renovate does not currently have the ability to determine the `minimumReleaseAge` from your package manager’s configuration. When Renovate performs a dependency update, it may delegate to your package manager to update artifacts, such as the lockfile. In some cases, this can lead to a transitive dependency being introduced, [which Renovate is not aware of](#what-happens-to-transitive-dependencies), and so could lead to a dependency being introduced without Renovate’s `minimumReleaseAge` check being followed. To protect against this, it’s recommended to ensure that your package manager configuration includes the relevant minimum release age checks, too. There is ongoing work to [integrate more closely with package manager checks](https://github.com/renovatebot/renovate/issues/41652) to make sure that Renovate’s minimum release age configuration is specified when calling package managers that support it. If you have a package manager you’d like supported, please raise a [Suggest an Idea Discussion](https://github.com/renovatebot/renovate/discussions/new?category=suggest-an-idea). #### npm When `minimumReleaseAge` is configured, Renovate passes `--before=` to npm commands during lock file generation. This ensures that npm only resolves package versions that were available before the cooldown threshold, protecting against newly published (and potentially malicious) transitive dependencies. The `--before` date is calculated as `now - minimumReleaseAge`. If a `before=` or `min-release-age=` setting already exists in the project’s `.npmrc`, Renovate uses the stricter (older) of the two dates. If the existing lock file contains packages published after the `--before` cutoff (for example, from dependencies merged before `minimumReleaseAge` was configured), npm will fail with an `ETARGET` error. In this case, Renovate automatically retries without `--before` and logs a warning. This ensures existing lock files are never broken by the `--before` flag. After the next lock file maintenance run (which regenerates the lock file from scratch with `--before`), subsequent updates will fully enforce the `minimumReleaseAge` constraint. ### What happens if the datasource and/or registry does not provide a release timestamp, when using `minimumReleaseAge`? !!! warning Renovate 42 changed the behaviour detailed below. In Renovate 42, the absence of a release timestamp will be treated as if the release is not yet past the timestamp, which provides a safer default. Prior to Renovate 42, we would treat the dependency without a release timestamp **as if it has passed** the `minimumReleaseAge`, and will **immediately suggest that dependency update**. If using Renovate prior you can opt into the more secure behaviour (which is default in Renovate 42) by using [`minimumReleaseAgeBehaviour=timestamp-required`](../configuration-options.md#minimumreleaseagebehaviour) (added in 41.150.0) Consider that: - we have set `minimumReleaseAge` to apply to a given dependency - that dependency has 4 updates available - 1 of which has a release timestamp that has passed - 2 of which have a release timestamp that has _not_ yet passed - 1 of which does not have a release timestamp Renovate will create a PR for the 1 dependency update that has passed the release timestamp, and the others will be marked as “Pending Status Checks” on the Dependency Dashboard. As time goes on, if the 2 updates with a release timestamp are now passed the minimum release age, Renovate will add them to the PR (or create a new one). ### What happens when an update is not yet passing the minimum release age checks? Renovate will decide whether it will create a branch for a dependency update using [`internalChecksFilter`](../configuration-options.md#internalchecksfilter). #### `internalChecksFilter=strict` If you have not configured [`internalChecksFilter`](../configuration-options.md#internalchecksfilter), Renovate will use `internalChecksFilter=strict` as the default. This will make sure that branches are not created if the `minimumReleaseAge` status check, `renovate/stability-days`, does not pass. Debug logs example when `internalChecksFilter=strict` ``` DEBUG: Branch renovate/actions-checkout-5.x creation is disabled because internalChecksFilter was not met (repository=..., branch=renovate/actions-checkout-5.x) ``` In this case, no branch is created. If you have a Dependency Dashboard enabled, it will be found in the Dependency Dashboard in the “Pending Status Checks”. You can force the dependency update by requesting it via the Dependency Dashboard, or if you are self-hosting, you can use the [`checkedBranches`](../self-hosted-configuration.md#checkedbranches) to force the branch creation. !!! note A previous version of the documentation (up until Renovate 42.19.9) recommended configuring [`prCreation`](../configuration-options.md#prcreation). This is no longer the case. If no branch is created, Renovate will not raise a PR, regardless of [`prCreation`](../configuration-options.md#prcreation)’s settings. #### Recommended settings The recommendation is to set `internalChecksFilter=strict` when using `minimumReleaseAge`, so Renovate will create neither branches (nor PRs) on updates that haven’t yet met minimum release age checks. ### Which update types take `minimumReleaseAge` into account? Depending on your manager, datasource and the given package(s), it may be that some updates provide a release timestamp that can have `minimumReleaseAge` enforced. Update Type Supports `minimumReleaseAge`? Notes `major` ✅ Depends on the Manager, Datasource, and package(s) `minor` ✅ Depends on the Manager, Datasource, and package(s) `patch` ✅ Depends on the Manager, Datasource, and package(s) `pin` ❌ [Not yet supported](https://github.com/renovatebot/renovate/issues/40288) `digest` 🟡 Generally not supported. Depends on the Manager, Datasource, and package(s) `pinDigest` ❌ [Not yet supported](https://github.com/renovatebot/renovate/issues/40288) `lockFileMaintenance` ❌ Not possible, as we delegate to the package manager to perform the required changes to update package(s). `lockFileUpdate` ❌ `rollback` ❌ `bump` ❌ `replacement` ❌ [Not yet supported](https://github.com/renovatebot/renovate/issues/39400) You can validate which update types may have release timestamps by following something similar to how [verify if the registry you’re using](#which-registries-support-release-timestamps). ### What happens to security updates? Security updates bypass any `minimumReleaseAge` checks, and so will be raised as soon as Renovate detects them. ### What happens if a package has multiple updates available? !!! note This is based on the [recommended settings above](#recommended-settings) Renovate waits for the set duration to pass for each **separate** version. If Renovate sees that a package has multiple updates available, it will only raise update(s) that are passing the `minimumReleaseAge` check. Let us consider a repository with `minimumReleaseAge=1 hour`, and with the following timeline: - 0000: Renovate runs, and sees no updates - 0010: Package releases 1.1.0 - 0030: Renovate runs, and sees 1.1.0 and marks it as pending - 0100: Renovate runs, still sees 1.1.0 as pending - 0110: Package releases 1.1.1 - 0130: Renovate runs, and sees 1.1.0 and 1.1.1 releases. As 1.1.0 is now past the `minimumReleaseAge`, Renovate raises a PR, and marks 1.1.1 as pending - 0200: Renovate runs, still sees 1.1.1 as pending - 0230: No humans have merged the PR for 1.1.0, so when Renovate runs, it sees 1.1.1 is now past the `minimumReleaseAge`, so updates the existing PR to bump the version to 1.1.1 ### What happens to transitive dependencies? Renovate does not currently manage any transitive dependencies - instead leaving that to package managers and [`lockFileMaintenance`](../configuration-options.md#lockfilemaintenance). ### How do I opt out dependencies from minimum release age checks? To opt out a dependency from minimum release age checks, create a package rule with `minimumReleaseAge=null`: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": [ // for instance "security:minimumReleaseAgeNpm", ], "packageRules": [ { "description": "Disable minimum release age checks for internal dependencies", "matchPackageNames": ["@super-secret-organisation/*"], "minimumReleaseAge": null, }, ], } ``` !!! note As of Renovate 42.19.5, using `minimumReleaseAge=0 days` is treated the same as `minimumReleaseAge=null`. ### Which datasources support release timestamps? !!! tip You can confirm if your datasource supports the release timestamp by viewing [the documentation for the given datasource](../modules/datasource/index.md). The datasource that Renovate uses must have a release timestamp for the `minimumReleaseAge` config option to work. Some datasources may have a release timestamp, but in a format Renovate does not support. In those cases a feature request needs to be implemented. Note that you will also need to [verify if the registry you’re using](#which-registries-support-release-timestamps) provides the release timestamp. ### Which registries support release timestamps? The below is a non-exhaustive list of public registries which support release timestamps: Datasource Registry URL Supported Notes `crate` `https://crates.io` ✅ `rubygems` `https://rubygems.org` ✅ `docker` `https://index.docker.io` ✅ `docker` (not Docker Hub) ❌ [Issue](https://github.com/renovatebot/renovate/issues/38656) `docker` `https://ghcr.io` ❌ [Issue](https://github.com/renovatebot/renovate/issues/39064) `docker` `https://quay.io` ❌ [Issue](https://github.com/renovatebot/renovate/issues/38572) `github-releases` `https://github.com` ✅ `terraform-module` `https://registry.terraform.io` ✅ `terraform-module` `https://registry.opentofu.org` ✅ Queries `api.opentofu.org` for release timestamps `terraform-provider` `https://registry.terraform.io` ✅ `terraform-provider` `https://registry.opentofu.org` ✅ Queries `api.opentofu.org` for release timestamps `github-tags` `https://github.com` ✅ `go` `https://proxy.golang.org,` ✅ `golang-version` `https://raw.githubusercontent.com/golang/website` ✅ `maven` `https://repo1.maven.org/maven2` ✅ `node-version` `https://nodejs.org/dist` ✅ `npm` `https://registry.npmjs.org` ✅ `nuget` `https://api.nuget.org/v3/index.json` ✅ `pypi` `https://pypi.org/pypi/` ✅ `ruby-version` `https://www.ruby-lang.org` ✅ `jsr` `https://jsr.io` ✅ For packages without explicit timestamps, defaults to 2025-09-18 It is _likely_ that if you are using a public registry (i.e. `registry.npmjs.org`, `repo1.maven.org`, etc) the release timestamp data will be present. We welcome user contributions to this table. If you use a custom registry, for instance as a pull-through cache, [additional configuration may be required](#how-do-i-add-timestamp-data-to-custom-registries). If you are using a custom registry, or unsure about a public registry, you can confirm this using Renovate’s debug logs by looking for the `packageFiles with updates` debug log line, which may contain a `releaseTimestamp` field in dependency updates: `packageFiles with updates` debug log example ``` DEBUG: packageFiles with updates { "baseBranch": "main", "config": { "dockerfile": [ { "deps": [ // NOTE that we're not seeing a release timestamp for this Docker digest { "depName": "ghcr.io/renovatebot/base-image", "packageName": "ghcr.io/renovatebot/base-image", "currentValue": "10.67.5", "currentDigest": "sha256:d67e849707f38e11c8674a59d3fffef1ea6977757f3a65d9d1a3a198bdd160cf", "replaceString": "ghcr.io/renovatebot/base-image:10.67.5@sha256:d67e849707f38e11c8674a59d3fffef1ea6977757f3a65d9d1a3a198bdd160cf", "autoReplaceStringTemplate": "{{depName}}{{#if newValue}}:{{newValue}}{{/if}}{{#if newDigest}}@{{newDigest}}{{/if}}", "datasource": "docker", "depType": "stage", "updates": [ { "bucket": "major", "newVersion": "11.40.5", "newValue": "11.40.5", "newMajor": 11, "newMinor": 40, "newPatch": 5, "updateType": "major", "isBreaking": true, "newDigest": "sha256:81bbc8c8c561f6c4c2d059a5bcdfc95ef837682a41ac45bfbc1380d8d07dc941", "branchName": "renovate/main-ghcr.io-renovatebot-base-image-11.x" } ], } // ... ], "github-actions": [ { "deps": [ // NOTE that we get a release timestamp for this GitHub Action major version bump, as well as the current version's timestamp { "depName": "actions/setup-node", "commitMessageTopic": "{{{depName}}} action", "datasource": "github-tags", "versioning": "docker", "depType": "action", "replaceString": "actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0", "autoReplaceStringTemplate": "{{depName}}@{{#if newDigest}}{{newDigest}}{{#if newValue}} # {{newValue}}{{/if}}{{/if}}{{#unless newDigest}}{{newValue}}{{/unless}}", "currentValue": "v4.4.0", "currentDigest": "49933ea5288caeca8642d1e84afbd3f7d6820020", "updates": [ { "bucket": "major", "newVersion": "v6.0.0", "newValue": "v6.0.0", "newDigest": "2028fbc5c25fe9cf00d9f06a71cc4710d4507903", "releaseTimestamp": "2025-10-14T02:37:06.000Z", "newVersionAgeInDays": 10, "newMajor": 6, "newMinor": 0, "newPatch": 0, "updateType": "major", "isBreaking": true, "libYears": 0.5323368531202435, "branchName": "renovate/main-actions-setup-node-6.x" } ], "packageName": "actions/setup-node", "warnings": [], "sourceUrl": "https://github.com/actions/setup-node", "registryUrl": "https://github.com", "mostRecentTimestamp": "2025-10-14T02:37:06.000Z", "isAbandoned": false, "currentVersion": "v4.4.0", "currentVersionTimestamp": "2025-04-02T19:20:51.000Z", "currentVersionAgeInDays": 204, "isSingleVersion": true, "fixedVersion": "v4.4.0" }, ``` Given a log line such as ☝️ you can also use the following `jq` query to identify any dependencies (or their updates) that are missing the `currentVersionTimestamp` or `releaseTimestamp` fields like so: `jq` query ``` # Code snippet licensed under the Apache-2.0, and co-authored-by: gpt-oss:20b jq ' { # -------- missing currentVersionTimestamp ---------- missingCurrentVersionTimestamps: [ .config | to_entries[] as $ent | $ent.value[] as $group | $group.deps[] as $dep | select($dep.currentVersionTimestamp == null) | { manager: $ent.key, depName: $dep.depName, packageFile: $group.packageFile, datasource: $dep.datasource, registryUrls: ( ($dep.registryUrl? | if . != null then [.] else [] end) + ($dep.registryUrls // []) ) } ], # -------- missing releaseTimestamp in updates ---------- missingReleaseTimestamps: [ .config | to_entries[] as $ent | $ent.value[] as $group | $group.deps[] as $dep | select(any($dep.updates[]?; .releaseTimestamp == null)) | { manager: $ent.key, depName: $dep.depName, packageFile: $group.packageFile, datasource: $dep.datasource, registryUrls: ( ($dep.registryUrl? | if . != null then [.] else [] end) + ($dep.registryUrls // []) ), missingUpdates: [ $dep.updates[]? | select(.releaseTimestamp == null) | . + { dependencyCurrentVersionTimestamp: $dep.currentVersionTimestamp, datasource: $dep.datasource } ] } ] } ' debug-log.txt ``` Will then output: `jq` query output ``` { "missingCurrentVersionTimestamps": [ { "manager": "dockerfile", "datasource": "docker", "depName": "ghcr.io/containerbase/devcontainer", "packageFile": ".devcontainer/Dockerfile", "registryUrls": ["https://ghcr.io"] }, { "manager": "renovate-config", "datasource": null, "depName": "renovatebot/.github", "packageFile": "renovate.json", "registryUrls": [] }, { "manager": "regex", "datasource": "docker", "depName": "ghcr.io/renovatebot/base-image", "packageFile": "lib/config/options/index.ts", "registryUrls": ["https://ghcr.io"] } ], "missingReleaseTimestamps": [ { "manager": "dockerfile", "datasource": "docker", "depName": "ghcr.io/renovatebot/base-image", "packageFile": "tools/docker/Dockerfile", "registryUrls": ["https://ghcr.io"], "missingUpdates": [ { "bucket": "major", "newVersion": "11.40.5", "newValue": "11.40.5", "newMajor": 11, "newMinor": 40, "newPatch": 5, "updateType": "major", "isBreaking": true, "newDigest": "sha256:81bbc8c8c561f6c4c2d059a5bcdfc95ef837682a41ac45bfbc1380d8d07dc941", "branchName": "renovate/main-ghcr.io-renovatebot-base-image-11.x", "dependencyCurrentVersionTimestamp": null, "dependencyDatasource": "docker" } ] }, { "manager": "dockerfile", "datasource": "docker", "depName": "ghcr.io/renovatebot/base-image", "packageFile": "tools/docker/Dockerfile", "registryUrls": ["https://ghcr.io"], "missingUpdates": [ { "bucket": "major", "newVersion": "11.40.5", "newValue": "11.40.5-full", "newMajor": 11, "newMinor": 40, "newPatch": 5, "updateType": "major", "isBreaking": true, "newDigest": "sha256:824737973a79d8c280f8ab1928017780fb936396dc83075a4f7770610eda37bd", "branchName": "renovate/main-ghcr.io-renovatebot-base-image-11.x", "dependencyCurrentVersionTimestamp": null, "dependencyDatasource": "docker" } ] }, { "manager": "dockerfile", "datasource": "docker", "depName": "ghcr.io/renovatebot/base-image", "packageFile": "tools/docker/Dockerfile", "registryUrls": ["https://ghcr.io"], "missingUpdates": [ { "bucket": "major", "newVersion": "11.40.5", "newValue": "11.40.5", "newMajor": 11, "newMinor": 40, "newPatch": 5, "updateType": "major", "isBreaking": true, "newDigest": "sha256:81bbc8c8c561f6c4c2d059a5bcdfc95ef837682a41ac45bfbc1380d8d07dc941", "branchName": "renovate/main-ghcr.io-renovatebot-base-image-11.x", "dependencyCurrentVersionTimestamp": null, "dependencyDatasource": "docker" } ] } ] } ``` Notice that this indicates that: - There are 3 dependencies that do not have a release timestamp, across different Managers and Datasources - There are 3 dependency updates, where neither the dependency nor the dependency update itself have a release timestamp ### How do I add timestamp data to custom registries? Renovate [requires release timestamp to be provided by the registry](#where-does-the-release-timestamp-need-to-be-set). A common solution is to point Renovate to a registry that _does_ have the release timestamp in the form that Renovate is expecting. You can achieve this by using `packageRules` to **prepend** the public registry’s URL to the `registryUrls`. You can see exact examples below: #### Maven datasource For `minimumReleaseAge` to work, the Maven source must return reliable `last-modified` headers. If your custom Maven source registry is **pull-through** and does _not_ support the `last-modified` header, like GAR (Google Artifact Registry’s Maven implementation) then you can extend the Maven source registry URL with `https://repo1.maven.org/maven2` as the first item. Then the `currentVersionTimestamp` via `last-modified` will be taken from Maven central for public dependencies. ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "packageRules": [ { "matchDatasources": ["maven"], "registryUrls": [ "https://repo1.maven.org/maven2", "https://europe-maven.pkg.dev/org-artifacts/maven-virtual" ] } ] } ``` #### Pypi datasource ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "packageRules": [ { "matchDatasources": ["pypi"], "registryUrls": [ "https://pypi.org/pypi/", "https://custom-registry.example.com/pypi/some-repo/simple/" ] } ] } ``` ## [Presets](https://docharvest.github.io/docs/renovate/usage/key-concepts/presets/) Contents renovate Presets Renovate Learn about Renovate configuration presets Renovate presets are reusable bits of configuration, stored in JSON, JSON5 or JSONC format. Presets that are included with Renovate are referenced by their name, like [`:dependencyDashboard`](../presets-default.md#dependencydashboard) and [`security:minimumReleaseAgeNpm`](../presets-security.md#securityminimumreleaseagenpm). Custom presets are referenced by repository location. To learn how to create and host them, read the [Shareable Config Presets](../config-presets.md) page. ## Why you should use presets Use presets to: - Set up the bot with good default settings - Avoid duplicating your configuration - Share your configuration with others - Use somebody else’s configuration as-is, or extend it with your own rules ## How to use presets Say you’re using the `config:recommended` preset, and want to pin your GitHub Action digests. Instead of writing your own Renovate config, you search the docs, and find the `helpers:pinGitHubActionDigests` preset. Then you add the preset to the `"extends"` array in your Renovate configuration file: ``` { "extends": ["config:recommended", "helpers:pinGitHubActionDigests"] } ``` In the example above, Renovate follows the rules from the `config:recommended` preset, plus the rules for `helpers:pinGitHubActionDigests`. !!! tip If there is a logical conflict between presets, then the _last_ preset in the `"extends"` array “wins”. ## Managing config for many repositories If you manage the Renovate configuration for many repositories, we recommend that you: 1. Create a global preset configuration 2. Extend from the global preset in all of the repositories that should use your global preset as base This way, when you want to change your global Renovate configuration, you only need to edit the global preset file. ## Presets are modular Preset configs are modular: a preset can be as small or large as you need. A preset can even extend from _other_ presets. ## Built-in presets Renovate comes with many built-in presets. We recommend you browse [Renovate’s default presets](../presets-default.md). Again, to use the preset: add it to the `"extends"` array in your Renovate config file. ### Contributing a new built-in preset If you have a Renovate config that may help others, you can put it into Renovate’s built-in presets. Read [Contributing to presets](../config-presets.md#contributing-to-presets) to learn how. ## Summary In short: - Browse [Renovate’s default presets](../presets-default.md), or our other presets, to find helpful presets - Use presets by putting them in the `"extends"` array in your Renovate config file - To manage the Renovate configuration for many repositories at once, create a global preset config file - The order of presets matters: in a logical conflict, the last preset in the `"extends"` array “wins” ## [Pull requests](https://docharvest.github.io/docs/renovate/usage/key-concepts/pull-requests/) Contents renovate Pull requests Renovate Learn about Renovate pull requests This page describes how Renovate pull requests work. ## How Renovate finds existing PRs Renovate does not need to maintain any database/state about open or closed Pull Requests. Instead, it uses the code platform’s APIs to search and find such PRs. Renovate finds existing PRs (open or closed) by matching both: - the branch name, for example: `renovate/lodash-4.x`, - _and_ the Pull Request title, for example: `Update lodash to v4.17.21` In cases like the above, there is typically one existing PR with a matching branch name and PR title. But if you group PRs and use titles like “All non-major updates”, then multiple past PRs may match. ## Normal PRs As explained above, Renovate PRs normally have some “uniqueness” in their title relating to the version in the upgrade. When you close a “unique” PR, Renovate assumes you don’t want to see that PR again in future, for example: 1. You ignored `lodash@4.17.21` by closing Renovate’s PR 2. Renovate assumes you don’t want any updates to `4.17.21` of `lodash` 3. Renovate creates a new PR when the branch + title “uniqueness” exists again, like when `lodash@4.17.22` releases Renovate behaves similarly for `major` updates, for example: 1. You ignored a `major` update for Lodash (pr title: “Update lodash to v4”) by closing Renovate’s PR 2. Renovate assumes you don’t want any updates to `v4` of `lodash` 3. Renovate won’t create any update PRs for `v4` of `lodash`, even if there are newer versions of `v4` ## Immortal PRs Some Renovate pull requests have a section like this: > 👻 **Immortal:** This PR will be recreated if closed unmerged. Get [config help](https://github.com/renovatebot/renovate/discussions) if that’s undesired. An **immortal** PR keeps popping up again after you close it. This document explains why we have immortal PRs, and how you can fix them. ### Why we have immortal PRs First off, we don’t have immortal PRs for some philosophical reason like: “don’t ignore this update, it’s good for you!”. We have no good way to ignore some PRs after they’re closed. #### Branch name and PR title are cache keys Renovate uses the branch name and PR title like a cache key. If the same key exists _and_ the PR was closed, then we ignore the PR. ##### Cache keys can cause problems Let’s say you have an “All non-major updates” PR. If you close the PR, and Renovate ignores it based on the PR title, then you would never get a non-major update again. #### Only unique version PRs can be ignored Renovate can only ignore PRs if they have a unique version, like “to v16.1.2” or “to v16” in the title. #### Grouped updates with different versions The problem comes when there are groups of updates which have different versions. Then the update becomes “Update react (major)”, which is not safely ignorable, instead of “Update react to v16”. ### Future plans for immortal PRs In the future we may embed metadata in each PR identifying the exact files and packages + versions that PR contains. Then we could allow such PRs to be closed/ignored but then as soon as there’s any chance to files/packages/versions being updated then we’d be cache busted and create a new PR. If you regularly wish to close immortal PRs, it’s an indication that you may be grouping too widely. ### How to fix immortal PRs Avoid grouping dependencies together which have different versions, or which you have a high chance of wanting to ignore. If you have immortal PRs which you want to keep closed, then set `"recreateWhen": "never"`. #### Major updates require Dependency Dashboard approval Avoid grouping major upgrades together unless they are related dependencies. Instead, set `"dependencyDashboardApproval": true` for major updates so that you have control about when they are created. ## Ignoring PRs Close a Renovate PR to ignore it. !!! note Renovate re-creates any PRs that are marked “immortal”. This means that any immortal PR you close, pops up again the next time Renovate runs. To ignore immortal PRs, follow the advice in the [How to fix immortal PRs](#how-to-fix-immortal-prs) section. ## [Renovate scheduling](https://docharvest.github.io/docs/renovate/usage/key-concepts/scheduling/) Contents renovate Renovate scheduling Renovate Learn how to schedule when Renovate runs This document describes Renovate’s scheduling. ## Default behavior On the backend side, Renovate bot runs as often as its administrator has configured Renovate to run. For example, the administrator configure Renovate to begin its runs hourly, daily, or outside office hours only. How often Renovate runs per-repository subsequently depends on how many repositories there are to check, and how many updates are pending for each repository at the time. If the backend configuration for Renovate means it runs scheduled jobs per-repo approximately every X hours, it is not possible for _repository configuration_ to reduce that to less than X, or to force Renovate to run at exact times on specific repos. ### Default timezone By default, Renovate schedules use the UTC timezone. But you can set your own timezone with the `timezone` config option. ### How long Renovate takes to run when scheduled How often Renovate processes individual repositories depends on: - How often Renovate runs - How many repositories Renovate is onboarded to, in your organization or user account - How much work Renovate must do in each repository The table below shows how the number of dependencies and repositories affect Renovate run times. Dependencies to update Repositories with the dependencies Run time 1 1 Very fast 1 10 Fast 1 100 Slow 50 1 Slow 100 100 Very slow ## Global schedule vs specific schedule At a high level, you have two ways to schedule Renovate, a “global way” and a “specific way”: Way to schedule Renovate What this does Notes Global Decides when Renovate runs. This schedule is usually controlled by your organization’s bot administor. For the Mend Renovate app, Mend decides when Renovate runs. Specific When Renovate runs it checks the schedule to see if it should look for updates to a specific dependency. Usually set in the `renovate.json` config file, or similar config file. Renovate can only update a dependency if _both_ of these conditions are true: - The Renovate program is running (on your hardware, or on Mend’s hardware) - The schedule set in the Renovate config file(s) allows Renovate to look for updates for that dependency ### Managing update frequency Because Renovate defaults to “always on” and “open PRs right away” it can overwhelm you with “new PR” notifications. Use the schedule to control when Renovate looks for updates, for example: - Limit Renovate to check for updates in your repository to once a week. (In your repository’s Renovate config file) - Set update schedules for a package, or group of packages ## Scheduling use cases You can use the scheduling tools to: - Run Renovate outside office hours, to free up continous integration resources for your developers - Get updates for certain packages on a regular interval, instead of right away - Reduce Renovate bot PR notifications during the day ## Customizing the schedule Use the `timezone` and `schedule` configuration options to control when Renovate runs. At a high level you need to follow these steps: 1. Tell Renovate what `timezone` you want to use 2. Learn about the scheduling syntax 3. _Optional_ set an “in-repository schedule” 4. _Optional_ set packageRules with a custom `schedule` for a package, or group of packages ### Setting your timezone By default, Renovate’s schedules use the UTC timezone. If you want Renovate to use your local time, use the `timezone` configuration option. You must use a valid [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)! ``` { "timezone": "America/Los_Angeles" } ``` Also read the [`timezone` config option docs](../configuration-options.md#timezone). ### Scheduling syntax After you’ve set your local timezone, you can set “days of the week” or “hours of the day” in which Renovate is allowed to make changes. #### Recommended cron syntax We recommend you use the `cron` syntax in your Renovate schedules. Description Cron syntax every weekend `* * * * 0,6` before 5:00am `* 0-4 * * *` after 10pm and before 5am every weekday `* 22-23,0-4 * * 1-5` on friday and saturday `* * * * 5,6` every 3 months on the first day of the month `* * 1 */3 *` !!! note For Cron schedules, you _must_ use the `*` wildcard for the minutes value, as Renovate doesn’t support minute granularity. And the cron schedule must have five parts. #### Deprecated breejs/later syntax This section explains the deprecated `@breejs/later` syntax. We plan to remove the `@breejs/later` library in a future major Renovate release if we can find a way to migrate all valid schedules to cron syntax. Due to this upcoming change, we strongly recommend you use `cron` schedules. Renovate uses the [`@breejs/later` library](https://github.com/breejs/later) to parse the text. For Renovate to understand the schedule, you must use valid `@breejs/later` syntax. Read the [@breejs/later parses docs at breejs.github.io](https://breejs.github.io/later/parsers.html#text) for more details. The `@breejs/later` library also controls the interpretation of “days”, time\_before“, and “time\_after” keywords. Valid, but deprecated later syntax Cron syntax every weekend `* * * * 0,6` before 5:00am `* 0-4 * * *` after 10pm and before 5am every weekday `* 22-23,0-4 * * 1-5` on friday and saturday `* * * * 5,6` every 3 months on the first day of the month `* * 1 */3 *` !!! warning Renovate does _not_ support scheduled minutes or “at an exact time” granularity. Granularity must be at least one hour. ### In-repository schedule configuration Important: _when_ the Renovate process runs is usually controlled by the bot admin, using tools such as `cron`. For the Mend Renovate App, the Mend maintainers control when the Renovate process runs, usually hourly. If you control the hardware that Renovate runs on, we recommend you: - Schedule enough time on the hardware for Renovate to process your repositories - Avoid schedules like “Run Renovate for an hour each Sunday” as you _will_ run into problems Some config examples: ``` { "description": "Schedule daily before 4 AM", "schedule": ["* 0-3 * * *"] } ``` ``` { "description": "Schedule during typical non-office hours on weekdays (i.e., 10 PM - 5 AM) and anytime on weekends", "schedule": ["* 0-4,22-23 * * 1-5", "* * * * 0,6"] } ``` #### Schedule presets Renovate has built-in presets for common schedules, like “once a week”, “outside office hours” and so on. Before you create your own custom schedule, check if the [Schedule Presets](../presets-schedule.md) has what you need. The preset schedules only decide when Renovate looks for updates, and do _not_ affect any specific dependencies/packages. ### Schedule when to update specific dependencies With Renovate’s scheduling features you can “limit the noise” from frequently updating dependencies, like the AWS SDK: ``` { "packageRules": [ { "description": "Schedule AWS SDK updates on Sunday nights (9 PM - 12 AM)", "matchPackageNames": ["@aws-sdk/*"], "schedule": ["* 21-23 * * 0"] } ] } ``` Important tips for the `"schedule"` property: - Always use the array syntax `[]`, even if you only set a single schedule - Separate entries with a comma, like this: `["cron for schedule 1", "cron for schedule 2"]` - Multiple entries in the `"schedule"` array are interpreted with the Boolean OR logic Read the [schedule config option](../configuration-options.md#schedule) documentation to learn more. ## [Known limitations](https://docharvest.github.io/docs/renovate/usage/known-limitations/) Contents renovate Known Limitations Renovate Known Limitations Learn about the limitations of Renovate bot. ## Introduction Renovate, like any computer program has limitations. Sometimes these are functionality limitations - perhaps something is impossible or too complex to do, or we simply haven’t implemented it yet. At other times it may be a “performance” limitation, because jobs neither start nor complete instantly, even if the user may start with that expectation. This document tries to list out the most commonly seen limitations and describe whether they’re permanent and if there’s any plans to improving the situation. ## Time/schedule based limitations When a user configures a schedule in their repo config, they may think that this schedule “controls” when Renovate runs. In actuality, Renovate may be running frequently, but skipping updates to the repo if the configured schedule is not met. Additionally, the Renovate admin may have put the bot on its own schedule, or the job queue may be too long, so Renovate doesn’t even get a chance to run on your repository during a certain scheduled time window. For scheduled action to take place, both these need to happen: - The bot needs to run against your repository - The current time needs to fall within your repository’s configured schedule ### The Mend Renovate app and scheduled jobs The Mend Renovate App checks each active repository roughly every three hours, if no activity has been seen before then (merged PRs, etc). For this reason, you should set your schedule window to at least three or four hours. This makes it likely that Renovate bot checks your repository at least once during the schedule. ## Automerge limitations - Renovate automerges at most one branch/PR per run - If an automerge happened, the repository run will be restarted at most once. The second run can also potentially automerge, so it may appear as like two automerges in one run. - Renovate will only automerge a branch when it is up-to-date with the target branch - Renovate may not be able to automerge as many branches as you expect, especially if your base branch is receiving regular commits at the same time The limitation to only merge one branch per run is because Renovate’s dependency and branch state is based on what was present in the base branch at the start of the run. If a branch is merged into the base branch during Renovate’s run - including by other users - it means that remaining Renovate branches may have Git conflicts. It also means that Renovate’s knowledge about dependencies in the base branch is now invalid and other branches may need changing as a result of the merge. The limitation to only automerge branches which are up-to-date is a decision due to this example: - Two dependencies are in use: `alice@1.0.0` and `bob@1.0.0` - PRs exist for `alice@2.0.0` and `bob@2.0.0` and both pass tests - The PR for `alice@2.0.0` is automerged - The PR for `bob@2.0.0` remains open, does not have conflicts, and has all tests passing - But `alice@2.0.0` and `bob@2.0.0` are incompatible so merging the PR without rebasing and retesting it first would result in a broken base branch ## [Language constraints and upgrading](https://docharvest.github.io/docs/renovate/usage/language-constraints-and-upgrading/) Contents renovate Language Constraints And Upgrading Renovate Language Constraints And Upgrading ## Package releases have language constraints Many ecosystems have the concept where each release of a package has its own language “constraint”. For example, a npm package may support Node.js 18 and 20 in its `v1` releases and Node.js 20 and 22 from `v2.0.0` onwards. In an ideal scenario: - Package files allow a project to show its supported language constraints, and - Package registries allow packages to show the supported language constraints per release ## Restricting upgrades to compatible releases By default Renovate _does not_ apply language constraints to upgrades. This means Renovate will propose “any” stable upgrade. Renovate will _not_ check if the language version you’re using actually supports that upgrade. In certain ecosystems, changes to language constraints are made with a major release, and are documented in the release notes. So Renovate’s default behavior may be okay in those ecosystems. For other ecosystems Renovate’s default behavior may seem _wrong_. As a Renovate user, you can opt into strict compatibility filtering by setting `constraintsFiltering=strict`. Before you set `constraintsFiltering=strict`, you should: - understand the limitations of this setting - understand why `constraintsFiltering=strict` is _not_ the default behavior Please keep reading to learn more. ## Language constraint updating The first challenge is that Renovate may not yet support the ability to update your language constraints in an automated manner, and even when it does, users may not understand how many updates are depending on it. For example: a Node.js project has set its `engines` field to `"node": "^18.0.0 || ^20.0.0"`. Should Renovate _skip_ Node.js `v21` because it is a non-LTS release? When Node.js `v22` releases, should Renovate add it to your `engines`, or wait until `v22` becomes the LTS version? When Node.js `v18` is EOL, should Renovate drop it from the `engines` field? Renovate can not guess what users want. Users have strong and different opinions on what Renovate should do for each example listed above. Also, even _if_ Renovate guesses right or adds advanced capabilities to allow this to be configurable: users might still wait on any of these “major” upgrades for months. If a project waits to create or merge the update to drop Node.js `v18` from `engines`, then they can _not_ upgrade to any new versions of library dependencies. Those library dependencies may have dropped support for Node.js `v18` already. ## Strict filtering limitations Let’s go back to the Node.js project which has its `engines` field set to `"node": "^18.0.0 || ^20.0.0"`. Now also consider a library which sets its `engines` field to `"node": "^18.12.0 || ^20.9.0"` because the library only supports “LTS releases” of Node.js. Strictly speaking, this library is _not_ compatible with the project above, because the project has _wider requirements_ for their Node versions. This means Renovate holds back any upgrades for it. Should Renovate somehow “think” and _assume_ that this narrower `engines` support is actually OK? What if the project _already_ used a current version of this library “in a way that’s not officially supported”? A second problem is that if: - Renovate can _not_ update the language constraints, or - a user _ignores_ or does not see the language upgrade Then the user may not know that many dependencies are out of date, because Renovate is not creating PRs. For example: a project may have 10 dependencies, and 8 of those have updates. But all 8 dependencies need the project to update its language constraints _first_. The project administrator thinks they are up to date, because Renovate is not creating PRs, but 80% of their dependencies are outdated. In short, users who set `constraintsFiltering=strict` often do not understand how _strict_ that setting is and how many releases it will _filter out_. ## Transitive constraint limitations Often a library sets language constraints (like the `engines` examples above), and then depend on libraries with _narrower_ constraints, like `"node": "^20.0.0"`. In cases like these, Renovate “trusts” the declaration of the library and may create a update, even _with_ strict constraints filtering. For some package managers, like `npm`, this incompatibility will _not_ be detected or warned about (even during lock file generation), but this may not be a problem for your application. Other package managers, like Poetry, may detect and warn about incompatible language constraints during lock file generation, which Renovate reports as an “Artifacts update error”. ## Applying constraints through config You can set language constraints in the Renovate config. For example: ``` { "constraints": { "node": "^18.0.0 || >=20.0.0" } } ``` You may need to set constraints in the Renovate config when: - The package manager of the project does not support constraints declarations, or - The project has not declared any constraints, or - You want Renovate to use _different_ constraints to what’s declared in the _project_ Renovate will _not_ create “update” PRs to update any of these versions once they become outdated, so you must update those by hand. For this reason, setting constraints manually in the Renovate config is _undesirable_. We prefer to fix problems in Renovate itself, instead of you setting constraints. ## Future Work Please start, or join, a GitHub Discussion if you are interested in this topic. Subtopics include: - Improving language constraints update automation in package files - Improving versioning calculations of “subset” (is range A a subset of range B) ## [Logo and brand guidelines](https://docharvest.github.io/docs/renovate/usage/logo-brand-guidelines/) Contents renovate Logo Brand Guidelines Renovate Logo Brand Guidelines This page explains how you may use the Renovate name, logo and branding. ## Do not pretend to be the real Renovate app Avoid using our name, logo, or branding in a way that causes people to think you are the real Renovate app on a public platform. For example: do _not_ call your self-hosted version something like @realrenovatebot on GitHub. ## Do not pretend to be a Renovate developer Avoid using our name, logo, or branding in a way that causes people to think you are a developer of Renovate. ## Allowed uses of the Renovate name You are allowed to use the Renovate name: - to refer to the official Renovate app - as a nickname/shorthand, in contexts where it is clear you are referring to your self-hosted version ## Allowed uses of the Renovate logo You are allowed to use our logo as: - an icon in your repository readme, that says you are using Renovate - part of a badge in your repository readme, that says you are using Renovate - an avatar image for your self-hosted version of Renovate, but give your bot a _different_ name ## Allowed uses of the Renovate branding Do not use our banner images. ## We keep the rights to our logo, name, and branding You may only use our logo, name and branding as described in this guideline. We keep the rights to our logo, name and branding. ## [Using secrets with Mend cloud Apps](https://docharvest.github.io/docs/renovate/usage/mend-hosted/credentials/) Contents renovate Credentials Renovate Credentials The information on this page is for the Mend-hosted cloud apps: - Renovate App on GitHub - Mend App on Bitbucket - Mend App on Azure DevOps If you self-host, you can skip reading this page. ## :warning: Migrate secrets in your Renovate config file :warning: The Mend Renovate cloud apps no longer read `encrypted` secrets from Renovate config files in your repositories. You must migrate any secrets you currently keep in a Renovate config file, and upload them as secrets to org or repo settings pages on [developer.mend.io](https://developer.mend.io). To add secrets you must have admin-level rights. Read [Migrating encrypted secrets from Repo Config to App Settings](migrating-secrets.md) to learn more. ## Managing secrets via the Web UI This section explains how to manage secrets for the Mend-hosted cloud apps via the Web UI. Only administrators of an Org or Repo can manage the secrets for that Org or Repo. ### Adding a secret through the UI To add a secret for the Mend cloud app: 1. Go to the web UI at [developer.mend.io](https://developer.mend.io). 2. Open your organization/repository settings. 3. Put the secret in the _Credentials_ section: 4. Reference the secret from Renovate config files inside the repo. Alternatively, you can use the Host Rules UI (see below). ``` { "hostRules": [ { "matchHost": "github.com", "token": "{{ secrets.MY_ORG_SECRET }}" } ] } ``` ### Adding a host rule through the UI You can centrally add/configure Host Rules through the Mend UI as an alternative to including them in Renovate presets. 1. Open the _Credentials_ section of the settings page for the relevant Org or Repo. 2. Select `ADD HOST RULE` to open the “Add a Host Rule” dialog box. 3. Fill out the details for your host rule. As an example, if you are a Bitbucket or Azure DevOps user, and you want to specify a github.com token to fetch release notes and enable github-based datasources, you could create a host rule like this: ## Organization secrets vs repository secrets ### Secret scope Secrets can be scoped to your organization _or_ to your repository: Secret scoped to your What will happen? Organization Secrets are inherited by all repositories in your organization Repository Secrets are referenced by that repository only ### Make changes on the right page The web UI has _two_ settings pages. One page is for the organization, and the other page is for the repository. Make sure you’re making the changes on the right page! ### Example The screenshot shows inherited organization secrets and specific repository secrets. ### Managing organization-level secrets The **Installed Repositories** table means you are on your organization’s page. Select the _Settings_ button to manage your organization secrets: ### Managing repository-level secrets The **Recent jobs** table means you are on your repository’s page. Select the _Settings_ button to manage your repository secrets: ## Automating secrets via APIs (GitHub only) Administrators of GitHub organizations and repositories can use the Developer Platform APIs to manage secrets. See the [Developer Platform API documentation](https://api-docs.mend.io/developer-platform/1.0/repo-secret) for details. ### Authenticating the APIs Calls to the APIs require authentication with a personal access token from the GitHub user making the request. The token must be included in the request header as the `authorization` property. You can use a [classic token](https://github.com/settings/tokens) or a [fine-grained token](https://github.com/settings/personal-access-tokens). Mend recommends the use of fine-grained tokens for enhanced security. #### Scopes and permissions for tokens No additional scopes or permissions need to be added when calling APIs on _public_ repositories. When calling APIs on _private_ repositories, the following scopes and permissions are required: - Classic tokens require `repo` scope (Full control of private repositories) - Fine-grained tokens must set the “Resource owner” as the org that the API is being called on, and must have a minimum of `metadata:read-only` permission on the selected repositories. ##### Fine-grained token example To create a fine-grained token for the APIs, follow these steps: - Provide a name for the token in the “Token name” field. - \[Optional\] Provide a description for the token. - Set the “Resource owner” to be the User or Org for the APIs that will be called. - Choose an expiry date in the “Expiration” field. - Choose the “Repository access” setting. If using APIs to update secrets on a private-repository, choose “All repositories” or “Only selected repositories”. - In the “Permissions” section, add permissions for “Metadata” (read-only). ## Known Issues ### Error deleting host rule from Developer Portal Problem: When deleting a host rule from the Developer Portal, an error is shown “Error deleting host rule”. Workaround: Update the host rule to point to a valid host that you are not using in your repo. This way, the host rule will have no effect. ## [Frequently Asked Questions](https://docharvest.github.io/docs/renovate/usage/mend-hosted/faq/) Contents renovate Faq Renovate Faq ## I’m hitting a `timeout` / `kernel-out-of-memory` limit with a `pnpm`/`yarn` project If you’re seeing that your jobs are regularly hitting a `timeout` / `kernel-out-of-memory`, this might be due to a package manager trying to update a large set of dependencies. On Mend-hosted apps, it is recommended to use the repo-level configuration, [`toolSettings.nodeMaxMemory`](../configuration-options.md#toolsettingsnodemaxmemory), to tune the maximum memory available for the `pnpm`/`yarn` commands to use this. Mend-hosted apps don’t set a maximum allowed `nodeMaxMemory`, so you can use [the upper limit of memory from your plan](./overview.md#resources-and-scheduling) as the maximum limit. It is recommended to set this between 1.5GB and 2.5GB but may require tweaking according to your repository. !!! note It is at the discretion of Mend to raise the memory limit for repositories, in a similar way to how [there are increased resources for Open Source projects on Renovate Cloud](https://github.com/renovatebot/renovate/discussions/33617). ## What IP Addresses are used by Mend Renovate Cloud? If you are looking at restricting access to your source code via IP allowlisting, you will need to know which public IPs Mend’s Developer Platform accesses from. These can be found documented [on the Mend docs site](https://docs.mend.io/platform/latest/ip-addresses-used-by-mend-io) under the `developer-platform` section. - the `us` grouping is for [`developer.mend.io`](https://developer.mend.io/) - the `eu` grouping is for [`developer-eu.mend.io/`](https://developer-eu.mend.io/) ## [Purpose of github.com Token](https://docharvest.github.io/docs/renovate/usage/mend-hosted/github-com-token/) Contents renovate Github Com Token Renovate Github Com Token Users of Mend’s Renovate apps on Bitbucket Cloud and Azure DevOps need to provide a github.com token to retrieve release notes and changelogs, plus some package files. If github.com credentials are not provided, Renovate will continue to run, but with the following limitations: - release notes and changelogs will be disabled in Renovate pull requests - lookups for packages hosted on github.com may fail due to rate limiting ## Do I need to provide a github.com token? ### github.com (Cloud) users If your repositories are hosted on github.com (Cloud) and you are using the Renovate App on GitHub, you do not need to provide a token for github.com because the Renovate App already has access to GitHub. ### Bitbucket and Azure DevOps users If your repositories are hosted on Bitbucket or Azure DevOps, you will need to provide a github.com token if you want your Renovate PRs to contain release notes and changelogs, or if you want updates on packages that live exclusively on github.com. If the github.com token is not provided, a warning will be shown in the Developer Portal and in the Dependency Dashboard. ## How to provide a github.com token Renovate will accept a github.com token from any GitHub user. The token requires no special access or permissions. ### Step 1: Acquire a github.com token 1. Log in to github.com (any user) 2. Navigate to [Personal access tokens](https://github.com/settings/tokens) in Developer settings 3. Choose `Generate new token` (either fine-grained or classic) 4. Provide a `Token name` (fine-grained) or `Note` (optional for classic token) 5. Choose the expiration date. (No additional scopes or repository permissions are required.) 6. Press `Generate token` 7. Copy the token when it is presented on the screen > \[!IMPORTANT\] > > Make sure to copy your personal access token now as you will not be able to see this again. ### Step 2: Add the token to the Org/Repo credentials Use the token generated in the previous step to provide a secret and host rule for the Org or Repos. > \[!NOTE\] > > If a github.com token is added to the settings for an Org, Workspace or Project, the token will be inherited by all of its child repositories. 1. Log in to [Developer Portal](https://developer.mend.io/) 2. Navigate to the Settings for an Org/Workspace/Project or a Repo 3. Go to the `Credentials` settings page 4. Choose `ADD SECRET` and create a secret to store the token - Provide a `Secret Name` (e.g. `GITHUB_TOKEN`) - Store the github.com token in the `Secret Value` 5. Choose `ADD HOST RULE` and create a host rule for `github` - Select host type `github` - Select Secret Type as `Token` - Select the github.com token as the secret For more information about providing Secrets and Host Rules in the Developer Portal UI, see the documentation for [Credentials](credentials.md). ## [Mend-hosted Apps Configuration](https://docharvest.github.io/docs/renovate/usage/mend-hosted/hosted-apps-config/) Contents renovate Hosted Apps Config Renovate Hosted Apps Config This page: - covers all non-default Renovate behavior of these Mend-hosted apps - is a supplement to the CLI documentation !!! note For general configuration of the Renovate CLI, read the main [Configuration/Overview](../config-overview.md) section. ## Finding the logs The Renovate logs for the Mend-hosted apps are on the [Mend Developer Portal](https://developer.mend.io). Reading the logs can help you understand the configuration that Renovate used. ## Renovate Version The Renovate version used by the Mend-hosted apps is updated manually by the maintainers of the app. The maintainers don’t follow any release schedule or release cadence, but try to update at least once a week. This means the Mend Renovate App can lag a few hours to a week behind the open source version. Major releases of Renovate are held back until the maintainers are reasonably certain it works for most users. ### Which version is the Mend Renovate app using? Follow these steps to see which version the Mend Renovate app used for a specific job: 1. Sign in to the [Mend Developer Portal](https://developer.mend.io/) with your GitHub or Bitbucket account 2. Select your organization 3. Select a installed repository 4. Select a job from the _Recent jobs_ overview 5. Select the _Info_ Log Level from the dropdown menu 6. You should see something like this: ``` INFO: Renovate started { "renovateVersion": "43.246.1" } ... INFO: Repository started { "renovateVersion": "43.246.1" } ``` !!! tip The PRs that Renovate creates have a link to the “repository job log” in the footer of the PR body text. ## Onboarding behavior ### Installing Renovate into all repositories leads to silent mode If an Organization installed Renovate with “All repositories” (instead of “Selected repositories”), then Renovate defaults to “Silent” mode (`dryRun=lookup`). We chose this behavior because: - Too often an account or org administrator selects the “All repositories” option and accidentally onboards hundreds of repositories, and - By offering this option, it means that org administrators _can_ install Renovate into “All repositories” without worrying about the noise, and let individual repository admins decide if/when to start onboarding #### Why we call this silent mode - It’s not just no PRs, it’s also no Issues - It’s a common term across other Mend capabilities, such as OSS security and SAST security, where status checks also use silent/non-silent ### Get onboarding PRs from Renovate by getting out of silent mode If Renovate is installed, _and_ you can see a job log, but Renovate is _not_ onboarding your repository: look for `dryRun` in the logs to confirm you are in Silent mode. To get a onboarding PR from Renovate, change to Interactive mode either at the Repository level or Organization level. ### Installing Renovate into selected repositories always leads to onboarding PRs Additionally, if an Organization is installed with “Selected repositories” then the app will change `onboardingNoDeps` to `"enabled"`. This change causes Renovate to create an Onboarding PR, even if Renovate does not detect any dependencies. ## Fork Processing If an Organization installs Renovate with the “All repositories” option, then `forkProcessing` will remain set to its default value `disabled`. This means forked repositories are _not_ onboarded, Renovate ignores them. To change this behavior, push a `renovate.json` file to the repository with `"forkProcessing": "enabled"`. If an Organization installs Renovate with “Selected repositories”, we assume the organization wants to onboard _all_ of the selected repositories, even forked repositories. Therefore we set `forkProcessing` to “enabled”. ## Inherited config The Mend Renovate app automatically applies inherited config to all installed repositories in an organization, if these conditions are met: 1. A repository called `renovate-config` exists in the same organization, and the organization has installed the Mend Renovate app. The repository does not need to be onboarded 2. Renovate finds a file called `org-inherited-config.json` in the `renovate-config` repository If you use a Mend-hosted app, you can _not_ change the values for the `inheritConfigFileName` and the `inheritConfigRepoName` config options. To avoid wasted API calls, Mend apps will enable `inheritConfig` in an org only when Renovate detects a commit for the `inheritConfig` file. This means the `inheritConfig` file will not be detected if the Mend Renovate app is not installed on the `renovate-config` repository at the time of adding or changing the file. If you have such a file but the Mend app has not enabled `inheritConfig` in your org, try pushing a commit to that file and wait a minute to see if Renovate detects the change. ## Default presets The Mend Renovate app automatically adds the `mergeConfidence:all-badges` preset to the `extends` array. If you do not want the Merge Confidence badges: add the `mergeConfidence:all-badges` preset to the `ignorePresets` array. Additionally, the preset `config:recommended` is added to `onboardingConfig`. ## Allowed Post-upgrade commands A limited set of approved `postUpgradeTasks` commands are allowed in the app. The commands are not documented, as they may change over time. You can find the allowed `postUpgradeTasks` commands in Renovate’s log output, when searching for a log line which references [`allowedCommands`](../self-hosted-configuration.md#allowedcommands). ## Validating configuration As noted in [Validation of Renovate config change PRs](../config-validation.md#validation-of-renovate-config-change-prs), Renovate will automagically validate your configuration changes when pushing to the “reconfigure” branch. !!! tip When using a Mend-hosted app, the “reconfigure” branch defaults to `renovate/reconfigure`. When pushing to this specific branch name, Renovate will run its validation and report a status check to the Platform whether this passes/fails validation. !!! note The reconfigure branch **must** be pushed to the source repository that Renovate runs against, not a fork. If you have a Pull Request open from this branch (including draft PRs), Renovate will comment on the PR to note: - If there are any failures, and if so, what’s wrong - If the configuration passed validation, and if so, what the new configuration will do [For example](https://github.com/JamieTanna-Mend-testing/mend-reconfigure/pull/2), when failing validation: { loading=lazy } And when the PR then passes validation: { loading=lazy } ## [Job Scheduling & Renovate Status](https://docharvest.github.io/docs/renovate/usage/mend-hosted/job-scheduling/) Contents renovate Job Scheduling Renovate Job Scheduling Mend Renovate Cloud will automatically schedule Renovate jobs to be run on installed repos. When the scheduler runs, selected repositories are added to the Job Queue, and eventually executed by the job runners. ## Job Schedulers There are four types of job schedulers, each with a different frequency and selection of repositories. Job Scheduler Frequency Renovate statuses Active jobs 4-hourly1 new, activated Inactive jobs Daily onboarded, onboarding, silent, failed Blocked Weekly timeout, resource-limit, kernel-out-of-memory, unknown All repos Monthly All installed repos (including disabled) (1) Renovate Enterprise jobs are scheduled every hour for repositories on GitHub and Azure DevOps. ## Renovate Status Each repository installed with Renovate Cloud has a Renovate Status. The Renovate Status is used by the job scheduler to determine which repositories will be selected. The status appears in the list of repositories shown on the Org page of the Developer Portal. The table below describes all the Renovate statuses. Renovate Status Description Schedule <-blank-> New repo. Renovate has never run on this repo. Hourly onboarding Onboarding PR has not been merged Daily onboarded Onboarding PR has been merged. No Renovate PRs merged Daily activated At least one Renovate PR has been merged Hourly silent Renovate will run, but not deliver PRs or issues Daily failed An error occurred while running the last job Daily timeout A timeout occurred while running the last job Weekly kernel-out-of-memory An OOM error occurred while running the last job Weekly resource-limit A resource limit was hit while running the last job Weekly unknown An unknown error occurred while running the last job Weekly disabled Renovate will not run on this repository Monthly ``` flowchart TD A[Installed Repository] --> B{Renovate Status} B -->|new| C[Active jobs
4-hourly #40;1#41;] B -->|activated| C B -->|onboarded| D[Inactive jobs
Daily] B -->|onboarding| D B -->|silent| D B -->|failed| D B -->|timeout| E[Blocked jobs
Weekly] B -->|resource-limit| E B -->|kernel-out-of-memory| E B -->|unknown| E B -->|disabled| F[All repos
Monthly] C --> G[Job Queue] D --> G E --> G F --> G G --> H[Job Runner] ``` 1 Renovate Enterprise jobs are scheduled every hour for repositories on GitHub and Azure DevOps. ## [Migrating Secrets from Repo Config to App Settings](https://docharvest.github.io/docs/renovate/usage/mend-hosted/migrating-secrets/) Contents renovate Migrating Secrets Renovate Migrating Secrets The Mend Renovate Cloud apps no longer read encrypted secrets from Renovate config files in your repositories. Previously, you could encrypt a secret with the [Renovate encryption tool](https://app.renovatebot.com/encrypt) and then put it in your Renovate config file. When using the Mend Renovate Cloud apps, all secrets must be stored in the App settings on the cloud. The secrets can be referenced from the Renovate config files inside the repo using `{{ secrets.SECRET_NAME }}` notation. ## Old method This method is deprecated: ``` { "hostRules": [ { "matchHost": "github.com", "encrypted": { "token": "drsMDVf6M2hTZCN......+gQm/0Rpw" } } ] } ``` ## New method This is the new method that you should start using: ``` { "hostRules": [ { "matchHost": "github.com", "token": "{{ secrets.GITHUB_COM_TOKEN }}" } ] } ``` ## Tips ### Do not change the secret during migration Mend recommends that you do _not_ change the secret during the migration, as this introduces an extra point of failure. After the migration you can of course change/rotate the secret. ### Migrate your secrets in the raw form (plain text) When migrating secrets, DO NOT migrate the encrypted form of the secret. You must input the secret in the web UI from plain text. (The web UI will store the value securely.) If you do not have the original plain text form of the secret being migrated, you will need to create a new secret. ## How to migrate secrets ### Use Plain text values - not encrypted values You must Migrate encrypted secrets using the PLAIN TEXT value. You can not use the encrypted version of the secret. ### Add the secret to the correct Org or Repo When you migrate a secret from a repository, make sure you are adding the secret to the _same_ organization or repository for which you generated the secret! - A secret generated for a specific repository can only be added to that _same_ repository. - A secret generated for a specific repository can only be added to the repository settings for the matching repository. This secret can _not_ be added to the organization’s settings. - A secret generated without a specific repository _can_ be added into the organization _or_ into the repository settings under that organization. ### Steps to migrate a secret to the Renovate Cloud App 1. Go to the correct settings page for your organization or repository in the web UI at [developer.mend.io](https://developer.mend.io). 2. On the **Credentials** page, select `ADD SECRET` to add the plaintext secret. 3. Give a value for `Secret name`, paste the plaintext secret into the `Secret Value` field, and select `SAVE`. 4. Wait for the confirmation dialog: **“Successfully stored secret”**. ### Using the API The [Mend Developer Platform has an API](https://api-docs.mend.io/developer-platform/1.0), allowing programmatic management of repo secrets and org secrets. ## Troubleshooting ### Secret is stored successfully, but it doesn’t work when used in the app The secret might be wrong. Try uploading the secret again. - Ensure that the PLAIN TEXT value of the secret is used - not the encrypted value. - Ensure that the secret was uploaded to the correct Org or Repo. ## Related links - [Using Secrets with Mend Cloud Apps](credentials.md) - [Mend Developer Platform API (1.0)](https://api-docs.mend.io/developer-platform/1.0) ## [Mend Renovate Cloud-hosted (Community and Enterprise)](https://docharvest.github.io/docs/renovate/usage/mend-hosted/overview/) Contents renovate Overview Renovate Overview Mend provides cloud hosting services for running Renovate in free and paid versions: - Mend Renovate Community Cloud (Free) - Mend Renovate Enterprise Cloud (Paid) They are available for Git repositories hosted on the following cloud platforms: - GitHub - Bitbucket Cloud - Azure DevOps Mend Renovate cloud will regularly schedule Renovate jobs against all installed repositories. It also listens to webhooks and enqueues a Renovate job when relevant changes occur in a repo, or when actions are triggered from the Renovate PRs or Dashboard issue. There is a web UI with functionality to view and interact with installed repositories, their jobs and job logs. ## Getting started To get started using Mend Renovate Cloud versions, access the Developer Portal at [https://developer.mend.io/](https://developer.mend.io/). Developers can log in using the OAuth credentials from their cloud-based Git repository. Features of the Developer Portal include: - Ability to install, uninstall and view installed repositories - Trigger Renovate jobs to run on demand - View logs for all Renovate jobs - Configure settings that apply at the Org-level or Repo-level ## Plans ### Mend Renovate Community Cloud A generous free tier, available for all across an unlimited number of public and private repositories. ### Mend Renovate Community (OSS) Cloud As part of Mend’s commitment to support the Open Source community, we provide an enhanced free offering for maintainers of the projects the ecosystem rely upon. This offering provides increased resources and concurrency, as well as access to [Merge Confidence Workflows](../merge-confidence.md#merge-confidence-workflows) to allow maintainers to more intelligently receive updates based on signals Mend collects from other projects. Projects licensed under an Open Source Initiative (OSI) approved license can request increased resources on Mend Renovate Cloud under the Community (OSS) plan. !!! tip To request increased resources, create a [Mend Hosted Request](https://github.com/renovatebot/renovate/discussions/new?category=mend-hosted-request) on the Renovate GitHub Discussions board. Acceptance is at the discretion of Mend. ### Mend Renovate Enterprise Cloud Mend’s premium offering for our Cloud product, with support, enhanced scalability and scheduling, and access to [Merge Confidence Workflows](../merge-confidence.md#merge-confidence-workflows). Contact Mend at [sales@mend.io](mailto:sales@mend.io) for purchase details. ### Resources and Scheduling The resources, scheduling and concurrency of Renovate jobs is determined by the Mend Renovate plan used by the Org, which can be seen below: Mend Renovate Community Cloud Mend Renovate Community (OSS) Cloud Mend Renovate Enterprise Cloud Concurrent jobs per Org 1 2 16 Job scheduling (active repos) Every 4 hours Every 4 hours Hourly1 Job runner CPUs 1 vCPU 2 vCPU 2 vCPU Job runner Memory 3GB 6GB 8GB Job runner Disk space 15GB 25GB 40GB Job timeout 30 minutes 60 minutes 60 minutes Merge Confidence Workflows ❌ Not included ✅ Included ✅ Included Mend.io Helpdesk Support ❌ Not included ❌ Not included ✅ Included 1 Bitbucket repositories running Mend Renovate Enterprise are scheduled to run every 4 hours, to avoid hitting rate limits on GitHub APIs. ## [Merge Confidence](https://docharvest.github.io/docs/renovate/usage/merge-confidence/) Contents renovate Merge Confidence Renovate Merge Confidence Look at the Merge Confidence badges before merging to: - Prevent updates which break in production - See at a glance if you should update Merge Confidence finds and flags undeclared breaking releases. It analyzes test and release adoption data from the Mend Renovate App users. ## Pull request badges Merge Confidence adds the following badges to your pull requests: - **Age**: The age of the package - **Adoption**: The percentage of this package’s users (within Renovate) which are using this release - **Passing**: The percentage of updates which have passing tests for this package - **Confidence**: The confidence level for this update ## Supported platforms Merge Confidence badges for pull requests are available on any supported platform or Renovate distribution, including Mend Remediate. ## Supported languages Renovate will show Merge Confidence badges for these languages: Language Datasource Golang `go` JavaScript `npm` Java `maven` Python `pypi` .NET `nuget` PHP `packagist` Ruby `rubygems` We plan to support more languages soon. ## Enabling and disabling If you use the Mend Renovate App then the badges are enabled automatically. If you’re self-hosting Renovate, you can enable the badges by adding the `mergeConfidence:all-badges` preset to the `extends` array in your Renovate config: ``` { "extends": ["mergeConfidence:all-badges"] } ``` !!! note The `mergeConfidence:age-confidence-badges` preset can be used to only show the Age and Confidence badges. If you want to disable the badges in the Mend Renovate App, add the `mergeConfidence:all-badges` preset to the `ignorePresets` array in your config: ``` { "ignorePresets": ["mergeConfidence:all-badges"] } ``` ## Confidence levels and their meaning Merge Confidence uses the following confidence levels: - **Low**: We think the update contains breaking changes. Often this is expected because it’s a `major` version update, but updates can have unknown breaking changes - **Neutral**: We don’t have enough data about the update, or we can’t decide if the update should be Low or High confidence - **High**: We rank updates as High confidence when the combination of `Age`, `Adoption` and `Passing` tests means there’s a very low chance of breaking changes - **Very High**: We only use this for updates which are months old and have either high `Adoption` or have very high test `Passing` scores ## How it works The Mend Renovate App created millions of pull requests on `github.com` to help developers update their dependencies since 2017. We bundle and analyze metrics such as package `Age`, package `Adoption`, and `Passing` tests. This way we can find packages that have undeclared breaking changes. ### Algorithm The algorithm that decides on the values is private and is not something we plan to share. Similar to a search engine’s algorithm, we plan to adjust and improve it over time, for example by using historical data to set a baseline confidence level for packages. ### Data We plan to expose much more of the data via a companion website, such as number of users of a package and popular repositories which already updated to the version in question. ## Merge Confidence Workflows If you are a paying Mend customer, or you are an Open Source project who has access to Mend Renovate Community (OSS) Cloud, you will have access to [Merge Confidence Workflows](https://docs.mend.io/wsk/smart-merge-control). This makes it possible to introduce more intelligent workflows, such as “only raise a PR once the update is in High confidence” or “automerge Very High confidence updates”. ## Explanations ### Package ranking npm packages less than three days old can be [unpublished](https://docs.npmjs.com/policies/unpublish), which can result in a service impact if you have updated to a package that gets unpublished. This is why npm packages can only get the **High** Confidence badge when they are at least three days old. ### Percentage values weighting The percentages for `Adoption` and `Passing` are weighted towards Organizations, private repositories, and projects with high test reliability. This means those values aren’t _raw_ percentages. ## Questions and feedback If you have any feedback about Merge Confidence, please [add it to our feedback megathread](https://github.com/renovatebot/renovate/discussions/43119). ## [Modules introduction](https://docharvest.github.io/docs/renovate/usage/modules/) Contents renovate Modules introduction Renovate Modules introduction Renovate modules, please select a subsection. ## Supported modules - [Datasources](./datasource/index.md) - [Managers](./manager/index.md) - [Platform](./platform/index.md) - [Versioning](./versioning/index.md) ## [Datasources](https://docharvest.github.io/docs/renovate/usage/modules/datasource/) Contents renovate Datasources Renovate Datasources After Renovate’s manager scanned the files and extracted the dependencies, it assigns a `datasource` to each extracted package file or dependency. The `datasource` tells Renovate how to search for new versions. You don’t need to configure or override datasources. But you may use datasources in a `packageRules` array to configure Renovate’s behavior, for example: ``` { "packageRules": [ { "matchDatasources": ["npm"], "matchPackageNames": ["lodash"], "automerge": true } ] } ``` ## Supported Datasources ## [Managers](https://docharvest.github.io/docs/renovate/usage/modules/manager/) Contents renovate Managers Renovate Managers Renovate is based around the concept of “package managers”, or “managers” for short. These range from traditional package managers like npm, Bundler and Composer through to less traditional concepts like CircleCI or Travis config files. The goal of Renovate is to detect and maintain all third-party dependencies in your repositories, through the use of managers. ## Supported Managers ## Configuring Managers ### File Matching Most Renovate managers have a default `managerFilePatterns` array. The `managerFilePatterns` array can hold a regular expression or glob pattern, that match against the repository file list. #### Managers with no default managerFilePatterns Some managers have no default `managerFilePatterns`, because they have no filename convention that would let Renovate intelligently filter them. If there is no default `filePattern`, the manager is disabled. For the manager to work, you must create a `managerFilePatterns` regular expression, or glob pattern. For example: ``` { "kubernetes": { "managerFilePatterns": ["/^config/.*\\.yaml$/"] } } ``` #### Extending a manager’s default managerFilePatterns If the default `managerFilePatterns` for a manager does not match your file(s), you can _extend_ the pattern. You extend the pattern by configuring the manager’s `managerFilePatterns`. For example: ``` { "dockerfile": { "managerFilePatterns": ["does-not-look-like-a-docker-file"] } } ``` #### Ignoring files that match the default managerFilePatterns Renovate will _extend_ the existing [`managerFilePatterns`](../../configuration-options.md#managerfilepatterns), meaning you don’t need to include the default patterns like `Dockerfile` in your own array. In other words, the patterns are “additive”. If a manager matches a file that you _don’t_ want it to, ignore it using the [`ignorePaths`](../../configuration-options.md#ignorepaths) configuration option. Also, if you ever find that Renovate is _not_ matching a file name that you’re certain it should, check your preset config isn’t the cause of it. The `config:recommended` preset ignores common test and example directory names, for example. ### Enabling and disabling managers #### Enabling experimental managers Most managers are enabled by default. For those that aren’t, typically because they are considered experimental, you can opt-in manually. If there was a manager called `some-new-manager` you would enable it like this: ``` { "some-new-manager": { "enabled": true } } ``` #### Disabling managers ``` { "gradle": { "enabled": false } } ``` Please check the [list of supported managers](#supported-managers). #### Limiting enabled managers Say you only want to use Renovate for JavaScript packages, and to update your Dockerfile, and don’t want any other updates. You can use the `enabledManagers` array, to list the managers you want to use (`npm`, `dockerfile`): ``` { "enabledManagers": ["npm", "dockerfile"] } ``` Using the `enabledManagers` array disables all other managers, this includes Bundler, Composer, Docker Compose, etc. ## [Renovate Platforms](https://docharvest.github.io/docs/renovate/usage/modules/platform/) Contents renovate Platforms Renovate Platforms Renovate aims to be platform-neutral, while also taking advantage of good platform-specific features. ## Supported platforms ## [Versioning](https://docharvest.github.io/docs/renovate/usage/modules/versioning/) Contents renovate Versioning Renovate Versioning Versioning is one of Renovate’s core “module” types. The other modules are Platform, Manager and Datasource. Renovate uses the version module to answer questions such as: - Is this a valid version string? - Is this a valid constraint/range? - Does this version match with this constraint? - If the current constraint is X, what would the new constraint be if we updated to version Y? - Is this a `major`, `minor` or `patch` update? - Is this a breaking change? How Renovate uses its core modules during a run: 1. Renovate’s Manager module _extracts_ the dependencies 2. Renovate’s Datasource _finds_ the versions of the dependencies 3. Renovate’s Versioning scheme _sorts and filters_ the results The “versioning” chosen can be different per package manager, because different package managers use different versioning schemes. For example, `npm` uses `1.0.0-beta.1` while `pip` uses `1.0.0b1`. ## Why you might need to manually configure versioning Renovate interprets versions correctly out-of-the-box most of the time. But Renovate can’t automatically detect **all** versioning schemes. So sometimes you need to tell the bot what versioning scheme it should use. For some ecosystems, automatic version selection works nearly every time (e.g. for npm-compliant managers, use `npm` versioning). For other ecosystems such as Docker or GitHub tags, there is no consistent convention for versions, so the default choice may not always work. For example some Docker images may use SemVer, some PEP440, some Calendar Versioning, etc. If the automatic version selection does _not_ work for a dependency update: set the `versioning` for that dependency in the Renovate config file. ## General concepts behind overriding versioning - Although you can reconfigure versioning per-manager or per-datasource, you probably don’t need such a broad change - More commonly you would need to configure `versioning` for individual packages or potentially package patterns - The best way to do this is with `packageRules`, with a combination of `matchManagers`, `matchDatasources`, and `matchPackageNames`. Avoid configuring `versioning` in a rule that also uses `matchUpdateTypes`, as the update types aren’t known at the time the `versioning` is applied ## Examples of versioning overrides ### Overriding Docker versioning to use a versioning specific for a package The configuration below overrides Renovate’s default `docker` versioning for the `python` Docker image and instead uses the `pep440` versioning scheme to evaluate versions. ``` { "packageRules": [ { "matchDatasources": ["docker"], "matchPackageNames": ["python"], "versioning": "pep440" } ] } ``` ### Using a custom regex versioning scheme ``` { "packageRules": [ { "matchPackageNames": ["foo/bar"], "versioning": "regex:^(?.*)-v?(?\\d+)\\.(?\\d+)\\.(?\\d+)?$" } ] } ``` ## Breaking Changes In most ecosystems, especially SemVer, major upgrades are treated as breaking changes. But other updates may have breaking changes too, for example: - In SemVer, any update from a 0.x version may be breaking (including `0.1.0` → `0.1.1`, `0.1.0` → `0.2.0` and `0.1.0` → `1.0.0`) - Updates from pre-release versions like `1.0.0-pre.1` to other versions (including stable versions like `1.0.0`) can be breaking - Python makes breaking changes in minor updates, e.g. from `3.12` to `3.13` It can be tempting to propose ideas like “let’s treat minor updates of Python as major updates” but that is swapping one problem for a worse problem. The definitions of major and minor should not be redefined and broken in order to shoehorn in the related concept of “breaking change”. Instead, Renovate has the concept of `isBreaking`, which can be decided independently of `updateType`. Here’s an example of grouping all non-breaking updates together: ``` { "packageRules": [ { "description": "Group non-breaking updates", "matchUpdateTypes": ["minor", "patch", "digest"], "matchJsonata": ["isBreaking != true"], "groupName": "Non-breaking updates" } ] } ``` ## Supported Versioning ## [Node.js Versions](https://docharvest.github.io/docs/renovate/usage/node/) Contents renovate Node.js Versions Renovate Node.js Versions Renovate can upgrade the [Node.js](https://nodejs.org/en/) runtime used by your project. This way you’re using the latest bug fixes, performance improvements, security mitigations, etc. ## LTS codenames Renovate understands [codenames for Node.js LTS releases](https://github.com/nodejs/Release/blob/main/CODENAMES.md) and will offer upgrades for them (e.g. from `fermium` to `gallium`) as long as the `node` versioning scheme is being used. ## File Support Renovate can manage the Node.js version in the following files: - The [`engines`](https://docs.npmjs.com/files/package.json#engines) field in [`package.json`](https://docs.npmjs.com/files/package.json) - The [`volta`](https://docs.volta.sh/guide/understanding#managing-your-project) field in [`package.json`](https://docs.npmjs.com/files/package.json) - The [`.nvmrc`](https://github.com/creationix/nvm#nvmrc) file for the [Node Version Manager](https://github.com/creationix/nvm) - The [`.node-version`](https://github.com/nodenv/nodenv#choosing-the-node-version) file for the [nodenv](https://github.com/nodenv/nodenv) environment manager - The [`.tool-versions`](https://asdf-vm.com/manage/configuration.html#tool-versions) file for the [asdf](https://github.com/asdf-vm/asdf) version manager - The mise [configuration files](https://mise.jdx.dev/configuration.html#mise-toml) (e.g., `mise.toml`, `.mise.toml`, `.config/mise.toml`) for the [mise](https://github.com/jdx/mise) version manager - The [`node_js`](https://docs.travis-ci.com/user/languages/javascript-with-nodejs/#Specifying-Node.js-versions) field in [`.travis.yml`](https://docs.travis-ci.com/user/customizing-the-build/) ## Configuring which version of npm Renovate uses When `binarySource=install`, such as in the Mend Renovate App, Renovate will choose and install an `npm` version dynamically. To control which version or constraint is installed, you should use the `engines.npm` property in your `package.json` file. Renovate bot will then use that version constraint for npm when it creates a pull request. For example, if you want to use at least npm `8.1.0` and also allow newer versions of npm in the `8.x` range, you would put this in your `package.json` file: ``` { "engines": { "npm": "^8.1.0" } } ``` Alternatively, the npm version can also be configured via the [`constraints` option](./configuration-options.md#constraints). ## [Noise Reduction](https://docharvest.github.io/docs/renovate/usage/noise-reduction/) Contents renovate Noise Reduction Renovate Noise Reduction Generally, the first reaction people have to automated dependency updates like Renovate is “oh great/feel the power of automation”. The next reaction a few days or weeks later is often “this is getting overwhelming”. Indeed, if you leave Renovate on its default settings of raising a PR every single time any dependency receives any update.. you will get a lot of PRs and related notifications. This document will give you some ideas of how to reduce the amount of “noise” in your repository and the Pros/Cons of each approach. Of course, please keep in mind that people’s definitions of “noise” may differ. For some people, it’s noisy only if they get a notification or email from GitHub. For others, too many commits in their base branch may be “noise”. In other words, your mileage may vary. If you have any ideas on this topic, please contact the author by starting a [new discussion on the Renovate repository](https://github.com/renovatebot/renovate/discussions). ## Package Grouping To reduce noise, you can reduce the number of updates in total, and a good way to do that is via intelligent grouping of related packages. As an example, our default `":app"` and `":library"` [presets](./config-presets.md) include the rule `"group:monorepos"`, which means that “sibling” packages from known monorepos will always be grouped into the same branch/PR by renovate. For example, all `@angular/*` packages that are updated at the same time will be raised in a “Renovate angular monorepo packages” PR. And every package in the React monorepo will be grouped together in a React monorepo PR too. You may wish to take this further, for example you might want to group together all packages related to `eslint`, even if they come from separate repositories/authors. In that case you might create a config like this: ``` { "packageRules": [ { "matchPackageNames": ["/eslint/"], "groupName": "eslint" } ] } ``` By setting `matchPackageNames` to `/eslint/`, it means that any package with eslint anywhere in its name will be grouped into a `renovate/eslint` branch and related PR. ### Be smart about grouping dependencies Grouping dependencies _may_ help you, but can also cause problems. Sometimes you’re better off getting a single PR per dependency! Grouping dependencies versus single PRs: - Grouping dependencies increases the chance that the branch has an error (“break” your build) - When you upgrade multiple dependencies in one PR, it takes longer to find out which package broke the build - If a group PR “breaks”, you’ll have to wait upgrading your other dependencies until _all_ updates in the PR pass - You will have less flexibility when one (or more) dependencies in the group have a major upgrade, but the other dependencies are good to go ## Scheduling Renovate For a high level overview of scheduling when Renovate bot runs, read the [key concepts, scheduling](./key-concepts/scheduling.md) docs. On its own, the Renovate CLI tool runs once and then exits. Hence, it only runs as often as its administrator sets it to (e.g. via `cron`). For [the Mend Renovate App](https://github.com/apps/renovate), it currently runs continuously using a job queue that gets refreshed hourly for [Enterprise users, and every 4 hours for Community users](./mend-hosted/overview.md#resources-and-scheduling), or when you make relevant commits to your repository. You can expect to get PRs at any time of the day, e.g. soon after versions are published to npm. Receiving PRs at any hour can increase the feeling of being “overwhelmed” by updates and possibly interrupt your flow during working hours, so many Renovate users also consider reducing Renovate’s schedule to be outside their normal working hours, for example weeknights and weekends. This is achievable by configuring `schedule` in your Renovate config and optionally `timezone` (Renovate’s default time zone is UTC, so you may find it easier to write schedules if you override `timezone` to your local one). Another example of adjusting schedules to fit with your workflow might be if your company performs releases every Monday. In that case, you might schedule Renovate to run every Tuesday after midnight to pick up new dependency updates that you can test over the following week before the next release. **Caution**: You need to make sure you leave yourself and Renovate enough time in a week to actually get all your updating and merging done. There are multiple reasons why Renovate may need to “recreate” PRs after you merge another: 1. Conflict with `package.json` (sometimes) 2. Conflict with lock files (often) 3. If you have configured Renovate or GitHub that PRs must always be kept up-to-date with the base branch Any of the above reasons can lead to a Renovate branch being considered “stale” and then Renovate needs to rebase it off the base branch before you can test and merge again, and Renovate won’t do this until it’s back in schedule. ### Selective scheduling Don’t think that you need to apply blanket rules to scheduling. Remember that Renovate’s configuration is highly flexible so you can configure `automerge` anywhere from globally (entire repo) right down to a package/upgrade type level. You could even configure a nonsensical rule like: “patch updates of `jquery` are for Mondays only”. Remember our example of grouping all `eslint` packages? If you think about it, updates to `eslint` rules don’t exactly need to be applied in real time! You don’t want to get too far behind, so how about we update `eslint` packages only once a month? ``` { "packageRules": [ { "description": "Schedule updates on first day of each month", "matchPackageNames": ["/eslint/"], "groupName": "eslint", "schedule": ["* * 1 * *"] } ] } ``` Or perhaps at least weekly: ``` { "packageRules": [ { "description": "Schedule updates on Monday mornings(before 4 AM)", "matchPackageNames": ["/eslint/"], "groupName": "eslint", "schedule": ["* 0-3 * * 1"] } ] } ``` If you’re wondering what is supported and not, under the hood, the schedule is parsed using [@breejs/later](https://github.com/breejs/later) using the `later.parse.text(scheduleString)` API. Read the parser documentation at [breejs.github.io/later/parsers.html#text](https://breejs.github.io/later/parsers.html#text). Renovate does not support scheduled minutes or “at an exact time” granularity. Granularity must be at least one hour. ## Automerging Automerging is a Renovate feature that can save you a lot of time/noise directly, while also benefiting grouping and scheduling. In short: it means that Renovate can merge PRs or even branches itself if they pass your tests. We recommend that you enable automerge for any type of dependency update where you would select Merge anyway. We all know that there are some types of updates that we (nearly) always verify manually before merging, and plenty of others that we don’t bother looking at unless tests fail. Every time you select Merge on a Renovate PR without manually testing it, you should consider if you can enable automerge and save yourself the time in future. Automerge works particularly well for `devDependencies` and for production `dependencies` that have great test coverage. For example, if you have `jest` or `mocha` as a dependency, and it has an upgrade with passing tests: automerge them! If you have a linter like `eslint` or `tslint` and its update passes: automerge them! If you have an API with 100% test coverage and `express` is updated: automerge it! ### Branch automerging Those of you familiar with GitHub might note that even if you automerge PRs, you are still going to get notifications (noise) anyway - one when the PR is created and another when it is merged. For this reason we recommend you consider setting `automergeType=branch` which will mean: - Renovate first creates a branch and no PR - If tests pass, Renovate pushes a commit directly to the base branch without PR - If tests fail, Renovate raises a PR for you to review The result is that passing updates are essentially “silent” - the only sign of them are the commits to your base branch. ### Automerging and scheduling Automerging is particularly beneficial if you have configured a schedule, because Renovate on its own may be able to automerge the majority of your updates. And this is especially so if your repository needs rebasing, e.g. because you use lock files. e.g. let’s say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file. - At the start of the schedule, `Renovate` will create branches for `abc` and `xyz` upgrades, including `yarn.lock` updates - After `abc` passes tests, `Renovate` will automerge it to your base branch - The `xyz` branch probably now has `yarn.lock` conflicts - Renovate will immediately check all other branches and rebase them - The change to `xyz` branch will trigger another round of CI tests - After the updated `xyz` branch passes, Renovate will automerge it too This is a lot better than you waking up to two PRs and then having to deal with conflicts yourself after you merge the first one. Remember our running `eslint` example? Let’s automerge it if all the linting updates pass: ``` { "packageRules": [ { "description": "Schedule updates on Monday mornings(before 4 AM)", "matchPackageNames": ["/eslint/"], "groupName": "eslint", "schedule": ["* 0-3 * * 1"], "automerge": true, "automergeType": "branch" } ] } ``` Have you come up with a rule that would help others? How about a PR to [our presets](https://github.com/renovatebot/renovate/tree/main/lib/config/presets/internal)? For example the above rule could be named `":automergeEslintWeekly"` in `schedule.ts`. ## Lock file considerations Using lock files greatly increases the chance that merging one PR will result in a second PR becoming conflicted with the base branch. The table below highlights different noise reduction strategies and their effect on pull request and potential lock file conflicts: Action Effect on pull requests Chance of lock file conflicts Group dependencies together Decreases separate PRs Decreases Automerge dependencies Decreases concurrent PRs Decreases Decrease scheduled time for Renovate Increases concurrent PRs Increases ## The Future of Noise Reduction First of all, if you ever have any ideas about how to make Renovate less noisy, please raise or comment on issues in the [main repository](https://github.com/renovatebot/renovate). Our philosophy is: 1. Nearly everyone should use Renovate-like dependency update automation 2. Over time, you should “see” Renovate less and less One of our hopes with preset configs is that a set of “sensible” configs can be maintained by the community that combine grouping, scheduling and automerging to reduce the amount of noise in repositories with little downside or increased risk. Such lists could be maintained and used somewhat like Adblock lists - kept up to date by maintainers but for the majority of users they are simply trusted/automatic/invisible. ## [NuGet](https://docharvest.github.io/docs/renovate/usage/nuget/) Contents renovate NuGet (.NET) Renovate NuGet (.NET) Renovate can upgrade dependencies in these files: - `.csproj` - `.fsproj` - `.sqlproj` (SSDT SQL projects) - `.vbproj` ## Version Support Renovate only works with SDK-style `.csproj`, `.fsproj` or `.vbproj` files. By default, this includes: - .NET Core 1.0 and above - .NET Standard class libraries - `.csproj`, `.fsproj` or `.vbproj` files that use the SDK-style syntax To convert your .NET Framework `.csproj`, `.fsproj` or `.vbproj` files into an SDK-style project, follow the steps in this [guide](https://natemcmaster.com/blog/2017/03/09/vs2015-to-vs2017-upgrade/). ## How it works 1. Renovate searches in each repository for any files with a `.csproj`, `.fsproj`, `.sqlproj`, or `.vbproj` extension 2. Existing dependencies are extracted from `` and `` tags, and MSBuild SDK versions from ``, ``, and `` elements 3. Renovate looks up the latest version on [nuget.org](https://nuget.org) (or an alternative feed if configured) to see if any upgrades are available 4. If the source package includes a GitHub URL as its source, and has either: - a “changelog” file, or - uses GitHub releases then release notes for each version are embedded in the generated PR If your project file references a `packages.config` file, no dependencies will be extracted. Find out here how to [migrate from `packages.config` to `PackageReference`](https://learn.microsoft.com/nuget/consume-packages/migrate-packages-config-to-package-reference). ## Alternate feeds By default Renovate performs all lookups on `https://api.nuget.org/v3/index.json`, but you can set alternative NuGet feeds. You can set alternative feeds: - in a [`NuGet.config` file](https://learn.microsoft.com/nuget/reference/nuget-config-file#package-source-sections) within your repository (Renovate will not search outside the repository), or - in a Renovate configuration options file like `renovate.json` ``` { "packageRules": [ { "matchDatasources": ["nuget"], "registryUrls": [ "https://api.nuget.org/v3/index.json", "https://example1.com/nuget/", "https://example2.com/nuget/v3/index.json" ] } ] } ``` In the example above we’ve set three NuGet feeds. The package resolving process uses the `merge` strategy to handle the three feeds. All feeds are checked for dependency updates, and duplicate updates are merged into a single dependency update. !!! note Some alternative feeds (e.g. Artifactory) do not implement the full set of [required NuGet resources](https://learn.microsoft.com/en-us/nuget/api/overview#resources-and-schema) for the V3 API. If the `PackageBaseAddress` resource does not exist, Renovate falls back to using the `projectUrl` from the dependency’s catalog entry as the `sourceUrl` for the dependency, affecting [changelog detection](key-concepts/changelogs.md#how-renovate-detects-changelogs). ### Protocol versions NuGet supports two protocol versions, `v2` and `v3`. The NuGet client and server must use the same version. When Renovate acts as the client, it can use the `v2` and `v3` protocols. By default, Renovate uses the `v2` protocol. If the configured feed URL ends with `index.json`, Renovate uses the `v3` protocol. So Renovate behaves like the official NuGet client. #### v3 feed URL not ending with index.json If a `v3` feed URL does not end with `index.json`, you must specify the version explicitly. - If the feed is defined in a `NuGet.config` file set the `protocolVersion` attribute to `3`: ``` ``` - If the feed is defined via Renovate configuration append `#protocolVersion=3` to the registry URL: ``` { "packageRules": [ { "matchDatasources": ["nuget"], "registryUrls": ["https://example1.com/nuget/#protocolVersion=3"] } ] } ``` You may need this workaround when you use the JFrog Artifactory. ## Authenticated feeds Credentials for authenticated/private feeds can be given via host rules in the configuration options (file or command line parameter). ``` { "hostRules": [ { "hostType": "nuget", "matchHost": "http://example1.com/nuget", "username": "root", "password": "p4$$w0rd" } ] } ``` If you use Azure DevOps: - set `matchHost` to `pkgs.dev.azure.com` - set the username, so Renovate can build the project when it creates the PR !!! note Only Basic HTTP authentication (via username and password) is supported. For Azure DevOps: use a PAT with `read` permissions on `Packaging`. The username of the PAT must match the username of the _user of the PAT_. The generated `nuget.config` forces the basic authentication, which cannot be overridden externally! ## Ignoring package files when using presets Because `nuget` manager has a dedicated `ignorePaths` entry in the `:ignoreModulesAndTests` preset, if you’re using any presets that extend it (like `config:recommended`), you need to put your `ignorePaths` inside the `nuget` section for it to be merged. For example: ``` { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["config:recommended"], "nuget": { "ignorePaths": ["IgnoreThisPackage/**"] } } ``` Otherwise, all `nuget.ignorePaths` values in `:ignoreModulesAndTests` will override values you put inside `ignorePaths` at the top-level config. ## Future work We welcome contributions or feature requests to support more patterns or use cases. ## [OpenTelemetry and Renovate](https://docharvest.github.io/docs/renovate/usage/opentelemetry/) Contents renovate OpenTelemetry Renovate OpenTelemetry !!! warning “This feature is flagged as experimental” Experimental features might be changed at any time. Renovate’s OpenTelemetry support is stable enough to use in production, but there may be changes that rename attributes or fix bugs in a way that could be breaking to users, even in non-major version updates. Renovate supports the [OpenTelemetry](https://opentelemetry.io/) monitoring and observability standard. OpenTelemetry has three types of observability data it supports within the OpenTelemetry Protocol (OTLP): - traces - metrics - logs !!! note While the OpenTelemetry Protocol (OTLP) support traces, metrics, and logs, Renovate only supports traces, and some metrics. This means Renovate does not support other observability data like: stats on caching, error events, number of found updates, and so on. Renovate uses [`@opentelemetry/exporter-trace-otlp-http`](https://www.npmjs.com/package/@opentelemetry/exporter-trace-otlp-http) under the hood. This means that Renovate sends traces via [OTLP/HTTP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp) in JSON-encoded protobuf format only. ## Examples An example for setting up a local OpenTelemetry test setup with Docker can be found on [OpenTelemetry examples page](examples/opentelemetry.md). ## Usage To activate the instrumentation, you must set the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. This variable controls the endpoint for the telemetry data. Once this endpoint is set, you can use all environment variables listed in the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md). You can also set the following environment variables: - `OTEL_SERVICE_NAME`: to control the service name that will be emitted in traces, defaults to `renovate` - `OTEL_SERVICE_NAMESPACE`: to control the service namespace that will be emitted in traces, defaults to `renovatebot.com` - `OTEL_SERVICE_VERSION`: to control the service version that will be emitted in traces, defaults to using the release version of Renovate The following resource detectors are used: - `EnvDetector` from @opentelemetry/resources to allow users to add the custom attributes - `GithubDetector` from [@opentelemetry/resource-detector-github](https://www.npmjs.com/package/@opentelemetry/resource-detector-github), to determine if it’s running in [Renovate’s GitHub Action](https://github.com/renovatebot/github-action/), or via the npm package in GitHub Actions - `AWSDetector` from [@opentelemetry/resource-detector-aws](https://www.npmjs.com/package/@opentelemetry/resource-detector-aws) Users hosting on AWS - `GcpDetector` from [@opentelemetry/resource-detector-gcp](https://www.npmjs.com/package/@opentelemetry/resource-detector-gcp) Users hosting on GCP - `AzureDetector` from [@opentelemetry/resource-detector-azure](https://www.npmjs.com/package/@opentelemetry/resource-detector-azure) Users hosting on Azure You can disable all cloud detectors by setting the `RENOVATE_USE_CLOUD_METADATA_SERVICES` environment variable to `false`. Then only the `EnvDetector` will be used. Additionally you can use `OTEL_NODE_RESOURCE_DETECTORS` environment variable to control which resource detectors are used. The default values is `all`, which means all of the above detectors are used. Set it to `none` to disable all detectors, or a comma-separated list of the following values to specify which detectors to use: - `aws` - `azure` - `gcp` - `github` - `env` ## Supported OTLP data ### Traces Renovate provides instrumentation through traces for (non-exhaustively): - HTTP requests, via [@opentelemetry/instrumentation-http](https://www.npmjs.com/package/@opentelemetry/instrumentation-http) - A trace for each “splits” Renovate performs - `init`, `extract`, `lookup` and `update` - Any command execution (`rawExec: ...`) - Any Git operations - Per-manager traces when performing the `lookup` and `extract` splits - Per-branch traces when performing the `update` split - Cache lifecycle operations (repository cache load/save, package cache init/destroy) - Important functions (more instrumentation be added) As well as following [OpenTelemetry’s semantic conventions](https://opentelemetry.io/docs/specs/semconv/) where possible, Renovate defines several Custom Attributes, which can be found in [`lib/instrumentation/types.ts`](https://github.com/renovatebot/renovate/blob/main/lib/instrumentation/types.ts). ### Metrics Renovate does not currently support metrics in an OTLP format. However, as seen in the [OpenTelemetry examples page](examples/opentelemetry.md), it is possible to use the [spanmetrics connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector) to automagically generate metrics from the tracing support Renovate has. ### Logs Renovate does not currently support logging in an OTLP format. ## Debugging To help you debug, you can print the telemetry to the console. Use the environment variable `RENOVATE_TRACING_CONSOLE_EXPORTER`. You can also set `OTEL_LOG_LEVEL` to control the log level of OpenTelemetry’s internal [diagnostics](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/#troubleshooting), which can be helpful for debugging. ## Help wanted We’re continually looking to improve Renovate’s instrumentation, and are aware there may be gaps in instrumentation. As with the rest of Renovate, any additional contributions are very welcome! You can see our current planned TODO list using [the `core:instrumentation` label](https://github.com/renovatebot/renovate/issues?q=state%3Aopen%20label%3Acore%3Ainstrumentation). ## [Automated Dependency Updates for PHP Composer Dependencies](https://docharvest.github.io/docs/renovate/usage/php/) Contents renovate PHP Composer Support Renovate PHP Composer Support Renovate can upgrade dependencies in PHP’s `composer.json` and `composer.lock` files. ## How It Works 1. Renovate searches in each repository for any `composer.json` files 2. Existing dependencies are extracted from the relevant sections of the JSON 3. Renovate resolves the dependency on Packagist (or elsewhere if configured), and filter for SemVer versions 4. A PR is created with `composer.json` and `composer.lock` updated in the same commit 5. If the source repository has either a “changelog” file or uses GitHub releases, then Release Notes for each version will be embedded in the generated PR ## Enabling Either install the [Renovate App](https://github.com/apps/renovate) on GitHub, or check out [Renovate OSS](https://github.com/renovatebot/renovate) for self-hosted. ## Private packages If you are using a [privately hosted Composer package](https://getcomposer.org/doc/articles/authentication-for-private-packages.md) you can pass the credentials via the [`hostRules`](./configuration-options.md#hostrules) configuration. ``` { "hostRules": [ { "matchHost": "some.vendor.com", "hostType": "packagist", "username": "", "password": "" }, { "matchHost": "bearer-auth.for.vendor.com", "hostType": "packagist", "token": "abcdef0123456789" } ] } ``` This host rule is best added to the bot’s `config.js` config so that it is not visible to users of the repository. If you are using the Mend Renovate App then you can encrypt it with Renovate’s public key instead, so that only Renovate can decrypt it. Go to [https://app.renovatebot.com/encrypt](https://app.renovatebot.com/encrypt), paste in the secret string you wish to encrypt, select _Encrypt_, then copy the encrypted result. You may encrypt your `password` only, but you can encrypt your `username` as well. ``` { "hostRules": [ { "matchHost": "some.vendor.com", "hostType": "packagist", "encrypted": { "username": "", "password": "" } }, { "matchHost": "bearer-auth.for.vendor.com", "hostType": "packagist", "encrypted": { "token": "" } } ] } ``` ## Update all dependencies By default, Renovate will invoke `composer update` with the `--with-dependencies` flag. Add `composerWithAll` to your `postUpdateOptions` array to use the `--with-all-dependencies` flag instead. ## [Python package manager support](https://docharvest.github.io/docs/renovate/usage/python/) Contents renovate Python Package Manager Support Renovate Python Package Manager Support Renovate supports several Python package managers, including `pip`, `pipenv`, `poetry`, etc. See [all supported managers](./modules/manager/index.md). ## Versioning support We’ve written a JavaScript version of the [PEP440 specification](https://www.python.org/dev/peps/pep-0440/) so we can use it in Renovate bot. You can find this project in our [`renovatebot/pep440` repository](https://github.com/renovatebot/pep440). Our PEP440 implementation supports pinned versions and ranges. Legacy versions with the `===` prefix are ignored. ## How it works 1. Renovate searches through each repository for package files 2. Existing dependencies are extracted from the package files 3. Renovate searches for the latest version on [PyPI](https://pypi.org/) to decide if there are upgrades 4. If the source package includes a GitHub URL as its source, and has a “changelog” file _or_ uses GitHub releases, a Release Note will be embedded in the generated PR ## Package name matching Your `matchPackageName` or `matchPackagePattern` rules will be matching against normalized names. So if you have specified package `some.package` or `ANOTHER_DEP` in your package files (`requirements.txt`, `pyproject.toml`), they will be treated as `some-package` and `another-dep` respectively. Not only they will be case insensitive but will replace any amount `._-` to a single `-`. [Consult Python packaging documentation for the specification](https://packaging.python.org/en/latest/specifications/name-normalization/). ## Alternate registries By default Renovate checks for upgrades on the `pypi.org` registry. If you want, you can set alternative index URLs. There are three ways to do this: - index-url in `requirements.txt` - sources in `Pipfile` - sources in `pyproject.toml` - set URL in Renovate configuration ### index-url in `requirements.txt` ``` --index-url http://example.com/private-pypi/ some-package==0.3.1 some-other-package==1.0.0 ``` ### Sources in `Pipfile` Renovate finds and uses any custom sources in your `Pipfile`. ### Sources in `pyproject.toml` Renovate detects any custom-configured sources in `pyproject.toml` and uses them. ### Specify URL in configuration Create a `packageRules` entry with `matchDatasources=pypi` and a `registryUrls` array. Fill the array with alternate index URL(s). ``` { "packageRules": [ { "matchDatasources": ["pypi"], "registryUrls": ["http://example.com/private-pypi/"] } ] } ``` !!! tip If a `requirements.txt` file has an index-url then Renovate follows that link, instead of following any link set in the `registryUrls` array. To override the URL found in `requirements.txt`, you must create a custom `packageRules` setting. This is because `packageRules` are applied _after_ package file extraction. ## Disabling Python support ``` { "packageRules": [ { "matchCategories": ["python"], "enabled": false } ] } ``` Alternatively, you can use `enabledManagers` to tell Renovate what package managers it can use. ``` { "enabledManagers": ["npm"] } ``` ## [Reading list](https://docharvest.github.io/docs/renovate/usage/reading-list/) Contents renovate Reading List Renovate Reading List Renovate’s documentation has a lot of pages. To ease you into using Renovate we created reading lists. The reading lists contain the essential information for each type of user. How much you should read depends on how much you want to customize Renovate’s behavior. ## How to use this page We created reading lists for these types of users: - Beginners - Intermediate - Advanced Start with the “Beginners” reading list. If you’re self-hosting or need to update private packages, complete the relevant reading lists for those. ## I don’t know where to start If you’re new to Renovate, you should: - Use the Mend Renovate App, or let someone else host Renovate for you - Stick with the [`config:recommended`](./presets-config.md#configrecommended) preset - Use the Dependency Dashboard ([`config:recommended`](./presets-config.md#configrecommended) enables it automatically) - Read the pages in the “Beginners” list - Only create custom Renovate configuration when really needed ## Beginners Start by reading: - [Installing & Onboarding](./getting-started/installing-onboarding.md) - [Key concepts, Dependency Dashboard](./key-concepts/dashboard.md) - [Use Cases](./getting-started/use-cases.md) - [Running Renovate](./getting-started/running.md) - [Troubleshooting](./troubleshooting.md) - [Known limitations](./known-limitations.md) ## Intermediate First, complete the “Beginners” reading list. Read this list _after_ experiencing Renovate’s default behavior, once you really want/need to make changes to Renovate’s behavior. - [Upgrade best practices](./upgrade-best-practices.md) - [Key concepts, presets](./key-concepts/presets.md) - [Key concepts, Renovate scheduling](./key-concepts/scheduling.md) - [Key concepts, automerge](./key-concepts/automerge.md) - [Key concepts, pull requests](./key-concepts/pull-requests.md) - [Noise Reduction](./noise-reduction.md) Skim the [repository configuration options](./configuration-options.md) to learn about the kind of customizations you can make to Renovate. Feel free to read up on anything that looks interesting to you. ## Advanced First, complete the “Beginners” and the “Intermediate” reading list. Then read: - Define your own custom manager with [`customManagers`](./configuration-options.md#custommanagers) (previously `regexManagers`) - Define your own custom datasources with [`customDatasources`](./configuration-options.md#customdatasources) - [Shareable config presets](./config-presets.md) ## Self-hosting Renovate If you’re going to self-host Renovate then read: - [Running Renovate](./getting-started/running.md) - [Self-hosting examples](./examples/self-hosting.md) - Skim the [self hosted configuration options](./self-hosted-configuration.md) ## Private packages If you want Renovate to update private packages then read: - [Private package support](./getting-started/private-packages.md) ## [Automated dependency updates for Ruby Bundler dependencies](https://docharvest.github.io/docs/renovate/usage/ruby/) Contents renovate Ruby Bundler support Renovate Ruby Bundler support Renovate supports upgrading dependencies in Bundler’s Gemfiles and associated `Gemfile.lock` files. ## How it works 1. Renovate searches in each repository for any Gemfiles 2. Existing dependencies are extracted from the Gemfiles 3. Renovate resolves the dependency on Rubygems.org (or elsewhere if configured), and checks for newer versions 4. A PR is created which updates the `Gemfile` and `Gemfile.lock` in a single commit ## Warnings When using `"rangeStrategy": "update-lockfile"`, all gems listed in the `Gemfile` will be updated, even if they do not have a version specified. When using other `rangeStrategy` options, Renovate doesn’t update dependencies without a version constraint. Example: `gem 'some-gem', '~> 1.2.3'` will update `some-gem` if a new version matching the constraint is available, but `gem 'some-gem'` won’t. If you always want to have the latest available version, consider specifying `gem 'some-gem', '> 0'`. ## Enabling You can install the [Renovate App](https://github.com/apps/renovate) on GitHub. Or you can check out [Renovate OSS](https://github.com/renovatebot/renovate) to self-host Renovate. ## [Automated Dependency Updates for Rust crates](https://docharvest.github.io/docs/renovate/usage/rust/) Contents renovate Rust crates Renovate Rust crates Renovate supports upgrading dependencies in `Cargo.toml` files and associated `Cargo.lock` checksums. ## How it works 1. Renovate searches in each repository for any `Cargo.toml` files 2. Renovate extracts existing dependencies from `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]` and `[workspace.dependencies]` 3. Renovate looks up Cargo configuration to find index URLs for private registries 4. Renovate resolves the dependency’s version using the crates.io API or by cloning the index URL 5. If Renovate finds an update, Renovate will use `cargo update` to update both `Cargo.toml` and `Cargo.lock` ## Enabling Rust Modules Updating Renovate updates Rust crates by default. ## Cargo configuration and private registry discovery Renovate can find private registry URLs in these Cargo configuration files: - `.cargo/config.toml` - `.cargo/config` (legacy) Renovate can also find private registry URLs via a `CARGO_REGISTRIES__INDEX` environment variable. Read the [Rust environment variables docs](https://doc.rust-lang.org/cargo/reference/environment-variables.html#configuration-environment-variables) to learn more. ## Private crate registries and private Git dependencies You as user can set authentication for private crates by adding a `hostRules` configuration to your `renovate.json` file. All token `hostRules` with a `hostType` (e.g. `github`, `gitlab`, `bitbucket`, etc.) and host rules without a `hostType` will be automatically setup for authentication. You can also configure a `hostRules` that’s only for Cargo authentication (e.g. `hostType: 'crate'`). ``` module.exports = { hostRules: [ { matchHost: 'github.enterprise.com', token: process.env.GITHUB_TOKEN, hostType: 'github', }, { matchHost: 'someGitHost.enterprise.com', token: process.env.CARGO_GIT_TOKEN, hostType: 'crate', }, ], }; ``` ## [Security and Permissions](https://docharvest.github.io/docs/renovate/usage/security-and-permissions/) Contents renovate Security And Permissions Renovate Security And Permissions This page talks about our security stance, and explains what permissions are needed for the different ways you can run Renovate. ## Security Stance Renovate is open source software, and comes with no guarantees or warranties of any kind. That said, we will try to fix security problems in a reasonable timeframe if possible. ### Certifications Renovate the open source project is **not** certified. Mend is the company which maintains Renovate and provides the Mend Renovate App. Mend is ISO 27001 and SOC2 certified. ### Security / Disclosure If you find any bug with Renovate that may be a security problem, please report it through the [GitHub Security Advisories process](https://github.com/renovatebot/renovate/security/advisories). This way we can evaluate the bug and hopefully fix it before it gets abused. Please give us enough time to investigate the bug before you report it anywhere else. If you would like to discuss a potential finding before raising the Advisory, then e-mail us at: [renovate-disclosure@mend.io](mailto:renovate-disclosure@mend.io). Please do not create GitHub issues for security-related doubts or problems. ## Permissions We apply the Principle of Least Privilege (PoLP) but do need substantial privileges for our apps to work. ### Global Permissions These permissions are always needed to run the respective app. Permission The Mend Renovate App Forking Renovate Why Dependabot alerts `read` `read` Create vulnerability fix PRs Administration `read` `read` Read branch protections and to be able to assign teams to PRs Metadata `read` `read` Mandatory for all apps Checks `read` and `write` not applicable Read and write status checks Code `read` and `write` `read` Read for repository content and write for creating branches Commit statuses `read` and `write` `read` and `write` Read and write commit statuses for Renovate PRs Issues `read` and `write` `read` and `write` Create Dependency Dashboard or Config Warning issues Pull Requests `read` and `write` `read` and `write` Create update PRs Workflows `read` and `write` not applicable Explicit permission needed to update workflows ### User permissions Renovate can also request users’s permission to the following resources. These permissions will be requested and authorized on an individual-user basis. Permission The Mend Renovate App Forking Renovate Why email `read` not applicable Per-user consent requested if logging into App dashboard ## Privacy ### Self-hosted (Renovate OSS CLI, Mend Renovate On-Premises) Renovate is designed to operate autonomously and directly with package and source repositories, so does not “phone home”, send telemetry, or need to request information from Mend or any project infrastructure. An exception to this is when Merge Confidence badges are requested, because those are hosted on Mend servers. Such badges are public, do not require authentication, and Renovate does not identify the source user or repository when requesting them. Self-hosted Renovate does not send or submit any package data to Mend for the purpose of calculating Merge Confidence figures. According to a strict definition, Renovate may “send data” to third-party registries and source code hosts directly to look up new releases. For example, if you have an `npm` package and do not configure a private registry then Renovate will query URLs on `https://registry.npmjs.org` including names of packages used in your repositories. You could avoid this by configuring private registries but such registries need to query public registries anyway. We don’t know of any public registries which reverse lookup IP addresses to associate companies with packages. #### Security awareness for self-hosted Renovate instances ##### Introduction Before you start self-hosting Renovate you must understand the security implications associated with monitoring and updating repositories. The process that Renovate uses to update dependencies runs under the same user context as the Renovate process itself. This also means the process has the same level of access to information and resources as the user context! ##### Trusting Repository Developers All self-hosted Renovate instances must operate under a trust relationship with the developers of the monitored repositories. This has the following implications: - Access to information - Execution of code Keep reading to learn more. ###### Access to information Since the update process runs with the _same_ user privileges as the Renovate process, it inherently has access to the same information and resources. This includes sensitive data that may be stored within the environment where Renovate is hosted. ###### Execution of code (insider attack) In certain scenarios, code from the monitored repository is executed as part of the update process. This is particularly true during, for example: - `postUpgradeTasks`, where scripts specified by the repository are run - when a wrapper within the repository is called, like `gradlew` (if setting [`allowedUnsafeExecutions=["gradleWrapper"]`](./self-hosted-configuration.md#allowedunsafeexecutions). - when `mise trust` / `mise lock` are run from the repository checkout (if setting [`allowedUnsafeExecutions=["mise"]`](./self-hosted-configuration.md#allowedunsafeexecutions). These scripts can contain arbitrary code. This may pose a significant security risk if the repository’s integrity is compromised, or if the repository maintainers have malicious intentions. Because such insider attack is an inherent and unavoidable risk, the Renovate project will not issue CVEs (or GHSAs) for such attacks or weaknesses other than in exceptional circumstances. If you require `postUpgradeTasks` to run inside a shell, you can enable this using [`allowShellExecutorForPostUpgradeCommands=true`](./self-hosted-configuration.md#allowshellexecutorforpostupgradecommands). Note that this means that these commands can call out to other commands or access shell variables, if the allowlist via `allowedCommands` does not restrict it. As it is difficult to craft a regular expression that may deny usage of special characters to shells, it is likely that this will not be possible to avoid at this time. ###### Execution of code (outsider attack) Separately, there are also opportunities for malicious external code to execute, as part of Renovate’s update process. !!! warning Below are _some_ of the options, but note that this is **not exhaustive**. For instance: - updates that invoke Gradle (i.e. `./gradlew`), such as [updating the Gradle Wrapper](./modules/manager/gradle-wrapper/index.md) or [performing Gradle Verification Metadata](./modules/manager/gradle/index.md#dependency-verification) - because the Gradle buildscript is evaluated at this time (i.e. to determine which dependencies are available to then update the verification metadata) - executing any `postUpgradeTasks` in a way that may use an updated dependency - i.e. if you have a postUpgradeTask for `make docs`, where the version of your docs builder has updated - i.e. if your pre-commit hook, where the version of a linter has updated Depending on the self-hosted configuration, it may also be possible for package manager scripts to execute post-update (if using [`allowScripts=true`](./self-hosted-configuration.md#allowscripts) alongside [`ignoreScripts=false`](./configuration-options.md#ignorescripts)): - when an `npm install`, `composer install`, etc is executed on a branch update - performing [lock file maintenance](./configuration-options.md#lockfilemaintenance) ##### Centralized logging and sensitive information management Centralized logging is key to monitor and troubleshoot self-hosted Renovate environments. But logging may inadvertently capture and expose sensitive information. Operations that involve `customEnvVariables`, among others, could expose sensitive data, when logging is used. ##### Recommendations The Renovate maintainers recommend you follow these guidelines. ###### Vet and monitor repositories _Before_ integrating a repository with your self-hosted Renovate instance, thoroughly vet the repository for security and trustworthiness. This means that you should review the: - repository’s ownership - contribution history - open issues - open pull requests ###### Limit permissions Configure the environment running Renovate with the principle of least privilege. Ensure that the Renovate process has only the permissions needed to perform its tasks and no more. This reduces the impact of any malicious code execution. ###### Regularly review post-upgrade tasks Regularly review the actions taken by `postUpgradeTasks` to make sure they do not execute unnecessary or risky operations. Consider implementing a review process for changes to these tasks within repositories. Where possible, restrict the commands executed to an allowlist you control, and try to limit the opportunity for those commands to execute additional commands. For instance, allowlisting the command `make lint-fix` could run other tasks, including running `npm install --foreground-scripts`, which would bypass the global [`allowScripts`](./self-hosted-configuration.md#allowscripts) configuration ###### Use security tools Employ security tools and practices, like code scanning and vulnerability assessments, on the Renovate configuration _and_ the repositories Renovate manages. This helps identify potentially malicious code before it is executed. ###### Securing environment variables When configuring `customEnvVariables`: _always_ use Renovate’s secrets management syntax `({{ secrets.VAR_NAME }})` to reference sensitive variables securely. This makes sure that sensitive data is not exposed as plain text. ###### Logging infrastructure security Ensure that the logging infrastructure is configured to handle logs as sensitive data. This includes measures like: - log encryption - access controls to restrict log viewing to authorized personnel only - secure storage and transmission of log data ###### Log review and redaction processes Implement rigorous log review mechanisms to regularly scan for and redact sensitive information that might be logged inadvertently. Automated tools can assist in identifying patterns indicative of sensitive data, such as credentials or personal information, enabling timely redaction or alerting. ###### Stay informed Keep abreast of updates and security advisories related to Renovate itself. Apply updates promptly to ensure that your self-hosted instances get the latest security enhancements and bug fixes. #### Conclusion The flexibility and power of self-hosting Renovate also means you must take steps to manage your security. By understanding the risks associated with repository management and taking steps to mitigate those risks, organizations can maintain a secure and efficient development workflow. ### Hosted/SaaS (the Mend Renovate App) Users of the Mend Renovate App fall under [Mend’s Terms of Service](https://www.mend.io/terms-of-service/) and Privacy Policy. In this case the app needs to temporarily clone source code for Renovate to run, but the app does not keep the source code anywhere after jobs are completed. Mend anonymizes and aggregates package use and update success rates within the hosted app to derive Merge Confidence scores. The app database keeps a list of dependencies and versions per repo, plus basic into about any Renovate PRs it’s created. ## [Self-Hosted configuration options](https://docharvest.github.io/docs/renovate/usage/self-hosted-configuration/) Contents renovate Self-Hosted configuration Renovate Self-Hosted configuration 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](./getting-started/running.md#using-configjs). !!! tip This documentation corresponds with the JSON schema in [`docs.renovatebot.com/renovate-global-schema.json`](renovate-global-schema.json), and any [inherited config options](./config-overview.md#inherited-config) are also present in [`docs.renovatebot.com/renovate-inherited-schema.json`](renovate-inherited-schema.json). Please also see [Self-Hosted Experimental Options](./self-hosted-experimental.md). !!! note Config options with `type=string` are always non-mergeable, so `mergeable=false`. ## `allowCustomCrateRegistries` ## `allowPlugins` ## `allowScripts` ## `allowShellExecutorForPostUpgradeCommands` Enabling this allows `postUpgradeTasks`’ `commands` to execute as if they’re in a shell. This takes effect if you are using shell semantics, such as: ``` { "postUpgradeTasks": { "commands": ["echo '...' > go.mod", "go mod tidy || true"], "fileFilters": ["**/*.go"], "executionMode": "branch" } } ``` This will not affect calling a script like: ``` { "postUpgradeTasks": { "commands": ["bash .scripts/post-yarn-update.sh"], "fileFilters": ["yarn.lock", "**/*.js"], "executionMode": "update" } } ``` !!! warning This has the risk of arbitrary environment variable access or additional command execution. It is very likely this will be susceptible to these risks, even if you allowlist (via `allowedCommands`), as there may be special characters included in the given commands that can be leveraged ## `allowedCommands` 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` 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-options.md#env) configuration. Examples: ``` { "env": { "SOME_ENV_VARIABLE": "some_value", "EXTRA_ENV_NAME": "value" } } ``` The above would require `allowedEnv` to be configured similar to the following: ``` 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](./string-pattern-matching.md). ## `allowedHeaders` `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](./string-pattern-matching.md). 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` ``` { "allowedHeaders": ["X-Auth-Token"], "hostRules": [ { "matchHost": "https://domain.com/all-versions", "headers": { "X-Auth-Token": "secret" } } ] } ``` Or with custom `allowedHeaders`: ``` module.exports = { allowedHeaders: ['custom-header'], }; ``` ## `allowedUnsafeExecutions` This should be configured to a list of commands which are allowed to be run automatically as part of a dependency upgrade. This is a separate class of commands that could be executed compared to [`allowedCommands`](#allowedcommands), or package managers that are controlled with [`allowScripts=true`](#allowscripts) and [`ignoreScripts=false`](./configuration-options.md#ignorescripts), where seemingly “safe” commands can result in code execution. As there is a security risk of running these commands automatically when a dependency upgrades, self hosted implementations need to explicitly declare which commands are permitted for their installation. For more details of where this may be found, see [“Trusting Repository Developers”](./security-and-permissions.md#trusting-repository-developers). Allowed options: Option Description `bazelModDeps` Allows the `bazel mod deps` when perfoming bazelisk or bazel-module updates. `goGenerate` Allows the `goGenerate` `postUpdateOption` to run after a go mod update. `gradleWrapper` Allows using `./gradlew` or `gradle.bat` when performing updates with Gradle. `mise` Allows running any `mise` commands, for instance `mise lock` when updating `mise.lock` files. ## `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`. 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](./string-pattern-matching.md). 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` 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` 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. ``` { "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](./string-pattern-matching.md). ## `autodiscoverRepoOrder` 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. Platform supported sort options: Platform Supported sort options GitLab `created_at`, `updated_at`, `id` Forgejo, Gitea `alpha`, `created`, `updated`, `size`, `id` > If multiple `autodiscoverTopics` are used resulting order will be per topic not global. ## `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](https://support.atlassian.com/bitbucket-cloud/docs/branch-a-repository/#The-branching-model) 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 three 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](https://github.com/containerbase/base) environment, otherwise falls back to `global` - `hermit`: Uses the [Hermit](https://github.com/cashapp/hermit) tool installation approach. 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. !!! warning The usage of `binarySource=docker` is deprecated, and [will be removed in the future](https://github.com/renovatebot/renovate/issues/40747). We also have a deprecated `docker` mode. For this to work, `docker` needs to be installed and the Docker socket available to Renovate. If you are using this mode, and cannot migrate to `binarySource=install`, [please provide feedback in this Discussion](https://github.com/renovatebot/renovate/discussions/40742). ## `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 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/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`](./self-hosted-configuration.md#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` In the self-hosted setup, use option to enable caching of private packages to improve performance. ## `cacheTtlOverride` 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`](./self-hosted-configuration.md#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`](./self-hosted-configuration.md#cacheprivatepackages). Other valid cache namespaces are as follows: ## `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.\` ## `configFileNames` 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`](#onboardingconfigfilename). ## `configValidationError` If enabled, config validation errors will be reported as errors instead of warnings, and Renovate will exit with a non-zero exit code. ## `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. !!! 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. 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. 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` 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: - `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` 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 `ghcr.io/renovatebot/base-image` 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` 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](https://docs.docker.com/config/containers/resource_constraints/) to learn more. ## `dockerMaxPages` 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` By default Renovate pulls the sidecar Docker containers from `ghcr.io/renovatebot/base-image`. 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/renovatebot/base-image`. ## `dockerUser` 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](https://docs.docker.com/engine/reference/run/#user) for more information on user and group syntax. Set this to `1001:1002` to use UID 1001 and GID 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` 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` 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` ## `executionTimeout` Default execution timeout in minutes for child processes Renovate creates. If this option is not set, Renovate will fallback to 15 minutes. ## `exposeAllEnv` 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`](./self-hosted-configuration.md#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` 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` 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` 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. ## `forkOrg` 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 ## `forkToken` 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. ## `gitNoVerify` 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](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---no-verify) and [git push –no-verify](https://git-scm.com/docs/git-push#Documentation/git-push.txt---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](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks). ## `gitPrivateKey` 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` 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` 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` 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 !!! note On GitHub, `default` and `endpoint` are equivalent: both build the HTTPS URL from the configured endpoint with credentials embedded. `ssh` uses the repository’s `sshUrl` and authenticates via SSH key. In fork mode (`forkToken` set with `forkCreation`), `ssh` applies to both the fork’s working URL and the upstream URL. ## `githubTokenWarn` 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` 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` 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` 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` 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` 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` 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` 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` 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` `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` 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` 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/](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`](configuration-options.md#packagerulesmatchconfidence) `packageRule`, you only need to set this variable at the _workers_. This feature is in private beta. ## `migratePresets` 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` 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 ## `onboardingAutoCloseAge` Maximum number of days after which Renovate will stop trying to onboard the repository, and will close any existing onboarding PRs. By default this option is set to `null`. ## `onboardingBranch` !!! 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` 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` ## `onboardingConfigFileName` If set to one of the valid [config file names](./configuration-options.md), 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`](#configfilenames) option. ## `onboardingNoDeps` 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` 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` ## `optimizeForDisabled` 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` ## `persistRepoData` 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` ## `prCacheSyncMaxPages` Maximum number of pages to fetch when syncing the pull request cache. ## `prCommitsPerRunLimit` 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` 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](#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` 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](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 = key expires in n days w = key expires in n weeks m = key expires in n months 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 " 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 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 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](https://app.renovatebot.com/encrypt) for your own use. !!! note “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` 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` Used as an alternative to `privateKey`, if you want the key to be read from disk instead. ## `privateKeyPathOld` Used as an alternative to `privateKeyOld`, if you want the key to be read from disk instead. ## `processEnv` 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` 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` 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 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` ## `reportFormatting` This option only applies when [`reportType`](#reporttype) is `file` or `s3`. ## `reportPath` `reportPath` describes the location where the report is written to. If [`reportType`](#reporttype) is set to `file`, then set `reportPath` to a filepath. For example: `/foo/bar.json`. If the value `s3` is used in [`reportType`](#reporttype), then use a S3 URI. For example: `s3://bucket-name/key-name`. ## `reportType` Defines how the report is exposed: - `` 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`](#reportpath) - `s3` The report is pushed to an S3 bucket defined by [`reportPath`](#reportpath). This option reuses [`s3Endpoint`](#s3endpoint) and [`s3PathStyle`](#s3pathstyle) ## `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` 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. ## `repositoryCacheForceLocal` If set to `true`, Renovate will persist repository cache locally after uploading to S3. This is useful if you want to keep a local copy of the cache for debugging purposes or for faster access to the cache. ## `repositoryCacheType` ``` { repositoryCacheType: 's3://bucket-name'; } ``` Renovate uses the [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) 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](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromnodeproviderchain). !!! 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 latter remotely, define [Redis URL](#redisurl). ## `requireConfig` 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. ## `s3PathStyle` 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](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/bucketendpointinputconfig.html) to learn more about path-style URLs. ## `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` ## `unicodeEmoji` If enabled emoji shortcodes are replaced with their Unicode equivalents. For example: `:warning:` will be replaced with `⚠️`. ## `useCloudMetadataServices` Some cloud providers offer services to receive metadata about the current instance, for example [AWS Instance metadata](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-instance-metadata.html) or [GCP VM metadata](https://cloud.google.com/compute/docs/metadata/overview). You can control if Renovate should try to access these services with the `useCloudMetadataServices` config option. !!! note This should only be set via an environment variable, as it is used before Renovate initialises its global configuration. ## `userAgent` Specifies the `user-agent` header sent with HTTP requests. Supports `{{renovateVersion}}` as a template variable for the current Renovate version. ## `username` 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` 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](#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` 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](https://github.com/renovatebot/renovate/discussions/13172). Usage: `renovate --write-discovered-repos=/tmp/renovate-repos.json` ``` ["myOrg/myRepo", "myOrg/anotherRepo"] ``` ## [Self-hosted experimental environment variables](https://docharvest.github.io/docs/renovate/usage/self-hosted-experimental/) Contents renovate Self Hosted Experimental Renovate Self Hosted Experimental The following environment variables are “experimental” because they: - are not commonly needed - are typically an effort to work around some other service’s or platform’s problem - can be removed at any time - are variables for Renovate’s internal use to validate they work as intended Experimental variables which are commonly used and for which there is no external solution in sight can be converted to an official configuration option by the Renovate bot developers. Use these experimental variables at your own risk. We do not follow Semantic Versioning for any experimental variables. These variables may be removed or have their behavior changed in **any** version. We will try to keep breakage to a minimum, but make no guarantees that an experimental variable will keep working. ## `OTEL_EXPORTER_OTLP_ENDPOINT` If set, Renovate will export OpenTelemetry data to the supplied endpoint. For more information see [the OpenTelemetry docs](opentelemetry.md). ## `RENOVATE_PAGINATE_ALL` If set to any value, Renovate will always paginate requests to GitHub fully, instead of stopping after 10 pages. ## `RENOVATE_X_DOCKER_HUB_DISABLE_LABEL_LOOKUP` If set to any value, Renovate will skip attempting to get release labels (e.g. gitRef, sourceUrl) from manifest annotations for `https://index.docker.io`. Due to the missing label information like sourceUrl, Renovate will not be able to perform certain actions dependent on these information for the images. This includes the following: - Generating changelogs - Applying package rules dependent on the labels - Including the sourceUrls in PR bodies ## `RENOVATE_X_DOCKER_HUB_TAGS_DISABLE` If set to any value, Renovate will stop using the Docker Hub API (`https://hub.docker.com`) to fetch tags and instead use the normal Docker API for images pulled from `https://index.docker.io`. ## `RENOVATE_X_ENCRYPTED_STRICT` If set to `"true"`, a config error Issue will be raised in case repository config contains `encrypted` objects without any `privateKey` defined. ## `RENOVATE_X_EXEC_GPID_HANDLE` If set, Renovate will terminate the whole process group of a terminated child process spawned by Renovate. ## `RENOVATE_X_GITLAB_AUTO_APPROVE_TOKEN` If set, when `autoApprove` is enabled, the provided token is used to authenticate GitLab approve requests instead of the default one. This is useful in environments where a user cannot approve its own PRs. ## `RENOVATE_X_GITLAB_AUTO_MERGEABLE_CHECK_ATTEMPS` If set to an positive integer, Renovate will use this as the number of attempts to check if a merge request on GitLab is mergeable before trying to automerge. The formula for the delay between attempts is `RENOVATE_X_GITLAB_MERGE_REQUEST_DELAY * attempt * attempt` milliseconds. Default value: `5` (attempts results in max. 13.75 seconds timeout). ## `RENOVATE_X_GITLAB_BRANCH_STATUS_CHECK_ATTEMPTS` If set to a positive integer, Renovate will use this as the number of attempts to check branch status before trying to add a status check. The delay between attempts is `RENOVATE_X_GITLAB_BRANCH_STATUS_DELAY` milliseconds. Default value: `2` (attempts results in maximum 2 seconds timeout). !!! warning Increasing this value too much penalizes projects that do not have defined pipelines, Renovate will systematically wait `RENOVATE_X_GITLAB_BRANCH_STATUS_CHECK_ATTEMPTS * RENOVATE_X_GITLAB_BRANCH_STATUS_DELAY` milliseconds on these projects and slow down the Renovate analyzes. ## `RENOVATE_X_GITLAB_BRANCH_STATUS_DELAY` Adjust default time (in milliseconds) given to GitLab to create pipelines for a commit pushed by Renovate. Can be useful for slow-running, self-hosted GitLab instances that don’t react fast enough for the default delay to help. Default value: `1000` (milliseconds). ## `RENOVATE_X_GITLAB_MERGE_REQUEST_DELAY` If set, Renovate will use this as a delay to proceed with an automerge. Default value: `250` (milliseconds). ## `RENOVATE_X_GITLAB_SKIP_STATUS_WITHOUT_PIPELINE` If set to `true` value, Renovate will skip setting a branch status check on GitLab when no pipeline is found for the commit. This is useful for GitLab configurations where pipelines are only created for merge requests, not for branches. ## `RENOVATE_X_HARD_EXIT` If set to any value, Renovate will use a “hard” `process.exit()` once all work is done, even if a sub-process is otherwise delaying Node.js from exiting. See [issue 8660](https://github.com/renovatebot/renovate/issues/8660) for background on why this was created. ## `RENOVATE_X_IGNORE_RE2` Skip initializing `RE2` for regular expressions and instead use Node-native `RegExp` instead. ## `RENOVATE_X_NUGET_DOWNLOAD_NUPKGS` If set to any value, Renovate will download `nupkg` files for determining package metadata. ## `RENOVATE_X_PGP_RUNTIME` Specify which PGP runtime to use for decrypting Renovate config. Allowed values are `js-java`, `wasm-java` and `wasm-dotnet`. !!! note `js-java` and `wasm-dotnet` are not recommended due to performance reasons. Incompatible with `RENOVATE_X_USE_OPENPGP`. Default: `wasm-java`. ## `RENOVATE_X_PLATFORM_VERSION` Specify this string for Renovate to skip API checks and provide Bitbucket server, Forgejo or GitLab version directly. Particularly useful with GitLab’s `CI_JOB_TOKEN` to authenticate Renovate or to reduce API calls for Bitbucket. Read [platform details](modules/platform/gitlab/index.md) to learn why we need the server version on GitLab. ## `RENOVATE_X_REBASE_PAGINATION_LINKS` If set, Renovate will rewrite GitHub Enterprise Server’s pagination responses to use the `endpoint` URL from the Renovate config. !!! note For the GitHub Enterprise Server platform only. ## `RENOVATE_X_SQLITE_BUSY_TIMEOUT` Set the SQLite busy timeout in milliseconds. Defaults to `5000`. Only applies when `RENOVATE_X_SQLITE_PACKAGE_CACHE` is set. ## `RENOVATE_X_SQLITE_PACKAGE_CACHE` If set, Renovate will use SQLite as the backend for the package cache. Don’t combine with `redisUrl`, Redis would be preferred over SQlite. ## `RENOVATE_X_STATIC_REPO_CONFIG_FILE` If set to a valid path pointing to a file containing a _valid_ Renovate configuration in `JSON` format, it will be applied to the repository config before resolving the actual configuration file within the repository. !!! warning If the file is missing or contains invalid configuration, the scan will be aborted. !!! note You probably **shouldn’t use this** unless you have a very specific reason to override the repository’s normal configuration resolution process. ## `RENOVATE_X_SUPPRESS_PRE_COMMIT_WARNING` Suppress the pre-commit support warning in PR bodies. ## `RENOVATE_X_USE_OPENPGP` !!! note Incompatible with `RENOVATE_X_PGP_RUNTIME`. Use `openpgp` instead of [Bouncy Castle](https://www.bouncycastle.org/) for `PGP` decryption. ## `RENOVATE_X_YARN_PROXY` Configure global Yarn proxy settings if HTTP proxy environment variables are detected. ## [Semantic Commit messages](https://docharvest.github.io/docs/renovate/usage/semantic-commits/) Contents renovate Semantic Commit messages Renovate Semantic Commit messages Renovate looks at the last 20 commit messages in the base branch to decide if the repository uses semantic commits. If there are Semantic Commits, Renovate uses an algorithm inspired by the [conventional-commits-detector](https://github.com/conventional-changelog/conventional-commits-detector) package to decide what convention the commit messages follow. Merge commits are ignored when looking for semantic commits, so they do not affect the result. Renovate can only find [conventional commits](https://www.conventionalcommits.org) style (including Angular-style conventional commits), it does not “understand” other commit conventions. When Renovate finds conventional commits, Renovate creates commit messages and PR titles like this: - chore(deps): update eslint to v7.30.0 By default, Renovate uses the `chore` prefix. If you extend from `config:recommended` then Renovate uses the `chore` prefix for nearly all updates. There are some exceptions: - if the `depType` is a known “production dependency” type (e.g. `dependencies` or `require`), then Renovate uses the `fix` prefix - if an update uses the `maven` datasource _and_ `matchDepTypes` is a known production type (e.g. `compile`, `provided`, `runtime`, `system`, `import` or `parent`) then Renovate uses the `fix` prefix Be aware that the semantic commits feature does not work if you have a `commitMessagePrefix` configured - `commitMessagePrefix` will take priority. ## Manually enabling or disabling semantic commits You can override the default settings, and disable or enable Semantic Commits. ``` { "extends": [":semanticCommits"] } ``` ``` { "extends": [":semanticCommitsDisabled"] } ``` ## Changing the Semantic Commit type You can change the Semantic Commit type that Renovate uses. For example: - If you want Renovate to use the “chore” type for every PR, add `":semanticCommitTypeAll(chore)"` to your `extends` array: ``` { "extends": [":semanticCommitTypeAll(chore)"] } ``` PR titles and commit messages start with `chore(deps):`. - If you want Renovate to use the “ci” type for every PR, add `":semanticCommitTypeAll(ci)"` to your `extends` array: ``` { "extends": [":semanticCommitTypeAll(ci)"] } ``` PR titles and commit messages start with `ci(deps):`. ## Changing the Semantic Commit scope You can set your own word for the scope, if you do not like the default “deps” scope. For example, to set the scope to “package”, add the preset `":semanticCommitScope(package)"` to your `extends` array: ``` { "extends": [":semanticCommitScope(package)"] } ``` To _remove_ the Semantic Commit scope, so Renovate uses `chore:` instead of `chore(deps):`, add the `":semanticCommitScopeDisabled"` preset to your `extends` array: ``` { "extends": [":semanticCommitScopeDisabled"] } ``` ## [String Pattern Matching - Regex or Glob](https://docharvest.github.io/docs/renovate/usage/string-pattern-matching/) Contents renovate String Pattern Matching Renovate String Pattern Matching Renovate string matching syntax for some configuration options allows you, as user, to choose between: - [`minimatch`](https://github.com/isaacs/minimatch) glob patterns, including exact strings matches - regular expression (regex) patterns In cases where there are potentially multiple _inputs_, e.g. managers can have multiple categories, then the matcher will return `true` if _any_ of them match. ## Special case: Match everything The value `*` is a special case which means “match everything”. It is not valid to combine `*` with any other positive or negative match. ``` { "allowedEnv": ["*"] } ``` ``` { "allowedEnv": ["*", "ABC"] } ``` ``` { "allowedEnv": ["*", "!ABC"] } ``` In the latter case, the `*` can be omitted and achieve the same thing. ## Regex matching A valid regex pattern: 1. Starts with `/` or `!/` 2. Ends with `/` or `/i` ### Regex is case sensitive by default By default, regex patterns are evaluated as case sensitive. To ignore case sensitivity you must set the `i` flag, see the regex patterns table for an example. ### Renovate uses re2 syntax Renovate uses the [`re2` library](https://github.com/google/re2) for regex matching. `re2` is different from the full regex specification, because `re2` has a different syntax/support. For the full `re2` syntax, read [the `re2` syntax wiki page](https://github.com/google/re2/wiki/Syntax). ### Example regex patterns Pattern Regex pattern explanation `/^abc/` matches any string starting with lower-case `abc` `/^abc/i` matches any string starting with `abc` in lower or upper case, or a mix `!/^a/` matches any string not starting with `a` in lower case ### Use regex101 to test your patterns If you want to test your patterns interactively online, we recommend [regex101.com](https://regex101.com/?flavor=javascript&flags=ginst). You can use the Code Generator in the sidebar and copy the regex in the generated “Alternative syntax” comment into JSON. !!! warning “Escape the backslashes from regex101” Before you copy/paste the regex from regex101 into your Renovate config, you must escape the backslashes (`\`) first. For example: `\n\s` → `\\n\\s`. ## Glob matching If the string provided is not a regex pattern then it will be treated as a glob pattern and parsed using the `minimatch` library. Although glob patterns were designed originally for file name matching, many users find glob syntax easier to understand than regex so prefer it. ### Glob patterns always ignore casing Glob patterns are always evaluated with case _insensitivity_ and you can not change this. If you need a case-sensitive pattern you must use a regex pattern. ### Example glob patterns Pattern Glob pattern explanation `abc123` matches `abc123` exactly, or `AbC123` `abc*` matches `abc`, `abc123`, `ABCabc`, but not `abc/def` `abc**/*` matches `abc/def` but not `abc`, `abcd`, or `abc/def/ghi`, `abc**/**` matches `abc/def` and `abc/def/ghi`, but not `abc` or `abcd` `abc{/,}**` matches `abc`, `abcd`, `abc/def`, and `abc/def/ghi` All matches above are case-insensitive, even if not shown. ### Test your glob patterns If you want to test your glob patterns interactively online, we recommend [Digital Ocean’s glob tool](https://www.digitalocean.com/community/tools/glob). ## Negative matching Renovate has a specific approach to negative matching strings. “Positive” matches are patterns (in glob or regex) which do _not_ start with `!`. “Negative” matches are patterns starting with `!`, like `!/^a/` or `!b*`. For an array of patterns to match, the following must be true: - If any _positive_ matches are included, at least _one_ must match - If any _negative_ matches are included, _none_ must match For example, the pattern `["/^abc/", "!/^abcd/", "!/abce/"]`: - matches `"abc"` and `"abcf"` - does _not_ match `"foo"`, `"abcd"`, `"abce"`, or `"abcdef"` If you find yourself in a situation where you need to positive-match a string which starts with `!`, then you need to do so using a regular expression pattern. For example, `["/^!abc$/"]` will positively match against the string `"!abc"`. One limitation of negative matching is when there may be multiple inputs to match against. For example, a manager may have multiple categories, such as `java` and `docker`. If you have a rule such as `"matchCategories": ["!docker"]` then this will return `true` because the `java` category satisfies this rule. ## Usage in Renovate configuration options Renovate has evolved its approach to string pattern matching over time, but this means that existing configurations may have a mix of approaches and not be entirely consistent with each other. The configuration options that support “regex or glob” syntax mention this in their documentation, and also link to this page. ## [Template fields](https://docharvest.github.io/docs/renovate/usage/templates/) Contents renovate Template fields Renovate Template fields In order to provide flexible configuration, Renovate supports using “templates” for certain fields like `addLabels`, `branchName`, `extractVersionTemplate`, `labels`. Renovate’s templates use [handlebars](https://handlebarsjs.com/) under the hood. You can recognize templates when you see strings like `{{depName}}` in configuration fields. Below you can find lists of fields/values that you can use in templates. Some are configuration options passed through, while others are generated as part of Renovate’s run. `logJSON` and `releases` are only allowed in `commitBody` template. ## Options that support templating ## Exposed config options ## Other available fields ## Additional Handlebars helpers ### add Returns the sum of the fields. `{{add major 1}}` In the example above, it will add `1` to the `major` of current version and return the value. ### and Returns `true` only if all expressions are `true`. `{{#if (and isMajor hasReleaseNotes)}}Backwards Incompatible release! Check out the Release notes.{{/if}}` In the example above, it will only show a text if `isMajor=true` and `hasReleaseNotes=true`. ### containsString Returns `true` if a given string is a substring. `{{#if (containsString depName 'python')}}Python{{else}}Other{{/if}}` ### decodeBase64 If you want to convert a Base64 value to a string, use the built-in function `decodeBase64` like this: `{{{decodeBase64 body}}}` In the example above `body` is the base64 encoded value you want to decode. ### decodeURIComponent If you want to decode a percent-encoded string, use the built-in function `decodeURIComponent` like this: `{{{decodeURIComponent depName}}}` In the example above `depName` is the string you want to decode. Read the [MDN Web Docs, decodeURIComponent()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) to learn more. ### distinct Removes duplicate elements from an array. `{{#each (distinct (lookupArray (lookupArray upgrades "prBodyDefinitions") "Issue"))}} {{{.}}}{{/each}}` ### encodeBase64 If you want to convert a string to Base64, use the built-in function `encodeBase64` like this: `{{{encodeBase64 body}}}` In the example above `body` is the string you want to transform into a Base64-encoded value. ### encodeURIComponent If you want to convert a string to a valid URI, use the built-in function `encodeURIComponent` like this: `{{{encodeURIComponent baseDir}}}` In the example above `baseDir` is the string you want to transform into a valid URI. Read the [MDN Web Docs, encodeURIComponent()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) to learn more. ### equals Returns `true` if two values are equal (checks strict equality, i.e. `===`). `{{#if (equals datasource 'git-refs')}}git-refs{{else}}Other{{/if}}` ### includes Returns `true` if an array contains a given string element. `{{#if (includes labels 'ci')}}Has CI label{{else}}No CI label{{/if}}` ### lookupArray Similar to the built-in [`lookup`](https://handlebarsjs.com/guide/builtin-helpers.html#lookup) helper, but performs lookups in every element of an array, instead of just one object. For example: `{{#each (lookupArray upgrades "prBodyDefinitions")}} {{{Issue}}}{{/each}}` will produce the same output as: `{{#each upgrades}}{{#with prBodyDefinitions}} {{{Issue}}}{{/with}}{{/each}}`. The return value of `lookupArray` can be passed to other helpers - for example, to `distinct`. ### lowercase The `lowercase` helper converts a given string to lower case. `{{{ lowercase depName }}}` ### or Returns `true` if at least one expression is `true`. `{{#if (or isPatch isSingleVersion}}Small update, safer to merge and release.{{else}}Check out the changelog for all versions before merging!{{/if}}` ### replace The `replace` helper replaces _all_ found strings matching the given regex with the replacement string. If you want to replace some characters in a string, use the built-in function `replace` like this: `{{{replace '[a-z]+\\.github\\.com' 'ghc' depName}}}` In the example above all matches of the regex `[a-z]+\.github\.com` will be replaced by `ghc` in `depName`. Read the [MDN Web Docs, String.prototype.replace()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) to learn more. ### split Splits a string into an array of substrings. This example splits a package name by `-` and gets the second part: `{{ lookup (split packageName '-') 1 }}` An input of `foo-bar-test` therefore would return `bar`. ### stringToPrettyJSON If you want to print pretty JSON with Handlebars you can use the built-in function `stringToPrettyJSON` like this: `{{{stringToPrettyJSON myvar}}}` In the example above `myvar` is a variable/field, that has valid JSON. ### toArray If you want to convert elements to an array, use `toArray`, e.g., `{{{ toJSON (toArray 'value1' 'value2' 'value3') }}}` will render `["value1","value2","value3"]`. ### toJSON If you want to convert an object to a JSON string, you can use the built-in function `toJSON` like this: `{{{ toJSON upgrades }}}` ### toObject If you want to convert key-value pairs to an object, use `toObject`, e.g., `{{{ toJSON (toObject 'key1' 'value1' 'key2' 'value2') }}}` will render `{"key1":"value1","key2":"value2"}`. ## Environment variables By default, templates can only access [a subset of environment variables](./environment-variable-handling.md#with-child-processes) like `HOME` or `PATH`. This is for security reasons. You can reference environment variables like so: `HOME is {{env.HOME}}` If you’re self-hosting Renovate, you can expose more variables with the [`customEnvVariables`](./self-hosted-configuration.md#customenvvariables) config option, which will also be available to all child processes. See also: [environment variable handling](./environment-variable-handling.md). !!! warning It is possible to use the [`exposeAllEnv`](./self-hosted-configuration.md#exposeallenv) config option to allow all environment variables in templates, but make sure to consider the security implications of giving the scripts unrestricted access to all variables. ## [Troubleshooting Renovate](https://docharvest.github.io/docs/renovate/usage/troubleshooting/) Contents renovate Troubleshooting Renovate Troubleshooting Learn how to troubleshoot problems with Renovate, where to find the logging output, and how to get help if needed. ## Getting the logs Renovate’s debug-level logs are usually enough to help troubleshoot most problems. Where you can find the logs depends on how you’re running Renovate. ### The Mend Renovate App Each pull request from the Mend Renovate App has a link to the [Mend Developer Portal](https://developer.mend.io/) in the PR body text. The text you’re looking for is: > This PR was generated by Mend Renovate. View the repository job log. Select the blue text “repository job log” to go to the Recent jobs page in the [Mend Developer Portal](https://developer.mend.io/). Sign in with your GitHub account. Once you’re logged in, you can see the logs for the Renovate jobs on your repository. You should have access to any repository which you have write access to and which has Renovate installed. The Mend Renovate App provides logs for the most recent 2 weeks of logs, for each repository. After selecting a recent job, you can select the debug level that you care about. For a full overview, select the `DEBUG` log level. ### Self-hosted The easiest way to gather logs from Renovate for any platform is to use the default logging to `stdout`/console. By default, Renovate will log in a human-readable format at `INFO` level. For troubleshooting it’s recommended to increase logging to `DEBUG` level by adding `LOG_LEVEL=debug` to your environment variables before invoking Renovate. If your Renovate logs are being processed by a log service before you access them, you may find it better to have Renovate output logs in JSON format instead so that they can be reliably parsed and filtered. This can be achieved by adding `LOG_FORMAT=json` to your environment variables before invoking Renovate. ## Log debug levels There are different severity levels for the log output. From least severe to most severe: - `DEBUG` - `INFO` - `WARN` - `ERROR` - `FATAL` To check for problems, look for `WARN` or `ERROR` logs (level 40 or 50 if in JSON format). To troubleshoot further, you usually need to look at `DEBUG` logs. ## Resolving problems using logs We recommend you follow this process: 1. Try to narrow in on the problem area e.g. by looking for relevant branches or `WARN` or `ERROR` messages 2. Find all relevant `DEBUG` or `INFO` messages from before and after the problem occurred 3. Copy/paste the relevant parts of the logs into your discussion post or bug report If you cannot fix the problem yourself after reading the logs, and reading - or searching through - our documentation, search the [`renovatebot/renovate` discussion](https://github.com/renovatebot/renovate/discussions) forum to see if somebody has asked a similar or related question. If none of these steps have helped you, then create a new discussion post to get help from the Renovate maintainers. Please locate the relevant parts of the logs as described earlier before asking for help or posting a bug report. Do not expect the Renovate maintainers to read through the full logs when trying to help you, as that takes a lot of time on our part. If later it turns out that the full logs are necessary, you will be asked for them then. ## Validating configuration changes Sometimes you will have to change your Renovate configuration to solve a problem. The [`renovate-config-validator` program](config-validation.md) helps validate such configuration changes without committing them to your repository. ## [Updating and rebasing branches](https://docharvest.github.io/docs/renovate/usage/updating-rebasing/) Contents renovate Updating and Rebasing branches Renovate Updating and Rebasing branches There are many situations in which Renovate must update/rebase a branch. Here is a list of the most common cases where Renovate must update/rebase the branch: - When a pull request has conflicts due to changes on the base branch - When you have enabled “Require branches to be up to date before merging” on GitHub - When you have manually told Renovate to rebase when behind the base branch with `"rebaseWhen": "behind-base-branch"` - When you have set `keepUpdatedLabel` and included the label on a PR - When a newer version of the dependency is released - When you request a manual rebase from the Renovate bot - When you use `"automerge": true` and `"rebaseWhen": "auto"` on a branch / pr Renovate uses its own version of “rebasing”, which is _not the same_ as doing a `git rebase` with Git. Instead, Renovate reapplies all updates into a new commit based off of the head of the base branch. ## No rebasing if you have made edits First of all, here is the one time when Renovate _won’t_ update branches. If you push a new commit to a Renovate branch, for example to fix your code so the tests pass, then Renovate stops all updates of that branch. It is up to you to either finish the job and merge the PR, or rename it and close it so that Renovate can take over again. !!! warning Do _not_ amend Renovate’s commits, because Renovate will rebase over your amended commit. Keep your work safe and always push your own _new_ commit to any Renovate branch. ## Rebasing conflicted PRs If new commits to the base branch - such as merging another Renovate PR - result in an open Renovate PR having merge conflicts, then Renovate will recreate (“rebase”) any conflicted PRs. This applies both to commits to dependency files such as `package.json` as well as lock files such as `yarn.lock`. You should not ever need to resolve such conflicts manually. You can disable this functionality by configuring `"rebaseWhen": "never"` (not recommended). ## Rebasing out-of-date branches There are multiple cases where Renovate will rebase its branches off the base branch every time they are out of date: 1. If you configure `"rebaseWhen": "behind-base-branch"` 2. If you use the default configuration `"rebaseWhen": "auto"` and the repository has a requirement that branches must be up-to-date before merging (e.g. “Require branches to be up to date before merging” on GitHub, or fast-forward-only settings on Bitbucket Server or GitLab) 3. If you use the default configuration `"rebaseWhen" : "auto"` and configure `"automerge" : true` In that case Renovate PRs will be rebased off the repository’s base branch whenever they are behind the base branch, even if the PRs are not conflicted. ## Newer dependency versions If an existing PR is open to upgrade dependency “foo” to v1.1.0 and then v1.1.1 is released, then Renovate will regenerate the branch again. This way: - Each Renovate branch will always have 1 and only 1 commit - The newest version will be based off the latest base branch commit at the time ## Manual rebasing You can request that Renovate rebase a PR by selecting the rebase/retry checkbox on GitHub or GitLab. Or you can add a “rebase” label to the PR. The label name is configurable via the `rebaseLabel` option. If you apply a rebase label then Renovate will regenerate its commit for the branch, even if the branch has been modified. The rebase label is useful in situations like: - If a branch is behind the base branch but you don’t have `rebaseWhen=behind-base-branch` enabled - If a branch has been edited and you want to discard the edits and have Renovate create it again - If a branch was created with an error (e.g. lockfile generation) and you want Renovate to try again ## [Upgrade best practices](https://docharvest.github.io/docs/renovate/usage/upgrade-best-practices/) Contents renovate Upgrade Best Practices Renovate Upgrade Best Practices This page explains what we (the Renovate maintainers) recommend you do to update your dependencies. ## General recommendations In general, you should: - Run Renovate on _every_ repository - Use the `config:best-practices` preset, instead of the `config:recommended` preset - Use the Dependency Dashboard issue (it’s on by default) - Update your dependencies often - Read the changelogs for the updates - Update to new `major` versions in good time - Talk with your team about the update strategy If Renovate is too noisy for you, read the [noise reduction docs](./noise-reduction.md). ## Use the `config:best-practices` preset The `config:recommended` preset is the recommended configuration for most Renovate users. Renovate also has a `config:best-practices` preset that includes our upgrade best practices. You should extend from the `config:best-practices` preset: ``` { "extends": ["config:best-practices"] } ``` If you’re using `config:recommended` now, replace it with `config:best-practices`: ``` - "extends": ["config:recommended"] + "extends": ["config:best-practices"] ``` ### What’s in the `config:best-practices` preset? The [`config:best-practices` preset](./presets-config.md#configbest-practices) has this configuration: ``` { "extends": [ "config:recommended", "docker:pinDigests", "helpers:pinGitHubActionDigests", ":configMigration", ":pinDevDependencies", "abandonments:recommended", "security:minimumReleaseAgeNpm", ":maintainLockFilesWeekly" ] } ``` The next sections explain what each part of the preset does. #### Config migration Renovate creates a config migration PR to replace old config option names with their new replacements. This way your configuration file and the Renovate docs always use the same terms. You’ll get config migration PRs no matter _how_ you run Renovate: self-hosting or the Mend Renovate app. #### Extends `config:recommended` The `config:recommended` preset is a good base to start from. That’s why we extend from it. #### Extends `docker:pinDigests` The [Renovate docs, Docker Digest pinning](./docker.md#digest-pinning) section explains _why_ you should pin your Docker containers to an exact digest. #### Extends `helpers:pinGitHubActionDigests` The [GitHub Docs, using third-party actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions) recommend that you pin third-party GitHub Actions to a full-length commit SHA. We recommend pinning _all_ Actions. That’s why the `helpers:pinGitHubActionDigests` preset pins all GitHub Actions. For an in-depth explanation why you should pin your Github Actions, read the [Palo Alto Networks blog post about the GitHub Actions worm](https://www.paloaltonetworks.com/blog/prisma-cloud/github-actions-worm-dependencies/). #### Extends `:pinDevDependencies` Pinning your development dependencies means you, and your team, are using the same versions of development tools. This makes the developer-tool side of your builds reproducible. Debugging faulty versions of your tools is easier, because you can use Git to check out different versions of the tools. ## Why updating often is easier, faster and safer You may think that updating takes too much time. But updating regularly actually _saves_ you time, because: - Regular updates tend to be small - Applying `major` updates is easier - You’ll be ready for CVE patches - You’ll look for ways to automate the updates ### Regular updates tend to be small Firstly, when you update regularly updates tend to be small. The update’s changelogs are small, quick to read, and easy to understand. You probably only need to make changes in a few places (if at all) to merge the PR and get going again. Because you’re reading the changelogs regularly, you’ll get a feel for the direction of the upstream project. ### Applying `major` updates is easier Secondly, when you’re current with upstream, `major` updates are easier. This is because you already: - follow the latest best practices of upstream - use the latest names for features/variables - read the previous changelogs ### You’ll be ready for CVE patches Thirdly, you’ll be ready when a upstream package releases a patch for a critical CVE. If you’re current, you can review and merge Renovate’s PR quickly. When you’re behind on updates, you’ll have a bad time, because you must read _more_ changelogs and make _more_ changes before you can merge the critical patch. ### You’ll look for ways to automate the updates Finally, when you’re updating often, you’ll start looking for ways to automate the updates. You may start to [`automerge`](./configuration-options.md#automerge) development dependencies like Prettier, or ESLint when the linter passes. Or you may decide to automerge any `patch` type upgrades, by using the [`default:automergePatch`](./presets-default.md#automergepatch) preset. #### Wait two weeks before automerging third-party dependencies If you `automerge` third-party dependencies, we recommend setting [`minimumReleaseAge`](./configuration-options.md#minimumreleaseage) to `"14 days"`. By waiting two weeks before automerging the dependencies, you give the upstream registries time to pull malicious dependencies, before Renovate merges them. If you want a third-party dependency update _now_, instead of waiting two weeks, you can request the update from the Dependency Dashboard. #### Use GitHub Pull Request Merge Queues You may also start using [GitHub’s pull request merge queues](./key-concepts/automerge.md#github-merge-queue) to speed up the merge process. On GitLab projects with merge trains enabled, Renovate adds automerged MRs to the merge train automatically (requires GitLab 17.11 or later). ## Starting from a new project Let’s assume you’re starting a new project. You created a new Git repository, installed the latest frameworks, libraries and development tools. After pushing the initial commit, you should enable and onboard Renovate. Now you’ll have to stay on the “update often” train. ## Project with one year old dependencies If you have a project that’s a year behind on dependencies, you’ll need to do some work. Let’s assume that most dependencies need a `patch` or `minor` update, and at _least_ one dependency needs a `major` update. Start small, and get the `patch` and `minor` updates first. Read the changelogs for your updates. You may have to make small changes to get things working again. When you have the latest `patch` and `minor` versions, you are ready for `major` updates. Start with `major` version updates for tools like Prettier or ESLint. Then work on `major` updates for your framework or library. Take your time, read the changelogs, and make the necessary changes. Let multiple team members review your work before merging, it’s easy to miss something. Finally, update your development tools. Now you’re up to date, you should think how to make updating a regular habit. ## Project with five year old dependencies Let’s assume your Dependency Dashboard lists more than 50 updates, and you have a few `major` version updates pending. If your project is this badly behind on updates, you have two problems: - Updating your dependencies - Improving your update process ### Focus on critical updates first Fix the easier problem first: getting back up to date. Update any dependencies that have critical updates for CVEs or other security related improvements. If you’re on the GitHub platform: follow the steps listed in the [`vulnerabilityAlerts`](./configuration-options.md#vulnerabilityalerts) docs to make sure Renovate is reading GitHub’s Vulnerability Alerts. You may want to enable the experimental `osvVulnerabilityAlerts` config option, to get OSV-based vulnerability alerts for _direct_ dependencies. Read the [`osvVulnerabilityAlerts` config option docs](./configuration-options.md#osvvulnerabilityalerts) to learn more. ### Fix blocking updates Next, update any dependency that’s blocking another update. You may need to update dependency `A` before you can update dependency `B` or `C`. In that case, update dependency `A` first. ### Update to latest `minor` or `patch` of current version Then update all dependencies to their latest `minor` or `patch` version, to prepare for the `major` updates. ### Take `major` updates in sequence Take `major` updates in sequence. This way you’ll read the changelogs for each `major` version, and learn _why_ upstream made certain breaking changes. Say you’re on version `1` of a dependency, and the latest `major` version is at `4`. You should update to `2`, then `3` and finally `4`. Avoid updating from `1` directly to `4`. Use the [`:separateMultipleMajorReleases`](./presets-default.md#separatemultiplemajorreleases) preset to get separate `major` updates. ### Update development tools Finally update development tools like Prettier, ESLint, TSLint, Cypress, and so on. ### Improve the human side You’re done with the _technical_ side. Now comes the harder part, fixing the _human_ side. There are probably a number of reasons why the project got this badly out of date. When working on the human side, focus on the process, rules, and habits. Avoid blaming developers for not updating often. ## Why developers avoid updating Let’s assume most developers _want_ a project that’s up to date. So why are your developers avoiding updates? Some common reasons: - Developers get blamed when things break in production - There are no tests, so merging updates is scary - The test suite is slow - Releasing a new version of the project must be done by hand - Updating must be done by hand - The company doesn’t allow developer time for updates - The company has complex rules about updates If updating is painful, or takes a lot of time, developers tend to avoid it. Make it easy and fast to update dependencies. ### Talk with your team about the update process Listen to your team, write down their problems. Then fix each problem as best as you can. ### Make updating easy and fast Respect your developer’s time and brains: - Run Renovate on _all_ projects - Use Renovate to propose updates - Building the project _must_ be as fast as possible - Have automated tests for the critical path of your project - Run the automated tests on _every_ pull request - If you’re on GitHub: use [GitHub’s Merge Queue](./key-concepts/automerge.md#github-merge-queue) to speed up merges - Follow SemVer versioning - Use the [`semantic-release` bot](https://github.com/semantic-release/semantic-release) to automate the release process - Refactor existing code to make future changes easier #### Ground rules As a starting point: - Avoid long lived branches that diverge from `main` over time - Dig beyond “developer error” when things go wrong, again: focus on the process - Ensure company policy allows frequent updates ## How we use Renovate - We run Renovate on all repositories - Most of our repositories have automated tests for the critical path of the application - We automerge some dependencies, but request `major` updates from the Dependency Dashboard - When a developer merges a breaking change, we revert to a known-good version, and try again later - We automated the release with the [`semantic-release`](https://github.com/semantic-release/semantic-release) bot - We spend time to make our build and automated tests as fast as possible ## How others use Renovate Read the [Swissquote user story](./user-stories/swissquote.md) to see how they use Renovate. ## Recommended reading There’s a lot of good information out there, so we can only highlight a few resources. Martin Fowler has two great resources: - The free page [Patterns for Managing Source Code Branches](https://martinfowler.com/articles/branching-patterns.html) to help you decide what Git branch pattern to use - The book [Refactoring, Improving the Design of Existing Code](https://martinfowler.com/books/refactoring.html) to help your developers gradually refactor to clean, modular and easy to read code The `git bisect` command can help you find the commit that introduced a bug, or other behavior change. Read the [ProGit 2 book, section on binary search](https://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git#_binary_search) to learn more. ## [Maintaining AUR packages with Renovate](https://docharvest.github.io/docs/renovate/usage/user-stories/maintaining-aur-packages-with-renovate/) Contents renovate Maintaining AUR packages with Renovate Renovate Maintaining AUR packages with Renovate > This article was written by [Jamie Magee](https://github.com/JamieMagee) and originally published on [Jamie Magee’s blog](https://jamiemagee.co.uk/blog/maintaining-aur-packages-with-renovate/). !!! note Jamie Magee helps to maintain Renovate. They obviously like Renovate, and want you to use it. One big advantage that Arch Linux has over other distributions, apart from being able to say “BTW I use Arch.”, is the Arch User Repository (AUR). It’s a community-driven repository with over 80,000 packages. If you’re looking for a package, chances are you’ll find it in the AUR. Keeping all those packages up to date, takes a lot of manual effort by a lot of volunteers. People have created and used tools, like [`urlwatch`](https://github.com/thp/urlwatch) and [`aurpublish`](https://github.com/eli-schwartz/aurpublish), to let them know when upstream releases are cut and automate some parts of the process. I know I do. But I wanted to automate the entire process. I think [Renovate](https://github.com/renovatebot/renovate/) can help here. ## Updating versions with Renovate Renovate is an automated dependency update tool. You might have seen it opening pull requests on GitHub and making updates for npm or other package managers, but it’s a lot more powerful than just that. Renovate has a couple of concepts that I need to explain first: [datasources](../modules/datasource/index.md) and [managers](../modules/manager/index.md). Datasources define where to look for new versions of a dependency. Renovate comes with over 50 different datasources, but the one that is important for AUR packages is the [`git-tags` datasource](../modules/datasource/git-tags/index.md). Managers are the Renovate concept for package managers. There isn’t an AUR or `PKGBUILD` manager, but there is a [regex manager](../modules/manager/regex/index.md) that I can use. I can create a `renovate.json` configuration with the following custom manager configuration: ``` { "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/(^|/)PKGBUILD$/"], "matchStrings": [ "pkgver=(?.*) # renovate: datasource=(?.*) depName=(?.*)" ], "extractVersionTemplate": "^v?(?.*)$" } ] } ``` Breaking that down: - The `managerFilePatterns` setting tells Renovate to look for any `PKGBUILD` files in a repository - The `matchStrings` is the regex format to extract the version, datasource, and dependency name from the `PKGBUILD` - The `extractVersionTemplate` is to handle a “v” in front of any version number that is sometimes added to Git tags And here’s an extract from the PKGBUILD for the [bicep-bin](https://aur.archlinux.org/packages/bicep-bin) AUR package that I maintain: ``` pkgver=0.15.31 # renovate: datasource=github-tags depName=Azure/bicep ``` Here I’m configuring Renovate to use the [`github-tags`](../modules/datasource/github-tags/index.md) datasource and to look in the [`Azure/bicep` GitHub repository](https://github.com/Azure/bicep) for new versions. That means it’ll look in the [list of tags for the `Azure/bicep` repository](https://github.com/Azure/bicep/tags) for any new versions. If Renovate finds any new versions, it’ll automatically update the `PKGBUILD` and open a pull request with the updated version. So I’ve automated the `PKGBUILD` update, but that’s only half of the work. The checksums and `.SRCINFO` must be updated before pushing to the AUR. Unfortunately, Renovate can’t do that (yet, see [Renovate issue #16923](https://github.com/renovatebot/renovate/issues/16923)), but GitHub Actions can! ## Updating checksums and `.SRCINFO` with GitHub Actions Updating the checksums with `updpkgsums` is easy, and generating an updated `.SRCINFO` with `makepkg --printsrcinfo > .SRCINFO` is straightforward too. But doing that for a whole repository of AUR packages is going to be a little trickier. So let me build up the GitHub actions workflow step-by-step. First, I only want to run this workflow on pull requests targeting the `main` branch. ``` on: pull_request: types: - opened - synchronize branches: - main ``` Next, I’m going to need to check out the entire history of the repository, so I can compare the files changed in the latest commit with the Git history. ``` jobs: updpkgsums: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4.0.0 with: fetch-depth: 0 ref: ${{ github.ref }} ``` Getting the package that changed in a pull request requires a little bit of shell magic. ``` - name: Find updated package run: | #!/usr/bin/env bash set -euxo pipefail echo "pkgbuild=$(git diff --name-only origin/main origin/${GITHUB_HEAD_REF} "*PKGBUILD" | head -1 | xargs dirname)" >> $GITHUB_ENV ``` Now I’ve found the package that changed in the Renovate pull request, I can update the files. This step in the workflow uses a private GitHub Action that I have in my `aur-packages` repository. I’m not going to break it down here, but at its core it runs `updpkgsums` and `makepkg --printsrcinfo > .SRCINFO` with a little extra configuration required to run Arch Linux on GitHub Actions runners. You can [check out the full code on GitHub](https://github.com/JamieMagee/aur-packages/tree/main/.github/actions/aur). ``` - name: Validate package if: ${{ env.pkgbuild != '' }} uses: ./.github/actions/aur with: action: 'updpkgsums' pkgname: ${{ env.pkgbuild }} ``` Finally, once the `PKGBUILD` and `.SRCINFO` are updated I need to commit that change back to the pull request. ``` - name: Commit if: ${{ env.pkgbuild != '' }} uses: stefanzweifel/git-auto-commit-action@3ea6ae190baf489ba007f7c92608f33ce20ef04a # v4.16.0 with: file_pattern: '*/PKGBUILD */.SRCINFO' ``` Check out [this pull request for `bicep-bin`](https://github.com/JamieMagee/aur-packages/pull/62) where Renovate opened a pull request, and my GitHub Actions workflow updated the `b2sums` in the `PKGBUILD` and updated the `.SRCINFO`. But why stop there? Let’s talk about publishing. ## Publishing to the AUR Each AUR package is its own Git repository. So to update a package in the AUR, I only need to push a new commit with the updated `PKGBUILD` and `.SRCINFO`. Thankfully, [KSXGitHub](https://github.com/KSXGitHub) created the [`github-actions-deploy-aur` GitHub Action](https://github.com/KSXGitHub/github-actions-deploy-aur) to streamline the whole process. If I create a new GitHub Actions workflow to publish to the AUR, I can reuse the first two steps from my previous workflow to check out the repository and find the updated package. Then all I need to do is to use the `github-actions-deploy-aur` GitHub Action: ``` - name: Publish package uses: KSXGitHub/github-actions-deploy-aur@065b6056b25bdd43830d5a3f01899d0ff7169819 # v2.6.0 if: ${{ env.pkgbuild != '' }} with: pkgname: ${{ env.pkgbuild }} pkgbuild: ${{ env.pkgbuild }}/PKGBUILD commit_username: ${{ secrets.AUR_USERNAME }} commit_email: ${{ secrets.AUR_EMAIL }} ssh_private_key: ${{ secrets.AUR_SSH_PRIVATE_KEY }} ``` ### All together now If you own any AUR packages and want to automate some of the maintenance burden, check out [my AUR packages template GitHub repository](https://github.com/JamieMagee/aur-packages-template/). It contains all of the steps I showed in this blog post. And if you want to see how it works in practice, check out [my AUR packages GitHub repository](https://github.com/JamieMagee/aur-packages). ## [How Swissquote is keeping software dependencies up-to-date with Renovate](https://docharvest.github.io/docs/renovate/usage/user-stories/swissquote/) Contents renovate Swissquote Renovate Swissquote > This article was originally published on [Medium](https://medium.com/swissquote-engineering/how-swissquote-is-keeping-software-dependencies-up-to-date-with-renovate-6246e8b20437) by [Stéphane Goetz](https://onigoetz.ch/), Principal Software Engineer at [Swissquote Bank](https://github.com/swissquote/). Swissquote has more than 1000 distinct applications running in production. They come in many different flavors including services, daemons, and web apps, and their age can be counted from days to more than a decade. While there are many topics of interest when talking about software maintenance, today’s topic is software dependencies. We’ll see in this article why it’s important to keep them up-to-date and why it’s not as simple as one may think. Software dependencies have been a heavily discussed topic in the past months. One aspect that’s discussed a lot is security issues like the recent [Log4Shell](https://en.wikipedia.org/wiki/Log4Shell), [Supply chain attacks](https://blog.sonatype.com/npm-project-used-by-millions-hijacked-in-supply-chain-attack), [an expiring SSL Certificate](https://www.webnic.cc/root-ssl-certificate-expiry-and-what-happens-next-for-brands/). But there are also other aspects like bugs caused by your dependencies. Depending on third-party software is a sword of Damocles; you never know when a new issue will force you to drop everything to upgrade your software. !\[Tower of blocks, with a small block that supports many large blocks. The whole stack is labeled: All modern digital infrastructure. A arrow points to the small block, with the label: A project some random person in Nebraska has been thanklessly maintaining since 2003.\](../assets/images/swissquote\_xkcd.png){ loading=lazy } [](https://xkcd.com/2347)XKCD comic 2347 is always relevant when talking about dependencies. Each software dependency is a risk. For example: SQL Injections, is the ORM you are using properly escaping the content you are passing to it? Will your current driver be able to connect to your database if it gets upgraded? Every dependency, while solving an issue for you, will also bring new risks to your software. How can you mitigate those risks? If the title of the article is of any help, the idea would be to keep your dependencies up-to-date to fix bugs, security issues, and more. ## I don’t feel like upgrading, what if? But what if the upgrades do the complete opposite? What if the new version introduces a new security issue? For example, a new version of a dependency could be victim of a supply chain attack. If you never update your dependencies, you won’t get the infected version. Sounds fair, right? It’s a valid argument, but your application doesn’t exist in a vacuum; many external factors could force you to upgrade at some point, and when it happens it’s usually at the wrong time. Let’s go through some examples. ### An external factor has changed, forcing you to change your app Let’s say the machine your apps runs on is obsolete and you need to move to another machine. This could be as simple as “install app on machine; done” but usually ends up with: 1. The newer OS version prevents you from installing an outdated runtime 2. You need to find a compatible runtime for your new hardware 3. Your app’s dependencies aren’t compatible with your new runtime, you need to update them as well Instead of a single change, you now have a combination of changes, each can go wrong in a different way. ### A new vulnerability is found on a library you depend on As we’ve covered at the beginning of the article this can happen and can be an all-hands-on-deck kind of situation. Imagine a legacy application; continuous integration is constantly failing — or worse it may not even exist. How long do you think it will take to deploy that single library update? ### The team already has too many dependencies in too many different versions That’s unfortunate, but it will happen if your team or company exists for long enough. Upgrading libraries is not only about bumping versions, sometimes it’s also about replacing a library by another library. ## How do you see your dependencies? Look at your software as if it was a train. You are the locomotive and each wagon is a dependency, how long would your train be? Locomotives can pull dozens, even hundreds of wagons, but they eventually reach a limit. The situation is the same for your brain, each dependency adds to your cognitive load, at some point it’s just too much. You are using three different libraries for caching? There is a chance you need to know how each library works, and your present and future teammates might have to know that too. Which of these two would you prefer to start with: - A project that is fairly up-to-date where you can bump the dependency, run the deployment pipeline and go back to your day - A project that wasn’t touched in years; every dependency is outdated and Continuous Integration is red on all branches, if running at all Am I exaggerating with my examples? Maybe a little, but I have seen cases very close to those. Let me ask you some questions about your projects: - How many times did you create a project and never upgrade its dependencies? - How many times did you have to get back to an old project, and had to use a new library but couldn’t because there is another library at an old version that isn’t compatible? - How fast can you upgrade a single dependency on all your applications? As time goes forward, projects come and go, you will most likely have decade-old, and recent ones. Some might be using the latest version of Java with the latest Spring, some with slightly outdated libraries and others might be using Stripes and libraries that have had no release in 7 years. Every company that’s been around for sometime has that old project still running. People talk about it laughingly but become livid when a request comes to change anything in it. !\[Close-up of black man with streams of sweat on his face\](../assets/images/swissquote\_sweating\_guy.jpg){ loading=lazy } There is a fix to make on that project, the last person working on it left three years ago. ## Dependencies at Swissquote I’ve identified three main approaches people use to upgrade their dependencies at Swissquote: 1. Critical fixes only; update dependencies that have a CVE attached 2. Opportunistic; also known as the boy scout rule, leave the project with more up-to-date dependencies than you found it 3. Update your dependencies regularly; manually or with a tool ### Critical fixes only Every once in a while, a library gets an update that fixes a vulnerability. Our security team is on the lookout for critical vulnerabilities and will quickly warn all impacted teams if an update needs to be done. We also configured [GitHub’s Dependabot Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) that will inform teams that a vulnerability has been discovered and which version they should upgrade to to be safe (more on this later). This approach, while it mostly works, can be very risky. If the project hasn’t been touched for quite a while, the number of dependencies to update can be high depending on the vulnerability and the time to update will increase significantly. ### Opportunistic This rule is simple, when you receive a task on a project, the first step is to upgrade its dependencies. Once that is done, you can go ahead with the implementation of your task. This approach is similar to fixing a bit of tech debt with every business project you take on, it helps to stay ahead in case a vulnerability comes up and keep a baseline for all your projects. ### Update your dependencies regularly This one sounds easy, every few weeks you check what’s outdated, bump the versions and run your CI. If it succeeds, you push the change. Maybe there is even a way to automate that? #### Let’s give Renovate a try One day in November 2019, I discovered that [Renovate](https://www.mend.io/free-developer-tools/renovate/) provides a Docker image that you can run on-premise with your own package registries. The app creates Pull Requests automatically to inform you of dependencies updates and the CI can then build it automatically so you know if it’s safe to merge or not. On our first try, we enabled 30 repositories, a cron task was running every hour to create Pull Requests. We received 700 Pull Requests in the first month, it was a never ending Pull Request whack-a-mole: every time we merged one, another replaced it. !\[A cat batting at fingers coming out of holes in a box, Whack-A-Mole style\](../assets/images/swissquote\_cat\_whack\_a\_mole.jpg){ loading=lazy } Me and my team merging Pull Requests. The awesome thing with Renovate is that it’s very configurable, and this configuration can be shared. Very early on we created a shared configuration for our team with some custom policies, here are a few things we decided to do: - Group PRs for `minor` and `patch` dependencies - Internal dependencies could create a PR anytime of the day - Third party dependencies could create PRs only during the weekend This helped a lot to reduce the noise in PRs, the second month we got 400 Pull Requests, and on the third month only 200. ## What we learned from automating dependencies updates - You need to be confident that your code coverage will warn you in case of updates. At the beginning we missed quite a few breaking updates because the build was green but the application broke as soon as it was deployed - Once you’re confident enough, auto-merge is a must have. In our team we enabled Renovate on about 100 of our repositories and generally spend 1–2 hours per week to stay up-to-date - “On the bleeding edge it’s not the edge that’s bleeding; it’s you”. When updating to a new major version as soon as it’s released you might encounter some surprises. It happened to us a few times that a patch version breaks the library. Usually a fix came out the next day, but we still spent a few hours debugging why the update broke our applications. We’ve opened quite a few Issues and sent some PRs to fix issues like this - Updating dependencies is one thing, but when should you release them? As our team mostly provides libraries, we don’t want to release them on every dependency upgrade (as this would create PRs downstream and create noise for them). We’ve decided to release right after critical upgrades or contributions and a dashboard informs us when a repository hasn’t been released for 30 days ### A word on Renovate > The next section could look like an ad or a sponsored post; it’s not. We’re just big fans of the product. The ease of getting started with Renovate’s Docker image is what got us onboard easily. But what confirmed our choice is the insane crazy amount of features and [configuration options](../configuration-options.md). Some features and options we enjoy: - [Shared configurations (presets)](../key-concepts/presets.md), we have a Swissquote default configuration we set for all repositories, each team can extend it with their own practices - [Integration with GitHub’s Dependabot alerts](../configuration-options.md#vulnerabilityalerts) to raise the priority and send security remediation PRs as soon as possible - Each rule can be customized either globally [or specified per package](../configuration-options.md#packagerules) - Works with your [private package registry](../getting-started/private-packages.md) - Supports more than 70 [languages and package managers](../modules/manager/index.md#supported-managers): Maven, Docker, npm, Docker Compose, Python - If you are using dependencies in a custom way, [there is a `customManagers` option](../configuration-options.md#custommanagers) that allows you to transform patterns into dependencies There is an [on-premise option](https://www.mend.io/free-developer-tools/renovate/on-premises/), but you can also use [the Mend Renovate App](https://github.com/marketplace/renovate). On our side, we’re not using the on-premise but rather a custom scheduler using the open source Docker image. ## Some stats after four years with Renovate > The figures here have been updated in November 2023 We started using Renovate Bot in 2019, using the (now deprecated) `renovate/pro` Docker image. We installed it as a GitHub app and some early adopters started to use it. Pretty quickly, we ran into the biggest limitation; this Docker image runs all repositories one after another. A single loop was taking hours and made it very difficult to check the logs as they weren’t separated per repository. This is why we created our own scheduler; each hour, all repositories would be queued to run, and GitHub app events would schedule a single repository. We started to collect metrics and store the logs separately for each repository. Here is the dashboard for our current scheduler: !\[Swissquote scheduler dashboard\](../assets/images/swissquote\_stats.png){ loading=lazy } A dashboard we made at Swissquote to keep our Renovate runs in check, November 2023. We don’t force any team to use Renovate, each team can decide to opt-in and do it for each project separately. Some statistics: - 857 repositories enabled out of about 2000 active repositories - 11000 PRs were merged since we installed Renovate - 239 PRs were merged last month - 2 SSDs died on our Renovate machine with the number of projects to clone again and again ### How does the scheduler work? The scheduler is a Node.js application that handles an in-memory queue and starts Docker containers to run Renovate on. Our custom scheduler application regularly sends data points to our InfluxDB database, which we then display in Grafana. Here is how it works: !\[Swissquote scheduler diagram\](../assets/images/swissquote\_stats\_collection.png){ loading=lazy } A diagram explaining how our scheduler interacts with Renovate. All the information on the dashboard you saw above is created from three measurements: 1. Queue: Every 5 minutes, we send the status of the queue size and the number of jobs currently running 2. Webhook: When receiving a webhook request from GitHub, we send a data point on the duration of treatment for that item 3. Runs: After each run, we send a data point on the run duration, success, and number of PRs created/updated/merged/closed The queue is filled by webhooks _or_ by re-queueing all repositories at regular intervals. For each repository, we start a Renovate Docker image and pipe its logs to a file. This allows us to run ten workers in parallel. We could technically run more workers but decided not to hammer our GitHub instance. You can find more details in this [discussion on the Renovate repository, from November 2023](https://github.com/renovatebot/renovate/discussions/23105#discussioncomment-6366621). ## The future of Renovate at Swissquote Not all teams are using Renovate at this stage, as some teams prefer to manually update their dependencies. We would like to enable Renovate for critical dependencies in all repositories and hope to make it useful and easy so other teams will adopt it for more dependencies. ## How should I get started with Renovate? If this article convinced you, how should you get started? 1. First, if you know your software is very outdated; don’t enable Renovate right away, you will be swamped with Pull Requests, we’ve been there and it’s not a happy memory. First take the time to **manually upgrade all that you can**. `npm outdated`, `mvn versions:display-dependency-updates` or your package manager’s equivalent of that command can help you get started, test your application and commit that 2. You can now enable Renovate and will receive a Pull Request to add a configuration file, **read this first PR carefully** as it will explain what kind of PRs you are going to receive and when 3. Make sure to **pick a schedule**, otherwise you will receive PRs at any time of the day. Our team schedules all third party dependencies on the weekend, automatically merging when the tests pass and we investigate the failing ones on Monday morning 4. **Group Pull Requests**, if every PR has to go through CI, it can become quite heavy, once most PRs succeed, you can start grouping minor and patch updates so that you get a single PR per repository. Investigating issues becomes a bit trickier because of that. To give you some numbers out of 90 repositories enabled with Renovate, we have on average 4 PRs to investigate per week. Everything else is automatically merged 5. **Enable auto merging after some time**, make sure your tests are solid and that you won’t upgrade something that wasn’t tested and will break once in production ## Is all this effort worth it? The short answer is yes! It took us almost a year, way longer than we thought, to catch up with the latest version of everything in our technical stack. But once we were confident enough in our tests to enable automatic merging of Pull Requests we were satisfied with the work we did to update our software stack. We knew we would be ready when an unplanned change arrives. When that day came, in December 2021 with Log4Shell, it was a matter of hours to release the freshly merged Pull Requests, deploy the few applications we had, and notify the teams depending on our libraries. We were so quick to do it, in fact, that we had to do that three times with the chain of vulnerabilities that was found in Log4j that week. Keep in mind that keeping your dependencies up-to-date is not just about the tooling, it’s also about having a process: - When will you merge this PR? - How will you handle the PR that doesn’t build? - The new major version of an external library that’s not yet compatible with the rest of your libraries? - When will you release this constant flow of library updates? - Do you want PRs during the day? During the night? Or on weekends only? We know the answers for our situation, we’ll let you decide what the answers are for you. :smile: