queue.yml

name: Queue

# GitHub's merge queue tests each picked PR on top of main, one at a time, on
# the host's self-hosted runner, and merges exactly the tree it tested. When the
# queue drops a PR, moq-dev/quest's queue watcher on the host runs the land
# fixer and re-enqueues it at the back of the queue.
#
# `main`'s ruleset requires this job's `Queue` context. GitHub admits a PR to
# the queue only once its required checks pass on the PR itself, so the job
# also runs, as skipped, on main pull requests; a skipped job satisfies the
# requirement. Only the merge group build runs code, and only a maintainer's
# pick enters the queue.
#
# A repository without GitHub's merge queue, such as a private one on GitHub
# Team, lands through the watcher's own queue instead. Its base keeps requiring
# the unreported `quest land` context, and its queue workflow, under any name,
# also builds the watcher's queue branches:
#
#   push:
#     branches: ["quest-queue/**"]
#
# The watcher pushes `quest-queue/<base>/<number>`, the base merged into PR
# <number>'s picked head: a merge commit whose second parent (`HEAD^2`) is the
# base it tested. The build runs as for a merge group, and the base's required
# checks besides `quest land`, reported on that commit, decide whether the PR
# lands, so the required job reports the build's result there.
on:
  pull_request:
    branches: [main]
    # `edited` covers a PR retargeted to main, which needs the context too.
    types: [opened, synchronize, reopened, edited]
  merge_group:
    types: [checks_requested]
  # Reports the skipped context on a PR's head without a pull_request event.
  # A PR whose test merge commit predates this workflow gets no pull_request
  # run from it (GitHub runs PR workflows from that commit, and a dispatch reads
  # the workflow from the ref it runs on), so
  # `gh workflow run queue.yml -f sha=<head>` on main reports it there.
  workflow_dispatch:
    inputs:
      sha:
        description: The PR head commit to report the skipped Queue context on.
        required: true

permissions:
  contents: read
  pull-requests: read

# No concurrency group. A pull request's `Queue` job waits on `build` before it
# skips, so cancelling the run then, as a second event for the PR would,
# reports `Queue` cancelled and fails the requirement; even a group without
# cancel-in-progress cancels a pending run. Each merge group has its own ref, so
# its run never had another to replace, and a repeated dispatch only reports the
# same skipped context twice.

jobs:
  # The build runs in queue-build.yml so its runner group can admit that
  # workflow alone; see that file. It calls main's copy, not the merge group's,
  # since the group admits that workflow only at refs/heads/main: a PR's edit to
  # queue-build.yml runs only after it lands.
  build:
    name: Queue build
    if: github.event_name == 'merge_group'
    uses: moq-dev/quest/.github/workflows/queue-build.yml@main

  # The required context. A reusable workflow's jobs report as
  # `Queue build / Build`, so this job reports the build's result under the
  # name main's ruleset requires. It skips with the build on pull requests, and
  # runs even when the build fails or is cancelled, since a skipped context
  # would pass the group.
  queue:
    name: Queue
    needs: build
    if: always() && github.event_name == 'merge_group'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Require the build to pass
        env:
          RESULT: ${{ needs.build.result }}
        run: '[[ "$RESULT" == success ]] || { echo "::error::the queue build ended $RESULT" >&2; exit 1; }'

  # The merge queue still builds every group with the jobs above; this only
  # satisfies the PR-side requirement, as a pull_request run's skipped job does.
  report:
    name: Report Queue
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      checks: write
    steps:
      - name: Report the skipped Queue context
        env:
          GH_TOKEN: ${{ github.token }}
          REPO: ${{ github.repository }}
          SHA: ${{ inputs.sha }}
        run: |
          [[ "$SHA" =~ ^[0-9a-f]{40}$ ]] || { echo "::error::sha must be a full commit SHA" >&2; exit 1; }
          gh api "repos/$REPO/check-runs" -f name=Queue -f head_sha="$SHA" -f status=completed -f conclusion=skipped \
            -f 'output[title]=Queue' -f 'output[summary]=Skipped on the pull request; the merge queue builds the group.' --silent