ci: Skip merge queue if pull request is up-to-date (#7514)

## Explanation

This adds a new action which determines whether a pull request in the
merge queue is up-to-date, meaning:

- The pull request is based on the latest commit on `main`.
- The pull request is the first in the merge queue.

In this case, all status checks have already passed on the branch, and
running in the merge queue would be redundant, meaning we can skip the
merge queue checks.

To accomplish this, I've added an output to the action (`up-to-date`)
which we can use in all steps in the main workflow to determine if they
should run. If `up-to-date` is `true`, all jobs except `all-jobs-pass`
will be skipped, and the pull request will be merged much quicker.

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

WPC-184

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds a composite action to detect up-to-date PRs in the merge queue
and gates workflow jobs to skip queue checks when eligible.
> 
> - **CI**:
>   - **New composite action** `/.github/actions/check-merge-queue`:
> - Extracts PR number from `head-ref`, queries GraphQL for
`headRefName` and `mergeQueueEntry.position`, and outputs `up-to-date`
when branch is based on latest `base-ref` and queue position is `1`.
>   - **Workflow updates** `/.github/workflows/main.yml`:
> - Adds `check-skip-merge-queue` job (merge_group only) exposing
`skip-merge-queue`.
> - Gates `check-workflows` with conditional `needs`/`if` to skip when
`skip-merge-queue` is `true`.
> - Updates `all-jobs-pass` to depend on `check-skip-merge-queue` and
succeed if either all jobs passed or skipping is allowed via `PASSED`
env.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
ceccfa8. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Mrtenz

.github/actions/check-merge-queue/action.yml

@@ -0,0 +1,91 @@
+name: Check merge queue
+description: Check whether a pull request can skip the merge queue when it's
+  up-to-date with the base branch.
+
+inputs:
+  head-ref:
+    description: The name of the head ref (the pull request branch).
+    required: true
+    default: ${{ github.event.merge_group.head_ref }}
+
+  base-ref:
+    description: The name of the base ref (e.g., main, master).
+    required: true
+    default: main
+
+  github-token:
+    description: The GitHub token to use for authentication.
+    required: true
+    default: ${{ github.token }}
+
+outputs:
+  up-to-date:
+    value: ${{ steps.up-to-date.outputs.up-to-date }}
+    description: Whether the pull request is up-to-date with the base branch
+      and is first in the merge queue, allowing it to skip the merge queue.
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+      with:
+        fetch-depth: 0
+
+    - name: Get pull request details
+      id: pr-details
+      uses: actions/github-script@v8
+      env:
+        HEAD_REF: ${{ inputs.head-ref }}
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const { HEAD_REF } = process.env;
+          const match = HEAD_REF.match(/\/pr-([0-9]+)-/u);
+          if (!match) {
+            return core.setFailed(`Could not extract pull request number from head ref: "${HEAD_REF}".`);
+          }
+
+          const number = parseInt(match[1], 10);
+          const result = await github.graphql(`
+            query($owner: String!, $name: String!, $number: Int!) {
+              repository(owner: $owner, name: $name) {
+                pullRequest(number: $number) {
+                  headRefName
+                  mergeQueueEntry { position }
+                }
+              }
+            }
+          `, {
+            owner: context.repo.owner,
+            name: context.repo.repo,
+            number,
+          });
+
+          if (!result.repository.pullRequest) {
+            return core.setFailed(`Pull request #${number} not found in repository "${context.repo.owner}/${context.repo.repo}".`);
+          }
+
+          const position = result.repository.pullRequest.mergeQueueEntry?.position;
+          if (!position) {
+            return core.setFailed(`Pull request #${number} is not in the merge queue.`);
+          }
+
+          core.setOutput('pr-number', number);
+          core.setOutput('pr-branch', result.repository.pullRequest.headRefName);
+          core.setOutput('merge-queue-position', position);
+
+    - name: Check if pull request is up-to-date with base branch
+      id: up-to-date
+      shell: bash
+      env:
+        BASE_REF: ${{ inputs.base-ref }}
+        PR_BRANCH: ${{ steps.pr-details.outputs.pr-branch }}
+        MERGE_QUEUE_POSITION: ${{ steps.pr-details.outputs.merge-queue-position }}
+      run: |
+        set -euo pipefail
+        if git merge-base --is-ancestor "origin/${BASE_REF}" "origin/${PR_BRANCH}" && [ "${MERGE_QUEUE_POSITION}" -eq 1 ]; then
+          echo "up-to-date=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "up-to-date=false" >> "$GITHUB_OUTPUT"
+        fi

.github/workflows/main.yml

@@ -11,8 +11,29 @@ concurrency:
   cancel-in-progress: ${{ !contains(github.ref, 'refs/heads/main') }}
 
 jobs:
+  check-skip-merge-queue:
+    name: Check if pull request can skip merge queue
+    runs-on: ubuntu-latest
+    outputs:
+      skip-merge-queue: ${{ steps.check-skip-merge-queue.outputs.up-to-date }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        if: github.event_name == 'merge_group'
+      - name: Check pull request merge queue status
+        id: check-skip-merge-queue
+        if: github.event_name == 'merge_group'
+        uses: ./.github/actions/check-merge-queue
+        with:
+          head-ref: ${{ github.event.merge_group.head_ref }}
+          base-ref: main
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
   check-workflows:
     name: Check workflows
+    needs:
+      - check-skip-merge-queue
+    if: github.event_name != 'merge_group' || needs.check-skip-merge-queue.outputs.skip-merge-queue != 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -127,11 +148,14 @@ jobs:
     name: All jobs pass
     if: ${{ always() }}
     runs-on: ubuntu-latest
-    needs: all-jobs-complete
+    needs:
+      - all-jobs-complete
+      - check-skip-merge-queue
+    env:
+      PASSED: ${{ needs.all-jobs-complete.outputs.passed == 'true' || needs.check-skip-merge-queue.outputs.skip-merge-queue == 'true' }}
     steps:
       - name: Check that all jobs have passed
         run: |
-          passed="${{ needs.all-jobs-complete.outputs.passed }}"
-          if [[ $passed != "true" ]]; then
+          if [[ "$PASSED" != "true" ]]; then
             exit 1
           fi