expand on undiverged branches (#2072)

Author: motatoes

docs/ce/howto/apply-requirements.mdx

@@ -26,4 +26,59 @@ workflows:
       on_pull_request_closed: ["digger unlock"]
       on_commit_to_default: ["digger unlock"]
       skip_merge_check: true
-```
+```
+
+## Requiring undiverged branches in PRs
+
+While PR locks prevent you from PRs stepping on eachother in parallel, they still do not protect you from a stale branch
+that is behind the current main head. In order to safeguard against this you have a few options:
+
+Force your repo to always have rebased branches from main. In github this is done by adding the branch protection rule:
+
+Under settings > branch protection rules >  Require branches to be up to date before merging → check this
+
+Since digger will always query github api for mergability status, this protects you from any stale apply from PRs being performed.
+
+![](/images/howto/force-refactor-into-main.png)
+
+Understandably this may not be feasible to mark especially for monorepos that mix code and terraform. In such cases you can achieve a similar effect by using a custom workflow like below (digger.yml):
+
+```
+projects:
+- name: gcp-infra
+  dir: cloud/terraform/gcp
+  workflow: terraform-strict
+
+workflows:
+  terraform-strict:
+    plan:
+      steps:
+        - run: |
+            echo "Checking if branch is up-to-date with main..."
+            git fetch --unshallow origin main || git fetch origin main
+            git fetch --unshallow origin HEAD || git fetch origin HEAD
+            if ! git merge-base --is-ancestor origin/main HEAD; then
+              echo "❌ Branch is not up-to-date with main. Please rebase or merge main into your branch."
+              echo "Run: git fetch origin && git rebase origin/main"
+              exit 1
+            fi
+            echo "✅ Branch is up-to-date with main"
+        - init
+        - plan
+    apply:
+      steps:
+        - run: |
+            echo "Checking if branch is up-to-date with main..."
+            git fetch --unshallow origin main || git fetch origin main
+            git fetch --unshallow origin HEAD || git fetch origin HEAD
+            if ! git merge-base --is-ancestor origin/main HEAD; then
+              echo "❌ Branch is not up-to-date with main. Please rebase or merge main into your branch."
+              echo "Run: git fetch origin && git rebase origin/main"
+              exit 1
+            fi
+            echo "✅ Branch is up-to-date with main"
+        - init
+        - apply
+```
+
+We plan to eventually support this natively as a flag in digger