docs: masterIssue

Closes #2937

lib/config/definitions.js

@@ -166,6 +166,33 @@ const options = [
     default: true,
     admin: true,
   },
+  // Master Issue
+  {
+    name: 'masterIssue',
+    description: 'Whether to create a "Master Issue" within the repository.',
+    type: 'boolean',
+    default: false,
+  },
+  {
+    name: 'masterIssueApproval',
+    description:
+      'Whether updates should require manual approval from within the Master Issue before creation.',
+    type: 'boolean',
+    default: false,
+  },
+  {
+    name: 'masterIssueAutoclose',
+    description:
+      'Set to `true` and Renovate will autoclose the Master Issue if there are no updates.',
+    type: 'boolean',
+    default: false,
+  },
+  {
+    name: 'masterIssueTitle',
+    description: 'Title to use for the Master Issue',
+    type: 'string',
+    default: `Update Dependencies (${appName} Bot)`,
+  },
   // encryption
   {
     name: 'privateKey',

lib/config/validation.js

@@ -69,12 +69,8 @@ async function validateConfig(config, isPreset, parentPath) {
       'forkToken',
       'repository',
       'vulnerabilityAlertsOnly',
-      'copyLocalLibs', // deprecated - functinoality is now enabled by default
+      'copyLocalLibs', // deprecated - functionality is now enabled by default
       'prBody', // deprecated
-      'masterIssue',
-      'masterIssueTitle',
-      'masterIssueApproval',
-      'masterIssueAutoclose',
     ];
     return ignoredNodes.includes(key);
   }

renovate-schema.json

@@ -101,6 +101,26 @@
       "type": "boolean",
       "default": true
     },
+    "masterIssue": {
+      "description": "Whether to create a \"Master Issue\" within the repository.",
+      "type": "boolean",
+      "default": false
+    },
+    "masterIssueApproval": {
+      "description": "Whether updates should require manual approval from within the Master Issue before creation.",
+      "type": "boolean",
+      "default": false
+    },
+    "masterIssueAutoclose": {
+      "description": "Set to `true` and Renovate will autoclose the Master Issue if there are no updates.",
+      "type": "boolean",
+      "default": false
+    },
+    "masterIssueTitle": {
+      "description": "Title to use for the Master Issue",
+      "type": "string",
+      "default": "Update Dependencies (Renovate Bot)"
+    },
     "privateKey": {
       "description": "Server-side private key",
       "type": "string"

test/workers/repository/updates/__snapshots__/flatten.spec.js.snap

@@ -41,6 +41,10 @@ Array [
     "lazyGrouping": true,
     "manager": "npm",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "newValue": "1.0.0",
     "npmToken": null,
     "npmrc": null,
@@ -144,6 +148,10 @@ Array [
     "lazyGrouping": true,
     "manager": "npm",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "newValue": "2.0.0",
     "npmToken": null,
     "npmrc": null,
@@ -245,6 +253,10 @@ Array [
     "lazyGrouping": true,
     "manager": "npm",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "npmToken": null,
     "npmrc": null,
     "packageFile": "package.json",
@@ -350,6 +362,10 @@ Array [
     "lazyGrouping": true,
     "manager": "npm",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "newValue": "3.0.0",
     "npmToken": null,
     "npmrc": null,
@@ -451,6 +467,10 @@ Array [
     "lazyGrouping": true,
     "manager": "npm",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "npmToken": null,
     "npmrc": null,
     "packageFile": "backend/package.json",
@@ -556,6 +576,10 @@ Array [
     "lazyGrouping": true,
     "manager": "npm",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "newValue": "3.0.1",
     "npmToken": null,
     "npmrc": null,
@@ -659,6 +683,10 @@ Array [
     "lazyGrouping": true,
     "manager": "dockerfile",
     "managerBranchPrefix": "",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "newValue": "10.0.1",
     "npmToken": null,
     "npmrc": null,
@@ -762,6 +790,10 @@ Array [
     "lazyGrouping": true,
     "manager": "dockerfile",
     "managerBranchPrefix": "docker-",
+    "masterIssue": false,
+    "masterIssueApproval": false,
+    "masterIssueAutoclose": false,
+    "masterIssueTitle": "Update Dependencies (Renovate Bot)",
     "newValue": "3.2.0",
     "npmToken": null,
     "npmrc": null,

website/docs/configuration-options.md

@@ -434,6 +434,35 @@ Add to this object if you wish to define rules that apply only to major updates.
 
 This value defaults to empty string, as historically no prefix was necessary for when Renovate was JS-only. Now - for example - we use `docker-` for Docker branches, so they may look like `renovate/docker-ubuntu-16.x`.
 
+## masterIssue
+
+Configuration `masterIssue` to `true` will lead to the creation of a "Master Issue" within the repository. This Master Issue is akin to a mini dashboard and contains a list of all PRs pending, open, closed (unmerged) or in error.
+
+Examples of what having a master issue will allow you to do:
+
+- View all PRs in one place, rather than having to filter PRs by author
+- Rebase/retry multiple PRs without having to open each individually
+- Override any rate limiting (e.g. concurrent PRs) or scheduling to force Renovate to create a PR that would otherwise be suppressed
+- Recreate an unmerged PR (e.g. for a major update that you put off by closing the original PR)
+
+Note: Enabling the Master Issue does not itself change any of the "flow" of Renovate, e.g. it will otherwise still create and manage PRs exactly as it always has. The Master Issue therefore provides visibility as well as additional control.
+
+## masterIssueApproval
+
+Setting `masterIssueApproval` to `true` means that Renovate will no longer create branches/PRs automatically but instead wait for manual approval from within the Master Issue.
+
+In this case, the Master Issue _does_ change the flow of Renovate, because PRs will stop appearing until you approve them within the issue. Instead of enabling this repository-wide, you may instead with to use package rules to enable it selectively, e.g. for major updates only, or for certain package managers, etc. i.e. it is possible to require approval for only certain types of updates only.
+
+Note: Enabling Master Issue Approval implicitly enables `masterIssue` too, so it is not necessary to set both to `true`.
+
+## masterIssueAutoclose
+
+You can set this to `true` if you prefer Renovate to autoclose its Master Issue whenever there are no outstanding PRs left.
+
+## masterIssueTitle
+
+Set this option if you prefer a different title for the Master Issue.
+
 ## maven
 
 ## meteor