feat(config)!: experimental flags

docs/usage/.pages

@@ -7,6 +7,7 @@ nav:
       - 'Overview': 'config-overview.md'
       - 'Repository': 'configuration-options.md'
       - 'Self-hosted': 'self-hosted-configuration.md'
+      - 'Self-hosted experimental flags': 'self-hosted-experimental-flags.md'
       - 'Presets': 'config-presets.md'
       - 'Validation': 'config-validation.md'
   - ... | key-concepts

docs/usage/self-hosted-configuration.md

@@ -548,6 +548,25 @@ Information provided mainly in debug log level.
 Default execution timeout in minutes for child processes Renovate creates.
 If this option is not set, Renovate will fallback to 15 minutes.
 
+## experimentalFlags
+
+The `experimentalFlags` configuration option streamlines managing experimental settings within Renovate.
+This option replaces the use of environment variables (prefixed with `RENOVATE_X_`), providing a more structured and manageable approach.
+
+Old Approach: Previously, users had to set experimental environment variables like `RENOVATE_X_DOCKER_MAX_PAGES`, and others.
+
+New Approach: With `experimentalFlags`, users can specify experimental settings directly within the configuration file, enhancing clarity and ease of maintenance.
+
+```js
+module.exports = {
+  experimentalFlags: ['dockerMaxPages=10'],
+};
+```
+
+Each setting can be specified in the two formats available `flagName` or `flagName=value`.
+
+Read [Self-Hosted Experimental Flags](./self-hosted-experimental.md) for the full list of flags supported by Renovate.
+
 ## exposeAllEnv
 
 To keep you safe, Renovate only passes a limited set of environment variables to package managers.

docs/usage/self-hosted-experimental-flags.md

@@ -0,0 +1,35 @@
+# Self-hosted experimental flags
+
+The following flags are "experimental" because they:
+
+- are not commonly needed
+- are typically an effort to work around some other service's or platform's problem
+- can be removed at any time
+- are variables for Renovate's internal use to validate they work as intended
+
+Experimental variables which are commonly used and for which there is no external solution in sight can be converted to an official configuration option by the Renovate bot developers.
+
+Use these experimental flags at your own risk.
+We do not follow Semantic Versioning for any experimental variables.
+These flags may be removed or have their behavior changed in **any** version.
+We will try to keep breakage to a minimum, but make no guarantees that an experimental flag will keep working.
+
+## `dockerHubTags`
+
+If added to the `experimentalFlags` list, Renovate will use the Docker Hub API (`https://hub.docker.com`) to fetch tags instead of the normal Docker API for images pulled from `https://index.docker.io`.
+
+```js
+experimentalFlags: ['dockerHubTags'];
+```
+
+## `dockerMaxPages`
+
+The default maximum page number for Docker tags lookup on Docker registries is `20`.
+You can override this default by setting a new integer number in the `dockerMaxPages` field.
+This is useful for registries which ignore the `n` parameter in the query string and only return `50` tags per page.
+
+Example usage:
+
+```js
+experimentalFlags: ['dockerMaxPages=10'];
+```

docs/usage/self-hosted-experimental.md

@@ -84,15 +84,6 @@ You can set the config file Renovate should read with the `RENOVATE_CONFIG_FILE`
 
 The process that runs Renovate must have the correct permissions to delete the config file.
 
-## `RENOVATE_X_DOCKER_HUB_TAGS`
-
-If set to any value, Renovate will use the Docker Hub API (`https://hub.docker.com`) to fetch tags instead of the normal Docker API for images pulled from `https://index.docker.io`.
-
-## `RENOVATE_X_DOCKER_MAX_PAGES`
-
-If set to an integer, Renovate will use this as max page number for docker tags lookup on docker registries, instead of the default 20 pages.
-This is useful for registries which ignores the `n` parameter in the query string and only return 50 tags per page.
-
 ## `RENOVATE_X_EAGER_GLOBAL_EXTENDS`
 
 Resolve and merge `globalExtends` presets before other global config, instead of after.

lib/config/global.ts

@@ -32,6 +32,7 @@ export class GlobalConfig {
     'gitTimeout',
     'platform',
     'endpoint',
+    'experimentalFlags',
   ];
 
   private static config: RepoGlobalConfig = {};

lib/config/options/index.ts

@@ -2981,6 +2981,15 @@ const options: RenovateOptions[] = [
     default: null,
     supportedPlatforms: ['github'],
   },
+  {
+    name: 'experimentalFlags',
+    description:
+      'Set which experimental flags you want Renovate to use.',
+    type: 'array',
+    subType: 'string',
+    default: null,
+    globalOnly: true,
+  },
 ];
 
 export function getOptions(): RenovateOptions[] {

lib/config/types.ts

@@ -158,6 +158,7 @@ export interface RepoGlobalConfig {
   presetCachePersistence?: boolean;
   privateKey?: string;
   privateKeyOld?: string;
+  experimentalFlags?: string[];
 }
 
 export interface LegacyAdminConfig {

lib/config/validation.spec.ts

@@ -1702,4 +1702,123 @@ describe('config/validation', () => {
       expect(errors).toHaveLength(0);
     });
   });
+
+  describe('validate experimental flags', () => {
+    beforeEach(() => {
+      GlobalConfig.reset();
+    });
+
+    it('warns if invalid flag found', async () => {
+      const config = {
+        experimentalFlags: [
+          'invalidintegertag=10',
+          'invalidtag',
+          'invalidstringtag=string',
+          'invalidarraytag=a,b,c',
+          10,
+        ],
+      };
+      const { warnings } = await configValidation.validateConfig(
+        'global',
+        config,
+      );
+      expect(warnings).toEqual([
+        {
+          topic: 'Configuration Error',
+          message:
+            'Experimental flags can only be of type string. Found invalid type',
+        },
+        {
+          topic: 'Configuration Error',
+          message:
+            'Invalid flag `invalidarraytag` found in `experimentalFlags`.',
+        },
+        {
+          topic: 'Configuration Error',
+          message:
+            'Invalid flag `invalidintegertag` found in `experimentalFlags`.',
+        },
+        {
+          topic: 'Configuration Error',
+          message:
+            'Invalid flag `invalidstringtag` found in `experimentalFlags`.',
+        },
+        {
+          topic: 'Configuration Error',
+          message: 'Invalid flag `invalidtag` found in `experimentalFlags`.',
+        },
+      ]);
+    });
+
+    it('dockerHubTags', async () => {
+      const config = {
+        experimentalFlags: ['dockerHubTags'],
+      };
+      const { warnings } = await configValidation.validateConfig(
+        'global',
+        config,
+      );
+      expect(warnings).toBeEmptyArray();
+    });
+
+    it('warns if invalid value set for dockerHubTags', async () => {
+      const config = {
+        experimentalFlags: ['dockerHubTags=10'],
+      };
+      const { warnings } = await configValidation.validateConfig(
+        'global',
+        config,
+      );
+      expect(warnings).toEqual([
+        {
+          topic: 'Configuration Error',
+          message: 'Experimental flag `dockerHubTags` should not have a value.',
+        },
+      ]);
+    });
+
+    it('dockerMaxPages', async () => {
+      const config = {
+        experimentalFlags: ['dockerMaxPages=10'],
+      };
+      const { warnings } = await configValidation.validateConfig(
+        'global',
+        config,
+      );
+      expect(warnings).toBeEmptyArray();
+    });
+
+    it('warns if invalid value set for dockerMaxPages', async () => {
+      const config = {
+        experimentalFlags: ['dockerMaxPages=string'],
+      };
+      const { warnings } = await configValidation.validateConfig(
+        'global',
+        config,
+      );
+      expect(warnings).toEqual([
+        {
+          topic: 'Configuration Error',
+          message:
+            'Experimental flag `dockerMaxPages` should be of type integer. Found invalid type instead.',
+        },
+      ]);
+    });
+
+    it('warns if no value set for dockerMaxPages', async () => {
+      const config = {
+        experimentalFlags: ['dockerMaxPages'],
+      };
+      const { warnings } = await configValidation.validateConfig(
+        'global',
+        config,
+      );
+      expect(warnings).toEqual([
+        {
+          topic: 'Configuration Error',
+          message: 'Experimental flag `dockerMaxPages` should have a value.',
+        },
+      ]);
+    });
+  });
 });

lib/config/validation.ts

@@ -940,7 +940,24 @@ async function validateGlobalConfig(
       }
     } else if (type === 'array') {
       if (is.array(val)) {
-        if (key === 'gitNoVerify') {
+        if (key === 'experimentalFlags') {
+          for (const flag of val) {
+            if (is.string(flag)) {
+              const [flagName, flagValue] = flag.split('=');
+              validateExperimentalFlag(
+                flagName,
+                flagValue ?? null,
+                warnings,
+                currentPath,
+              );
+            } else {
+              warnings.push({
+                topic: 'Configuration Error',
+                message: `Experimental flags can only be of type string. Found invalid type`,
+              });
+            }
+          }
+        } else if (key === 'gitNoVerify') {
           const allowedValues = ['commit', 'push'];
           for (const value of val as string[]) {
             if (!allowedValues.includes(value)) {
@@ -1019,3 +1036,68 @@ function isFalseGlobal(optionName: string, parentPath?: string): boolean {
 
   return false;
 }
+
+function validateExperimentalFlag(
+  flagName: string,
+  flagValue: string | null,
+  warnings: ValidationMessage[],
+  currentPath: string | undefined,
+): void {
+  const allowedExperimentalFlags: Record<string, Record<string, string>> = {
+    dockerHubTags: {},
+    dockerMaxPages: { acceptedValue: 'integer' },
+  };
+
+  const flagDetails = allowedExperimentalFlags[flagName];
+  if (!flagDetails) {
+    warnings.push({
+      topic: 'Configuration Error',
+      message: `Invalid flag \`${flagName}\` found in \`${currentPath}\`.`,
+    });
+    return;
+  }
+
+  if (flagDetails.acceptedValue && !flagValue) {
+    warnings.push({
+      topic: 'Configuration Error',
+      message: `Experimental flag \`${flagName}\` should have a value.`,
+    });
+  }
+
+  if (!flagDetails.acceptedValue && flagValue) {
+    warnings.push({
+      topic: 'Configuration Error',
+      message: `Experimental flag \`${flagName}\` should not have a value.`,
+    });
+  }
+
+  // will add test soon, for review I wanted to keep it minimal
+  // istanbul ignore if
+  if (flagDetails.acceptedValue && flagValue) {
+    switch (flagDetails.acceptedValue) {
+      case 'integer':
+        if (!regEx(/^\d+$/).test(flagValue)) {
+          warnings.push({
+            topic: 'Configuration Error',
+            message: `Experimental flag \`${flagName}\` should be of type integer. Found invalid type instead.`,
+          });
+        }
+        break;
+      case 'string':
+        if (!regEx(/^\w+$/).test(flagValue)) {
+          warnings.push({
+            topic: 'Configuration Error',
+            message: `Experimental flag \`${flagName}\` should be of type string. Found invalid type instead.`,
+          });
+        }
+        break;
+      case 'array':
+        if (!regEx(/(\w+,?)+/).test(flagValue)) {
+          warnings.push({
+            topic: 'Configuration Error',
+            message: `Experimental flag \`${flagName}\` should be of type array of strings. Found invalid type instead.`,
+          });
+        }
+    }
+  }
+}

lib/modules/datasource/docker/index.spec.ts

@@ -10,6 +10,7 @@ import { getDigest, getPkgReleases } from '..';
 import { range } from '../../../../lib/util/range';
 import * as httpMock from '../../../../test/http-mock';
 import { logger, mocked } from '../../../../test/util';
+import { GlobalConfig } from '../../../config/global';
 import { EXTERNAL_HOST_ERROR } from '../../../constants/error-messages';
 import * as _hostRules from '../../../util/host-rules';
 import { DockerDatasource } from '.';
@@ -47,8 +48,7 @@ describe('modules/datasource/docker/index', () => {
       password: 'some-password',
     });
     hostRules.hosts.mockReturnValue([]);
-    delete process.env.RENOVATE_X_DOCKER_MAX_PAGES;
-    delete process.env.RENOVATE_X_DOCKER_HUB_TAGS;
+    GlobalConfig.reset();
   });
 
   describe('getDigest', () => {
@@ -1286,7 +1286,7 @@ describe('modules/datasource/docker/index', () => {
     });
 
     it('uses custom max pages', async () => {
-      process.env.RENOVATE_X_DOCKER_MAX_PAGES = '2';
+      GlobalConfig.set({ experimentalFlags: ['dockerMaxPages=2'] });
       httpMock
         .scope(baseUrl)
         .get('/library/node/tags/list?n=10000')
@@ -1793,7 +1793,7 @@ describe('modules/datasource/docker/index', () => {
     });
 
     it('Uses Docker Hub tags for registry-1.docker.io', async () => {
-      process.env.RENOVATE_X_DOCKER_HUB_TAGS = 'true';
+      GlobalConfig.set({ experimentalFlags: ['dockerHubTags'] });
       httpMock
         .scope(dockerHubUrl)
         .get('/library/node/tags?page_size=1000')
@@ -1834,7 +1834,7 @@ describe('modules/datasource/docker/index', () => {
     });
 
     it('adds library/ prefix for Docker Hub (implicit)', async () => {
-      process.env.RENOVATE_X_DOCKER_HUB_TAGS = 'true';
+      GlobalConfig.set({ experimentalFlags: ['dockerHubTags'] });
       const tags = ['1.0.0'];
       httpMock
         .scope(dockerHubUrl)
@@ -1863,7 +1863,7 @@ describe('modules/datasource/docker/index', () => {
     });
 
     it('adds library/ prefix for Docker Hub (explicit)', async () => {
-      process.env.RENOVATE_X_DOCKER_HUB_TAGS = 'true';
+      GlobalConfig.set({ experimentalFlags: ['dockerHubTags'] });
       httpMock
         .scope(dockerHubUrl)
         .get('/library/node/tags?page_size=1000')