From 82f1411dfbb5bdc34b1d936a2fc7609769184dc5 Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Sat, 16 Sep 2023 06:08:05 +0545 Subject: [PATCH 01/13] migrate: regexManagers -> customManagers --- lib/config/migration.spec.ts | 5 +- ...c.ts => custom-managers-migration.spec.ts} | 10 ++-- ...ration.ts => custom-managers-migration.ts} | 8 ++-- lib/config/migrations/migrations-service.ts | 5 +- lib/config/options/index.ts | 48 +++++++++---------- .../presets/internal/regex-managers.spec.ts | 19 ++++---- lib/config/presets/internal/regex-managers.ts | 10 ++-- lib/config/types.ts | 4 +- lib/config/validation.spec.ts | 40 ++++++++-------- lib/config/validation.ts | 42 ++++++++-------- .../extract-fingerprint-config.spec.ts | 2 +- .../extract/extract-fingerprint-config.ts | 7 +-- lib/workers/repository/extract/index.spec.ts | 4 +- lib/workers/repository/extract/index.ts | 2 +- 14 files changed, 104 insertions(+), 102 deletions(-) rename lib/config/migrations/custom/{regex-managers-migration.spec.ts => custom-managers-migration.spec.ts} (82%) rename lib/config/migrations/custom/{regex-managers-migration.ts => custom-managers-migration.ts} (67%) diff --git a/lib/config/migration.spec.ts b/lib/config/migration.spec.ts index 8f3a907702fa23..42c809ba193176 100644 --- a/lib/config/migration.spec.ts +++ b/lib/config/migration.spec.ts @@ -643,10 +643,11 @@ describe('config/migration', () => { expect(migratedConfig).toEqual({ extends: ['local>org/renovate-config'] }); }); - it('it migrates regexManagers', () => { + it('it migrates customManagers', () => { const config: RenovateConfig = { - regexManagers: [ + customManagers: [ { + customType: 'regex', fileMatch: ['(^|/|\\.)Dockerfile$', '(^|/)Dockerfile[^/]*$'], matchStrings: [ '# renovate: datasource=(?[a-z-]+?) depName=(?[^\\s]+?)(?: lookupName=(?[^\\s]+?))?(?: versioning=(?[a-z-0-9]+?))?\\s(?:ENV|ARG) .+?_VERSION="?(?.+?)"?\\s', diff --git a/lib/config/migrations/custom/regex-managers-migration.spec.ts b/lib/config/migrations/custom/custom-managers-migration.spec.ts similarity index 82% rename from lib/config/migrations/custom/regex-managers-migration.spec.ts rename to lib/config/migrations/custom/custom-managers-migration.spec.ts index be49c6bcf3c077..792975860915a4 100644 --- a/lib/config/migrations/custom/regex-managers-migration.spec.ts +++ b/lib/config/migrations/custom/custom-managers-migration.spec.ts @@ -1,12 +1,12 @@ import { partial } from '../../../../test/util'; import type { CustomManager } from '../../../modules/manager/custom/types'; -import { RegexManagersMigration } from './regex-managers-migration'; +import { CustomManagersMigration } from './custom-managers-migration'; -describe('config/migrations/custom/regex-managers-migration', () => { +describe('config/migrations/custom/custom-managers-migration', () => { it('migrates', () => { - expect(RegexManagersMigration).toMigrate( + expect(CustomManagersMigration).toMigrate( { - regexManagers: partial([ + customManagers: partial([ { fileMatch: ['js', '***$}{]]['], matchStrings: ['^(?foo)(?bar)$'], @@ -23,7 +23,7 @@ describe('config/migrations/custom/regex-managers-migration', () => { ]), }, { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['js', '***$}{]]['], diff --git a/lib/config/migrations/custom/regex-managers-migration.ts b/lib/config/migrations/custom/custom-managers-migration.ts similarity index 67% rename from lib/config/migrations/custom/regex-managers-migration.ts rename to lib/config/migrations/custom/custom-managers-migration.ts index afaad6c80537b2..a4271247056a26 100644 --- a/lib/config/migrations/custom/regex-managers-migration.ts +++ b/lib/config/migrations/custom/custom-managers-migration.ts @@ -2,19 +2,19 @@ import is from '@sindresorhus/is'; import type { CustomManager } from '../../../modules/manager/custom/types'; import { AbstractMigration } from '../base/abstract-migration'; -export class RegexManagersMigration extends AbstractMigration { - override readonly propertyName = 'regexManagers'; +export class CustomManagersMigration extends AbstractMigration { + override readonly propertyName = 'customManagers'; override run(value: unknown): void { if (is.nonEmptyArray(value)) { - const regexManagers = (value as CustomManager[]).map((mgr) => { + const customManagers = (value as CustomManager[]).map((mgr) => { if (mgr.customType) { return mgr; } return Object.assign({ customType: 'regex' }, mgr); // to make sure customType is at top, looks good when migration pr is created }); - this.rewrite(regexManagers); + this.rewrite(customManagers); } } } diff --git a/lib/config/migrations/migrations-service.ts b/lib/config/migrations/migrations-service.ts index 2bff1be478c00a..7162d697bbb37a 100644 --- a/lib/config/migrations/migrations-service.ts +++ b/lib/config/migrations/migrations-service.ts @@ -15,6 +15,7 @@ import { BranchNameMigration } from './custom/branch-name-migration'; import { BranchPrefixMigration } from './custom/branch-prefix-migration'; import { CompatibilityMigration } from './custom/compatibility-migration'; import { ComposerIgnorePlatformReqsMigration } from './custom/composer-ignore-platform-reqs-migration'; +import { CustomManagersMigration } from './custom/custom-managers-migration'; import { DatasourceMigration } from './custom/datasource-migration'; import { DepTypesMigration } from './custom/dep-types-migration'; import { DryRunMigration } from './custom/dry-run-migration'; @@ -41,7 +42,6 @@ import { RaiseDeprecationWarningsMigration } from './custom/raise-deprecation-wa import { RebaseConflictedPrs } from './custom/rebase-conflicted-prs-migration'; import { RebaseStalePrsMigration } from './custom/rebase-stale-prs-migration'; import { RecreateClosedMigration } from './custom/recreate-closed-migration'; -import { RegexManagersMigration } from './custom/regex-managers-migration'; import { RenovateForkMigration } from './custom/renovate-fork-migration'; import { RequireConfigMigration } from './custom/require-config-migration'; import { RequiredStatusChecksMigration } from './custom/required-status-checks-migration'; @@ -96,6 +96,7 @@ export class MigrationsService { ['masterIssueFooter', 'dependencyDashboardFooter'], ['masterIssueTitle', 'dependencyDashboardTitle'], ['masterIssueLabels', 'dependencyDashboardLabels'], + ['regexManagers', 'customManagers'], ]); static readonly customMigrations: ReadonlyArray = [ @@ -151,7 +152,7 @@ export class MigrationsService { RecreateClosedMigration, StabilityDaysMigration, FetchReleaseNotesMigration, - RegexManagersMigration, + CustomManagersMigration, ]; static run(originalConfig: RenovateConfig): RenovateConfig { diff --git a/lib/config/options/index.ts b/lib/config/options/index.ts index e0ae5ed58ac390..c02fc114409028 100644 --- a/lib/config/options/index.ts +++ b/lib/config/options/index.ts @@ -2493,7 +2493,7 @@ const options: RenovateOptions[] = [ default: false, }, { - name: 'regexManagers', + name: 'customManagers', description: 'Custom managers using regex matching.', type: 'array', subType: 'object', @@ -2505,21 +2505,21 @@ const options: RenovateOptions[] = [ { name: 'customType', description: - 'Custom manager to use. Valid only within a `regexManagers` object.', + 'Custom manager to use. Valid only within a `customManagers` object.', type: 'string', allowedValues: ['regex'], - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'matchStrings', description: - 'Regex capture rule to use. Valid only within a `regexManagers` object.', + 'Regex capture rule to use. Valid only within a `customManagers` object.', type: 'array', subType: 'string', format: 'regex', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, @@ -2529,88 +2529,88 @@ const options: RenovateOptions[] = [ type: 'string', default: 'any', allowedValues: ['any', 'recursive', 'combination'], - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'depNameTemplate', description: - 'Optional depName for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional depName for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'packageNameTemplate', description: - 'Optional packageName for extracted dependencies, else defaults to `depName` value. Valid only within a `regexManagers` object.', + 'Optional packageName for extracted dependencies, else defaults to `depName` value. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'datasourceTemplate', description: - 'Optional datasource for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional datasource for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'depTypeTemplate', description: - 'Optional `depType` for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional `depType` for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'currentValueTemplate', description: - 'Optional `currentValue` for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional `currentValue` for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'versioningTemplate', description: - 'Optional versioning for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional versioning for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'registryUrlTemplate', description: - 'Optional registry URL for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional registry URL for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'extractVersionTemplate', description: - 'Optional `extractVersion` for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional `extractVersion` for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, { name: 'autoReplaceStringTemplate', description: - 'Optional `extractVersion` for extracted dependencies. Valid only within a `regexManagers` object.', + 'Optional `extractVersion` for extracted dependencies. Valid only within a `customManagers` object.', type: 'string', - parent: 'regexManagers', + parent: 'customManagers', cli: false, env: false, }, diff --git a/lib/config/presets/internal/regex-managers.spec.ts b/lib/config/presets/internal/regex-managers.spec.ts index 13a947bec990c3..9cf34e20e6d8a7 100644 --- a/lib/config/presets/internal/regex-managers.spec.ts +++ b/lib/config/presets/internal/regex-managers.spec.ts @@ -5,7 +5,7 @@ import { presets } from './regex-managers'; describe('config/presets/internal/regex-managers', () => { describe('Update `_VERSION` variables in Dockerfiles', () => { - const regexManager = presets['dockerfileVersions'].regexManagers?.[0]; + const customManager = presets['dockerfileVersions'].customManagers?.[0]; it(`find dependencies in file`, async () => { const fileContent = codeBlock` @@ -29,7 +29,7 @@ describe('config/presets/internal/regex-managers', () => { const res = await extractPackageFile( fileContent, 'Dockerfile', - regexManager! + customManager! ); expect(res?.deps).toMatchObject([ @@ -76,13 +76,13 @@ describe('config/presets/internal/regex-managers', () => { ${'foo/Dockerfile-foo'} | ${true} ${'foo-Dockerfile'} | ${false} `('$path', ({ path, expected }) => { - expect(regexMatches(path, regexManager!.fileMatch)).toBe(expected); + expect(regexMatches(path, customManager!.fileMatch)).toBe(expected); }); }); }); describe('Update `_VERSION` environment variables in GitHub Action files', () => { - const regexManager = presets['githubActionsVersions'].regexManagers?.[0]; + const customManager = presets['githubActionsVersions'].customManagers?.[0]; it(`find dependencies in file`, async () => { const fileContent = codeBlock` @@ -116,7 +116,7 @@ describe('config/presets/internal/regex-managers', () => { const res = await extractPackageFile( fileContent, 'github-workflow.yaml', - regexManager! + customManager! ); expect(res?.deps).toMatchObject([ @@ -168,13 +168,14 @@ describe('config/presets/internal/regex-managers', () => { ${'.github/workflows/foo.json'} | ${false} ${'.github/workflows/foo.yamlo'} | ${false} `('$path', ({ path, expected }) => { - expect(regexMatches(path, regexManager!.fileMatch)).toBe(expected); + expect(regexMatches(path, customManager!.fileMatch)).toBe(expected); }); }); }); describe('Update `appVersion` value in Helm chart Chart.yaml', () => { - const regexManager = presets['helmChartYamlAppVersions'].regexManagers?.[0]; + const customManager = + presets['helmChartYamlAppVersions'].customManagers?.[0]; it(`find dependencies in file`, async () => { const fileContent = codeBlock` @@ -192,7 +193,7 @@ describe('config/presets/internal/regex-managers', () => { const res = await extractPackageFile( fileContent, 'Chart.yaml', - regexManager! + customManager! ); expect(res?.deps).toMatchObject([ @@ -228,7 +229,7 @@ describe('config/presets/internal/regex-managers', () => { ${'Chart.yamlo'} | ${false} ${'Charto.yaml'} | ${false} `('$path', ({ path, expected }) => { - expect(regexMatches(path, regexManager!.fileMatch)).toBe(expected); + expect(regexMatches(path, customManager!.fileMatch)).toBe(expected); }); }); }); diff --git a/lib/config/presets/internal/regex-managers.ts b/lib/config/presets/internal/regex-managers.ts index e50074ab597a80..42b992e0a179a6 100644 --- a/lib/config/presets/internal/regex-managers.ts +++ b/lib/config/presets/internal/regex-managers.ts @@ -1,11 +1,9 @@ import type { Preset } from '../types'; -/* eslint sort-keys: ["error", "asc", {caseSensitive: false, natural: true}] */ - export const presets: Record = { dockerfileVersions: { description: 'Update `_VERSION` variables in Dockerfiles.', - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: [ @@ -21,7 +19,7 @@ export const presets: Record = { githubActionsVersions: { description: 'Update `_VERSION` environment variables in GitHub Action files.', - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['^.github/(?:workflows|actions)/.+\\.ya?ml$'], @@ -33,7 +31,7 @@ export const presets: Record = { }, helmChartYamlAppVersions: { description: 'Update `appVersion` value in Helm chart `Chart.yaml`.', - regexManagers: [ + customManagers: [ { customType: 'regex', datasourceTemplate: 'docker', @@ -46,7 +44,7 @@ export const presets: Record = { }, tfvarsVersions: { description: 'Update `*_version` variables in `.tfvars` files.', - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['.+\\.tfvars$'], diff --git a/lib/config/types.ts b/lib/config/types.ts index ac6fa1788f70db..6a3178f6e0196a 100644 --- a/lib/config/types.ts +++ b/lib/config/types.ts @@ -247,7 +247,7 @@ export interface RenovateConfig vulnerabilityAlerts?: RenovateSharedConfig; osvVulnerabilityAlerts?: boolean; vulnerabilitySeverity?: string; - regexManagers?: CustomManager[]; + customManagers?: CustomManager[]; customDatasources?: Record; fetchReleaseNotes?: FetchReleaseNotesOptions; @@ -382,7 +382,7 @@ export interface RenovateOptionBase { | 'hostRules' | 'packageRules' | 'postUpgradeTasks' - | 'regexManagers'; + | 'customManagers'; stage?: RenovateConfigStage; diff --git a/lib/config/validation.spec.ts b/lib/config/validation.spec.ts index 785fd217b2e67f..a1d88bbf44f869 100644 --- a/lib/config/validation.spec.ts +++ b/lib/config/validation.spec.ts @@ -373,7 +373,7 @@ describe('config/validation', () => { it('validates regEx for each fileMatch', async () => { const config: RenovateConfig = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['js', '***$}{]]['], @@ -392,9 +392,9 @@ describe('config/validation', () => { expect(errors).toMatchSnapshot(); }); - it('errors if regexManager has empty fileMatch', async () => { + it('errors if customManager has empty fileMatch', async () => { const config = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: [], @@ -417,9 +417,9 @@ describe('config/validation', () => { `); }); - it('errors if no regexManager customType', async () => { + it('errors if no customManager customType', async () => { const config = { - regexManagers: [ + customManagers: [ { fileMatch: ['some-file'], matchStrings: ['^(?foo)(?bar)$'], @@ -444,9 +444,9 @@ describe('config/validation', () => { `); }); - it('errors if invalid regexManager customType', async () => { + it('errors if invalid customManager customType', async () => { const config = { - regexManagers: [ + customManagers: [ { customType: 'unknown', fileMatch: ['some-file'], @@ -472,9 +472,9 @@ describe('config/validation', () => { `); }); - it('errors if empty regexManager matchStrings', async () => { + it('errors if empty customManager matchStrings', async () => { const config = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['foo'], @@ -512,9 +512,9 @@ describe('config/validation', () => { `); }); - it('errors if no regexManager fileMatch', async () => { + it('errors if no customManager fileMatch', async () => { const config = { - regexManagers: [ + customManagers: [ { matchStrings: ['^(?foo)(?bar)$'], datasourceTemplate: 'maven', @@ -532,7 +532,7 @@ describe('config/validation', () => { it('validates regEx for each matchStrings', async () => { const config: RenovateConfig = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['Dockerfile'], @@ -555,7 +555,7 @@ describe('config/validation', () => { // since they are common to all custom managers it('validates all possible regex manager options', async () => { const config: RenovateConfig = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['Dockerfile'], @@ -571,9 +571,9 @@ describe('config/validation', () => { expect(errors).toHaveLength(4); }); - it('passes if regexManager fields are present', async () => { + it('passes if customManager fields are present', async () => { const config: RenovateConfig = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['Dockerfile'], @@ -594,9 +594,9 @@ describe('config/validation', () => { expect(errors).toHaveLength(0); }); - it('errors if extra regexManager fields are present', async () => { + it('errors if extra customManager fields are present', async () => { const config = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['Dockerfile'], @@ -616,9 +616,9 @@ describe('config/validation', () => { expect(errors).toHaveLength(1); }); - it('errors if regexManager fields are missing', async () => { + it('errors if customManager fields are missing', async () => { const config: RenovateConfig = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['Dockerfile'], @@ -749,7 +749,7 @@ describe('config/validation', () => { fileMatch: ['bar'], }, }, - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['build.gradle'], diff --git a/lib/config/validation.ts b/lib/config/validation.ts index d63a47aaaa2cbf..539b6737f2e9ed 100644 --- a/lib/config/validation.ts +++ b/lib/config/validation.ts @@ -51,7 +51,7 @@ const rulesRe = regEx(/p.*Rules\[\d+\]$/); function isManagerPath(parentPath: string): boolean { return ( - regEx(/^regexManagers\[[0-9]+]$/).test(parentPath) || + regEx(/^customManagers\[[0-9]+]$/).test(parentPath) || managerList.includes(parentPath) ); } @@ -405,7 +405,7 @@ export async function validateConfig( } } } - if (key === 'regexManagers') { + if (key === 'customManagers') { const allowedKeys = [ 'customType', 'description', @@ -422,30 +422,30 @@ export async function validateConfig( 'autoReplaceStringTemplate', 'depTypeTemplate', ]; - for (const regexManager of val as CustomManager[]) { + for (const customManager of val as CustomManager[]) { if ( - Object.keys(regexManager).some( + Object.keys(customManager).some( (k) => !allowedKeys.includes(k) ) ) { - const disallowedKeys = Object.keys(regexManager).filter( + const disallowedKeys = Object.keys(customManager).filter( (k) => !allowedKeys.includes(k) ); errors.push({ topic: 'Configuration Error', - message: `Regex Manager contains disallowed fields: ${disallowedKeys.join( + message: `Custom Manager contains disallowed fields: ${disallowedKeys.join( ', ' )}`, }); } else if ( - is.nonEmptyString(regexManager.customType) && - isCustomManager(regexManager.customType) + is.nonEmptyString(customManager.customType) && + isCustomManager(customManager.customType) ) { - if (is.nonEmptyArray(regexManager.fileMatch)) { - switch (regexManager.customType) { + if (is.nonEmptyArray(customManager.fileMatch)) { + switch (customManager.customType) { case 'regex': - validateRegexManagerFields( - regexManager, + validatecustomManagerFields( + customManager, currentPath, errors ); @@ -459,8 +459,8 @@ export async function validateConfig( } } else { if ( - is.emptyString(regexManager.customType) || - is.undefined(regexManager.customType) + is.emptyString(customManager.customType) || + is.undefined(customManager.customType) ) { errors.push({ topic: 'Configuration Error', @@ -469,7 +469,7 @@ export async function validateConfig( } else { errors.push({ topic: 'Configuration Error', - message: `Invalid customType: ${regexManager.customType}. Key is not a custom manager`, + message: `Invalid customType: ${customManager.customType}. Key is not a custom manager`, }); } } @@ -658,13 +658,13 @@ export async function validateConfig( return { errors, warnings }; } -function validateRegexManagerFields( - regexManager: Partial, +function validatecustomManagerFields( + customManager: Partial, currentPath: string, errors: ValidationMessage[] ): void { - if (is.nonEmptyArray(regexManager.matchStrings)) { - for (const matchString of regexManager.matchStrings) { + if (is.nonEmptyArray(customManager.matchStrings)) { + for (const matchString of customManager.matchStrings) { try { regEx(matchString); } catch (e) { @@ -685,8 +685,8 @@ function validateRegexManagerFields( for (const field of mandatoryFields) { const templateField = `${field}Template` as keyof RegexManagerTemplates; if ( - !regexManager[templateField] && - !regexManager.matchStrings?.some((matchString) => + !customManager[templateField] && + !customManager.matchStrings?.some((matchString) => matchString.includes(`(?<${field}>`) ) ) { diff --git a/lib/workers/repository/extract/extract-fingerprint-config.spec.ts b/lib/workers/repository/extract/extract-fingerprint-config.spec.ts index 34f46c9d3bec62..ade8d1b42d2c3c 100644 --- a/lib/workers/repository/extract/extract-fingerprint-config.spec.ts +++ b/lib/workers/repository/extract/extract-fingerprint-config.spec.ts @@ -20,7 +20,7 @@ describe('workers/repository/extract/extract-fingerprint-config', () => { }, }, enabledManagers: ['npm', 'regex'], - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['js', '***$}{]]['], diff --git a/lib/workers/repository/extract/extract-fingerprint-config.ts b/lib/workers/repository/extract/extract-fingerprint-config.ts index 8f3bf56a2fbf33..c30139c8744138 100644 --- a/lib/workers/repository/extract/extract-fingerprint-config.ts +++ b/lib/workers/repository/extract/extract-fingerprint-config.ts @@ -12,7 +12,8 @@ export interface FingerprintExtractConfig { managers: WorkerExtractConfig[]; } -function getRegexManagerFields( +// checks for regex manager fields +function getCustomManagerFields( config: WorkerExtractConfig ): CustomExtractConfig { const regexFields = {} as CustomExtractConfig; @@ -36,7 +37,7 @@ function getFilteredManagerConfig( config: WorkerExtractConfig ): WorkerExtractConfig { return { - ...(isCustomManager(config.manager) && getRegexManagerFields(config)), + ...(isCustomManager(config.manager) && getCustomManagerFields(config)), manager: config.manager, fileMatch: config.fileMatch, npmrc: config.npmrc, @@ -65,7 +66,7 @@ export function generateFingerprintConfig( for (const manager of managerList) { const managerConfig = getManagerConfig(config, manager); if (isCustomManager(manager)) { - const filteredCustomManagers = (config.regexManagers ?? []).filter( + const filteredCustomManagers = (config.customManagers ?? []).filter( (mgr) => mgr.customType === manager ); for (const customManager of filteredCustomManagers) { diff --git a/lib/workers/repository/extract/index.spec.ts b/lib/workers/repository/extract/index.spec.ts index 7d257cbbc3a049..5cdf1a9f1a880b 100644 --- a/lib/workers/repository/extract/index.spec.ts +++ b/lib/workers/repository/extract/index.spec.ts @@ -25,7 +25,7 @@ describe('workers/repository/extract/index', () => { managerFiles.getManagerPackageFiles.mockResolvedValue([ partial>>({}), ]); - delete config.regexManagers; // for coverage + delete config.customManagers; // for coverage const res = await extractAllDependencies(config); expect(Object.keys(res.packageFiles)).toContain('ansible'); }); @@ -58,7 +58,7 @@ describe('workers/repository/extract/index', () => { managerFiles.getManagerPackageFiles.mockResolvedValue([ partial>>({}), ]); - config.regexManagers = [ + config.customManagers = [ { customType: 'regex', fileMatch: ['README'], matchStrings: [''] }, ]; const res = await extractAllDependencies(config); diff --git a/lib/workers/repository/extract/index.ts b/lib/workers/repository/extract/index.ts index bcf281bb5f9071..99b3ffee136686 100644 --- a/lib/workers/repository/extract/index.ts +++ b/lib/workers/repository/extract/index.ts @@ -34,7 +34,7 @@ export async function extractAllDependencies( const managerConfig = getManagerConfig(config, manager); managerConfig.manager = manager; if (isCustomManager(manager)) { - const filteredCustomManagers = (config.regexManagers ?? []).filter( + const filteredCustomManagers = (config.customManagers ?? []).filter( (mgr) => mgr.customType === manager ); for (const customManager of filteredCustomManagers) { From eab742ad9f1a27da8224323efee83743f98af30e Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Sun, 17 Sep 2023 05:07:25 +0545 Subject: [PATCH 02/13] modify docs --- docs/usage/configuration-options.md | 3260 +++++++++-------- docs/usage/getting-started/use-cases.md | 4 +- docs/usage/reading-list.md | 2 +- .../maintaining-aur-packages-with-renovate.md | 5 +- docs/usage/user-stories/swissquote.md | 2 +- .../__snapshots__/validation.spec.ts.snap | 9 + lib/config/validation.spec.ts | 4 +- lib/config/validation.ts | 10 +- .../datasource/aws-machine-image/readme.md | 8 +- lib/modules/datasource/aws-rds/readme.md | 9 +- lib/modules/datasource/custom/readme.md | 18 +- .../datasource/endoflife-date/readme.md | 3 +- lib/modules/datasource/git-refs/readme.md | 5 +- .../datasource/gitlab-packages/readme.md | 5 +- .../datasource/gitlab-releases/readme.md | 5 +- lib/modules/datasource/gitlab-tags/readme.md | 5 +- lib/modules/datasource/repology/readme.md | 5 +- lib/modules/manager/custom/regex/readme.md | 26 +- 18 files changed, 1707 insertions(+), 1678 deletions(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 754a53e2b98191..5df249f2b76626 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -646,7 +646,7 @@ When using with `npm`, we recommend you: ## customDatasources Use `customDatasources` to fetch releases from APIs or statically hosted sites and Renovate has no own datasource. -These datasources can be referred by RegexManagers or can be used to overwrite default datasources. +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/). @@ -683,2633 +683,2637 @@ Currently `json` or `plain` are supported, see the `custom` [datasource document `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. -## 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. +## customManagers -To disable the Dependency Dashboard, add the preset `:disableDependencyDashboard` or set `dependencyDashboard` to `false`. +Use `customManagers` entries to configure the custom managers in Renovate. -```json -{ - "extends": ["config:recommended", ":disableDependencyDashboard"] -} -``` +You can define custom managers to handle: -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. +- Proprietary file formats or conventions +- Popular file formats not yet supported as a manager by Renovate -Examples of what having a Dependency Dashboard will allow you to do: +Currently we only have one custom manager. The `regex` manager which is based on using Regular Expression named capture groups. -- 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) +You must have a named capture group matching (e.g. `(?.*)`) _or_ configure its corresponding template (e.g. `depNameTemplate`) for these fields: - -!!! 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. +- `datasource` +- `depName` +- `currentValue` -## dependencyDashboardApproval +Use named capture group matching _or_ set a corresponding template. +We recommend you use only one of these methods, or you'll get confused. -This feature allows you to use Renovate's Dependency Dashboard to force approval of updates before they are created. +We recommend that you also tell Renovate what `versioning` to use. +If the `versioning` field is missing, then Renovate defaults to using `semver` versioning. -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. +For more details and examples, see our [documentation for the `regex` manager](/modules/manager/regex/). +For template fields, use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. !!! 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: + Look at our [Regex Manager Presets](https://docs.renovatebot.com/presets-regexManagers/), they may have what you need. -- all package upgrades -- major, minor, patch level upgrades -- specific package upgrades -- upgrades coming from specific package managers +### customType -If you want to approve _all_ upgrades, set `dependencyDashboardApproval` to `true`: +Example: ```json { - "dependencyDashboardApproval": true + "customManagers": [ + { + "customType": "regex", + "matchStrings": [ + "ENV .*?_VERSION=(?.*) # (?.*?)/(?.*?)\\s" + ] + } + ] } ``` -If you want to require approval for _major_ updates, set `dependencyDashboardApproval` to `true` within a `major` object: +### matchStrings -```json -{ - "major": { - "dependencyDashboardApproval": true - } -} -``` +`matchStrings` should each be a valid regular expression, optionally with named capture groups. -If you want to approve _specific_ packages, set `dependencyDashboardApproval` to `true` within a `packageRules` entry where you have defined a specific package or pattern. +Example: ```json { - "packageRules": [ - { - "matchPackagePatterns": ["^@package-name"], - "dependencyDashboardApproval": true - } + "matchStrings": [ + "ENV .*?_VERSION=(?.*) # (?.*?)/(?.*?)\\s" ] } ``` -## dependencyDashboardAutoclose - -You can configure this to `true` if you prefer Renovate to close an existing Dependency Dashboard whenever there are no outstanding PRs left. - -## 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 - -This feature is independent of the `osvVulnerabilityAlerts` option. - -The source of these CVEs is [OSV.dev](https://osv.dev/). - -## dependencyDashboardTitle - -Configure this option if you prefer a different title for the Dependency Dashboard. - -## description +### matchStringsStrategy -The description field can be used inside any configuration object to add a human-readable description of the object's config purpose. -Descriptions fields embedded within presets are also collated as part of the onboarding description. +`matchStringsStrategy` controls behavior when multiple `matchStrings` values are provided. +Three options are available: -## digest +- `any` (default) +- `recursive` +- `combination` -Add to this object if you wish to define rules that apply only to PRs that update digests. +#### any -## draftPR +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. -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`: +As example the following configuration will update all 3 lines in the Dockerfile. +renovate.json: ```json { - "draftPR": true + "customManagers": [ + { + "customType": "regex", + "fileMatch": ["^Dockerfile$"], + "matchStringsStrategy": "any", + "matchStrings": [ + "ENV [A-Z]+_VERSION=(?.*) # (?.*?)/(?.*?)(\\&versioning=(?.*?))?\\s", + "FROM (?\\S*):(?\\S*)" + ], + "datasourceTemplate": "docker" + } + ] } ``` -This option is evaluated at PR/MR creation time. +a Dockerfile: - -!!! 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!`. +```dockerfile +FROM amd64/ubuntu:18.04 +ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven +ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node +``` -## enabled +#### recursive -The most common use of `enabled` is if you want to turn Renovate's functionality off, for some reason. +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 used as basis be used as 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. -For example, if you wanted to disable Renovate completely on a repository, you could make this your `renovate.json`: +Matched groups will be available in subsequent matching layers. -```json -{ - "enabled": false -} -``` +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. -To disable Renovate for all `eslint` packages, you can configure a package rule like: +renovate.json: ```json { - "packageRules": [ + "customManagers": [ { - "matchPackagePatterns": ["^eslint"], - "enabled": false + "customType": "regex", + "fileMatch": ["^example.json$"], + "matchStringsStrategy": "recursive", + "matchStrings": [ + "\"backup\":\\s*{[^}]*}", + "\"test\":\\s*\\{[^}]*}", + "\"name\":\\s*\"(?.*)\"[^\"]*\"type\":\\s*\"(?.*)\"[^\"]*\"value\":\\s*\"(?.*)\"" + ], + "datasourceTemplate": "docker" + }, + { + "fileMatch": ["^example.json$"], + "matchStringsStrategy": "recursive", + "matchStrings": [ + "\"test\":\\s*\\{[^}]*}", + "\"name\":\\s*\"(?.*)\"[^\"]*\"type\":\\s*\"(?.*)\"[^\"]*\"value\":\\s*\"(?.*)\"" + ], + "datasourceTemplate": "docker" } ] } ``` -To disable Renovate for npm `devDependencies` but keep it for `dependencies` you could configure: +example.json: ```json { - "packageRules": [ - { - "matchManagers": ["npm"], - "matchDepTypes": ["devDependencies"], - "enabled": false + "backup": { + "test": { + "name": "grafana/loki", + "type": "docker", + "value": "1.6.1" } - ] + }, + "setup": { + "test": { + "name": "python", + "type": "docker", + "value": "3.9.0" + } + } } ``` -## enabledManagers +#### combination -This is a way to allow only certain package managers and implicitly disable all others. +This option allows the possibility to combine the values of multiple lines inside a file. +While using multiple lines is also possible using both other `matchStringStrategy` values, the `combination` approach is less susceptible to white space or line breaks stopping a match. -Example: +`combination` will only match at most one dependency per file, so if you want to update multiple dependencies using `combination` you have to define multiple custom managers. + +Matched group values will be merged to form a single dependency. + +renovate.json: ```json { - "enabledManagers": ["dockerfile", "npm"] + "customManagers": [ + { + "customType": "regex", + "fileMatch": ["^main.yml$"], + "matchStringsStrategy": "combination", + "matchStrings": [ + "prometheus_image:\\s*\"(?.*)\"\\s*//", + "prometheus_version:\\s*\"(?.*)\"\\s*//" + ], + "datasourceTemplate": "docker" + }, + { + "fileMatch": ["^main.yml$"], + "matchStringsStrategy": "combination", + "matchStrings": [ + "thanos_image:\\s*\"(?.*)\"\\s*//", + "thanos_version:\\s*\"(?.*)\"\\s*//" + ], + "datasourceTemplate": "docker" + } + ] } ``` -For the full list of available managers, see the [Supported Managers](https://docs.renovatebot.com/modules/manager/#supported-managers) documentation. +Ansible variable file ( yaml ): -## encrypted +```yaml +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 +``` -Before you put any secrets in your repository configuration, encrypt the secrets. -You can encrypt secrets using either a HTML page, or the CLI. +In the above example, each custom manager will match a single dependency each. -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. +### depNameTemplate -You can also encrypt secrets from the CLI, using the `curl`, `echo`, `jq`, `gpg`, `grep` and `tr` CLI programs. -Here is an example: +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. -``` -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' -``` +### extractVersionTemplate -The above script uses: +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. -- `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 +### packageNameTemplate -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. +`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. - -!!! 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. +### currentValueTemplate -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. +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. -For more information on how to use secrets for private packages, read [Private package support](./getting-started/private-packages.md). +### datasourceTemplate -## excludeCommitPaths +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. -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: +### depTypeTemplate -```json -{ - "excludeCommitPaths": ["vendor/golang.org/x/text/**"] -} -``` +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. -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. +### versioningTemplate -## extends +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. -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. +### registryUrlTemplate -## extractVersion +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. -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. +### autoReplaceStringTemplate -For example, to extract only the major.minor precision from a GitHub release, the following would work: +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. -```json -{ - "packageRules": [ - { - "matchPackageNames": ["foo"], - "extractVersion": "^(?v\\d+\\.\\d+)" - } - ] -} -``` +helm-values.yaml: -The above will change a raw version of `v1.31.5` to `v1.31`, for example. +```yaml +# The image of the service //: +image: my.old.registry/aRepository/andImage:1.18-alpine +``` -Alternatively, to strip a `release-` prefix: +regex definition: ```json { - "packageRules": [ + "customManagers": [ { - "matchPackageNames": ["bar"], - "extractVersion": "^release-(?.*)$" + "customType": "regex", + "fileMatch": ["values.yaml$"], + "matchStrings": [ + "image:\\s+(?my\\.old\\.registry/aRepository/andImage):(?[^\\s]+)" + ], + "depNameTemplate": "my.new.registry/aRepository/andImage", + "autoReplaceStringTemplate": "image: {{{depName}}}:{{{newValue}}}", + "datasourceTemplate": "docker" } ] } ``` -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: +This will lead to following update where `1.21-alpine` is the newest version of `my.new.registry/aRepository/andImage`: + +```yaml +# The image of the service //: +image: my.new.registry/aRepository/andImage:1.21-alpine +``` + +## 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`. ```json { - "packageRules": [ - { - "matchPackageNames": ["baz"], - "extractVersion": "^v(?.*)$" - } - ] + "extends": ["config:recommended", ":disableDependencyDashboard"] } ``` -## fetchReleaseNotes +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. -Use this config option to configure release notes fetching. -The available options are: +Examples of what having a Dependency Dashboard will allow you to do: -- `off` - disable release notes fetching -- `branch` - fetch release notes while creating/updating branch -- `pr`(default) - fetches release notes while creating/updating pull-request +- 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) -It is not recommended to set fetchReleaseNotes=branch unless you are embedding release notes in commit information, because it results in a performance decrease. + +!!! 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. -Renovate can fetch release notes when they are hosted on one of these platforms: +## dependencyDashboardApproval -- Bitbucket Cloud -- GitHub (.com and Enterprise Server) -- GitLab (.com and CE/EE) +This feature allows you to use Renovate's Dependency Dashboard to force approval of updates before they are created. -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-release-notes) to allow Renovate to fetch release notes from `github.com`. +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. -!!! note - Renovate can only show release notes from some platforms and some package managers. - We're planning improvements so that Renovate can show more release notes. - Read [issue 14138 on GitHub](https://github.com/renovatebot/renovate/issues/14138) to get an overview of the planned work. +!!! tip + When you set `dependencyDashboardApproval` to `true` the Dependency Dashboard issue will be created automatically, you do not need to turn on `dependencyDashboard` explicitly. -## fileMatch +You can configure Renovate to wait for approval for: -`fileMatch` is used by Renovate to know which files in a repository to parse and extract. -`fileMatch` patterns in the user config are added to the default values and do not replace them. -The default `fileMatch` patterns cannot be removed, so if you need to include or exclude specific paths then use the `ignorePaths` or `includePaths` configuration options. +- all package upgrades +- major, minor, patch level upgrades +- specific package upgrades +- upgrades coming from specific package managers -Some `fileMatch` patterns are short, like Renovate's default Go Modules `fileMatch` for example. -Here Renovate looks for _any_ `go.mod` file. -In this case you can probably keep using that default `fileMatch`. +If you want to approve _all_ upgrades, set `dependencyDashboardApproval` to `true`: -At other times, the possible files is too vague for Renovate to have any default. -For default, Kubernetes manifests can exist in any `*.yaml` file and we don't want Renovate to parse every single YAML file in every repository just in case some of them have a Kubernetes manifest, so Renovate's default `fileMatch` for manager `kubernetes` is actually empty (`[]`) and needs the user to tell Renovate what directories/files to look in. +```json +{ + "dependencyDashboardApproval": true +} +``` -Finally, there are cases where Renovate's default `fileMatch` is good, but you may be using file patterns that a bot couldn't possibly guess about. -For example, Renovate's default `fileMatch` 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 `fileMatch` is mergeable, you don't need to duplicate the defaults and could add the missing file like this: +If you want to require approval for _major_ updates, set `dependencyDashboardApproval` to `true` within a `major` object: ```json { - "dockerfile": { - "fileMatch": ["^ACTUALLY_A_DOCKERFILE\\.template$"] + "major": { + "dependencyDashboardApproval": true } } ``` -If you configure `fileMatch` then it must be within a manager object (e.g. `dockerfile` in the above example). -The full list of supported managers can be found [here](https://docs.renovatebot.com/modules/manager/). - -## 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 usecase is to follow a pre-release tag of a dependency, say TypeScripts's `"insiders"` build: +If you want to approve _specific_ packages, set `dependencyDashboardApproval` to `true` within a `packageRules` entry where you have defined a specific package or pattern. ```json { "packageRules": [ { - "matchPackageNames": ["typescript"], - "followTag": "insiders" + "matchPackagePatterns": ["^@package-name"], + "dependencyDashboardApproval": true } ] } ``` -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. +## dependencyDashboardAutoclose -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. +You can configure this to `true` if you prefer Renovate to close an existing Dependency Dashboard whenever there are no outstanding PRs left. -## forkModeDisallowMaintainerEdits +## dependencyDashboardFooter -Use `forkModeDisallowMaintainerEdits` to disallow maintainers from editing Renovate's pull requests when in fork mode. +## dependencyDashboardHeader -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. +## dependencyDashboardLabels -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). +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. -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. +## dependencyDashboardOSVVulnerabilitySummary - -!!! note - This option is only relevant if you set `forkToken`. +Use this option to control if the Dependency Dashboard lists the OSV-sourced CVEs for your repository. +You can choose from: -## forkProcessing +- `none` (default) do not list any CVEs +- `unresolved` list CVEs that have no fixes +- `all` list all CVEs -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. +This feature is independent of the `osvVulnerabilityAlerts` option. -**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. +The source of these CVEs is [OSV.dev](https://osv.dev/). -## gitAuthor +## dependencyDashboardTitle -You can customize the Git author that's used whenever Renovate creates a commit. -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. +Configure this option if you prefer a different title for the Dependency Dashboard. -``` -Development Bot -``` +## description - -!!! 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. +The description field can be used inside any configuration object to add a human-readable description of the object's config purpose. +Descriptions fields embedded within presets are also collated as part of the onboarding description. -## gitIgnoredAuthors +## digest -Specify commit authors ignored by Renovate. +Add to this object if you wish to define rules that apply only to PRs that update digests. -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`. +## draftPR -Example: +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`: ```json { - "gitIgnoredAuthors": ["some-bot@example.org"] + "draftPR": true } ``` -## gitLabIgnoreApprovals +This option is evaluated at PR/MR creation time. -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`, `automergeType=pr` or `automergeType=branch`, and `platformAutomerge=true`. -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). + +!!! 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!`. -## goGetDirs +## enabled -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: +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`: ```json { - "goGetDirs": ["./some-project/", "./tools/..."] + "enabled": false } ``` -## 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: +To disable Renovate for all `eslint` packages, you can configure a package rule like: ```json { "packageRules": [ { - "matchDepTypes": ["devDependencies"], - "matchUpdateTypes": ["patch", "minor"], - "groupName": "devDependencies (non-major)" + "matchPackagePatterns": ["^eslint"], + "enabled": false } ] } ``` -## 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: +To disable Renovate for npm `devDependencies` but keep it for `dependencies` you could configure: ```json { "packageRules": [ { + "matchManagers": ["npm"], "matchDepTypes": ["devDependencies"], - "matchUpdateTypes": ["patch", "minor"], - "groupName": "devDependencies (non-major)", - "groupSlug": "dev-dependencies" + "enabled": false } ] } ``` -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. +## enabledManagers -## hashedBranchLength +This is a way to allow only certain package managers and implicitly disable all others. -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: -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`. +```json +{ + "enabledManagers": ["dockerfile", "npm"] +} +``` -## hostRules +For the full list of available managers, see the [Supported Managers](https://docs.renovatebot.com/modules/manager/#supported-managers) documentation. -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. +## encrypted -The lookup keys for `hostRules` are: `hostType` and `matchHost`, both of which are optional. +Before you put any secrets in your repository configuration, encrypt the secrets. +You can encrypt secrets using either a HTML page, or the CLI. -Supported credential fields are `token`, `username`, `password`, `timeout`, `enabled` and `insecureRegistry`. +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. -Example for configuring `docker` auth: +You can also encrypt secrets from the CLI, using the `curl`, `echo`, `jq`, `gpg`, `grep` and `tr` CLI programs. +Here is an example: -```json -{ - "hostRules": [ - { - "matchHost": "docker.io", - "username": "", - "password": "" - } - ] -} +``` +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' ``` -If multiple `hostRules` match a request, then they will be applied in the following order/priority: +The above script uses: -1. rules with only `hostType` specified -1. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) -1. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) +- `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 -To disable requests to a particular host, you can configure a rule like: +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. -```json -{ - "hostRules": [ - { - "matchHost": "registry.npmjs.org", - "enabled": false - } - ] -} -``` + +!!! 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. -A preset alternative to the above is: +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. -```json -{ - "extends": [":disableHost(registry.npmjs.org)"] -} -``` +For more information on how to use secrets for private packages, read [Private package support](./getting-started/private-packages.md). -To match specific ports you have to add a protocol to `matchHost`: +## 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: ```json { - "hostRules": [ - { - "matchHost": "https://domain.com:9118", - "enabled": false - } - ] + "excludeCommitPaths": ["vendor/golang.org/x/text/**"] } ``` - -!!! warning - Using `matchHost` without a protocol behaves the same as if you had set no `matchHost` configuration. +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. - -!!! 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. +## extends -### abortIgnoreStatusCodes +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. -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: +## 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: ```json { - "hostRules": [ + "packageRules": [ { - "abortOnError": true, - "abortIgnoreStatusCodes": [404] + "matchPackageNames": ["foo"], + "extractVersion": "^(?v\\d+\\.\\d+)" } ] } ``` - -!!! tip - This field is _not_ mergeable, so the last-applied host rule takes precedence. - -### 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. +The above will change a raw version of `v1.31.5` to `v1.31`, for example. -To abort Renovate runs for http failures from _any_ host: +Alternatively, to strip a `release-` prefix: ```json { - "hostRules": [ + "packageRules": [ { - "abortOnError": true + "matchPackageNames": ["bar"], + "extractVersion": "^release-(?.*)$" } ] } ``` -To abort Renovate runs for any `docker` datasource failures: +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: ```json { - "hostRules": [ + "packageRules": [ { - "hostType": "docker", - "abortOnError": true + "matchPackageNames": ["baz"], + "extractVersion": "^v(?.*)$" } ] } ``` -To abort Renovate for errors for a specific `docker` host: +## fetchReleaseNotes -```json -{ - "hostRules": [ - { - "matchHost": "docker.company.com", - "abortOnError": true - } - ] -} -``` +Use this config option to configure release notes fetching. +The available options are: -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`); +- `off` - disable release notes fetching +- `branch` - fetch release notes while creating/updating branch +- `pr`(default) - fetches release notes while creating/updating pull-request -### authType +It is not recommended to set fetchReleaseNotes=branch unless you are embedding release notes in commit information, because it results in a performance decrease. -You may use the `authType` option to create a custom HTTP `authorization` header. -For `authType` to work, you must also set your own `token`. +Renovate can fetch release notes when they are hosted on one of these platforms: -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. +- Bitbucket Cloud +- GitHub (.com and Enterprise Server) +- GitLab (.com and CE/EE) -An example for npm basic auth with token: +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-release-notes) to allow Renovate to fetch release notes from `github.com`. -```json -{ - "hostRules": [ - { - "matchHost": "npm.custom.org", - "token": "", - "authType": "Basic" - } - ] -} -``` + +!!! note + Renovate can only show release notes from some platforms and some package managers. + We're planning improvements so that Renovate can show more release notes. + Read [issue 14138 on GitHub](https://github.com/renovatebot/renovate/issues/14138) to get an overview of the planned work. -This will generate the following header: `authorization: Basic `. +## fileMatch -To use a bare token in the authorization header (required by e.g. Hex) - use the `authType` "Token-Only": +`fileMatch` is used by Renovate to know which files in a repository to parse and extract. +`fileMatch` patterns in the user config are added to the default values and do not replace them. +The default `fileMatch` patterns cannot be removed, so if you need to include or exclude specific paths then use the `ignorePaths` or `includePaths` configuration options. + +Some `fileMatch` patterns are short, like Renovate's default Go Modules `fileMatch` for example. +Here Renovate looks for _any_ `go.mod` file. +In this case you can probably keep using that default `fileMatch`. + +At other times, the possible files is too vague for Renovate to have any default. +For default, Kubernetes manifests can exist in any `*.yaml` file and we don't want Renovate to parse every single YAML file in every repository just in case some of them have a Kubernetes manifest, so Renovate's default `fileMatch` for manager `kubernetes` is actually empty (`[]`) and needs the user to tell Renovate what directories/files to look in. + +Finally, there are cases where Renovate's default `fileMatch` is good, but you may be using file patterns that a bot couldn't possibly guess about. +For example, Renovate's default `fileMatch` 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 `fileMatch` is mergeable, you don't need to duplicate the defaults and could add the missing file like this: ```json { - "hostRules": [ - { - "matchHost": "https://hex.pm/api/repos/private_repo/", - "token": "", - "authType": "Token-Only" - } - ] + "dockerfile": { + "fileMatch": ["^ACTUALLY_A_DOCKERFILE\\.template$"] + } } ``` -This will generate the header `authorization: `. +If you configure `fileMatch` then it must be within a manager object (e.g. `dockerfile` in the above example). +The full list of supported managers can be found [here](https://docs.renovatebot.com/modules/manager/). -### concurrentRequestLimit +## filterUnavailableUsers -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. +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. -Example config: +## followTag + +For `followTag` to work, the datasource must support distribution streams or tags, like for example npm does. + +The main usecase is to follow a pre-release tag of a dependency, say TypeScripts's `"insiders"` build: ```json { - "hostRules": [ + "packageRules": [ { - "matchHost": "api.github.com", - "concurrentRequestLimit": 2 + "matchPackageNames": ["typescript"], + "followTag": "insiders" } ] } ``` -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. +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. -### maxRequestsPerSecond +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. -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. +## forkModeDisallowMaintainerEdits -Example config: +Use `forkModeDisallowMaintainerEdits` to disallow maintainers from editing Renovate's pull requests when in fork mode. -```json -{ - "hostRules": [ - { - "matchHost": "api.github.com", - "maxRequestsPerSecond": 2 - } - ] -} -``` +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. -### dnsCache +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). -Enable got [dnsCache](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#dnsCache) support. -It uses `QuickLRU` with a `maxSize` of `1000`. +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. -### enableHttp2 + +!!! note + This option is only relevant if you set `forkToken`. -Enable got [http2](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#http2) support. +## forkProcessing -### hostType +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. -`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. +**Process a fork in `autodiscover` mode`** -### insecureRegistry +If you want Renovate to run on a forked repository when in `autodiscover` mode then: -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. +- Ensure a `renovate.json` config exists with `"forkProcessing": "enabled"` in your repository, +- Or run the CLI command with `--fork-processing=enabled` -Example: +**Process a fork in other modes** -```json -{ - "hostRules": [ - { - "matchHost": "reg.insecure.com", - "insecureRegistry": true - } - ] -} -``` +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. -### keepalive +**When using the Mend Renovate App** -If enabled, this allows a single TCP connection to remain open for multiple HTTP(S) requests/responses. +The behavior of `forkProcessing` depends on how you allow Renovate to run on your account. -### artifactAuth +**Renovate runs on all repositories** -You may use this field whenever it is needed to only enable authentication for a specific set of managers. +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. -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. +**Renovate runs on selected repositories** -```json -{ - "hostRules": [ - { - "hostType": "gitlab", - "matchHost": "gitlab.myorg.com", - "token": "abc123", - "artifactAuth": ["composer"] - } - ] -} +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. +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 ``` -Supported artifactAuth and hostType combinations: + +!!! 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. -| artifactAuth | hostTypes | -| ------------ | ------------------------------------------- | -| `composer` | `gitlab`, `packagist`, `github`, `git-tags` | +## gitIgnoredAuthors -### matchHost +Specify commit authors ignored by Renovate. -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. +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`. -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. +Example: ```json { - "hostRules": [ - { - "matchHost": "https://gitlab.myorg.com/api/v4/packages/npm/", - "token": "abc123" - } - ] + "gitIgnoredAuthors": ["some-bot@example.org"] } ``` -The above corresponds with an `.npmrc` like the following: - -``` -registry=https://gitlab.myorg.com/api/v4/packages/npm/ -``` +## gitLabIgnoreApprovals - -!!! note - Values containing a URL path but missing a scheme will be prepended with 'https://' (e.g. `domain.com/path` -> `https://domain.com/path`) +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`, `automergeType=pr` or `automergeType=branch`, and `platformAutomerge=true`. +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). -### timeout +## goGetDirs -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: +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: ```json { - "hostRules": [ - { - "timeout": 10000 - } - ] + "goGetDirs": ["./some-project/", "./tools/..."] } ``` -### httpsCertificateAuthority +## group -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. +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. -### httpsPrivateKey +## groupName -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](https://docs.renovatebot.com/self-hosted-configuration/#secrets) to pass it down securely instead. - -### 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. - -## 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 +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 `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: +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: ```json { - "ignoreDeps": ["eslint", "eslint-config-base"] + "packageRules": [ + { + "matchDepTypes": ["devDependencies"], + "matchUpdateTypes": ["patch", "minor"], + "groupName": "devDependencies (non-major)" + } + ] } ``` -The above is the same as if you wrote this package rule: +## 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: ```json { "packageRules": [ { - "matchPackageNames": ["eslint", "eslint-config-base"], - "enabled": false + "matchDepTypes": ["devDependencies"], + "matchUpdateTypes": ["patch", "minor"], + "groupName": "devDependencies (non-major)", + "groupSlug": "dev-dependencies" } ] } ``` -## 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. +As a result of the above, the branchName would be `renovate/dev-dependencies` instead. -For instance if you have a project with an `"examples/"` directory you wish to ignore: + +!!! note + You shouldn't usually need to configure this unless you really care about your branch names. -```json -{ - "ignorePaths": ["**/examples/**"] -} -``` +## hashedBranchLength -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. +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. -## ignorePlugins +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`. -Set this to `true` if running plugins causes problems. -Applicable for Composer only for now. +## hostRules -## ignorePrAuthor +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. -This is usually needed if someone needs to migrate bot accounts, including from the Mend Renovate App to self-hosted. -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`. -It's recommended to revert this setting once that transition period is over and all old PRs are resolved. +The lookup keys for `hostRules` are: `hostType` and `matchHost`, both of which are optional. -## ignorePresets +Supported credential fields are `token`, `username`, `password`, `timeout`, `enabled` and `insecureRegistry`. -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: +Example for configuring `docker` auth: ```json { - "extends": ["config:recommended"], - "ignorePresets": [":prHourlyLimit2"] + "hostRules": [ + { + "matchHost": "docker.io", + "username": "", + "password": "" + } + ] } ``` -It would take the entire `"config:recommended"` preset - which has a lot of sub-presets - but ignore the `":prHourlyLimit2"` rule. +If multiple `hostRules` match a request, then they will be applied in the following order/priority: -## ignoreReviewers +1. rules with only `hostType` specified +1. rules with only `matchHost` specified (sorted by `matchHost` length if multiple match) +1. rules with both `matchHost` and `hostType` specified (sorted by `matchHost` length if multiple match) -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. +To disable requests to a particular host, you can configure a rule like: ```json { - "reviewers": ["foo"], - "ignoreReviewers": ["renovate-approve"] + "hostRules": [ + { + "matchHost": "registry.npmjs.org", + "enabled": false + } + ] } ``` -## ignoreScripts +A preset alternative to the above is: -Applicable for npm and Composer only for now. Set this to `true` if running scripts causes problems. +```json +{ + "extends": [":disableHost(registry.npmjs.org)"] +} +``` -## ignoreTests +To match specific ports you have to add a protocol to `matchHost`: -Currently Renovate's default behavior is to only automerge if every status check has succeeded. +```json +{ + "hostRules": [ + { + "matchHost": "https://domain.com:9118", + "enabled": false + } + ] +} +``` -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! + +!!! warning + Using `matchHost` without a protocol behaves the same as if you had set no `matchHost` configuration. -## ignoreUnstable + +!!! 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. -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`. +### abortIgnoreStatusCodes -Also check out the `followTag` configuration option above if you wish Renovate to keep you pinned to a particular release tag. +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: -## includePaths +```json +{ + "hostRules": [ + { + "abortOnError": true, + "abortIgnoreStatusCodes": [404] + } + ] +} +``` -If you wish for Renovate to process only select paths in the repository, use `includePaths`. + +!!! tip + This field is _not_ mergeable, so the last-applied host rule takes precedence. -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. +### abortOnError -## internalChecksAsSuccess +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. -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. +To abort Renovate runs for http failures from _any_ host: -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. +```json +{ + "hostRules": [ + { + "abortOnError": true + } + ] +} +``` -Change this setting to `true` if you want to use internal Renovate checks towards a passing branch result. +To abort Renovate runs for any `docker` datasource failures: -## internalChecksFilter +```json +{ + "hostRules": [ + { + "hostType": "docker", + "abortOnError": true + } + ] +} +``` -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. +To abort Renovate for errors for a specific `docker` host: -- `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 +```json +{ + "hostRules": [ + { + "matchHost": "docker.company.com", + "abortOnError": true + } + ] +} +``` -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. +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`); -## labels +### authType -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. +You may use the `authType` option to create a custom HTTP `authorization` header. +For `authType` to work, you must also set your own `token`. -Consider this example: +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: ```json { - "labels": ["dependencies"], - "packageRules": [ + "hostRules": [ { - "matchPackagePatterns": ["eslint"], - "labels": ["linting"] + "matchHost": "npm.custom.org", + "token": "", + "authType": "Basic" } ] } ``` -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`. +This will generate the following header: `authorization: Basic `. -Renovate only adds labels when it creates the PR, which means: +To use a bare token in the authorization header (required by e.g. Hex) - use the `authType` "Token-Only": -- If you remove labels which Renovate added, it won't re-apply them -- If you change your config, the new/changed labels are not applied to any open PRs +```json +{ + "hostRules": [ + { + "matchHost": "https://hex.pm/api/repos/private_repo/", + "token": "", + "authType": "Token-Only" + } + ] +} +``` -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. +This will generate the header `authorization: `. -## lockFileMaintenance +### concurrentRequestLimit -You can use `lockFileMaintenance` to refresh lock files to keep them up-to-date. +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. -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. +Example config: -Supported lock files: +```json +{ + "hostRules": [ + { + "matchHost": "api.github.com", + "concurrentRequestLimit": 2 + } + ] +} +``` -- `.terraform.lock.hcl` -- `Cargo.lock` -- `Chart.lock` -- `composer.lock` -- `flake.lock` -- `Gemfile.lock` -- `gradle.lockfile` -- `jsonnetfile.lock.json` -- `package-lock.json` -- `packages.lock.json` -- `pdm.lock` -- `Pipfile.lock` -- `pnpm-lock.yaml` -- `poetry.lock` -- `pubspec.lock` -- `pyproject.toml` -- `requirements.txt` -- `yarn.lock` +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. -Support for new lock files may be added via feature request. +### maxRequestsPerSecond -By default, `lockFileMaintenance` is disabled. -To enable `lockFileMaintenance` add this to your configuration: +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: ```json { - "lockFileMaintenance": { "enabled": true } + "hostRules": [ + { + "matchHost": "api.github.com", + "maxRequestsPerSecond": 2 + } + ] } ``` -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. +### dnsCache -## major +Enable got [dnsCache](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#dnsCache) support. +It uses `QuickLRU` with a `maxSize` of `1000`. -Add to this object if you wish to define rules that apply only to major updates. +### enableHttp2 -## minimumReleaseAge +Enable got [http2](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#http2) support. -This feature used to be called `stabilityDays`. +### hostType -If this is set _and_ an update has a release timestamp header, then Renovate will check if the set duration has passed. +`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. -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`). -`minimumReleaseAge` is not intended to help with slowing down fast releasing project updates. -If you want to slow down PRs for a specific package, setup a custom schedule for that package. -Read [our selective-scheduling help](./noise-reduction.md#selective-scheduling) to learn how to set the schedule. +### insecureRegistry -If the time since the release is less than the set `minimumReleaseAge` a "pending" status check is added to the branch. -If enough days have passed then the "pending" status is removed, and a "passing" status check is added. +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. -Some datasources don't have a release timestamp, in which case this feature is not compatible. -Other datasources may have a release timestamp, but Renovate does not support it yet, in which case a feature request needs to be implemented. +Example: -Maven users: you cannot use `minimumReleaseAge` if a Maven source returns unreliable `last-modified` headers. +```json +{ + "hostRules": [ + { + "matchHost": "reg.insecure.com", + "insecureRegistry": true + } + ] +} +``` - -!!! note - Configuring this option will add a `renovate/stability-days` option to the status checks. +### keepalive -There are a couple of uses for `minimumReleaseAge`: +If enabled, this allows a single TCP connection to remain open for multiple HTTP(S) requests/responses. - +### artifactAuth -#### Suppress branch/PR creation for X days +You may use this field whenever it is needed to only enable authentication for a specific set of managers. -If you combine `minimumReleaseAge=3 days` and `internalChecksFilter="strict"` then Renovate will hold back from creating branches until 3 or more days have elapsed since the version was released. -We recommend that you set `dependencyDashboard=true` so you can see these pending PRs. +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. -#### Prevent holding broken npm packages +```json +{ + "hostRules": [ + { + "hostType": "gitlab", + "matchHost": "gitlab.myorg.com", + "token": "abc123", + "artifactAuth": ["composer"] + } + ] +} +``` -npm packages less than 72 hours (3 days) old can be unpublished, 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: +Supported artifactAuth and hostType combinations: + +| artifactAuth | hostTypes | +| ------------ | ------------------------------------------- | +| `composer` | `gitlab`, `packagist`, `github`, `git-tags` | + +### 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. ```json { - "packageRules": [ + "hostRules": [ { - "matchDatasources": ["npm"], - "minimumReleaseAge": "3 days" + "matchHost": "https://gitlab.myorg.com/api/v4/packages/npm/", + "token": "abc123" } ] } ``` -#### Await X time duration before Automerging - -If you enabled `automerge` _and_ `minimumReleaseAge`, it means that PRs will be created immediately but automerging will be delayed until the time-duration has passed. -This works because Renovate will add a "renovate/stability-days" pending status check to each branch/PR and that pending check will prevent the branch going green to automerge. +The above corresponds with an `.npmrc` like the following: - +``` +registry=https://gitlab.myorg.com/api/v4/packages/npm/ +``` -## minor + +!!! note + Values containing a URL path but missing a scheme will be prepended with 'https://' (e.g. `domain.com/path` -> `https://domain.com/path`) -Add to this object if you wish to define rules that apply only to minor updates. +### timeout -## npmToken +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: -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. +```json +{ + "hostRules": [ + { + "timeout": 10000 + } + ] +} +``` -## npmrc +### httpsCertificateAuthority -See [Private npm module support](./getting-started/private-packages.md) for details on how this is used. +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. -## npmrcMerge +### httpsPrivateKey -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). +Specifies the private key in [PEM format](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) for mTLS authentication. -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`. + +!!! warning + Do _not_ put your private key into this field, to avoid losing confidentiality completely. + You must use [secrets](https://docs.renovatebot.com/self-hosted-configuration/#secrets) to pass it down securely instead. -## osvVulnerabilityAlerts +### httpsCertificate -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). +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. -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: +## ignoreDeprecated -- [`crate`](https://docs.renovatebot.com/modules/datasource/crate/) -- [`go`](https://docs.renovatebot.com/modules/datasource/go/) -- [`hex`](https://docs.renovatebot.com/modules/datasource/hex/) -- [`maven`](https://docs.renovatebot.com/modules/datasource/maven/) -- [`npm`](https://docs.renovatebot.com/modules/datasource/npm/) -- [`nuget`](https://docs.renovatebot.com/modules/datasource/nuget/) -- [`packagist`](https://docs.renovatebot.com/modules/datasource/packagist/) -- [`pypi`](https://docs.renovatebot.com/modules/datasource/pypi/) -- [`rubygems`](https://docs.renovatebot.com/modules/datasource/rubygems/) +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. -## packageRules +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. -`packageRules` is a powerful feature that lets you apply rules to individual packages or to groups of packages using regex pattern matching. +## ignoreDeps -Here is an example if you want to group together all packages starting with `eslint` into a single branch/PR: +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: ```json { - "packageRules": [ - { - "matchPackagePatterns": ["^eslint"], - "groupName": "eslint packages" - } - ] + "ignoreDeps": ["eslint", "eslint-config-base"] } ``` -Note how the above uses `matchPackagePatterns` with a regex value. - -Here's an example config to limit the "noisy" `aws-sdk` package to weekly updates: +The above is the same as if you wrote this package rule: ```json { "packageRules": [ { - "matchPackageNames": ["aws-sdk"], - "schedule": ["after 9pm on sunday"] + "matchPackageNames": ["eslint", "eslint-config-base"], + "enabled": false } ] } ``` -For Maven dependencies, the package name is ``, e.g. `"matchPackageNames": ["com.thoughtworks.xstream:xstream"]` +## ignorePaths -Note how the above uses `matchPackageNames` instead of `matchPackagePatterns` because it is an exact match package name. -This is the equivalent of defining `"matchPackagePatterns": ["^aws\-sdk$"]`. -However you can mix together both `matchPackageNames` and `matchPackagePatterns` in the same package rule and the rule will be applied if _either_ match. -Example: +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: ```json { - "packageRules": [ - { - "matchPackageNames": ["neutrino"], - "matchPackagePatterns": ["^@neutrino/"], - "groupName": "neutrino monorepo" - } - ] + "ignorePaths": ["**/examples/**"] } ``` -The above rule will group together the `neutrino` package and any package matching `@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: - -```json -{ - "packageRules": [ - { - "matchFileNames": ["examples/**"], - "extends": [":semanticCommitTypeAll(chore)"] - } - ] -} -``` +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. -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` pattern (which can include an exact file name match). -For example you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: +## ignorePlugins -```json -{ - "packageRules": [ - { - "matchFileNames": ["package.json"], - "dependencyDashboardApproval": true - } - ] -} -``` +Set this to `true` if running plugins causes problems. +Applicable for Composer only for now. - -!!! tip - Renovate evaluates all `packageRules` and does not stop after the first match. - 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. +## ignorePrAuthor - -!!! warning - Avoid nesting any `object`-type configuration in a `packageRules` array, such as a `major` or `minor` block. +This is usually needed if someone needs to migrate bot accounts, including from the Mend Renovate App to self-hosted. +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`. +It's recommended to revert this setting once that transition period is over and all old PRs are resolved. -### allowedVersions +## ignorePresets -Use this - usually within a packageRule - to limit how far to upgrade a dependency. -For example, if you wish to upgrade to Angular v1.5 but not to `angular` v1.6 or higher, you could define this to be `<= 1.5` or `< 1.6.0`: +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: ```json { - "packageRules": [ - { - "matchPackageNames": ["angular"], - "allowedVersions": "<=1.5" - } - ] + "extends": ["config:recommended"], + "ignorePresets": [":prHourlyLimit2"] } ``` -The valid syntax for this will be calculated at runtime because it depends on the versioning scheme, which is itself dynamic. +It would take the entire `"config:recommended"` preset - which has a lot of sub-presets - but ignore the `":prHourlyLimit2"` rule. -This field also supports Regular Expressions if they begin and end with `/`. -For example, the following will enforce that only 3 or 4-part versions are supported, without any prefixes: +## 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. ```json { - "packageRules": [ - { - "matchPackageNames": ["com.thoughtworks.xstream:xstream"], - "allowedVersions": "/^[0-9]+\\.[0-9]+\\.[0-9]+(\\.[0-9]+)?$/" - } - ] + "reviewers": ["foo"], + "ignoreReviewers": ["renovate-approve"] } ``` -This field also supports a special negated regex syntax for ignoring certain versions. -Use the syntax `!/ /` like the following: +## ignoreScripts -```json -{ - "packageRules": [ - { - "matchPackageNames": ["chalk"], - "allowedVersions": "!/java$/" - } - ] -} -``` +Applicable for npm and Composer only for now. Set this to `true` if running scripts causes problems. -### matchDepTypes +## ignoreTests -Use this field if you want to limit a `packageRule` to certain `depType` values. -Invalid if used outside of a `packageRule`. +Currently Renovate's default behavior is to only automerge if every status check has succeeded. -### excludeDepNames +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! -### excludeDepPatterns +## ignoreUnstable -### excludePackageNames +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`. -**Important**: Do not mix this up with the option `ignoreDeps`. -Use `ignoreDeps` instead if all you want to do is have a list of package names for Renovate to ignore. +Also check out the `followTag` configuration option above if you wish Renovate to keep you pinned to a particular release tag. -Use `excludePackageNames` if you want to have one or more exact name matches excluded in your package rule. -See also `matchPackageNames`. +## includePaths -```json -{ - "packageRules": [ - { - "matchPackagePatterns": ["^eslint"], - "excludePackageNames": ["eslint-foo"] - } - ] -} -``` +If you wish for Renovate to process only select paths in the repository, use `includePaths`. -The above will match all package names starting with `eslint` but exclude the specific package `eslint-foo`. +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. -### excludePackagePatterns +## internalChecksAsSuccess -Use this field if you want to have one or more package name patterns excluded in your package rule. -See also `matchPackagePatterns`. +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. -```json -{ - "packageRules": [ - { - "matchPackagePatterns": ["^eslint"], - "excludePackagePatterns": ["^eslint-foo"] - } - ] -} -``` +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. -The above will match all package names starting with `eslint` but exclude ones starting with `eslint-foo`. +Change this setting to `true` if you want to use internal Renovate checks towards a passing branch result. -### excludePackagePrefixes +## internalChecksFilter -Use this field if you want to have one or more package name prefixes excluded in your package rule, without needing to write a regex. -See also `matchPackagePrefixes`. +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. -```json -{ - "packageRules": [ - { - "matchPackagePrefixes": ["eslint"], - "excludePackagePrefixes": ["eslint-foo"] - } - ] -} -``` +- `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 above will match all package names starting with `eslint` but exclude ones starting with `eslint-foo`. +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. -### excludeRepositories +## labels -Use this field to restrict rules to a particular repository. e.g. +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: ```json { + "labels": ["dependencies"], "packageRules": [ { - "excludeRepositories": ["literal/repo", "/^some/.*$/", "**/*-archived"], - "enabled": false + "matchPackagePatterns": ["eslint"], + "labels": ["linting"] } ] } ``` -This field supports Regular Expressions if they begin and end with `/`, otherwise it will use `minimatch`. +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`. -### matchCategories +Renovate only adds labels when it creates the PR, which means: -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). +- If you remove labels which Renovate added, it won't re-apply them +- If you change your config, the new/changed labels are not applied to any open PRs - -!!! 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. +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. -```json -{ - "packageRules": [ - { - "matchCategories": ["python"], - "addLabels": ["py"] - } - ] -} -``` +## lockFileMaintenance -### matchRepositories +You can use `lockFileMaintenance` to refresh lock files to keep them up-to-date. -Use this field to restrict rules to a particular repository. e.g. +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. -```json -{ - "packageRules": [ - { - "matchRepositories": ["literal/repo", "/^some/.*$/", "**/*-archived"], - "enabled": false - } - ] -} -``` +Supported lock files: -This field supports Regular Expressions if they begin and end with `/`, otherwise it will use `minimatch`. +- `.terraform.lock.hcl` +- `Cargo.lock` +- `Chart.lock` +- `composer.lock` +- `flake.lock` +- `Gemfile.lock` +- `gradle.lockfile` +- `jsonnetfile.lock.json` +- `package-lock.json` +- `packages.lock.json` +- `pdm.lock` +- `Pipfile.lock` +- `pnpm-lock.yaml` +- `poetry.lock` +- `pubspec.lock` +- `pyproject.toml` +- `requirements.txt` +- `yarn.lock` -### matchBaseBranches +Support for new lock files may be added via feature request. -Use this field to restrict rules to a particular branch. e.g. +By default, `lockFileMaintenance` is disabled. +To enable `lockFileMaintenance` add this to your configuration: ```json { - "packageRules": [ - { - "matchBaseBranches": ["main"], - "excludePackagePatterns": ["^eslint"], - "enabled": false - } - ] + "lockFileMaintenance": { "enabled": true } } ``` -This field also supports Regular Expressions if they begin and end with `/`. e.g. +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. -```json -{ - "packageRules": [ - { - "matchBaseBranches": ["/^release/.*/"], - "excludePackagePatterns": ["^eslint"], - "enabled": false - } - ] -} -``` +## major -### matchManagers +Add to this object if you wish to define rules that apply only to major updates. -Use this field to restrict rules to a particular package manager. e.g. +## minimumReleaseAge -```json -{ - "packageRules": [ - { - "matchPackageNames": ["node"], - "matchManagers": ["dockerfile"], - "enabled": false - } - ] -} -``` +This feature used to be called `stabilityDays`. -For the full list of available managers, see the [Supported Managers](https://docs.renovatebot.com/modules/manager/#supported-managers) documentation. +If this is set _and_ an update has a release timestamp header, then Renovate will check if the set duration has passed. -### matchDatasources +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`). +`minimumReleaseAge` is not intended to help with slowing down fast releasing project updates. +If you want to slow down PRs for a specific package, setup a custom schedule for that package. +Read [our selective-scheduling help](./noise-reduction.md#selective-scheduling) to learn how to set the schedule. -Use this field to restrict rules to a particular datasource. e.g. +If the time since the release is less than the set `minimumReleaseAge` a "pending" status check is added to the branch. +If enough days have passed then the "pending" status is removed, and a "passing" status check is added. + +Some datasources don't have a release timestamp, in which case this feature is not compatible. +Other datasources may have a release timestamp, but Renovate does not support it yet, in which case a feature request needs to be implemented. + +Maven users: you cannot use `minimumReleaseAge` if a Maven source returns unreliable `last-modified` headers. + + +!!! note + Configuring this option will add a `renovate/stability-days` option to the status checks. + +There are a couple of uses for `minimumReleaseAge`: + + + +#### Suppress branch/PR creation for X days + +If you combine `minimumReleaseAge=3 days` and `internalChecksFilter="strict"` then Renovate will hold back from creating branches until 3 or more days have elapsed since the version was released. +We recommend that 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, 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: ```json { "packageRules": [ { - "matchDatasources": ["orb"], - "labels": ["circleci-orb!!"] + "matchDatasources": ["npm"], + "minimumReleaseAge": "3 days" } ] } ``` -### matchCurrentValue +#### Await X time duration before Automerging -This option is matched against the `currentValue` field of a dependency. +If you enabled `automerge` _and_ `minimumReleaseAge`, it means that PRs will be created immediately but automerging will be delayed until the time-duration has passed. +This works because Renovate will add a "renovate/stability-days" pending status check to each branch/PR and that pending check will prevent the branch going green to automerge. -`matchCurrentValue` supports Regular Expressions which must begin and end with `/`. -For example, the following enforces that only `1.*` versions will be used: + + +## minor + +Add to this object if you wish to define rules that apply only to minor updates. + +## 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`](https://docs.renovatebot.com/modules/datasource/crate/) +- [`go`](https://docs.renovatebot.com/modules/datasource/go/) +- [`hex`](https://docs.renovatebot.com/modules/datasource/hex/) +- [`maven`](https://docs.renovatebot.com/modules/datasource/maven/) +- [`npm`](https://docs.renovatebot.com/modules/datasource/npm/) +- [`nuget`](https://docs.renovatebot.com/modules/datasource/nuget/) +- [`packagist`](https://docs.renovatebot.com/modules/datasource/packagist/) +- [`pypi`](https://docs.renovatebot.com/modules/datasource/pypi/) +- [`rubygems`](https://docs.renovatebot.com/modules/datasource/rubygems/) + +## packageRules + +`packageRules` is a powerful feature that lets you apply rules to individual packages or to groups of packages using regex pattern matching. + +Here is an example if you want to group together all packages starting with `eslint` into a single branch/PR: ```json { "packageRules": [ { - "matchPackagePatterns": ["io.github.resilience4j"], - "matchCurrentValue": "/^1\\./" + "matchPackagePatterns": ["^eslint"], + "groupName": "eslint packages" } ] } ``` -This field also supports a special negated regex syntax to ignore certain versions. -Use the syntax `!/ /` like this: +Note how the above uses `matchPackagePatterns` with a regex value. + +Here's an example config to limit the "noisy" `aws-sdk` package to weekly updates: ```json { "packageRules": [ { - "matchPackagePatterns": ["io.github.resilience4j"], - "matchCurrentValue": "!/^0\\./" + "matchPackageNames": ["aws-sdk"], + "schedule": ["after 9pm on sunday"] } ] } ``` -### 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. +For Maven dependencies, the package name is ``, e.g. `"matchPackageNames": ["com.thoughtworks.xstream:xstream"]` -`matchCurrentVersion` can be an exact version or a version range: +Note how the above uses `matchPackageNames` instead of `matchPackagePatterns` because it is an exact match package name. +This is the equivalent of defining `"matchPackagePatterns": ["^aws\-sdk$"]`. +However you can mix together both `matchPackageNames` and `matchPackagePatterns` in the same package rule and the rule will be applied if _either_ match. +Example: ```json { "packageRules": [ { - "matchCurrentVersion": ">=1.0.0", - "matchPackageNames": ["angular"] + "matchPackageNames": ["neutrino"], + "matchPackagePatterns": ["^@neutrino/"], + "groupName": "neutrino monorepo" } ] } ``` -The syntax of the version range must follow the [versioning scheme](https://docs.renovatebot.com/modules/versioning/#supported-versioning) used by the matched package(s). -This is usually defined by the [manager](https://docs.renovatebot.com/modules/manager/#supported-managers) which discovered them or by the default versioning for the package's [datasource](https://docs.renovatebot.com/modules/datasource/). -For example, a Gradle package would typically need Gradle constraint syntax (e.g. `[,7.0)`) and not SemVer syntax (e.g. `<7.0`). +The above rule will group together the `neutrino` package and any package matching `@neutrino/*`. -This field also supports Regular Expressions which must begin and end with `/`. -For example, the following enforces that only `1.*` versions will be used: +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: ```json { "packageRules": [ { - "matchPackagePatterns": ["io.github.resilience4j"], - "matchCurrentVersion": "/^1\\./" + "matchFileNames": ["examples/**"], + "extends": [":semanticCommitTypeAll(chore)"] } ] } ``` -This field also supports a special negated regex syntax to ignore certain versions. -Use the syntax `!/ /` like this: +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` pattern (which can include an exact file name match). +For example you have multiple `package.json` and want to use `dependencyDashboardApproval` only on the root `package.json`: ```json { "packageRules": [ { - "matchPackagePatterns": ["io.github.resilience4j"], - "matchCurrentVersion": "!/^0\\./" + "matchFileNames": ["package.json"], + "dependencyDashboardApproval": true } ] } ``` -### matchFileNames + +!!! tip + Renovate evaluates all `packageRules` and does not stop after the first match. + 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. -Renovate will compare `matchFileNames` glob matching against the dependency's package file and also lock file if one exists. + +!!! warning + Avoid nesting any `object`-type configuration in a `packageRules` array, such as a `major` or `minor` block. -The following example matches `package.json` but _not_ `package/frontend/package.json`: +### allowedVersions + +Use this - usually within a packageRule - to limit how far to upgrade a dependency. +For example, if you wish to upgrade to Angular v1.5 but not to `angular` v1.6 or higher, you could define this to be `<= 1.5` or `< 1.6.0`: ```json { "packageRules": [ { - "matchFileNames": ["package.json"], - "labels": ["npm"] + "matchPackageNames": ["angular"], + "allowedVersions": "<=1.5" } ] } ``` -The following example matches any `package.json`, including files like `backend/package.json`: +The valid syntax for this will be calculated at runtime because it depends on the versioning scheme, which is itself dynamic. + +This field also supports Regular Expressions if they begin and end with `/`. +For example, the following will enforce that only 3 or 4-part versions are supported, without any prefixes: ```json { "packageRules": [ { - "description": "Group dependencies from package.json files", - "matchFileNames": ["**/package.json"], - "groupName": "All package.json changes" + "matchPackageNames": ["com.thoughtworks.xstream:xstream"], + "allowedVersions": "/^[0-9]+\\.[0-9]+\\.[0-9]+(\\.[0-9]+)?$/" } ] } ``` -The following example matches any file in directories starting with `app/`: +This field also supports a special negated regex syntax for ignoring certain versions. +Use the syntax `!/ /` like the following: ```json { "packageRules": [ { - "description": "Group all dependencies from the app directory", - "matchFileNames": ["app/**"], - "groupName": "App dependencies" + "matchPackageNames": ["chalk"], + "allowedVersions": "!/java$/" } ] } ``` -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`). +### matchDepTypes -### matchDepNames +Use this field if you want to limit a `packageRule` to certain `depType` values. +Invalid if used outside of a `packageRule`. -### matchDepPatterns +### excludeDepNames -### matchPackageNames +### excludeDepPatterns -Use this field if you want to have one or more exact name matches in your package rule. -See also `excludePackageNames`. +### excludePackageNames + +**Important**: Do not mix this up with the option `ignoreDeps`. +Use `ignoreDeps` instead if all you want to do is have a list of package names for Renovate to ignore. + +Use `excludePackageNames` if you want to have one or more exact name matches excluded in your package rule. +See also `matchPackageNames`. ```json { "packageRules": [ { - "matchPackageNames": ["angular"], - "rangeStrategy": "pin" + "matchPackagePatterns": ["^eslint"], + "excludePackageNames": ["eslint-foo"] } ] } ``` -The above will configure `rangeStrategy` to `pin` only for the package `angular`. +The above will match all package names starting with `eslint` but exclude the specific package `eslint-foo`. -### matchPackagePatterns +### excludePackagePatterns -Use this field if you want to have one or more package names patterns in your package rule. -See also `excludePackagePatterns`. +Use this field if you want to have one or more package name patterns excluded in your package rule. +See also `matchPackagePatterns`. ```json { "packageRules": [ { - "matchPackagePatterns": ["^angular"], - "rangeStrategy": "replace" + "matchPackagePatterns": ["^eslint"], + "excludePackagePatterns": ["^eslint-foo"] } ] } ``` -The above will configure `rangeStrategy` to `replace` for any package starting with `angular`. +The above will match all package names starting with `eslint` but exclude ones starting with `eslint-foo`. -### matchPackagePrefixes +### excludePackagePrefixes -Use this field to match a package prefix without needing to write a regex expression. -See also `excludePackagePrefixes`. +Use this field if you want to have one or more package name prefixes excluded in your package rule, without needing to write a regex. +See also `matchPackagePrefixes`. ```json { "packageRules": [ { - "matchPackagePrefixes": ["angular"], - "rangeStrategy": "replace" + "matchPackagePrefixes": ["eslint"], + "excludePackagePrefixes": ["eslint-foo"] } ] } ``` -Like the earlier `matchPackagePatterns` example, the above will configure `rangeStrategy` to `replace` for any package starting with `angular`. - -`matchPackagePrefixes` will match against `packageName` first, and then `depName`, however `depName` matching is deprecated and will be removed in a future major release. -If matching against `depName`, use `matchDepPatterns` instead. +The above will match all package names starting with `eslint` but exclude ones starting with `eslint-foo`. -### matchSourceUrlPrefixes +### excludeRepositories -Here's an example of where you use this to group together all packages from the `renovatebot` GitHub org: +Use this field to restrict rules to a particular repository. e.g. ```json { "packageRules": [ { - "matchSourceUrlPrefixes": ["https://github.com/renovatebot/"], - "groupName": "All renovate packages" + "excludeRepositories": ["literal/repo", "/^some/.*$/", "**/*-archived"], + "enabled": false } ] } ``` -### matchSourceUrls +This field supports Regular Expressions if they begin and end with `/`, otherwise it will use `minimatch`. -Here's an example of where you use this to group together all packages from the Vue monorepo: +### 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. ```json { "packageRules": [ { - "matchSourceUrls": ["https://github.com/vuejs/vue"], - "groupName": "Vue monorepo packages" + "matchCategories": ["python"], + "addLabels": ["py"] } ] } ``` -### matchUpdateTypes +### matchRepositories -Use `matchUpdateTypes` to match rules against types of updates. -For example to apply a special label to `major` updates: +Use this field to restrict rules to a particular repository. e.g. ```json { "packageRules": [ { - "matchUpdateTypes": ["major"], - "labels": ["UPDATE-MAJOR"] + "matchRepositories": ["literal/repo", "/^some/.*$/", "**/*-archived"], + "enabled": false } ] } ``` - -!!! 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. - -### matchConfidence +This field supports Regular Expressions if they begin and end with `/`, otherwise it will use `minimatch`. - -!!! 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. +### matchBaseBranches -For example to group high merge confidence updates: +Use this field to restrict rules to a particular branch. e.g. ```json { "packageRules": [ { - "matchConfidence": ["high", "very high"], - "groupName": "high merge confidence" + "matchBaseBranches": ["main"], + "excludePackagePatterns": ["^eslint"], + "enabled": false } ] } ``` -Tokens can be configured via `hostRules` using the `"merge-confidence"` `hostType`: +This field also supports Regular Expressions if they begin and end with `/`. e.g. ```json { - "hostRules": [ + "packageRules": [ { - "hostType": "merge-confidence", - "token": "********" + "matchBaseBranches": ["/^release/.*/"], + "excludePackagePatterns": ["^eslint"], + "enabled": false } ] } ``` -### customChangelogUrl +### matchManagers -Use this field to set the source URL for a package, including overriding an existing one. -Source URLs are necessary in order to look up release notes. +Use this field to restrict rules to a particular package manager. e.g. -Using this field we can specify the exact URL to fetch release notes from. +```json +{ + "packageRules": [ + { + "matchPackageNames": ["node"], + "matchManagers": ["dockerfile"], + "enabled": false + } + ] +} +``` -Example setting source URL for package "dummy": +For the full list of available managers, see the [Supported Managers](https://docs.renovatebot.com/modules/manager/#supported-managers) documentation. + +### matchDatasources + +Use this field to restrict rules to a particular datasource. e.g. ```json { "packageRules": [ { - "matchPackageNames": ["dummy"], - "customChangelogUrl": "https://github.com/org/dummy" + "matchDatasources": ["orb"], + "labels": ["circleci-orb!!"] } ] } ``` - -!!! note - Renovate can fetch changelogs from Bitbucket, Gitea (Forgejo), GitHub and GitLab platforms only, and setting the URL to an unsupported host/platform type won't change that. +### matchCurrentValue -### replacementName +This option is matched against the `currentValue` field of a dependency. -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. +`matchCurrentValue` supports Regular Expressions which must begin and end with `/`. +For example, the following enforces that only `1.*` versions will be used: -Managers which do not support replacement: +```json +{ + "packageRules": [ + { + "matchPackagePatterns": ["io.github.resilience4j"], + "matchCurrentValue": "/^1\\./" + } + ] +} +``` -- `bazel` -- `git-submodules` -- `gomod` -- `gradle` -- `hermit` -- `homebrew` -- `maven` -- `regex` +This field also supports a special negated regex syntax to ignore certain versions. +Use the syntax `!/ /` like this: -Use the `replacementName` config option to set the name of a replacement package. +```json +{ + "packageRules": [ + { + "matchPackagePatterns": ["io.github.resilience4j"], + "matchCurrentValue": "!/^0\\./" + } + ] +} +``` -Can be used in combination with `replacementVersion`. +### matchCurrentVersion -You can suggest a new community package rule by editing [the `replacements.ts` file on the Renovate repository](https://github.com/renovatebot/renovate/blob/main/lib/config/presets/internal/replacements.ts) and opening a pull request. +The `currentVersion` field will be one of the following (in order of preference): -### replacementNameTemplate +- locked version if a lock file exists +- resolved version +- current value - -!!! note - `replacementName` will take precedence if used within the same package rule. +Consider using instead `matchCurrentValue` if you wish to match against the raw string value of a dependency. -Use the `replacementNameTemplate` config option to control the replacement name. +`matchCurrentVersion` can be an exact version or a version range: -Use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. +```json +{ + "packageRules": [ + { + "matchCurrentVersion": ">=1.0.0", + "matchPackageNames": ["angular"] + } + ] +} +``` -For example, the following package rule can be used to replace the registry for `docker` images: +The syntax of the version range must follow the [versioning scheme](https://docs.renovatebot.com/modules/versioning/#supported-versioning) used by the matched package(s). +This is usually defined by the [manager](https://docs.renovatebot.com/modules/manager/#supported-managers) which discovered them or by the default versioning for the package's [datasource](https://docs.renovatebot.com/modules/datasource/). +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: ```json { "packageRules": [ { - "matchDatasources": ["docker"], - "matchPackagePatterns": ["^docker\\.io/.+"], - "replacementNameTemplate": "{{{replace 'docker\\.io/' 'ghcr.io/' packageName}}}" + "matchPackagePatterns": ["io.github.resilience4j"], + "matchCurrentVersion": "/^1\\./" } ] } ``` -Or, to add a registry prefix to any `docker` images that do not contain an explicit registry: +This field also supports a special negated regex syntax to ignore certain versions. +Use the syntax `!/ /` like this: ```json { "packageRules": [ { - "description": "official images", - "matchDatasources": ["docker"], - "matchPackagePatterns": ["^[a-z-]+$"], - "replacementNameTemplate": "some.registry.org/library/{{{packageName}}}" - }, - { - "description": "non-official images", - "matchDatasources": ["docker"], - "matchPackagePatterns": ["^[a-z-]+/[a-z-]+$"], - "replacementNameTemplate": "some.registry.org/{{{packageName}}}" + "matchPackagePatterns": ["io.github.resilience4j"], + "matchCurrentVersion": "!/^0\\./" } ] } ``` -### replacementVersion +### matchFileNames -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. +Renovate will compare `matchFileNames` glob matching against the dependency's package file and also lock file if one exists. -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`: +The following example matches `package.json` but _not_ `package/frontend/package.json`: ```json { "packageRules": [ { - "matchDatasources": ["npm"], - "matchPackageNames": ["jade"], - "replacementName": "pug", - "replacementVersion": "2.0.0" + "matchFileNames": ["package.json"], + "labels": ["npm"] } ] } ``` -## patch - -Add to this object if you wish to define rules that apply only to patch updates. +The following example matches any `package.json`, including files like `backend/package.json`: -## pin +```json +{ + "packageRules": [ + { + "description": "Group dependencies from package.json files", + "matchFileNames": ["**/package.json"], + "groupName": "All package.json changes" + } + ] +} +``` -Add to this object if you wish to define rules that apply only to PRs that pin dependencies. +The following example matches any file in directories starting with `app/`: -## pinDigest +```json +{ + "packageRules": [ + { + "description": "Group all dependencies from the app directory", + "matchFileNames": ["app/**"], + "groupName": "App dependencies" + } + ] +} +``` -Add to this object if you wish to define rules that apply only to PRs that pin digests. +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`). -## pinDigests +### matchDepNames -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. +### matchDepPatterns -## platformAutomerge +### matchPackageNames - -!!! 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. +Use this field if you want to have one or more exact name matches in your package rule. +See also `excludePackageNames`. -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. - -Renovate tries platform-native automerge only when it initially creates the PR. -Any PR that is being updated will be automerged with the Renovate-based automerge. - -`platformAutomerge` will configure PRs to be merged after all (if any) branch policies have been met. -This option is available for Azure, 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 [Key Concepts, Automerge, 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. - -## postUpdateOptions +```json +{ + "packageRules": [ + { + "matchPackageNames": ["angular"], + "rangeStrategy": "pin" + } + ] +} +``` -Table with options: +The above will configure `rangeStrategy` to `pin` only for the package `angular`. -| Name | Description | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `bundlerConservative` | Enable conservative mode for `bundler` (Ruby dependencies). This will only update the immediate dependency in the lockfile instead of all subdependencies. | -| `gomodMassage` | Enable massaging `replace` directives before calling `go` commands. | -| `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). | -| `helmUpdateSubChartArchives` | Update subchart archives in the `/charts` folder. | -| `npmDedupe` | Run `npm dedupe` after `package-lock.json` updates. | -| `pnpmDedupe` | Run `pnpm dedupe` 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. | +### matchPackagePatterns -## postUpgradeTasks +Use this field if you want to have one or more package names patterns in your package rule. +See also `excludePackagePatterns`. - -!!! note - Post-upgrade tasks can only be used on self-hosted Renovate instances. +```json +{ + "packageRules": [ + { + "matchPackagePatterns": ["^angular"], + "rangeStrategy": "replace" + } + ] +} +``` -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. +The above will configure `rangeStrategy` to `replace` for any package starting with `angular`. -Each command must match at least one of the patterns defined in `allowedPostUpgradeCommands` (a global-only configuration option) in order to be executed. -If the list of allowed tasks is empty then no tasks will be executed. +### matchPackagePrefixes -e.g. +Use this field to match a package prefix without needing to write a regex expression. +See also `excludePackagePrefixes`. ```json { - "postUpgradeTasks": { - "commands": ["tslint --fix"], - "fileFilters": ["yarn.lock", "**/*.js"], - "executionMode": "update" - } + "packageRules": [ + { + "matchPackagePrefixes": ["angular"], + "rangeStrategy": "replace" + } + ] } ``` -The `postUpgradeTasks` configuration consists of three fields: - -### commands - -A list of commands that are executed after Renovate has updated a dependency but before the commit is made. - -You can use variable templating in your commands as long as [`allowPostUpgradeCommandTemplating`](./self-hosted-configuration.md#allowpostupgradecommandtemplating) is enabled. +Like the earlier `matchPackagePatterns` example, the above will configure `rangeStrategy` to `replace` for any package starting with `angular`. - -!!! note - Do not use `git add` in your commands to add new files to be tracked, add them by including them in your [`fileFilters`](#filefilters) instead. +`matchPackagePrefixes` will match against `packageName` first, and then `depName`, however `depName` matching is deprecated and will be removed in a future major release. +If matching against `depName`, use `matchDepPatterns` instead. -### fileFilters +### matchSourceUrlPrefixes -A list of glob-style matchers that determine which files will be included in the final commit made by Renovate. -Dotfiles are included. +Here's an example of where you use this to group together all packages from the `renovatebot` GitHub org: -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. +```json +{ + "packageRules": [ + { + "matchSourceUrlPrefixes": ["https://github.com/renovatebot/"], + "groupName": "All renovate packages" + } + ] +} +``` -### executionMode +### matchSourceUrls -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. +Here's an example of where you use this to group together all packages from the Vue monorepo: -## prBodyColumns +```json +{ + "packageRules": [ + { + "matchSourceUrls": ["https://github.com/vuejs/vue"], + "groupName": "Vue monorepo packages" + } + ] +} +``` -Use this array to provide a list of column names you wish to include in the PR tables. +### matchUpdateTypes -For example, if you wish to add the package file name to the table, you would add this to your config: +Use `matchUpdateTypes` to match rules against types of updates. +For example to apply a special label to `major` updates: ```json { - "prBodyColumns": [ - "Package", - "Update", - "Type", - "New value", - "Package file", - "References" + "packageRules": [ + { + "matchUpdateTypes": ["major"], + "labels": ["UPDATE-MAJOR"] + } ] } ``` -!!! note - "Package file" is predefined in the default `prBodyDefinitions` object so does not require a definition before it can be used. +!!! 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. -## prBodyDefinitions +### matchConfidence -You can configure this object to either (a) modify the template for an existing table column in PR bodies, or (b) you wish to _add_ a definition for a new/additional column. + +!!! 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. -Here is an example of modifying the default value for the `"Package"` column to put it inside a `` block: +For example to group high merge confidence updates: ```json { - "prBodyDefinitions": { - "Package": "`{{{depName}}}`" - } + "packageRules": [ + { + "matchConfidence": ["high", "very high"], + "groupName": "high merge confidence" + } + ] } ``` -Here is an example of adding a custom `"Sourcegraph"` column definition: +Tokens can be configured via `hostRules` using the `"merge-confidence"` `hostType`: ```json { - "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" + "hostRules": [ + { + "hostType": "merge-confidence", + "token": "********" + } ] } ``` - -!!! 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. +### customChangelogUrl -## prBodyNotes +Use this field to set the source URL for a package, including overriding an existing one. +Source URLs are necessary in order to look up release notes. -Use this field to add custom content inside PR bodies, including conditionally. +Using this field we can specify the exact URL to fetch release notes from. -e.g. if you wish to add an extra Warning to major updates: +Example setting source URL for package "dummy": ```json { - "prBodyNotes": ["{{#if isMajor}}:warning: MAJOR MAJOR MAJOR :warning:{{/if}}"] + "packageRules": [ + { + "matchPackageNames": ["dummy"], + "customChangelogUrl": "https://github.com/org/dummy" + } + ] } ``` -## prBodyTemplate + +!!! note + Renovate can fetch changelogs from Bitbucket, Gitea (Forgejo), GitHub and GitLab platforms only, and setting the URL to an unsupported host/platform type won't change that. -The available sections are: +### replacementName -- `header` -- `table` -- `warnings` -- `notes` -- `changelogs` -- `configDescription` -- `controls` -- `footer` +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. -## prConcurrentLimit +Managers which do not support replacement: -This setting - if enabled - limits Renovate to a maximum of `x` concurrent PRs open at any time. +- `bazel` +- `git-submodules` +- `gomod` +- `gradle` +- `hermit` +- `homebrew` +- `maven` +- `regex` -This limit is enforced on a per-repository basis. +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.ts` file on the Renovate repository](https://github.com/renovatebot/renovate/blob/main/lib/config/presets/internal/replacements.ts) and opening a pull request. + +### replacementNameTemplate !!! note - Renovate always creates security PRs, even if the concurrent PR limit is already reached. - Security PRs have `[SECURITY]` in their PR title. + `replacementName` will take precedence if used within the same package rule. -## prCreation +Use the `replacementNameTemplate` config option to control the replacement name. -This setting tells Renovate when you would like it to raise PRs: +Use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. -- `immediate` (default): Renovate will create PRs immediately after creating the corresponding branch -- `not-pending`: Renovate will wait until status checks have completed (passed or failed) before raising the PR -- `status-success`: Renovate won't raise PRs unless tests pass - -Renovate defaults to `immediate` but you might want to change this to `not-pending` instead. +For example, the following package rule can be used to replace the registry for `docker` images: -With prCreation 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 or not. +```json +{ + "packageRules": [ + { + "matchDatasources": ["docker"], + "matchPackagePatterns": ["^docker\\.io/.+"], + "replacementNameTemplate": "{{{replace 'docker\\.io/' 'ghcr.io/' packageName}}}" + } + ] +} +``` -With prCreation 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 hrs have elapsed since creation of the commit. +Or, to add a registry prefix to any `docker` images that do not contain an explicit registry: -With prCreation set to `status-success`, Renovate creates the PR only if/ once all tests have passed. +```json +{ + "packageRules": [ + { + "description": "official images", + "matchDatasources": ["docker"], + "matchPackagePatterns": ["^[a-z-]+$"], + "replacementNameTemplate": "some.registry.org/library/{{{packageName}}}" + }, + { + "description": "non-official images", + "matchDatasources": ["docker"], + "matchPackagePatterns": ["^[a-z-]+/[a-z-]+$"], + "replacementNameTemplate": "some.registry.org/{{{packageName}}}" + } + ] +} +``` -For all cases of non-immediate PR creation, Renovate doesn't run instantly once tests complete. -Instead, Renovate can create the PR on its next run after relevant tests have completed, so there will be some delay. +### replacementVersion -## prFooter +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. -## prHeader +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`: -## prHourlyLimit +```json +{ + "packageRules": [ + { + "matchDatasources": ["npm"], + "matchPackageNames": ["jade"], + "replacementName": "pug", + "replacementVersion": "2.0.0" + } + ] +} +``` -This config option slows down the _rate_ at which Renovate creates PRs. +## patch -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`: +Add to this object if you wish to define rules that apply only to patch updates. -1. Renovate creates an Onboarding PR -1. You merge the onboarding PR to activate Renovate -1. Renovate creates a "Pin Dependencies" PR (if needed) -1. You merge the "Pin Dependencies" PR -1. Renovate creates every single upgrade PR needed, which can be a lot +## pin -The above may cause: +Add to this object if you wish to define rules that apply only to PRs that pin dependencies. -- Renovate bot's PRs to overwhelm your CI systems -- a lot of test runs, because branches are rebased each time you merge a PR +## pinDigest -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. +Add to this object if you wish to define rules that apply only to PRs that pin digests. - -!!! 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. +## pinDigests -## prNotPendingHours +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. -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. +## platformAutomerge !!! note - If the option `minimumReleaseAge` is non-zero then Renovate disables the `prNotPendingHours` functionality. + 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. -## prPriority +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. -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: +Renovate tries platform-native automerge only when it initially creates the PR. +Any PR that is being updated will be automerged with the Renovate-based automerge. -1. `pinDigest` -1. `pin` -1. `digest` -1. `patch` -1. `minor` -1. `major` +`platformAutomerge` will configure PRs to be merged after all (if any) branch policies have been met. +This option is available for Azure, Gitea, GitHub and GitLab. +It falls back to Renovate-based automerge if the platform-native automerge is not available. -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. +You can also fine-tune the behavior by setting `packageRules` if you want to use it selectively (e.g. per-package). -Here's an example of how you would define PR priority so that `devDependencies` are raised last and `react` is raised first: +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. -```json -{ - "packageRules": [ - { - "matchDepTypes": ["devDependencies"], - "prPriority": -1 - }, - { - "matchPackageNames": ["react"], - "prPriority": 5 - } - ] -} -``` +Please check platform specific docs for version requirements. -## prTitle +To learn how to use GitHub's Merge Queue feature with Renovate, read our [Key Concepts, Automerge, GitHub Merge Queue](./key-concepts/automerge.md#github-merge-queue) docs. -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. +## platformCommit -## prTitleStrict +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. -There are certain scenarios where the default behavior appends extra context to the PR title. +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. -These scenarios include if a `baseBranch` or if there is a grouped update and either `separateMajorMinor` or `separateMinorPatch` is true. +## postUpdateOptions -Using this option allows you to skip these default behaviors and use other templating methods to control the format of the PR title. +Table with options: -## printConfig +| Name | Description | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bundlerConservative` | Enable conservative mode for `bundler` (Ruby dependencies). This will only update the immediate dependency in the lockfile instead of all subdependencies. | +| `gomodMassage` | Enable massaging `replace` directives before calling `go` commands. | +| `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). | +| `helmUpdateSubChartArchives` | Update subchart archives in the `/charts` folder. | +| `npmDedupe` | Run `npm dedupe` after `package-lock.json` updates. | +| `pnpmDedupe` | Run `pnpm dedupe` 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. | -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. +## postUpgradeTasks -## pruneBranchAfterAutomerge + +!!! note + Post-upgrade tasks can only be used on self-hosted Renovate instances. -By default Renovate deletes, or "prunes", the branch after automerging. -Set `pruneBranchAfterAutomerge` to `false` to keep the branch after automerging. +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. -## pruneStaleBranches +Each command must match at least one of the patterns defined in `allowedPostUpgradeCommands` (a global-only configuration option) in order to be executed. +If the list of allowed tasks is empty then no tasks will be executed. -Configure to `false` to disable deleting orphan branches and autoclosing PRs. -Defaults to `true`. +e.g. -## rangeStrategy +```json +{ + "postUpgradeTasks": { + "commands": ["tslint --fix"], + "fileFilters": ["yarn.lock", "**/*.js"], + "executionMode": "update" + } +} +``` -Behavior: +The `postUpgradeTasks` configuration consists of three fields: -- `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`, `composer`, `npm`, `yarn`, `terraform` and `poetry` so far -- `in-range-only` = Update the lock file when in-range updates are available, ignore package file updates +### commands -Renovate's `"auto"` strategy works like this for npm: +A list of commands that are executed after Renovate has updated a dependency but before the commit is made. -1. Widen `peerDependencies` -1. 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"` -1. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` -1. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. +You can use variable templating in your commands as long as [`allowPostUpgradeCommandTemplating`](./self-hosted-configuration.md#allowpostupgradecommandtemplating) is enabled. -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. + +!!! note + Do not use `git add` in your commands to add new files to be tracked, add them by including them in your [`fileFilters`](#filefilters) instead. -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. +### fileFilters -This feature supports caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`. +A list of glob-style matchers that determine which files will be included in the final commit made by Renovate. +Dotfiles are included. -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. +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. -## rebaseLabel +### executionMode -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. +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. -## rebaseWhen +## prBodyColumns -Possible values and meanings: +Use this array to provide a list of column names you wish to include in the PR tables. -- `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 -- `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 +For example, if you wish to add the package file name to the table, you would add this to your config: -`rebaseWhen=conflicted` is not recommended if you have enabled Renovate automerge, because: +```json +{ + "prBodyColumns": [ + "Package", + "Update", + "Type", + "New value", + "Package file", + "References" + ] +} +``` -- 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 + +!!! note + "Package file" is predefined in the default `prBodyDefinitions` object so does not require a definition before it can be used. -It is also recommended to avoid `rebaseWhen=never` as it can result in conflicted branches with outdated PR descriptions and/or status checks. +## prBodyDefinitions -Avoid setting `rebaseWhen=never` and then also setting `prCreation=not-pending` as this can prevent creation of PRs. +You can configure this object to either (a) modify the template for an existing table column in PR bodies, or (b) you wish to _add_ a definition for a new/additional column. -## recreateWhen +Here is an example of modifying the default value for the `"Package"` column to put it inside a `` block: -This feature used to be called `recreateClosed`. +```json +{ + "prBodyDefinitions": { + "Package": "`{{{depName}}}`" + } +} +``` -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: +Here is an example of adding a custom `"Sourcegraph"` column definition: -- Package groups -- When pinning versions -- Lock file maintenance +```json +{ + "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" + ] +} +``` -You can select which behavior you want from Renovate: + +!!! 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. -- `always`: Recreates all closed or blocking PRs -- `auto`: The default option. Recreates only immortal PRs (default) -- `never`: No PR is recreated, doesn't matter if it is immortal or not +## prBodyNotes -We recommend that you stick with the default setting for this option. -Only change this setting if you really need to. +Use this field to add custom content inside PR bodies, including conditionally. -## regexManagers +e.g. if you wish to add an extra Warning to major updates: -Use `regexManagers` entries to configure the `regex` manager in Renovate. +```json +{ + "prBodyNotes": ["{{#if isMajor}}:warning: MAJOR MAJOR MAJOR :warning:{{/if}}"] +} +``` -You can define custom managers to handle: +## prBodyTemplate -- Proprietary file formats or conventions -- Popular file formats not yet supported as a manager by Renovate +The available sections are: -The custom manager concept is based on using Regular Expression named capture groups. +- `header` +- `table` +- `warnings` +- `notes` +- `changelogs` +- `configDescription` +- `controls` +- `footer` -You must have a named capture group matching (e.g. `(?.*)`) _or_ configure its corresponding template (e.g. `depNameTemplate`) for these fields: +## prConcurrentLimit -- `datasource` -- `depName` -- `currentValue` +This setting - if enabled - limits Renovate to a maximum of `x` concurrent PRs open at any time. -Use named capture group matching _or_ set a corresponding template. -We recommend you use only one of these methods, or you'll get confused. +This limit is enforced on a per-repository basis. -We recommend that you also tell Renovate what `versioning` to use. -If the `versioning` field is missing, then Renovate defaults to using `semver` versioning. + +!!! note + Renovate always creates security PRs, even if the concurrent PR limit is already reached. + Security PRs have `[SECURITY]` in their PR title. -For more details and examples, see our [documentation for the `regex` manager](/modules/manager/regex/). -For template fields, use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. +## prCreation - -!!! tip - Look at our [Regex Manager Presets](https://docs.renovatebot.com/presets-regexManagers/), they may have what you need. +This setting tells Renovate when you would like it to raise PRs: -### customType +- `immediate` (default): Renovate will create PRs immediately after creating the corresponding branch +- `not-pending`: Renovate will wait until status checks have completed (passed or failed) before raising the PR +- `status-success`: Renovate won't raise PRs unless tests pass -Example: +Renovate defaults to `immediate` but you might want to change this to `not-pending` instead. -```json -{ - "regexManagers": [ - { - "customType": "regex", - "matchStrings": [ - "ENV .*?_VERSION=(?.*) # (?.*?)/(?.*?)\\s" - ] - } - ] -} -``` +With prCreation 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 or not. -### matchStrings +With prCreation 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 hrs have elapsed since creation of the commit. -`matchStrings` should each be a valid regular expression, optionally with named capture groups. +With prCreation set to `status-success`, Renovate creates the PR only if/ once all tests have passed. -Example: +For all cases of non-immediate PR creation, Renovate doesn't run instantly once tests complete. +Instead, Renovate can create the PR on its next run after relevant tests have completed, so there will be some delay. -```json -{ - "matchStrings": [ - "ENV .*?_VERSION=(?.*) # (?.*?)/(?.*?)\\s" - ] -} -``` +## prFooter -### matchStringsStrategy +## prHeader -`matchStringsStrategy` controls behavior when multiple `matchStrings` values are provided. -Three options are available: +## prHourlyLimit -- `any` (default) -- `recursive` -- `combination` +This config option slows down the _rate_ at which Renovate creates PRs. -#### any +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`: -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. +1. Renovate creates an Onboarding PR +1. You merge the onboarding PR to activate Renovate +1. Renovate creates a "Pin Dependencies" PR (if needed) +1. You merge the "Pin Dependencies" PR +1. 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. -As example the following configuration will update all 3 lines in the Dockerfile. -renovate.json: + +!!! 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. -```json -{ - "regexManagers": [ - { - "fileMatch": ["^Dockerfile$"], - "matchStringsStrategy": "any", - "matchStrings": [ - "ENV [A-Z]+_VERSION=(?.*) # (?.*?)/(?.*?)(\\&versioning=(?.*?))?\\s", - "FROM (?\\S*):(?\\S*)" - ], - "datasourceTemplate": "docker" - } - ] -} -``` +## prNotPendingHours -a Dockerfile: +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. -```dockerfile -FROM amd64/ubuntu:18.04 -ENV GRADLE_VERSION=6.2 # gradle-version/gradle&versioning=maven -ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node -``` + +!!! note + If the option `minimumReleaseAge` is non-zero then Renovate disables the `prNotPendingHours` functionality. -#### recursive +## prPriority -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 used as basis be used as 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. +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: -Matched groups will be available in subsequent matching layers. +1. `pinDigest` +1. `pin` +1. `digest` +1. `patch` +1. `minor` +1. `major` -This is an example how this can work. -The first regex 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 regex manager will upgrade both definitions as its first `matchStrings` matches both `test` keys. +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. -renovate.json: +Here's an example of how you would define PR priority so that `devDependencies` are raised last and `react` is raised first: ```json { - "regexManagers": [ + "packageRules": [ { - "fileMatch": ["^example.json$"], - "matchStringsStrategy": "recursive", - "matchStrings": [ - "\"backup\":\\s*{[^}]*}", - "\"test\":\\s*\\{[^}]*}", - "\"name\":\\s*\"(?.*)\"[^\"]*\"type\":\\s*\"(?.*)\"[^\"]*\"value\":\\s*\"(?.*)\"" - ], - "datasourceTemplate": "docker" + "matchDepTypes": ["devDependencies"], + "prPriority": -1 }, { - "fileMatch": ["^example.json$"], - "matchStringsStrategy": "recursive", - "matchStrings": [ - "\"test\":\\s*\\{[^}]*}", - "\"name\":\\s*\"(?.*)\"[^\"]*\"type\":\\s*\"(?.*)\"[^\"]*\"value\":\\s*\"(?.*)\"" - ], - "datasourceTemplate": "docker" + "matchPackageNames": ["react"], + "prPriority": 5 } ] } ``` -example.json: +## prTitle -```json -{ - "backup": { - "test": { - "name": "grafana/loki", - "type": "docker", - "value": "1.6.1" - } - }, - "setup": { - "test": { - "name": "python", - "type": "docker", - "value": "3.9.0" - } - } -} -``` +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. -#### combination +## prTitleStrict -This option allows the possibility to combine the values of multiple lines inside a file. -While using multiple lines is also possible using both other `matchStringStrategy` values, the `combination` approach is less susceptible to white space or line breaks stopping a match. +There are certain scenarios where the default behavior appends extra context to the PR title. -`combination` will only match at most one dependency per file, so if you want to update multiple dependencies using `combination` you have to define multiple regex managers. +These scenarios include if a `baseBranch` or if there is a grouped update and either `separateMajorMinor` or `separateMinorPatch` is true. -Matched group values will be merged to form a single dependency. +Using this option allows you to skip these default behaviors and use other templating methods to control the format of the PR title. -renovate.json: +## printConfig -```json -{ - "regexManagers": [ - { - "fileMatch": ["^main.yml$"], - "matchStringsStrategy": "combination", - "matchStrings": [ - "prometheus_image:\\s*\"(?.*)\"\\s*//", - "prometheus_version:\\s*\"(?.*)\"\\s*//" - ], - "datasourceTemplate": "docker" - }, - { - "fileMatch": ["^main.yml$"], - "matchStringsStrategy": "combination", - "matchStrings": [ - "thanos_image:\\s*\"(?.*)\"\\s*//", - "thanos_version:\\s*\"(?.*)\"\\s*//" - ], - "datasourceTemplate": "docker" - } - ] -} -``` +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. -Ansible variable file ( yaml ): +## pruneBranchAfterAutomerge -```yaml -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 -``` +By default Renovate deletes, or "prunes", the branch after automerging. +Set `pruneBranchAfterAutomerge` to `false` to keep the branch after automerging. -In the above example, each regex manager will match a single dependency each. +## pruneStaleBranches -### depNameTemplate +Configure to `false` to disable deleting orphan branches and autoclosing PRs. +Defaults to `true`. -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. +## rangeStrategy -### extractVersionTemplate +Behavior: -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. +- `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`, `composer`, `npm`, `yarn`, `terraform` and `poetry` so far +- `in-range-only` = Update the lock file when in-range updates are available, ignore package file updates -### packageNameTemplate +Renovate's `"auto"` strategy works like this for npm: -`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. +1. Widen `peerDependencies` +1. 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"` +1. Otherwise, if the update is outside the existing range, Renovate replaces the range. So `"^2.0.0"` is replaced by `"^3.0.0"` +1. Finally, if the update is in-range, Renovate will update the lockfile with the new exact version. -### currentValueTemplate +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. -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. +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. -### datasourceTemplate +This feature supports caret (`^`) and tilde (`~`) ranges only, like `^1.0.0` and `~1.0.0`. -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. +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. -### depTypeTemplate +## rebaseLabel -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. +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. -### versioningTemplate +## rebaseWhen -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. +Possible values and meanings: -### registryUrlTemplate +- `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 +- `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 -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. +`rebaseWhen=conflicted` is not recommended if you have enabled Renovate automerge, because: -### autoReplaceStringTemplate +- 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 -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. +It is also recommended to avoid `rebaseWhen=never` as it can result in conflicted branches with outdated PR descriptions and/or status checks. -helm-values.yaml: +Avoid setting `rebaseWhen=never` and then also setting `prCreation=not-pending` as this can prevent creation of PRs. -```yaml -# The image of the service //: -image: my.old.registry/aRepository/andImage:1.18-alpine -``` +## recreateWhen -regex definition: +This feature used to be called `recreateClosed`. -```json -{ - "regexManagers": [ - { - "fileMatch": ["values.yaml$"], - "matchStrings": [ - "image:\\s+(?my\\.old\\.registry/aRepository/andImage):(?[^\\s]+)" - ], - "depNameTemplate": "my.new.registry/aRepository/andImage", - "autoReplaceStringTemplate": "image: {{{depName}}}:{{{newValue}}}", - "datasourceTemplate": "docker" - } - ] -} -``` +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: -This will lead to following update where `1.21-alpine` is the newest version of `my.new.registry/aRepository/andImage`: +- Package groups +- When pinning versions +- Lock file maintenance -```yaml -# The image of the service //: -image: my.new.registry/aRepository/andImage:1.21-alpine -``` +You can select which behavior you want from Renovate: + +- `always`: Recreates all closed or blocking PRs +- `auto`: The default option. Recreates only 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 diff --git a/docs/usage/getting-started/use-cases.md b/docs/usage/getting-started/use-cases.md index 095d72521d0007..04c51cf11422ce 100644 --- a/docs/usage/getting-started/use-cases.md +++ b/docs/usage/getting-started/use-cases.md @@ -58,8 +58,8 @@ 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 "regex" manager to set your own custom patterns to extract dependencies. -You configure the regex manager by telling it: +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 diff --git a/docs/usage/reading-list.md b/docs/usage/reading-list.md index 134a46e315195b..24b2d3df9c5db4 100644 --- a/docs/usage/reading-list.md +++ b/docs/usage/reading-list.md @@ -58,7 +58,7 @@ Feel free to read up on anything that looks interesting to you. First, complete the "Beginners" and the "Intermediate" reading list. Then read: -- Define your own regex manager with [`regexManagers`](./configuration-options.md#regexmanagers) +- Define your own custom manager with [`customManagers`](./configuration-options.md#custommanagers) - [Shareable config presets](./config-presets.md) ## Self-hosting Renovate diff --git a/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md b/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md index 9c3902bc18a419..291067546dcc99 100644 --- a/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md +++ b/docs/usage/user-stories/maintaining-aur-packages-with-renovate.md @@ -39,12 +39,13 @@ Renovate comes with over 50 different datasources, but the one that is important Managers are the Renovate concept for package managers. There isn’t an AUR or `PKGBUILD` manager, but there is a [regex manager](https://docs.renovatebot.com/modules/manager/regex/) that I can use. -I can create a `renovate.json` configuration with the following regex manager configuration: +I can create a `renovate.json` configuration with the following custom manager configuration: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["(^|/)PKGBUILD$"], "matchStrings": [ "pkgver=(?.*) # renovate: datasource=(?.*) depName=(?.*)" diff --git a/docs/usage/user-stories/swissquote.md b/docs/usage/user-stories/swissquote.md index 051a7b93958ff8..f4fe216c26bc39 100644 --- a/docs/usage/user-stories/swissquote.md +++ b/docs/usage/user-stories/swissquote.md @@ -177,7 +177,7 @@ Some features and options we enjoy: - 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](https://docs.renovatebot.com/modules/manager/#supported-managers): Maven, Docker, npm, Docker Compose, Python -- If you are using dependencies in a custom way, [there is a special regexManager](../configuration-options.md#regexmanagers) that allows you to transform patterns into dependencies +- If you are using dependencies in a custom way, [there is a special customManager](../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. diff --git a/lib/config/__snapshots__/validation.spec.ts.snap b/lib/config/__snapshots__/validation.spec.ts.snap index 41f8bd38992650..b9c645a4775bc8 100644 --- a/lib/config/__snapshots__/validation.spec.ts.snap +++ b/lib/config/__snapshots__/validation.spec.ts.snap @@ -113,6 +113,15 @@ exports[`config/validation validateConfig(config) errors for unsafe fileMatches ] `; +exports[`config/validation validateConfig(config) errors if customManager fields are missing 1`] = ` +[ + { + "message": "Regex Managers must contain currentValueTemplate configuration or regex group named currentValue", + "topic": "Configuration Error", + }, +] +`; + exports[`config/validation validateConfig(config) errors if fileMatch has wrong parent 1`] = ` [ { diff --git a/lib/config/validation.spec.ts b/lib/config/validation.spec.ts index a1d88bbf44f869..10f1e92ec46c17 100644 --- a/lib/config/validation.spec.ts +++ b/lib/config/validation.spec.ts @@ -410,7 +410,7 @@ describe('config/validation', () => { expect(errors).toMatchInlineSnapshot(` [ { - "message": "Each Regex Manager must contain a non-empty fileMatch array", + "message": "Each Custom Manager must contain a non-empty fileMatch array", "topic": "Configuration Error", }, ] @@ -437,7 +437,7 @@ describe('config/validation', () => { expect(errors).toMatchInlineSnapshot(` [ { - "message": "Each Regex Manager must contain a non-empty customType string", + "message": "Each Custom Manager must contain a non-empty customType string", "topic": "Configuration Error", }, ] diff --git a/lib/config/validation.ts b/lib/config/validation.ts index 539b6737f2e9ed..56217ec95400a3 100644 --- a/lib/config/validation.ts +++ b/lib/config/validation.ts @@ -444,7 +444,7 @@ export async function validateConfig( if (is.nonEmptyArray(customManager.fileMatch)) { switch (customManager.customType) { case 'regex': - validatecustomManagerFields( + validateRegexManagerFields( customManager, currentPath, errors @@ -454,7 +454,7 @@ export async function validateConfig( } else { errors.push({ topic: 'Configuration Error', - message: `Each Regex Manager must contain a non-empty fileMatch array`, + message: `Each Custom Manager must contain a non-empty fileMatch array`, }); } } else { @@ -464,7 +464,7 @@ export async function validateConfig( ) { errors.push({ topic: 'Configuration Error', - message: `Each Regex Manager must contain a non-empty customType string`, + message: `Each Custom Manager must contain a non-empty customType string`, }); } else { errors.push({ @@ -658,7 +658,7 @@ export async function validateConfig( return { errors, warnings }; } -function validatecustomManagerFields( +function validateRegexManagerFields( customManager: Partial, currentPath: string, errors: ValidationMessage[] @@ -677,7 +677,7 @@ function validatecustomManagerFields( } else { errors.push({ topic: 'Configuration Error', - message: `Each Regex Manager must contain a non-empty matchStrings array`, + message: `Each Custom Manager must contain a non-empty matchStrings array`, }); } diff --git a/lib/modules/datasource/aws-machine-image/readme.md b/lib/modules/datasource/aws-machine-image/readme.md index 909327622f937b..bbda36b359eec0 100644 --- a/lib/modules/datasource/aws-machine-image/readme.md +++ b/lib/modules/datasource/aws-machine-image/readme.md @@ -51,15 +51,15 @@ Example: ``` At the moment, this datasource has no "manager". -You have to use the regex manager for this. +You have to use the custom manager for this. **Usage Example** -Here's an example of using the regex manager: +Here's an example of using the custom manager: ```javascript module.exports = { - regexManagers: [ + customManagers: [ { customType: 'regex', fileMatch: ['.*'], @@ -77,7 +77,7 @@ Or as JSON: ```yaml { - 'regexManagers': + 'customManagers': [ { 'customType': 'regex', diff --git a/lib/modules/datasource/aws-rds/readme.md b/lib/modules/datasource/aws-rds/readme.md index fa074ab26005a8..be47f3644d2c1b 100644 --- a/lib/modules/datasource/aws-rds/readme.md +++ b/lib/modules/datasource/aws-rds/readme.md @@ -29,9 +29,9 @@ Read the [AWS RDS IAM reference](https://docs.aws.amazon.com/service-authorizati **Usage** -Because Renovate has no manager for the AWS RDS datasource, you need to help Renovate by configuring the regex manager to identify the RDS dependencies you want updated. +Because Renovate has no manager for the AWS RDS datasource, you need to help Renovate by configuring the custom manager to identify the RDS dependencies you want updated. -When configuring the regex manager, you have to pass a [filter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-rds/interfaces/describedbengineversionscommandinput.html#filters) as minified JSON as the `packageName`. +When configuring the custom manager, you have to pass a [filter](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-rds/interfaces/describedbengineversionscommandinput.html#filters) as minified JSON as the `packageName`. For example: ```yaml @@ -53,12 +53,13 @@ For example: [{"Name":"engine","Values":["mysql"]},{"Name":"engine-version","Values":["5.7"]}] ``` -Here's an example of using the regex manager to configure this datasource: +Here's an example of using the custom manager to configure this datasource: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["\\.yaml$"], "matchStrings": [ ".*amiFilter=(?.+?)[ ]*\n[ ]*(?[a-zA-Z0-9-_:]*)[ ]*?:[ ]*?[\"|']?(?[.\\d]+)[\"|']?.*" diff --git a/lib/modules/datasource/custom/readme.md b/lib/modules/datasource/custom/readme.md index b0be066f699e09..288856418c300b 100644 --- a/lib/modules/datasource/custom/readme.md +++ b/lib/modules/datasource/custom/readme.md @@ -3,7 +3,7 @@ This `custom` datasource allows requesting version data from generic HTTP(S) end ## Usage The `customDatasources` option takes a record of `customDatasource` configs. -This example shows how to update the `k3s.version` file with a custom datasource and a [regexManagers](../../manager/regex/index.md): +This example shows how to update the `k3s.version` file with a custom datasource and a [regex](../../manager/regex/index.md) custom manager: Options: @@ -19,8 +19,9 @@ Available template variables: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["k3s.version"], "matchStrings": ["(?\\S+)"], "depNameTemplate": "k3s", @@ -142,8 +143,9 @@ You can use this configuration to request the newest versions of the Hashicorp p ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["\\.yml$"], "datasourceTemplate": "custom.hashicorp", "matchStrings": [ @@ -176,8 +178,9 @@ You can use the following configuration to upgrade the Grafana Dashboards versio ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["\\.yml$"], "matchStrings": [ "#\\s+renovate:\\s+depName=\"(?.*)\"\\n\\s+gnetId:\\s+(?.*?)\\n\\s+revision:\\s+(?.*)" @@ -249,7 +252,7 @@ This example uses Nexus as the webserver. } ``` -This could be used to update Ansible YAML files with the latest version through a regex manager. +This could be used to update Ansible YAML files with the latest version through a custom manager. For example, with the following Ansible content: ```yaml @@ -257,12 +260,13 @@ For example, with the following Ansible content: something_version: '77' ``` -And the following regex manager: +And the following custom manager: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["\\.yml$"], "datasourceTemplate": "custom.nexus_generic", "matchStrings": [ diff --git a/lib/modules/datasource/endoflife-date/readme.md b/lib/modules/datasource/endoflife-date/readme.md index 36cec9fd13ca70..202f25039f19a3 100644 --- a/lib/modules/datasource/endoflife-date/readme.md +++ b/lib/modules/datasource/endoflife-date/readme.md @@ -20,8 +20,9 @@ Given the above `.tfvars` file, you put this in your `renovate.json`: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "description": "Update Kubernetes version for Amazon EKS in tfvars files", "fileMatch": [".+\\.tfvars$"], "matchStrings": [ diff --git a/lib/modules/datasource/git-refs/readme.md b/lib/modules/datasource/git-refs/readme.md index 86d27e39bb9e8d..0c2f904714d446 100644 --- a/lib/modules/datasource/git-refs/readme.md +++ b/lib/modules/datasource/git-refs/readme.md @@ -7,12 +7,13 @@ To fetch the latest digest of a reference instead of the named reference, specif **Usage example** The following is an example where you would maintain the HEAD digest of the `master` branch of a repository. -You would configure a generic regex manager in `renovate.json` for files named `versions.ini`: +You would configure a generic custom manager in `renovate.json` for files named `versions.ini`: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^versions.ini$"], "matchStrings": ["GOOGLE_API_VERSION=(?.*?)\\n"], "currentValueTemplate": "master", diff --git a/lib/modules/datasource/gitlab-packages/readme.md b/lib/modules/datasource/gitlab-packages/readme.md index 54388f498c83ce..9409519b1ac49a 100644 --- a/lib/modules/datasource/gitlab-packages/readme.md +++ b/lib/modules/datasource/gitlab-packages/readme.md @@ -15,12 +15,13 @@ If you are using a self-hosted GitLab instance, please note the following requir **Usage Example** A real-world example for this specific datasource would be maintaining package versions in a config file. -This can be achieved by configuring a generic regex manager in `renovate.json` for files named `versions.ini`: +This can be achieved by configuring a generic custom manager in `renovate.json` for files named `versions.ini`: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^versions.ini$"], "matchStrings": [ "# renovate: datasource=(?.*?) depName=(?.*?)( versioning=(?.*?))?( registryUrl=(?.*?))?\\s.*?_VERSION=(?.*)\\s" diff --git a/lib/modules/datasource/gitlab-releases/readme.md b/lib/modules/datasource/gitlab-releases/readme.md index 5b916841b8c993..22f3a5006ab786 100644 --- a/lib/modules/datasource/gitlab-releases/readme.md +++ b/lib/modules/datasource/gitlab-releases/readme.md @@ -14,12 +14,13 @@ Please note the following requirements: **Usage Example** A real-world example for this specific datasource would be maintaining package versions in a config file. -This can be achieved by configuring a generic regex manager in `renovate.json` for files named `versions.ini`: +This can be achieved by configuring a generic custom manager in `renovate.json` for files named `versions.ini`: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^versions.ini$"], "matchStrings": [ "# renovate: datasource=(?.*?) depName=(?.*?)( versioning=(?.*?))?( registryUrl=(?.*?))?\\s.*?_VERSION=(?.*)\\s" diff --git a/lib/modules/datasource/gitlab-tags/readme.md b/lib/modules/datasource/gitlab-tags/readme.md index d637c6042cdc24..86fb06a80381d2 100644 --- a/lib/modules/datasource/gitlab-tags/readme.md +++ b/lib/modules/datasource/gitlab-tags/readme.md @@ -9,12 +9,13 @@ To specify where to find a self-hosted GitLab instance, specify `registryUrl`. A **Usage Example** A real-world example for this specific datasource would be maintaining package versions in a config file. -This can be achieved by configuring a generic regex manager in `renovate.json` for files named `versions.ini`: +This can be achieved by configuring a generic custom manager in `renovate.json` for files named `versions.ini`: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^versions.ini$"], "matchStrings": [ "# renovate: datasource=(?.*?) depName=(?.*?)( versioning=(?.*?))?( registryUrl=(?.*?))?\\s.*?_VERSION=(?.*)\\s" diff --git a/lib/modules/datasource/repology/readme.md b/lib/modules/datasource/repology/readme.md index a2aa0dedb6d5c9..b99f695672d108 100644 --- a/lib/modules/datasource/repology/readme.md +++ b/lib/modules/datasource/repology/readme.md @@ -14,12 +14,13 @@ For example, the `Alpine Linux 3.12` repository has this URL: `https://repology. Say you're using system packages in a Dockerfile and want to update them with Repology. With the Repology datasource you can "pin" each dependency, and get automatic updates. -First you would set a generic regex manager in your `renovate.json` file for `Dockerfile`: +First you would set a generic custom manager in your `renovate.json` file for `Dockerfile`: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^Dockerfile$"], "matchStrings": [ "#\\s*renovate:\\s*datasource=(?.*?) depName=(?.*?)( versioning=(?.*?))?\\sENV .*?_VERSION=\"(?.*)\"\\s" diff --git a/lib/modules/manager/custom/regex/readme.md b/lib/modules/manager/custom/regex/readme.md index de2920487924b6..4cd89f1336343c 100644 --- a/lib/modules/manager/custom/regex/readme.md +++ b/lib/modules/manager/custom/regex/readme.md @@ -4,17 +4,17 @@ The `regex` manager is unique in Renovate because: - It is configurable via regex named capture groups - It can extract any `datasource` -- By using the `regexManagers` config, you can create multiple "regex managers" for the same repository +- By using the `customManagers` config, you can create multiple "regex managers" for the same repository We have [additional Handlebars helpers](https://docs.renovatebot.com/templates/#additional-handlebars-helpers) to help you perform common transformations on the regex manager's template fields. -Also read the documentation for the [`regexManagers` config option](https://docs.renovatebot.com/configuration-options/#regexmanagers). +Also read the documentation for the [`customManagers` config option](https://docs.renovatebot.com/configuration-options/#custommanagers). ### Required Fields The first two required fields are `fileMatch` and `matchStrings`: - `fileMatch` works the same as any manager -- `matchStrings` is a `regexManagers` concept and is used for configuring a regular expression with named capture groups +- `matchStrings` is a `regex` managers concept and is used for configuring a regular expression with named capture groups Before Renovate can look up a dependency and decide about updates, it needs this information about each dependency: @@ -64,8 +64,9 @@ Continuing the above example with Yarn, here is the full Renovate config: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^Dockerfile$"], "matchStrings": ["ENV YARN_VERSION=(?.*?)\\n"], "depNameTemplate": "yarn", @@ -78,7 +79,7 @@ Continuing the above example with Yarn, here is the full Renovate config: ### Advanced Capture Say your `Dockerfile` has many `ENV` variables that you want to keep up-to-date. -But you don't want to write a `regexManagers` rule for _each_ variable. +But you don't want to write a `customManagers` rule for _each_ variable. Instead you enhance your `Dockerfile` like this: ```Dockerfile @@ -100,8 +101,9 @@ You could configure Renovate to update the `Dockerfile` like this: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": ["^Dockerfile$"], "matchStrings": [ "datasource=(?.*?) depName=(?.*?)( versioning=(?.*?))?\\sENV .*?_VERSION=(?.*)\\s" @@ -125,7 +127,7 @@ But we included the `versioningTemplate` config option to show you why we call t You should use triple brace `{{{ }}}` templates like `{{{versioning}}}` to be safe. This is because Handlebars escapes special characters with double braces (by default). -By adding `renovate: datasource=` and `depName=` comments to the `Dockerfile` you only need _one_ `regexManager` instead of _four_. +By adding `renovate: datasource=` and `depName=` comments to the `Dockerfile` you only need _one_ `customManager` instead of _four_. The `Dockerfile` is documented better as well. The syntax in the example is arbitrary, and you can set your own syntax. @@ -145,12 +147,13 @@ type: application appVersion: 'v0.4.0' ``` -Using the `regexManagers` below, Renovate looks for available Docker tags of the image `amazon/amazon-eks-pod-identity-webhook`. +Using the `customManagers` below, Renovate looks for available Docker tags of the image `amazon/amazon-eks-pod-identity-webhook`. ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "datasourceTemplate": "docker", "fileMatch": ["(^|/)Chart\\.yaml$"], "matchStrings": [ @@ -161,7 +164,7 @@ Using the `regexManagers` below, Renovate looks for available Docker tags of the } ``` -### Using regexManager to update the dependency name in addition to version +### Using customManager to update the dependency name in addition to version #### Updating `gitlab-ci include` dep names @@ -173,8 +176,9 @@ For example: ```json { - "regexManagers": [ + "customManagers": [ { + "customType": "regex", "fileMatch": [".*y[a]?ml$"], "matchStringsStrategy": "combination", "matchStrings": [ From 3ae44eef599784364aaa5abaa167316809d3edbf Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Mon, 18 Sep 2023 07:58:10 +0545 Subject: [PATCH 03/13] docs: fix order --- docs/usage/configuration-options.md | 66 ++++++++++++++--------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 5df249f2b76626..a0908e53832e2e 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -650,39 +650,6 @@ These datasources can be referred by CustomManagers or can be used to overwrite For more details see the [`custom` datasource documentation](/modules/datasource/custom/). -## customizeDashboard - -You can use the `customizeDashboard` object to customize dependency dashboard. - -Supported fields: - -- `repoProblemsHeader`: This field will replace the header of the Repository Problems in dependency dashboard issue. - -### defaultRegistryUrlTemplate - -`registryUrl` which is used, if none is return by extraction. -As this is a template it can be dynamically set. E.g. add the `packageName` as part of the URL: - -```json5 -{ - customDatasources: { - foo: { - defaultRegistryUrlTemplate: 'https://exmaple.foo.bar/v1/{{ packageName }}', - }, - }, -} -``` - -### format - -Defines which format the API is returning. -Currently `json` or `plain` are supported, see the `custom` [datasource documentation](/modules/datasource/custom/) for more information. - -### 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` entries to configure the custom managers in Renovate. @@ -980,6 +947,39 @@ This will lead to following update where `1.21-alpine` is the newest version of image: my.new.registry/aRepository/andImage:1.21-alpine ``` +## customizeDashboard + +You can use the `customizeDashboard` object to customize dependency dashboard. + +Supported fields: + +- `repoProblemsHeader`: This field will replace the header of the Repository Problems in dependency dashboard issue. + +### defaultRegistryUrlTemplate + +`registryUrl` which is used, if none is return by extraction. +As this is a template it can be dynamically set. E.g. add the `packageName` as part of the URL: + +```json5 +{ + customDatasources: { + foo: { + defaultRegistryUrlTemplate: 'https://exmaple.foo.bar/v1/{{ packageName }}', + }, + }, +} +``` + +### format + +Defines which format the API is returning. +Currently `json` or `plain` are supported, see the `custom` [datasource documentation](/modules/datasource/custom/) for more information. + +### 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. + ## defaultRegistryUrls Override a datasource's default registries with this config option. From 44cfcec4ba52eff6e87e69b88a3559ea3d650183 Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Tue, 19 Sep 2023 07:19:03 +0545 Subject: [PATCH 04/13] fix tests --- .../__snapshots__/migration.spec.ts.snap | 56 +++++++++---------- .../__snapshots__/validation.spec.ts.snap | 11 +--- lib/config/validation.spec.ts | 4 +- 3 files changed, 31 insertions(+), 40 deletions(-) diff --git a/lib/config/__snapshots__/migration.spec.ts.snap b/lib/config/__snapshots__/migration.spec.ts.snap index 638becb9910024..b3f0b3deb66552 100644 --- a/lib/config/__snapshots__/migration.spec.ts.snap +++ b/lib/config/__snapshots__/migration.spec.ts.snap @@ -1,5 +1,33 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP +exports[`config/migration it migrates customManagers 1`] = ` +{ + "customManagers": [ + { + "customType": "regex", + "fileMatch": [ + "(^|/|\\.)Dockerfile$", + "(^|/)Dockerfile[^/]*$", + ], + "matchStrings": [ + "# renovate: datasource=(?[a-z-]+?) depName=(?[^\\s]+?)(?: lookupName=(?[^\\s]+?))?(?: versioning=(?[a-z-0-9]+?))?\\s(?:ENV|ARG) .+?_VERSION="?(?.+?)"?\\s", + ], + }, + { + "customType": "regex", + "fileMatch": [ + "(^|/|\\.)Dockerfile$", + "(^|/)Dockerfile[^/]*$", + ], + "matchStrings": [ + "# renovate: datasource=(?[a-z-]+?) depName=(?[^\\s]+?)(?: lookupName=(?[^\\s]+?))?(?: versioning=(?[a-z-0-9]+?))?\\s(?:ENV|ARG) .+?_VERSION="?(?.+?)"?\\s", + ], + "packageNameTemplate": "{{{holder}}}", + }, + ], +} +`; + exports[`config/migration it migrates gradle-lite 1`] = ` { "gradle": { @@ -51,34 +79,6 @@ exports[`config/migration it migrates nested packageRules 1`] = ` } `; -exports[`config/migration it migrates regexManagers 1`] = ` -{ - "regexManagers": [ - { - "customType": "regex", - "fileMatch": [ - "(^|/|\\.)Dockerfile$", - "(^|/)Dockerfile[^/]*$", - ], - "matchStrings": [ - "# renovate: datasource=(?[a-z-]+?) depName=(?[^\\s]+?)(?: lookupName=(?[^\\s]+?))?(?: versioning=(?[a-z-0-9]+?))?\\s(?:ENV|ARG) .+?_VERSION="?(?.+?)"?\\s", - ], - }, - { - "customType": "regex", - "fileMatch": [ - "(^|/|\\.)Dockerfile$", - "(^|/)Dockerfile[^/]*$", - ], - "matchStrings": [ - "# renovate: datasource=(?[a-z-]+?) depName=(?[^\\s]+?)(?: lookupName=(?[^\\s]+?))?(?: versioning=(?[a-z-0-9]+?))?\\s(?:ENV|ARG) .+?_VERSION="?(?.+?)"?\\s", - ], - "packageNameTemplate": "{{{holder}}}", - }, - ], -} -`; - exports[`config/migration migrateConfig(config, parentConfig) does not migrate multi days 1`] = ` { "schedule": "after 5:00pm on wednesday and thursday", diff --git a/lib/config/__snapshots__/validation.spec.ts.snap b/lib/config/__snapshots__/validation.spec.ts.snap index b9c645a4775bc8..c102eace3c1a5b 100644 --- a/lib/config/__snapshots__/validation.spec.ts.snap +++ b/lib/config/__snapshots__/validation.spec.ts.snap @@ -185,15 +185,6 @@ exports[`config/validation validateConfig(config) errors if manager objects are ] `; -exports[`config/validation validateConfig(config) errors if regexManager fields are missing 1`] = ` -[ - { - "message": "Regex Managers must contain currentValueTemplate configuration or regex group named currentValue", - "topic": "Configuration Error", - }, -] -`; - exports[`config/validation validateConfig(config) ignore packageRule nesting validation for presets 1`] = `[]`; exports[`config/validation validateConfig(config) included managers of the wrong type 1`] = ` @@ -259,7 +250,7 @@ exports[`config/validation validateConfig(config) selectors outside packageRules exports[`config/validation validateConfig(config) validates regEx for each fileMatch 1`] = ` [ { - "message": "Invalid regExp for regexManagers[0].fileMatch: \`***$}{]][\`", + "message": "Invalid regExp for customManagers[0].fileMatch: \`***$}{]][\`", "topic": "Configuration Error", }, ] diff --git a/lib/config/validation.spec.ts b/lib/config/validation.spec.ts index 10f1e92ec46c17..59c3676f981164 100644 --- a/lib/config/validation.spec.ts +++ b/lib/config/validation.spec.ts @@ -501,11 +501,11 @@ describe('config/validation', () => { expect(errors).toMatchInlineSnapshot(` [ { - "message": "Each Regex Manager must contain a non-empty matchStrings array", + "message": "Each Custom Manager must contain a non-empty matchStrings array", "topic": "Configuration Error", }, { - "message": "Each Regex Manager must contain a non-empty matchStrings array", + "message": "Each Custom Manager must contain a non-empty matchStrings array", "topic": "Configuration Error", }, ] From 20af10298508d8dd2d19a8263752ab03be11e450 Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Tue, 19 Sep 2023 10:35:58 +0545 Subject: [PATCH 05/13] Apply Suggestions --- lib/config/presets/internal/regex-managers.ts | 12 +++++++----- lib/modules/datasource/git-refs/readme.md | 2 +- lib/modules/datasource/gitlab-packages/readme.md | 2 +- lib/modules/datasource/gitlab-releases/readme.md | 2 +- lib/modules/datasource/gitlab-tags/readme.md | 2 +- lib/modules/datasource/repology/readme.md | 2 +- 6 files changed, 12 insertions(+), 10 deletions(-) diff --git a/lib/config/presets/internal/regex-managers.ts b/lib/config/presets/internal/regex-managers.ts index 42b992e0a179a6..63970ac5112118 100644 --- a/lib/config/presets/internal/regex-managers.ts +++ b/lib/config/presets/internal/regex-managers.ts @@ -1,8 +1,9 @@ import type { Preset } from '../types'; +/* eslint sort-keys: ["error", "asc", {caseSensitive: false, natural: true}] */ + export const presets: Record = { dockerfileVersions: { - description: 'Update `_VERSION` variables in Dockerfiles.', customManagers: [ { customType: 'regex', @@ -15,10 +16,9 @@ export const presets: Record = { ], }, ], + description: 'Update `_VERSION` variables in Dockerfiles.', }, githubActionsVersions: { - description: - 'Update `_VERSION` environment variables in GitHub Action files.', customManagers: [ { customType: 'regex', @@ -28,9 +28,10 @@ export const presets: Record = { ], }, ], + description: + 'Update `_VERSION` environment variables in GitHub Action files.', }, helmChartYamlAppVersions: { - description: 'Update `appVersion` value in Helm chart `Chart.yaml`.', customManagers: [ { customType: 'regex', @@ -41,9 +42,9 @@ export const presets: Record = { ], }, ], + description: 'Update `appVersion` value in Helm chart `Chart.yaml`.', }, tfvarsVersions: { - description: 'Update `*_version` variables in `.tfvars` files.', customManagers: [ { customType: 'regex', @@ -54,5 +55,6 @@ export const presets: Record = { versioningTemplate: '{{#if versioning}}{{{versioning}}}{{/if}}', }, ], + description: 'Update `*_version` variables in `.tfvars` files.', }, }; diff --git a/lib/modules/datasource/git-refs/readme.md b/lib/modules/datasource/git-refs/readme.md index 0c2f904714d446..0e0a989bc8b466 100644 --- a/lib/modules/datasource/git-refs/readme.md +++ b/lib/modules/datasource/git-refs/readme.md @@ -7,7 +7,7 @@ To fetch the latest digest of a reference instead of the named reference, specif **Usage example** The following is an example where you would maintain the HEAD digest of the `master` branch of a repository. -You would configure a generic custom manager in `renovate.json` for files named `versions.ini`: +You would configure a custom manager in `renovate.json` for files named `versions.ini`: ```json { diff --git a/lib/modules/datasource/gitlab-packages/readme.md b/lib/modules/datasource/gitlab-packages/readme.md index 9409519b1ac49a..42d39d0f78c07e 100644 --- a/lib/modules/datasource/gitlab-packages/readme.md +++ b/lib/modules/datasource/gitlab-packages/readme.md @@ -15,7 +15,7 @@ If you are using a self-hosted GitLab instance, please note the following requir **Usage Example** A real-world example for this specific datasource would be maintaining package versions in a config file. -This can be achieved by configuring a generic custom manager in `renovate.json` for files named `versions.ini`: +This can be achieved by configuring a custom manager in `renovate.json` for files named `versions.ini`: ```json { diff --git a/lib/modules/datasource/gitlab-releases/readme.md b/lib/modules/datasource/gitlab-releases/readme.md index 22f3a5006ab786..53952f713415e3 100644 --- a/lib/modules/datasource/gitlab-releases/readme.md +++ b/lib/modules/datasource/gitlab-releases/readme.md @@ -14,7 +14,7 @@ Please note the following requirements: **Usage Example** A real-world example for this specific datasource would be maintaining package versions in a config file. -This can be achieved by configuring a generic custom manager in `renovate.json` for files named `versions.ini`: +This can be achieved by configuring a custom manager in `renovate.json` for files named `versions.ini`: ```json { diff --git a/lib/modules/datasource/gitlab-tags/readme.md b/lib/modules/datasource/gitlab-tags/readme.md index 86fb06a80381d2..31f22fe2e2591b 100644 --- a/lib/modules/datasource/gitlab-tags/readme.md +++ b/lib/modules/datasource/gitlab-tags/readme.md @@ -9,7 +9,7 @@ To specify where to find a self-hosted GitLab instance, specify `registryUrl`. A **Usage Example** A real-world example for this specific datasource would be maintaining package versions in a config file. -This can be achieved by configuring a generic custom manager in `renovate.json` for files named `versions.ini`: +This can be achieved by configuring a custom manager in `renovate.json` for files named `versions.ini`: ```json { diff --git a/lib/modules/datasource/repology/readme.md b/lib/modules/datasource/repology/readme.md index b99f695672d108..9173fff287e222 100644 --- a/lib/modules/datasource/repology/readme.md +++ b/lib/modules/datasource/repology/readme.md @@ -14,7 +14,7 @@ For example, the `Alpine Linux 3.12` repository has this URL: `https://repology. Say you're using system packages in a Dockerfile and want to update them with Repology. With the Repology datasource you can "pin" each dependency, and get automatic updates. -First you would set a generic custom manager in your `renovate.json` file for `Dockerfile`: +First you would set a custom manager in your `renovate.json` file for `Dockerfile`: ```json { From a1a4e9761b4ab6a7ff209c9417339681c84308cc Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Wed, 20 Sep 2023 05:47:36 +0545 Subject: [PATCH 06/13] Apply suggestions from code review --- docs/usage/getting-started/use-cases.md | 2 +- lib/modules/manager/custom/regex/readme.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/getting-started/use-cases.md b/docs/usage/getting-started/use-cases.md index 04c51cf11422ce..5ab2f1c1feef91 100644 --- a/docs/usage/getting-started/use-cases.md +++ b/docs/usage/getting-started/use-cases.md @@ -58,7 +58,7 @@ 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. +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 diff --git a/lib/modules/manager/custom/regex/readme.md b/lib/modules/manager/custom/regex/readme.md index 4cd89f1336343c..5024363f734e81 100644 --- a/lib/modules/manager/custom/regex/readme.md +++ b/lib/modules/manager/custom/regex/readme.md @@ -14,7 +14,7 @@ Also read the documentation for the [`customManagers` config option](https://doc The first two required fields are `fileMatch` and `matchStrings`: - `fileMatch` works the same as any manager -- `matchStrings` is a `regex` managers concept and is used for configuring a regular expression with named capture groups +- `matchStrings` is a `regex` manager concept and is used for configuring a regular expression with named capture groups Before Renovate can look up a dependency and decide about updates, it needs this information about each dependency: From 077679e2b95c95d2e9109ed3e29558ee8e051afc Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Wed, 20 Sep 2023 18:36:32 +0545 Subject: [PATCH 07/13] Apply suggestions from code review Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- docs/usage/configuration-options.md | 33 ++++++++++--------- docs/usage/user-stories/swissquote.md | 2 +- .../custom/custom-managers-migration.ts | 2 +- 3 files changed, 20 insertions(+), 17 deletions(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index a0908e53832e2e..4c67a77d180590 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -646,7 +646,7 @@ When using with `npm`, we recommend you: ## 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. +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/). @@ -659,7 +659,8 @@ You can define custom managers to handle: - Proprietary file formats or conventions - Popular file formats not yet supported as a manager by Renovate -Currently we only have one custom manager. The `regex` manager which is based on using Regular Expression named capture groups. +Currently we only have one custom manager. +The `regex` manager which is based on using Regular Expression named capture groups. You must have a named capture group matching (e.g. `(?.*)`) _or_ configure its corresponding template (e.g. `depNameTemplate`) for these fields: @@ -668,7 +669,7 @@ You must have a named capture group matching (e.g. `(?.*)`) _or_ config - `currentValue` Use named capture group matching _or_ set a corresponding template. -We recommend you use only one of these methods, or you'll get confused. +We recommend you use only _one_ of these methods, or you'll get confused. We recommend that you also tell Renovate what `versioning` to use. If the `versioning` field is missing, then Renovate defaults to using `semver` versioning. @@ -699,7 +700,7 @@ Example: ### matchStrings -`matchStrings` should each be a valid regular expression, optionally with named capture groups. +Each `matchStrings` must be a valid regular expression, optionally with named capture groups. Example: @@ -725,7 +726,7 @@ Three options are available: 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 3 lines in the Dockerfile. +As example the following configuration will update all three lines in the Dockerfile. renovate.json: ```json @@ -745,7 +746,7 @@ renovate.json: } ``` -a Dockerfile: +A Dockerfile: ```dockerfile FROM amd64/ubuntu:18.04 @@ -758,7 +759,7 @@ ENV NODE_VERSION=10.19.0 # github-tags/nodejs/node&versioning=node 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 used as basis be used as the input for the next `matchStrings` pattern, and so on. +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. @@ -820,10 +821,11 @@ example.json: #### combination -This option allows the possibility to combine the values of multiple lines inside a file. -While using multiple lines is also possible using both other `matchStringStrategy` values, the `combination` approach is less susceptible to white space or line breaks stopping a match. +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` will only match at most one dependency per file, so if you want to update multiple dependencies using `combination` you have to define multiple custom managers. +`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. @@ -855,7 +857,7 @@ renovate.json: } ``` -Ansible variable file ( yaml ): +Ansible variable file (YAML): ```yaml prometheus_image: "prom/prometheus" // a comment @@ -914,14 +916,14 @@ 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. -helm-values.yaml: +`helm-values.yaml`: ```yaml # The image of the service //: image: my.old.registry/aRepository/andImage:1.18-alpine ``` -regex definition: +The regex definition: ```json { @@ -949,7 +951,7 @@ image: my.new.registry/aRepository/andImage:1.21-alpine ## customizeDashboard -You can use the `customizeDashboard` object to customize dependency dashboard. +You may use the `customizeDashboard` object to customize the Dependency Dashboard. Supported fields: @@ -958,7 +960,8 @@ Supported fields: ### defaultRegistryUrlTemplate `registryUrl` which is used, if none is return by extraction. -As this is a template it can be dynamically set. E.g. add the `packageName` as part of the URL: +As this is a template it can be dynamically set. +E.g. add the `packageName` as part of the URL: ```json5 { diff --git a/docs/usage/user-stories/swissquote.md b/docs/usage/user-stories/swissquote.md index f4fe216c26bc39..64e070353a6676 100644 --- a/docs/usage/user-stories/swissquote.md +++ b/docs/usage/user-stories/swissquote.md @@ -177,7 +177,7 @@ Some features and options we enjoy: - 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](https://docs.renovatebot.com/modules/manager/#supported-managers): Maven, Docker, npm, Docker Compose, Python -- If you are using dependencies in a custom way, [there is a special customManager](../configuration-options.md#custommanagers) that allows you to transform patterns into dependencies +- 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. diff --git a/lib/config/migrations/custom/custom-managers-migration.ts b/lib/config/migrations/custom/custom-managers-migration.ts index a4271247056a26..7131bac2054fde 100644 --- a/lib/config/migrations/custom/custom-managers-migration.ts +++ b/lib/config/migrations/custom/custom-managers-migration.ts @@ -11,7 +11,7 @@ export class CustomManagersMigration extends AbstractMigration { if (mgr.customType) { return mgr; } - return Object.assign({ customType: 'regex' }, mgr); // to make sure customType is at top, looks good when migration pr is created + return Object.assign({ customType: 'regex' }, mgr); // to make sure customType is at top, looks good when migration PR is created }); this.rewrite(customManagers); From 0b03e6aabb982372f3500e1faed3a33e3edbefb5 Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Wed, 20 Sep 2023 21:54:27 +0545 Subject: [PATCH 08/13] Update docs/usage/configuration-options.md Co-authored-by: Rhys Arkins --- docs/usage/configuration-options.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index 4c67a77d180590..ffd6c362614dbf 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -959,7 +959,10 @@ Supported fields: ### defaultRegistryUrlTemplate -`registryUrl` which is used, if none is return by extraction. +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 regex 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: From 6fc06ba9982a14bbb0b804ce248f507ec0fe2c40 Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Thu, 21 Sep 2023 04:39:33 +0545 Subject: [PATCH 09/13] fox formatting --- docs/usage/configuration-options.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index ffd6c362614dbf..c34fbe2f336eb9 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -961,10 +961,11 @@ Supported fields: 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 regex 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: + +- The dependency can be found with the default `registryUrls` of the datasource (e.g. npmjs registry if the datasource is `npm`), or +- The regex 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: ```json5 { From b78bf9a73519bd436fd5958c2251b8007beba0ad Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Fri, 22 Sep 2023 19:30:27 +0545 Subject: [PATCH 10/13] Apply Suggestions --- docs/usage/configuration-options.md | 6 +++--- docs/usage/reading-list.md | 2 +- lib/modules/manager/custom/regex/readme.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md index c34fbe2f336eb9..7658749dac56e8 100644 --- a/docs/usage/configuration-options.md +++ b/docs/usage/configuration-options.md @@ -652,7 +652,7 @@ For more details see the [`custom` datasource documentation](/modules/datasource ## customManagers -Use `customManagers` entries to configure the custom managers in Renovate. +Use `customManagers`(previously `regexManagers`) entries to configure the custom managers in Renovate. You can define custom managers to handle: @@ -674,7 +674,7 @@ We recommend you use only _one_ of these methods, or you'll get confused. We recommend that you also tell Renovate what `versioning` to use. If the `versioning` field is missing, then Renovate defaults to using `semver` versioning. -For more details and examples, see our [documentation for the `regex` manager](/modules/manager/regex/). +For more details and examples about it, see our [documentation for the `regex` manager](/modules/manager/regex/). For template fields, use the triple brace `{{{ }}}` notation to avoid Handlebars escaping any special characters. @@ -963,7 +963,7 @@ 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 regex groups you specified as part of the matching already include a `registryUrl` group +- 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: diff --git a/docs/usage/reading-list.md b/docs/usage/reading-list.md index a7e7e4e8354b24..1093151c3c6f0a 100644 --- a/docs/usage/reading-list.md +++ b/docs/usage/reading-list.md @@ -58,7 +58,7 @@ Feel free to read up on anything that looks interesting to you. First, complete the "Beginners" and the "Intermediate" reading list. Then read: -- Define your own custom manager with [`customManagers`](./configuration-options.md#custommanagers) +- Define your own custom manager with [`customManagers`](./configuration-options.md#custommanagers)(previously `regexManagers`) - [Shareable config presets](./config-presets.md) ## Self-hosting Renovate diff --git a/lib/modules/manager/custom/regex/readme.md b/lib/modules/manager/custom/regex/readme.md index 5024363f734e81..6c91fd35d930cd 100644 --- a/lib/modules/manager/custom/regex/readme.md +++ b/lib/modules/manager/custom/regex/readme.md @@ -14,7 +14,7 @@ Also read the documentation for the [`customManagers` config option](https://doc The first two required fields are `fileMatch` and `matchStrings`: - `fileMatch` works the same as any manager -- `matchStrings` is a `regex` manager concept and is used for configuring a regular expression with named capture groups +- `matchStrings` is a `regex` custom manager concept and is used for configuring a regular expression with named capture groups Before Renovate can look up a dependency and decide about updates, it needs this information about each dependency: @@ -79,7 +79,7 @@ Continuing the above example with Yarn, here is the full Renovate config: ### Advanced Capture Say your `Dockerfile` has many `ENV` variables that you want to keep up-to-date. -But you don't want to write a `customManagers` rule for _each_ variable. +But you don't want to write a regex custom manager rule for _each_ variable. Instead you enhance your `Dockerfile` like this: ```Dockerfile From 0e23d0cb2fb75b8b33f71c39e3f8919ddaeb3be4 Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Sun, 24 Sep 2023 09:57:50 +0545 Subject: [PATCH 11/13] missed rename: regexManager to customManager --- lib/config/presets/internal/regex-managers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/config/presets/internal/regex-managers.ts b/lib/config/presets/internal/regex-managers.ts index 9aa37ae388948a..287d913358b970 100644 --- a/lib/config/presets/internal/regex-managers.ts +++ b/lib/config/presets/internal/regex-managers.ts @@ -46,7 +46,7 @@ export const presets: Record = { }, mavenPropertyVersions: { description: 'Update `*.version` properties in `pom.xml` files.', - regexManagers: [ + customManagers: [ { customType: 'regex', datasourceTemplate: From a567b085920b82856c7ea65813773e04b218f41e Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Sun, 24 Sep 2023 10:05:34 +0545 Subject: [PATCH 12/13] lint: fix order of keys --- lib/config/presets/internal/regex-managers.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/config/presets/internal/regex-managers.ts b/lib/config/presets/internal/regex-managers.ts index 287d913358b970..47e16cd9185982 100644 --- a/lib/config/presets/internal/regex-managers.ts +++ b/lib/config/presets/internal/regex-managers.ts @@ -45,7 +45,6 @@ export const presets: Record = { description: 'Update `appVersion` value in Helm chart `Chart.yaml`.', }, mavenPropertyVersions: { - description: 'Update `*.version` properties in `pom.xml` files.', customManagers: [ { customType: 'regex', @@ -58,6 +57,7 @@ export const presets: Record = { versioningTemplate: '{{#if versioning}}{{{versioning}}}{{/if}}', }, ], + description: 'Update `*.version` properties in `pom.xml` files.', }, tfvarsVersions: { customManagers: [ From 20099f0af7c6f6284abc8e0b4fb8295265b425ea Mon Sep 17 00:00:00 2001 From: RahulGautamSingh Date: Sun, 24 Sep 2023 10:40:52 +0545 Subject: [PATCH 13/13] fix test --- lib/config/presets/internal/regex-managers.spec.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/config/presets/internal/regex-managers.spec.ts b/lib/config/presets/internal/regex-managers.spec.ts index e62801031e6e33..074e59a7b534b2 100644 --- a/lib/config/presets/internal/regex-managers.spec.ts +++ b/lib/config/presets/internal/regex-managers.spec.ts @@ -235,7 +235,7 @@ describe('config/presets/internal/regex-managers', () => { }); describe('finds dependencies in pom.xml properties', () => { - const regexManager = presets['mavenPropertyVersions'].regexManagers?.[0]; + const customManager = presets['mavenPropertyVersions'].customManagers?.[0]; it(`find dependencies in file`, async () => { const fileContent = codeBlock` @@ -252,7 +252,7 @@ describe('config/presets/internal/regex-managers', () => { const res = await extractPackageFile( fileContent, 'pom.xml', - regexManager! + customManager! ); expect(res?.deps).toMatchObject([