From 54c1ccdb38bfd6ed842a01ba622d4767d0b74cfa Mon Sep 17 00:00:00 2001
From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com>
Date: Mon, 27 Sep 2021 13:58:52 +0200
Subject: [PATCH] docs: explain limitation on amount of branches that can be
 automerged in one run (#11890)

---
 docs/usage/key-concepts/automerge.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/usage/key-concepts/automerge.md b/docs/usage/key-concepts/automerge.md
index 4d4d5df7a634a9..3eba817bdbc9e7 100644
--- a/docs/usage/key-concepts/automerge.md
+++ b/docs/usage/key-concepts/automerge.md
@@ -12,6 +12,12 @@ Keep in mind that Renovate automerges take a bit of time, do not expect Renovate
 Wait for at least an hour or two before troubleshooting to ensure that Renovate has had the time to run once in a state where tests have passed and the branch is up-to-date with its base branch.
 If you or others keep committing to the default branch then Renovate cannot find a suitable gap to automerge into!
 
+Once a branch is automerged, the "Git state" needs to be recalculated for every remaining branch.
+At times, merging one branch could result in another branch's updates being changed or even removed as unnecessary.
+Renovate's approach is to ensure that automerging branches are up-to-date with their target branch before automerging.
+Therefore merging multiple branches in a row won't reliably work, we prefer not to do that.
+What all this means is that Renovate will only automerge at most one branch/PR per target branch per run, before you need to wait for the next run.
+
 As a general guide, we recommend that you enable automerge for any type of dependency updates where you would just click "merge" anyway.
 For any updates where you want to review the release notes - or code - before you merge, you can keep automerge disabled.