diff --git a/docs/usage/configuration-options.md b/docs/usage/configuration-options.md
index f425d4266bd1d6f0898327d4612e61f1c39bb876..6cdef2a2467a086d525a39652bd73128090cc1eb 100644
--- a/docs/usage/configuration-options.md
+++ b/docs/usage/configuration-options.md
@@ -170,6 +170,8 @@ Warning: it's strongly recommended not to configure this field directly. Use at
 
 You can modify this field if you want to change the prefix used. For example if you want branches to be like `deps/eslint-4.x` instead of `renovate/eslint-4.x` then you configure `branchPrefix` = `deps/`. Or if you wish to avoid forward slashes in branch names then you could use `renovate_` instead, for example.
 
+`branchPrefix` must be configured at the root of the configuration (e.g. not within any package rule) and is not allowed to use template values. e.g. instead of `renovate/{{parentDir}}-`, configure the template part in `additionalBranchPrefix`, like `"additionalBranchPrefix": "{{parentDir}}-"`.
+
 Note that this setting does not change the default _onboarding_ branch name, i.e. `renovate/configure`. If you wish to change that too, you need to also configure the field `onboardingBranch` in your admin bot config.
 
 ## branchTopic
diff --git a/lib/config/__snapshots__/migration.spec.ts.snap b/lib/config/__snapshots__/migration.spec.ts.snap
index 3442949a7cb2644e6a6ed2eca81532a5de9a6ce0..e7467aa783e7aaf9a7e20ac560bd81ef7cf16cbf 100644
--- a/lib/config/__snapshots__/migration.spec.ts.snap
+++ b/lib/config/__snapshots__/migration.spec.ts.snap
@@ -8,13 +8,14 @@ Object {
 
 exports[`config/migration migrateConfig(config, parentConfig) it migrates config 1`] = `
 Object {
-  "additionalBranchPrefix": "foo",
+  "additionalBranchPrefix": "{{parentDir}}-",
   "autodiscover": true,
   "automerge": false,
   "automergeType": "branch",
   "baseBranches": Array [
     "next",
   ],
+  "branchPrefix": "renovate/",
   "commitMessage": "{{#if semanticCommitType}}{{semanticCommitType}}{{#if semanticCommitScope}}({{semanticCommitScope}}){{/if}}: {{/if}}some commit message",
   "commitMessageExtra": "{{currentValue}} something",
   "dependencyDashboard": true,
diff --git a/lib/config/migration.spec.ts b/lib/config/migration.spec.ts
index 86dae20755f835a24bdb2dcb174398be55a14187..b904f26f04a302cd8a2d3c0265af07f62d068e02 100644
--- a/lib/config/migration.spec.ts
+++ b/lib/config/migration.spec.ts
@@ -44,6 +44,7 @@ describe('config/migration', () => {
         automergeType: 'branch-push',
         baseBranch: 'next',
         managerBranchPrefix: 'foo',
+        branchPrefix: 'renovate/{{parentDir}}-',
         renovateFork: true,
         ignoreNodeModules: true,
         node: {
diff --git a/lib/config/migration.ts b/lib/config/migration.ts
index f71bd3e36775e9f9dc319536a5d482d1bb6196cd..e1aa1ab235dfd1aba02bb38f2bc87ae609a34ed1 100644
--- a/lib/config/migration.ts
+++ b/lib/config/migration.ts
@@ -194,6 +194,15 @@ export function migrateConfig(
         isMigrated = true;
         delete migratedConfig.managerBranchPrefix;
         migratedConfig.additionalBranchPrefix = val;
+      } else if (
+        key === 'branchPrefix' &&
+        is.string(val) &&
+        val.includes('{{')
+      ) {
+        isMigrated = true;
+        const templateIndex = val.indexOf(`{{`);
+        migratedConfig.branchPrefix = val.substring(0, templateIndex);
+        migratedConfig.additionalBranchPrefix = val.substring(templateIndex);
       } else if (key === 'upgradeInRange') {
         isMigrated = true;
         delete migratedConfig.upgradeInRange;