fix: review

docs/usage/configuration-options.md

@@ -1811,11 +1811,14 @@ Enable got [http2](https://github.com/sindresorhus/got/blob/v11.5.2/readme.md#ht
 
 ### header
 
-You can provide `header` object that includes fields to be forwarded to the HTTP request header. By default, all header starting with "X-" are allowed, a bot administrator may configure an override for [allowedHeader](./self-hosted-configuration.md#allowedHeader) to configure more permitted header.
+You can provide a `header` object that includes fields to be forwarded to the HTTP request header.
+By default, all headers starting with "X-" are allowed.
 
-Any `header` value configured in bot admin `hostRules` (e.g. `config.js`) won't be validated so can contain any desired header regardless of `allowedHeader`.
+A bot administrator may configure an override for [`allowedHeader`](./self-hosted-configuration.md#allowedHeader) to configure more permitted headers.
 
-Example:
+`header` value(s) configured in the bot admin `hostRules` (for example in a `config.js` file) are _not_ validated, so it may contain any header regardless of `allowedHeader`.
+
+For example:
 
 ```json
 {

docs/usage/self-hosted-configuration.md

@@ -65,17 +65,20 @@ But before you disable templating completely, try the `allowedPostUpgradeCommand
 
 ## allowedHeader
 
-This is option particularly useful when a registry employs a specific authentication system not already covered by Renovate's standard credential handling in `hostRules`.
-By default, all header starting with "X-" are allowed, but you can permit additional header using this option.
-If declared, it will override the default "X-" allowed header, so you should include them in your config if you wish for them to remain allowed.
-`allowedHeader` is an array of minimatch-compatible globs or re2-compatible regex strings.
+`allowedHeader` can be useful when a registry uses a authentication system that's not covered by Renovate's default credential handling in `hostRules`.
+By default, all headers starting with "X-" are allowed.
+If needed, you can allow additional headers with the `allowedHeader` option.
+Any set `allowedHeader` overrides the default "X-" allowed header, so you should include them in your config if you wish for them to remain allowed.
+The `allowedHeader` config option takes an array of minimatch-compatible globs or re2-compatible regex strings.
 
 Examples:
 
-- `/X/` - any header with `X` anywhere in the name (regex)
-- `!/X/` - any header without `X` anywhere in the name (regex)
-- `X-*` - any header starting with `X-` (glob pattern)
-- `X` - only the header matching exactly `X` (exact match glob)
+| Example header | Kind of pattern  | Explanation                                 |
+| -------------- | ---------------- | ------------------------------------------- |
+| `/X/`          | Regex            | Any header with `x` anywhere in the name    |
+| `!/X/`         | Regex            | Any header without `X` anywhere in the name |
+| `X-*`          | Global pattern   | Any header starting with `X-`               |
+| `X`            | Exact match glob | Only the header matching exactly `X`        |
 
 ```json
 {
@@ -90,7 +93,7 @@ Examples:
 }
 ```
 
-or with custom `allowedHeader`:
+Or with custom `allowedHeader`:
 
 ```js title="config.js"
 module.exports = {

lib/config/options/index.ts

@@ -8,7 +8,7 @@ const options: RenovateOptions[] = [
   {
     name: 'allowedHeader',
     description:
-      'List of allowed patterns for header names in repo hostRules config.',
+      'List of allowed patterns for header names in repository hostRules config.',
     type: 'array',
     default: ['X-*'],
     subType: 'string',
@@ -2406,7 +2406,7 @@ const options: RenovateOptions[] = [
   {
     name: 'header',
     description:
-      'An object that includes fields to be forwarded to the HTTP request header.',
+      'Put fields to be forwarded to the HTTP request header in the header config option.',
     type: 'object',
     parent: 'hostRules',
     cli: false,

lib/config/validation.spec.ts

@@ -922,7 +922,7 @@ describe('config/validation', () => {
       ]);
     });
 
-    it('errors if unallowed header in hostRules', async () => {
+    it('errors if forbidden header in hostRules', async () => {
       GlobalConfig.set({ allowedHeader: ['X-*'] });
 
       const config = {
@@ -967,7 +967,7 @@ describe('config/validation', () => {
       expect(errors).toMatchObject([
         {
           message:
-            'Invalid hostRules header value configuration: should be a string.',
+            'Invalid hostRules header value configuration: header must be a string.',
           topic: 'Configuration Error',
         },
       ]);

lib/config/validation.ts

@@ -688,13 +688,13 @@ export async function validateConfig(
           if (!is.string(value)) {
             errors.push({
               topic: 'Configuration Error',
-              message: `Invalid hostRules header value configuration: should be a string.`,
+              message: `Invalid hostRules header value configuration: header must be a string.`,
             });
           }
           if (!anyMatchRegexOrMinimatch(allowedHeader, header)) {
             errors.push({
               topic: 'Configuration Error',
-              message: `hostRules header \`${header}\` is not permitted by this bot's \`allowedHeader\`.`,
+              message: `hostRules header \`${header}\` is not allowed by this bot's \`allowedHeader\`.`,
             });
           }
         }

lib/util/http/host-rules.spec.ts

@@ -544,7 +544,7 @@ describe('util/http/host-rules', () => {
     });
   });
 
-  it('should remove unallowed header from request', () => {
+  it('should remove forbidden header from request', () => {
     GlobalConfig.set({ allowedHeader: ['X-*'] });
     const hostRule = {
       matchHost: 'https://domain.com/all-versions',