[mrz1836]

What Changed

• Docs (auto-merge-github-app.md): The "dismiss stale approvals on push" requirement now covers both the Dependabot workflow and Auto-merge on Approval, where before it covered only Dependabot. The new text says:
  • Auto-merge on Approval counts only approvals of the PR's current head commit.
  • It revokes its own arming when a push leaves the new head unapproved.
  • Both workflows approve or arm only when a base-branch ruleset requires an approval and voids it on a new push.
  • Without such a ruleset, both end in skip-stale-approvals-kept.
• Docs (anchors and troubleshooting): The section heading is now "Required for auto-merge: dismiss stale approvals on push", and the link anchor is updated to match. The troubleshooting row for skip-stale-approvals-kept now says "analysis or evaluation". The setup checklist now says that without the ruleset, neither workflow auto-merges.
• auto-merge-trigger.yml: Only comments changed. The synchronize comment now explains that approvals count only for the commit they reviewed, so a new head revokes the App's arming until it is approved. The header comment now says both auto-merge workflows only arm when the base branch's rulesets dismiss stale approvals.
• dependabot-auto-merge.yml:
  • The verify step now sets a decision output instead of result, and the job's result output and the summary step's RESULT env read from steps.verify.outputs.decision. Comments explain that actions/github-script overwrites its own result output with the script's return value.
  • The base-branch rules lookup in the "required status checks" guard now uses gh api --paginate with per_page=100, merges the pages with jq -s 'add // []', and falls back to [] if the read fails.
• auto-merge-on-approval.yml: Modified (+70/-23). The diff for this file was trimmed, so no specifics are described here.

Why It Was Necessary

• The previous docs and comments described stale-approval protection as Dependabot-only. Auto-merge on Approval needs the same safeguard, so that code pushed after a review cannot ride an earlier approval.
• actions/github-script overwrites the step's result output once the script returns, so the verification result could be lost. Using a separate decision output avoids that.
• Reading only the first page of branch rules could miss a required-status-checks rule on a later page. Paginating the read closes that gap.

Testing Performed

• No test runs are shown in the diff. The workflow changes would be exercised by the workflows themselves on a real PR.
• Reviewers should check that the verify job's result, reason, pr-number and head-sha outputs still reach the apply job through the renamed decision output.
• Reviewers should also check that the paginated rules call yields a valid JSON array, including when the API call fails and the fallback [] applies.

Impact / Risk

• Behavior change: Repositories without a base-branch ruleset that requires an approval and voids it on push will no longer have Auto-merge on Approval arm. Those repositories end in skip-stale-approvals-kept, and any earlier arming is disarmed.
• Regression risk: The output rename in dependabot-auto-merge.yml must stay consistent between the verify step, the job outputs and the summary step. A missed reference would leave the result empty.
• Low risk elsewhere: The trigger file changes are comments only. The pagination change affects only how the required-checks guard reads rules, and a failed read still falls back to an empty list.