Clarify fast-forwarding setup requirements

mergequeue/concepts/parallel-mode/fast-forwarding.md

@@ -18,15 +18,19 @@ By using this mode, the history in your Git repository remains linear and CI val
 
 Fast forwarding works by creating temporary branches in a sequential order for every new PR that is ready to merge. Aviator identifies PRs that are ready through GitHub labels.
 
-![](<../../../.gitbook/assets/ezgif.com-gif-maker (1).gif>)
+### When CI passes
 
 When a PR (`PR #1`) is labeled as ready for merging, Aviator picks the head commit for your base branch (typically `master` or `main`), creates a new branch (`branch A`), and applies all the commits of the labeled PR as a squash commit in `branch A`. Aviator will then validate the CI for this new squash commit. If a second PR (`PR #2`) is labeled while the CI for the first one is still running, Aviator will now pick the latest commit from `branch A` and create a new branch (`branch B`) and apply the commits of the second PR as a squash commit to `branch B`. This way the CI validation can happen in parallel using a speculative commit strategy.
 
 Once the CI for PR #1 passes, Aviator automatically fast forwards the head of your base branch to the head of `branch A`. Likewise if the CI for PR #2 passes, it fast forwards the head of your base branch to the head of `branch B`. By using this strategy, Aviator can both maintain the linear history of your PRs and also ensure that the builds pass on each commit.
 
-If the CI for PR #1 fails, Aviator will not discard `branch A`, and will recreate `branch B` with only the commits of `PR #2`. This way Aviator detects failures before the commits hit the base branch, ensuring that the base branch will always remain green.
+<figure><img src="../../../.gitbook/assets/ezgif.com-gif-maker (1).gif" alt="Animation of two pull requests being queued and merged in sequence."><figcaption><p>The passing case described above. The first temporary branch created is <code>branch A</code>, and the second, stacked on top of it, is <code>branch B</code>. The base branch advances only after CI passes.</p></figcaption></figure>
 
-![](<../../../.gitbook/assets/ezgif.com-gif-maker (2).gif>)
+### When CI fails
+
+If the CI for PR #1 fails, Aviator discards `branch A` and recreates `branch B` with only the commits of `PR #2`, so that PR #2 is no longer speculating on top of a broken change. This way Aviator detects failures before the commits hit the base branch, ensuring that the base branch will always remain green.
+
+<figure><img src="../../../.gitbook/assets/ezgif.com-gif-maker (2).gif" alt="Animation of a failing pull request being removed and the following branch being rebuilt."><figcaption><p>The failing case described above. <code>branch A</code> is discarded when its CI fails, and <code>branch B</code> is rebuilt from the base branch with only PR #2's commits.</p></figcaption></figure>
 
 ## Learn more
 

mergequeue/how-to-guides/fast-forwarding.md

@@ -19,21 +19,37 @@ version: 1.0.0
 merge_rules:
   labels:
     trigger: "label_name"
-preconditions:
-  required_checks:
-    - check 1
+  preconditions:
+    required_checks:
+      - check 1
   merge_mode:
     type: "parallel"
     parallel_mode:
-      use_fast_forwarding: false
+      use_fast_forwarding: true
       override_required_checks:
         - check 1
         - check 2
 ```
 
-## Modify your GitHub protected branch settings
+## Allow Aviator to update your protected branch
 
-* To ensure that Aviator can forward your default branch, it may require additional privileges. Aviator requires permission to be able to force push to the default branch. To do so, you should authorize the Aviator app to be able to force push to the protected branch. We don’t force push the commits, but this is required to be able to fast forward protected branches that requires PullRequests.
+Fast-forwarding moves the branch reference directly to the commit that CI already validated, instead of merging through a pull request. GitHub treats that as a direct update to the branch, so when your target branch is protected, Aviator has to be allowed to make it.
+
+### Do I need to change these settings?
+
+You need them if the target branch is covered by branch protection rules or a repository ruleset that requires pull requests or restricts who can push. If the target branch has no such rules, fast-forwarding works without any extra permission.
+
+If you are not sure which applies, enable fast-forwarding and watch the first merge. When a rule blocks the update, GitHub rejects it and Aviator reports the rejection on the pull request, naming the rule that was violated.
+
+### Is this safe?
+
+Aviator sends the branch update **without the force flag**. GitHub therefore applies it only when the update is a genuine fast-forward, meaning the new commit already has the current branch head as an ancestor. If that is not true, GitHub rejects the request. This operation cannot rewrite, reorder, or drop commits that are already on your branch.
+
+The permission is still required because GitHub evaluates branch protection on *any* direct update to a branch reference, regardless of whether that update is a fast-forward. Several of the settings that grant it are worded in terms of force pushes, which is why the setup below asks for a permission broader than what Aviator actually performs.
+
+### Branch protection rules
+
+* Authorize the Aviator app to update the protected branch. In GitHub's classic branch protection settings this permission is presented as force-push access, so `aviator-app` needs to be listed there even though Aviator does not force push.
 
 ![](<../../.gitbook/assets/Screen Shot 2022-07-18 at 9.55.56 AM.png>)
 
@@ -45,6 +61,20 @@ preconditions:
 
 <figure><img src="../../.gitbook/assets/Screen Shot 2022-10-13 at 3.45.53 PM.png" alt=""><figcaption></figcaption></figure>
 
+### Repository rulesets
+
+Rulesets are evaluated separately from classic branch protection, and a repository can have both. If a ruleset targets your default branch, add `aviator-app` to that ruleset's **bypass list**, under **Settings > Rules > Rulesets** in your repository.
+
+The rule that most commonly blocks fast-forwarding is **Require a pull request before merging**, because fast-forwarding updates the branch reference rather than merging a pull request. When it blocks a merge, GitHub returns an error like:
+
+```
+Repository rule violations found
+
+Changes must be made through a pull request.
+```
+
+If that message also mentions a required status check, the ruleset is still the cause. Adding `aviator-app` to the bypass list resolves both.
+
 ## Optimize CI execution rules (optional)
 
 * When creating fast-forward branches, Aviator uses temporary branches. If your CI is configured to run on every commit SHA, you can exclude certain branches from running CI. You can add a criterion to exclude branches with the prefix `mq-tmp-`

mergequeue/quick-setup.md

@@ -10,13 +10,13 @@ This setup guide will walk you through the initial set up for MergeQueue. Since
 
 1\. Create an account. [<mark style="color:blue;">Register here</mark>](https://app.aviator.co/auth/login).
 
-2\. Follow the onboarding flow to connect to the Aviator GitHub app, authorize one or more repositories that you want to automate.
+2\. Sign in at [<mark style="color:blue;">app.aviator.co</mark>](https://app.aviator.co) and follow the onboarding flow. It prompts you to install the Aviator GitHub app and to authorize one or more repositories that you want to automate. If you already have an account and want to add another repository, go straight to the [<mark style="color:blue;">Repositories page</mark>](https://app.aviator.co/repos) and connect it from there.
 
 {% hint style="info" %}
 If you have trouble connecting the app, please read the [<mark style="color:blue;">troubleshooting doc</mark>](../manage/faqs/troubleshooting-github-app-connection.md).
 {% endhint %}
 
-3\. Select the repository on the **Repositories** page to configure the rules. This will take you to the Basic Configuration page to customize some basic settings.
+3\. Select the repository on the [<mark style="color:blue;">**Repositories** page</mark>](https://app.aviator.co/repos) to configure the rules. This will take you to the Basic Configuration page to customize some basic settings.
 
 ![Configure a repository.](<../.gitbook/assets/Screen Shot 2022-05-23 at 2.38.56 PM.png>)