duel 0.1.1 → 0.1.2

data/docs/ci.md

@@ -12,9 +12,10 @@ example, a series of changes that are each 1.5% slower would each pass.
 To catch that kind of slow creep, also compare against your last release
 on a schedule. The slowdowns add up there until they're a regression.
 
-The following GitHub Actions workflow does both, and comments on a pull
-request when a benchmark fails. `duel init` writes it for you, as
-`.github/workflows/perf.yml`:
+The following GitHub Actions workflow does both. `duel init` writes it
+for you, as `.github/workflows/perf.yml`, with a second workflow that
+comments on a pull request when a benchmark fails (see
+[Comment on a pull request](#comment-on-a-pull-request)):
 
 ```yaml
 # .github/workflows/perf.yml
@@ -22,26 +23,39 @@ name: Perf
 
 on:
   pull_request:
+  merge_group: # (a merge queue's)
   push:
-    branches: [main]
+    branches: [main] # (and any other branch to guard, a stable one, say)
   schedule:
     - cron: "0 4 * * *"
   workflow_dispatch:
 
+# A pull request's newer push cancels its run, if that's still going, as
+# only its newest commit's result counts. Every other run (a push's, say)
+# runs to the end, so that each push is compared.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 # The Duel job runs the branch's code (its benchmarks too), so it only
-# reads. Commenting is the Comment job's, which runs none of it.
+# reads. Commenting on a commit is the Comment on the commit job's, which
+# runs none of it, and commenting on a pull request is the Perf comment
+# workflow's.
 permissions:
   contents: read
+  pull-requests: read # for the pull request's labels (see c.accept_label)
 
 jobs:
   duel:
     name: Duel
     runs-on: ubuntu-latest
-    # Whether the Comment job comments (post, change or none), and the
-    # run's status (passed, failed or neutral), from Duel.
+    # Whether to comment (post, change or none), the run's status (passed,
+    # failed or neutral), and whether to mark a push passed (true, or
+    # nothing), from Duel.
     outputs:
       comment: ${{ steps.compare.outputs.comment }}
       status: ${{ steps.compare.outputs.status }}
+      passed: ${{ steps.compare.outputs.passed }}
     steps:
       - uses: actions/checkout@v7
         with:
@@ -52,50 +66,80 @@ jobs:
         with:
           ruby-version: "3.4" # (or none, with a .ruby-version)
           bundler-cache: true
-      # Against the main branch for a pull request, what was there before
-      # for a push, and the last release on a schedule (slow creep). Duel
-      # adds its report to the job's summary, writes it to duel.md for the
-      # comment, and sets the step's outputs to say whether to comment, as
-      # c.comment in .duel.rb says, whatever the outcome.
+      # The labels of the pull request (or for a push, of the one that
+      # merged it), for c.accept_label in .duel.rb, as a JSON array. They're
+      # read as the job runs, so after adding the label, run it again.
+      - name: Find the pull request's labels
+        id: labels
+        if: github.event_name == 'pull_request' || github.event_name == 'merge_group' || github.event_name == 'push'
+        continue-on-error: true # (without them, nothing's accepted)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+          QUEUED: ${{ github.event.merge_group.head_ref }}
+        run: |
+          # (In a merge queue, the last pull request queued, which the queue's
+          # branch names: gh-readonly-queue/main/pr-123-<sha>.)
+          if [ -n "$QUEUED" ]; then
+            PR=${QUEUED##*/pr-}
+            PR=${PR%%-*}
+          fi
+          if [ -n "$PR" ]; then
+            labels=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR/labels" --jq '[.[].name]')
+          else
+            labels=$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/pulls" --jq '[.[0].labels[]?.name]')
+          fi
+          echo "labels=$labels" >> "$GITHUB_OUTPUT"
+      # Against the branch it targets for a pull request, the queue's base
+      # for a merge queue, what was there before for a push (or as
+      # c.push_base in .duel.rb says, the last commit Duel passed), and the
+      # last release on a schedule (slow creep). Duel adds its report to
+      # the job's summary, writes it to duel.md for the comment, and sets
+      # the step's outputs to say whether to comment, as c.comment in
+      # .duel.rb says, whatever the outcome.
       - name: Compare
         id: compare
         env:
-          DUEL_BASE: ${{ github.event_name == 'schedule' && 'last-release' || github.event_name == 'push' && github.event.before || '' }}
+          DUEL_BASE: ${{ github.event_name == 'schedule' && 'last-release' || github.event_name == 'push' && github.event.before || github.event_name == 'merge_group' && github.event.merge_group.base_sha || '' }}
           # (Run by hand, it compares anyway: with nothing changed, the code
           # with itself, which checks the setup.)
           DUEL_FORCE: ${{ github.event_name == 'workflow_dispatch' && '1' || '' }}
+          DUEL_LABELS: ${{ steps.labels.outputs.labels }}
+        run: bundle exec duel --markdown "$RUNNER_TEMP/duel/duel.md"
+      # For a pull request, what Duel said, for the Perf comment workflow,
+      # which can't see this job's outputs.
+      - name: Say whether to comment
+        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          COMMENT: ${{ steps.compare.outputs.comment }}
+          STATUS: ${{ steps.compare.outputs.status }}
         run: |
-          # (A branch's first push, or one that rewrote history, has no
-          # commit before it here to compare against.)
-          if [ "$GITHUB_EVENT_NAME" = push ] && ! git cat-file -e "$DUEL_BASE^{commit}" 2>/dev/null; then
-            echo "::notice::No commit before this push to compare against"
-            exit 0
-          fi
-          bundle exec duel --markdown "$RUNNER_TEMP/duel.md"
-      # The report, for the Comment job.
+          mkdir -p "$RUNNER_TEMP/duel"
+          printf 'pr=%s\ncomment=%s\nstatus=%s\n' "$PR" "$COMMENT" "$STATUS" > "$RUNNER_TEMP/duel/comment.env"
+      # The report, for the comments.
       - name: Keep the report
-        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        if: ${{ !cancelled() && (github.event_name == 'pull_request' || github.event_name == 'push') }}
         uses: actions/upload-artifact@v7
         with:
           name: duel-report
-          path: ${{ runner.temp }}/duel.md
+          path: ${{ runner.temp }}/duel/
           if-no-files-found: ignore # none when Duel didn't get to compare
           retention-days: 1
 
-  # The report, as a new comment on the pull request, when Duel says to:
-  # always (post), or only when its last comment's status differs from
-  # this run's (change), so the latest comment is never stale. It never
-  # edits or deletes a comment. This job checks nothing out and runs none
-  # of the branch's code, so it alone can write. (A pull request from a
-  # fork gets no comment, as its token can't write one: the Duel job's
-  # summary has the report.)
-  comment:
-    name: Comment
+  # The report, as a new comment on a pushed commit, which notifies its
+  # author, when Duel says to, as for a pull request (see the Perf comment
+  # workflow). It does only where a regression in a push passes, with
+  # c.fail_on = :pull_requests in .duel.rb, so the comment says what the
+  # check doesn't. Its last comment is the last one on any commit. This
+  # job checks nothing out and runs none of the code.
+  commit-comment:
+    name: Comment on the commit
     needs: duel
-    if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && (needs.duel.outputs.comment == 'post' || needs.duel.outputs.comment == 'change') }}
+    if: ${{ !cancelled() && github.event_name == 'push' && (needs.duel.outputs.comment == 'post' || needs.duel.outputs.comment == 'change') }}
     runs-on: ubuntu-latest
     permissions:
-      pull-requests: write # to comment on the pull request with the report
+      contents: write # to comment on the commit with the report
     steps:
       - name: Get the report
         id: report
@@ -104,31 +148,66 @@ jobs:
         with:
           name: duel-report
           path: ${{ runner.temp }}/report
-      - name: Comment on the pull request
+      - name: Comment on the commit
         if: steps.report.outcome == 'success'
         env:
           GH_TOKEN: ${{ github.token }}
-          PR: ${{ github.event.pull_request.number }}
           COMMENT: ${{ needs.duel.outputs.comment }}
           STATUS: ${{ needs.duel.outputs.status }}
         run: |
           marker="<!-- duel"
-          # The first line of the last comment Duel posted here: its marker,
-          # with its status (none in Duel 0.1.0's, which counts as another).
-          last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
-            --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\") or . == \"$marker -->\")" | tail -n 1)
+          last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\"))" | tail -n 1)
           if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
             { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
-            gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
+            gh api --method POST "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
           fi
+
+  # With c.push_base = :last_passed in .duel.rb, a push is compared with
+  # the last commit Duel passed, which a branch marks (each branch pushed
+  # has its own), so slowdowns too small for any one push to fail add up
+  # until they fail one. This job moves the branch to a push that passed
+  # (or makes it). It checks nothing out and runs none of the code. To
+  # accept a regression, move the branch yourself (for main, git push
+  # origin main:duel/passed/main).
+  passed:
+    name: Mark the commit passed
+    needs: duel
+    if: ${{ !cancelled() && github.event_name == 'push' && needs.duel.outputs.passed == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to move the branch
+    steps:
+      - name: Move the branch to the commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: duel/passed/${{ github.ref_name }}
+        run: |
+          gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$GITHUB_SHA" -F force=true > /dev/null 2>&1 ||
+            gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$GITHUB_SHA" > /dev/null
 ```
 
+A newer push to a pull request cancels the pull request's run, if it's
+still going, because only the newest commit's result counts. Every other
+run, such as a push's to `main`, runs to the end, so each push is
+compared.
+
 The workflow compares the following:
 
-- A pull request, against the main branch.
-- A push to `main`, against the commit before the push. If that commit
-  isn't in the history, such as after a force push or for a branch's
-  first push, the workflow skips the comparison with a notice.
+- A pull request, against the branch that it targets: usually `main`,
+  but a stable branch, or another pull request's branch in a stack of
+  them, too.
+- A merge queue's group, against the queue's base, the commit that the
+  group merges into. With a merge queue, a required Duel check must run
+  on `merge_group` too, or the queue waits for it forever. A regression
+  fails a merge queue's run as it fails a pull request's, and the run
+  reads the labels of the last pull request queued, for
+  [`c.accept_label`](#accept-a-regression-with-a-label).
+- A push to `main`, against the commit before the push, or with
+  [`c.push_base = :last_passed`](#compare-a-push-with-the-last-commit-that-passed),
+  the last commit that Duel passed. If that commit isn't in the history,
+  such as after a force push or for a branch's first push, Duel reports
+  that there's nothing to compare against, and passes.
 - On a schedule, the last release. Until you tag your first release,
   Duel reports that there's nothing to compare against, and passes.
 - When you run the workflow manually, your code against itself. This
@@ -175,20 +254,368 @@ GitHub Actions, the Compare step's `duel` sets two step outputs, which
 the Duel job passes on as its own: `comment`, and `status` (`passed`,
 `failed`, or `neutral`). `comment` is one of the following:
 
-| `comment` | What the Comment job does |
+| `comment` | What the Perf comment workflow does |
 |---|---|
 | `post` | Posts a new comment. |
 | `change` | Posts a new comment only if the pull request has one from the workflow, and the last one's status isn't this run's. |
-| `none` | Nothing: the Comment job doesn't run. |
+| `none` | Nothing. |
 
 The Duel job runs the pull request's code, its benchmarks included, so
-it only reads (`contents: read`), and it keeps the report as an
-artifact for a day. A job of its own, Comment, posts the report. It
-checks nothing out and runs none of the pull request's code, so it
-alone gets the `pull-requests: write` permission that commenting takes.
-When the Duel job fails before it compares, there's no report, and no
-comment. A pull request from a fork gets no comment either, because its
-token can't write one, but the Duel job's summary still has the report.
+it only reads (`contents: read`). It keeps the report as an artifact
+for a day, with a file, `comment.env`, that says what Duel decided:
+the pull request's number, `comment`, and `status`. A second workflow,
+`.github/workflows/perf-comment.yml`, posts the report. It runs when
+the Perf workflow completes (`workflow_run`), with your repository's
+own copy of the workflow and a token that can write, so a pull request
+from a fork gets a comment too. It checks nothing out and runs none of
+the pull request's code. The pull request's code ran in the Duel job,
+and could have written anything into the artifact, so the workflow
+trusts only what Duel could have said there: a number that names the
+pull request whose head the run compared, and a `comment` and a
+`status` that Duel uses. The report's Markdown is the comment's body,
+which can only say something on the pull request that the pull request
+could say itself. When the Duel job fails before it compares, there's
+no report, and no comment. GitHub runs a `workflow_run` workflow only
+from your default branch, so the pull request that adds the workflow
+gets no comment.
+
+```yaml
+# .github/workflows/perf-comment.yml
+name: Perf comment
+
+# Duel's report, as a new comment on the pull request, when Duel says to:
+# always (post), or only when its last comment's status differs from the
+# run's (change), so the latest comment is never stale. It never edits or
+# deletes a comment. It runs once the Perf workflow has, with this
+# repository's own workflow and a token that can write, so a pull request
+# from a fork gets a comment too. It checks nothing out and runs none of
+# the pull request's code, and of what the Duel job kept (where that code
+# ran), it trusts only what that job could have said: the pull request's
+# number, if it names the pull request the run compared, and the comment
+# and the status, if they're ones Duel says. (The workflow must be on the
+# default branch before it runs at all.)
+on:
+  workflow_run:
+    workflows: ["Perf"]
+    types: [completed]
+
+permissions: {}
+
+jobs:
+  comment:
+    name: Comment
+    if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion != 'cancelled' }}
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read # to get the report from the Perf run
+      pull-requests: write # to comment on the pull request with the report
+    steps:
+      - name: Get the report
+        id: report
+        continue-on-error: true # there's none when the Duel job failed before comparing
+        uses: actions/download-artifact@v8
+        with:
+          name: duel-report
+          path: ${{ runner.temp }}/report
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+      - name: Comment on the pull request
+        if: steps.report.outcome == 'success'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          said() { grep -xE "$1=($2)" "$RUNNER_TEMP/report/comment.env" | tail -n 1 | cut -d= -f2; }
+          PR=$(said pr '[0-9]+')
+          COMMENT=$(said comment 'post|change')
+          STATUS=$(said status 'passed|failed|neutral')
+          [ -n "$PR" ] && [ -n "$COMMENT" ] && [ -n "$STATUS" ] || exit 0
+          [ "$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR" --jq .head.sha)" = "$HEAD_SHA" ] || exit 0
+          marker="<!-- duel"
+          # The first line of the last comment Duel posted here: its marker,
+          # with its status (none in Duel 0.1.0's, which counts as another).
+          last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\") or . == \"$marker -->\")" | tail -n 1)
+          if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
+            { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
+            gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
+          fi
+```
+
+## Comment on a pushed commit
+
+With [`c.fail_on = :pull_requests`](configuration.md#fail-only-a-pull-request),
+a regression in a push to `main` passes, and the workflow's Comment on
+the commit job comments on the pushed commit with the report instead.
+GitHub notifies the commit's author. It comments as `c.comment` says,
+the way the Comment job does on a pull request, but its last comment is
+the workflow's last one on any commit. So with the default, each push
+that fails gets a comment, the first push after them that passes gets
+one, and the passing pushes after it get none.
+
+By default, a push gets no comment: Duel sets the `comment` output to
+`none`, and a regression fails the push's check instead. The Comment on
+the commit job checks nothing out either, and it alone gets the
+`contents: write` permission that a commit comment takes.
+
+## Accept a regression with a label
+
+With [`c.accept_label`](configuration.md#accept-a-regression-with-a-label),
+a pull request with that label passes a regression. The Duel job's Find
+the pull request's labels step reads the labels of the pull request,
+or for a push, of the pull request that merged it, and passes them to
+`duel` as a JSON array, in `DUEL_LABELS`. That takes the
+`pull-requests: read` permission. Without the labels, such as when
+GitHub's API fails, nothing is accepted.
+
+## Compare a push with the last commit that passed
+
+By default, the workflow compares each push with the commit before it.
+A series of pushes that are each a little slower each pass, and a push
+that the workflow doesn't compare, such as one whose run was cancelled,
+is never compared. With
+[`c.push_base = :last_passed`](configuration.md#compare-a-push-with-the-last-commit-that-passed),
+the workflow compares each push with the last commit that Duel passed,
+so the slowdowns add up until they fail a push.
+
+A branch, `duel/passed/main` for `main`, marks that commit. Each
+branch that the workflow guards has its own (see
+[Guard other branches](#guard-other-branches)). When a push passes, or has
+nothing to compare, Duel sets the `passed` output to `true`, and the
+Mark the commit passed job moves the branch to the push, or creates the
+branch. That job checks nothing out either, and it gets the
+`contents: write` permission that moving a branch takes. Until the
+branch exists, and when the push's history doesn't have its commit,
+Duel compares the push with the commit before it. For a project in a
+subdirectory of its repository, the branch names the directory, such as
+`duel/passed-gems-parser/main`.
+
+After a regression, the branch stays where it is, so every push fails
+(or with [`c.fail_on = :pull_requests`](#comment-on-a-pushed-commit),
+is reported) until one is no slower. To accept a regression, move the
+branch yourself:
+
+```sh
+git push origin main:duel/passed/main
+```
+
+If you set `c.push_base` back to `:before`, delete the branches too
+(`git push origin --delete duel/passed/main`), because the step that
+finds the baseline's Ruby uses one whenever it exists.
+
+## Guard other branches
+
+The workflow compares the pushes to `main`. To guard another branch,
+such as a stable branch that gets backports, add it to the workflow's
+`push` branches:
+
+```yaml
+  push:
+    branches: [main, 2-x-stable]
+```
+
+Duel compares a push to each branch with the commit before it, or with
+`c.push_base = :last_passed`, with the last commit that Duel passed on
+that branch, which a branch of its own marks: `duel/passed/2-x-stable`.
+A pull request into the branch is compared with the branch, whatever
+the workflow guards.
+
+## Run Duel on GitLab CI
+
+`duel init --gitlab` writes GitLab CI jobs, in
+`.gitlab/duel.gitlab-ci.yml`, instead of the GitHub Actions workflows.
+Include them from your `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: .gitlab/duel.gitlab-ci.yml
+```
+
+The Duel job compares a merge request with the branch that it targets,
+a push to your default branch with the commit before it (or with
+[`c.push_base = :last_passed`](#compare-a-push-with-the-last-commit-that-passed),
+the last commit that Duel passed), and on a schedule, your last
+release. It runs on the `ruby` image of the version that your
+`.ruby-version` names, or else of your Ruby. On GitLab, a branch that
+upgrades Ruby can't compare each version on its own Ruby, because the
+image has only one. Duel reads GitLab's variables: a merge request's
+target, and its labels, for
+[`c.accept_label`](configuration.md#accept-a-regression-with-a-label).
+A push's labels aren't available.
+
+With [`c.fail_on = :pull_requests`](configuration.md#fail-only-a-pull-request),
+a regression outside a merge request makes `duel` exit with status 3,
+and the job lets that fail (`allow_failure: exit_codes: [3]`), so the
+pipeline shows a warning, not a failure.
+
+The Duel job writes what it decided to a dotenv report (`DUEL_OUTPUT`):
+`DUEL_COMMENT`, `DUEL_STATUS`, and `DUEL_PASSED`. The jobs after it act
+on them. They check nothing out and run none of the code. GitLab's own
+job token can't comment, so they need project access tokens, in masked
+CI/CD variables. Without them, the jobs don't run, and the Duel job's
+log and its `duel.md` artifact have the report.
+
+- `DUEL_COMMENT_TOKEN`, with the Reporter role and the `api` scope, and
+  not protected, so a merge request's pipeline has it, to comment on a
+  merge request. Every job in that pipeline has it, the Duel job too,
+  which runs the merge request's code, so give it no more than the
+  Reporter role.
+- `DUEL_TOKEN`, with the Developer role and the `api` scope, and
+  protected, so only your protected branches' pipelines have it, to
+  comment on a pushed commit and to mark a push passed.
+
+The comment on a pushed commit looks only at the comments on the commit
+before it for its last status. A merge request from a fork runs its
+pipeline in the fork, without your variables, so it gets no comment.
+
+```yaml
+# .gitlab/duel.gitlab-ci.yml
+# Duel on GitLab CI: https://github.com/sferik/duel-ruby/blob/main/docs/ci.md#run-duel-on-gitlab-ci
+#
+# Include it from .gitlab-ci.yml:
+#
+#   include:
+#     - local: .gitlab/duel.gitlab-ci.yml
+#
+# It compares a merge request with the branch it targets, a push to the
+# default branch with the commit before it (or as c.push_base in .duel.rb
+# says, the last commit Duel passed), and on a schedule, the last release.
+# The Duel job's log, and its duel.md artifact, have the report. Comments
+# need project access tokens, in masked CI/CD variables:
+#
+# - DUEL_COMMENT_TOKEN (the Reporter role, with the api scope, and not
+#   protected), to comment on a merge request. Every job of a merge
+#   request's pipeline has it, the Duel job too, which runs the merge
+#   request's code, so the token can do no more than comment.
+# - DUEL_TOKEN (the Developer role, with the api scope, and protected, so
+#   only the default branch's pipelines have it), to comment on a pushed
+#   commit (see c.fail_on), and to mark a push passed (see c.push_base).
+
+duel:
+  image: ruby:3.4
+  stage: test
+  variables:
+    GIT_DEPTH: 0 # the baseline comes from history, tags included
+    DUEL_OUTPUT: duel.env # whether to comment, and mark a push passed
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      variables:
+        DUEL_BASE: $CI_COMMIT_BEFORE_SHA
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+      variables:
+        DUEL_BASE: last-release
+    # (Run by hand, it compares anyway: with nothing changed, the code
+    # with itself, which checks the setup.)
+    - if: $CI_PIPELINE_SOURCE == "web"
+      variables:
+        DUEL_FORCE: "1"
+  # A regression outside a merge request, where only a merge request
+  # fails (c.fail_on in .duel.rb), exits 3: a warning.
+  allow_failure:
+    exit_codes: [3]
+  before_script:
+    # The branch a merge request targets, the last commits Duel passed,
+    # and the releases.
+    - git fetch --quiet --tags origin "+refs/heads/duel/*:refs/remotes/origin/duel/*"
+    - if [ -n "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" ]; then git fetch --quiet origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"; fi
+    - bundle install
+  script:
+    - bundle exec duel --markdown duel.md
+  artifacts:
+    when: always
+    paths:
+      - duel.md
+    reports:
+      dotenv: duel.env
+    expire_in: 1 day
+
+# The report, as a new comment on the merge request, when Duel says to:
+# always (post), or only when its last comment's status differs from this
+# run's (change), so the latest comment is never stale. It never edits or
+# deletes a comment.
+duel:comment:
+  image: alpine:3
+  stage: .post
+  needs: [duel]
+  rules:
+    - if: $DUEL_COMMENT_TOKEN && $CI_PIPELINE_SOURCE == "merge_request_event"
+      when: always
+  variables:
+    GIT_STRATEGY: none # it runs none of the code
+  script:
+    - apk add --no-cache --quiet curl jq
+    - |
+      case "$DUEL_COMMENT" in post|change) ;; *) exit 0 ;; esac
+      report=duel.md
+      [ -f "$report" ] || exit 0
+      api="$CI_API_V4_URL/projects/$CI_PROJECT_ID"
+      token="PRIVATE-TOKEN: $DUEL_COMMENT_TOKEN"
+      marker="<!-- duel"
+      me=$(curl -sf -H "$token" "$CI_API_V4_URL/user" | jq .id)
+      # The first line of the last comment Duel posted here: its marker,
+      # with its status.
+      last=$(curl -sf -H "$token" "$api/merge_requests/$CI_MERGE_REQUEST_IID/notes?sort=desc&order_by=created_at&per_page=100" |
+        jq -r --argjson me "$me" --arg marker "$marker status=" '.[] | select(.author.id == $me) | .body | split("\n")[0] | rtrimstr("\r") | select(startswith($marker))' | head -n 1)
+      if [ "$DUEL_COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$DUEL_STATUS -->" ]; }; then
+        { echo "$marker status=$DUEL_STATUS -->"; cat "$report"; } | jq -Rs '{body: .}' |
+          curl -sf -H "$token" -H "Content-Type: application/json" --data @- "$api/merge_requests/$CI_MERGE_REQUEST_IID/notes" > /dev/null
+      fi
+
+# The report, as a new comment on a pushed commit, when Duel says to, as
+# for a merge request: only where a regression in a push passes (see
+# c.fail_on), so the comment says what the check doesn't. Its last comment
+# is the commit before's.
+duel:commit-comment:
+  image: alpine:3
+  stage: .post
+  needs: [duel]
+  rules:
+    - if: $DUEL_TOKEN && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      when: always
+  variables:
+    GIT_STRATEGY: none # it runs none of the code
+  script:
+    - apk add --no-cache --quiet curl jq
+    - |
+      case "$DUEL_COMMENT" in post|change) ;; *) exit 0 ;; esac
+      report=duel.md
+      [ -f "$report" ] || exit 0
+      api="$CI_API_V4_URL/projects/$CI_PROJECT_ID"
+      token="PRIVATE-TOKEN: $DUEL_TOKEN"
+      marker="<!-- duel"
+      me=$(curl -sf -H "$token" "$CI_API_V4_URL/user" | jq .id)
+      last=$(curl -sf -H "$token" "$api/repository/commits/$CI_COMMIT_BEFORE_SHA/comments?per_page=100" |
+        jq -r --argjson me "$me" --arg marker "$marker status=" '.[] | select(.author.id == $me) | .note | split("\n")[0] | rtrimstr("\r") | select(startswith($marker))' | tail -n 1)
+      if [ "$DUEL_COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$DUEL_STATUS -->" ]; }; then
+        { echo "$marker status=$DUEL_STATUS -->"; cat "$report"; } | jq -Rs '{note: .}' |
+          curl -sf -H "$token" -H "Content-Type: application/json" --data @- "$api/repository/commits/$CI_COMMIT_SHA/comments" > /dev/null
+      fi
+
+# With c.push_base = :last_passed in .duel.rb, a push is compared with the
+# last commit Duel passed, which a branch marks (duel/passed/main for
+# main), so slowdowns too small for any one push to fail add up until they
+# fail one. This job moves the branch to a push that passed (or makes it).
+# To accept a regression, move the branch yourself (for main, git push
+# origin main:duel/passed/main).
+duel:passed:
+  image: alpine:3
+  stage: .post
+  needs: [duel]
+  rules:
+    - if: $DUEL_TOKEN && $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  variables:
+    GIT_STRATEGY: none # it runs none of the code
+  script:
+    - apk add --no-cache --quiet curl
+    - |
+      [ "$DUEL_PASSED" = true ] || exit 0
+      api="$CI_API_V4_URL/projects/$CI_PROJECT_ID"
+      token="PRIVATE-TOKEN: $DUEL_TOKEN"
+      branch="duel/passed/$CI_COMMIT_BRANCH"
+      curl -s -o /dev/null -H "$token" -X DELETE "$api/repository/branches/$(echo "$branch" | sed 's|/|%2F|g')"
+      curl -sf -o /dev/null -H "$token" --data-urlencode "branch=$branch" --data-urlencode "ref=$CI_COMMIT_SHA" "$api/repository/branches"
+```
 
 ## Run each version on its own Ruby on CI
 
@@ -222,20 +649,27 @@ match. `duel init` adds these steps for a project that has a
       # .duel.rb). When the baseline's names another Ruby than this code's,
       # that one is installed too, and linked where Duel finds it (as
       # chruby would), before the project's own Ruby, which runs Duel. The
-      # baseline is the Compare step's: where HEAD left the main branch
-      # (for a pull request, and run by hand), the commit before a push, or
-      # on a schedule the last release, the newest tag before HEAD that
-      # RELEASE_TAGS matches. (If .duel.rb sets c.main_branch or
-      # c.release_tags, set MAIN_BRANCH or RELEASE_TAGS to match.)
+      # baseline is the Compare step's: where HEAD left the branch a pull
+      # request targets (or run by hand, the main branch), a merge queue's
+      # base, the commit before a push (or the last commit Duel passed, PASSED, if there is
+      # one: see the Mark the commit passed job), or on a schedule the last
+      # release, the newest tag before HEAD that RELEASE_TAGS matches. (If
+      # .duel.rb sets c.main_branch or c.release_tags, set MAIN_BRANCH or
+      # RELEASE_TAGS to match.)
       - name: Find the baseline's Ruby
         id: baseline
         env:
           BEFORE: ${{ github.event.before }}
-          MAIN_BRANCH: origin/${{ github.event.repository.default_branch }}
+          QUEUE_BASE: ${{ github.event.merge_group.base_sha }}
+          PASSED: origin/duel/passed/${{ github.ref_name }}
+          MAIN_BRANCH: origin/${{ github.base_ref || github.event.repository.default_branch }}
           RELEASE_TAGS: "v*"
         run: |
           case "$GITHUB_EVENT_NAME" in
-            push) base=$BEFORE ;;
+            push)
+              base=$BEFORE
+              if git merge-base --is-ancestor "$PASSED" HEAD 2>/dev/null; then base=$PASSED; fi ;;
+            merge_group) base=$QUEUE_BASE ;;
             schedule) base=$(git describe --tags --abbrev=0 --match "$RELEASE_TAGS" HEAD^ 2>/dev/null) || base= ;;
             *) base=$(git merge-base HEAD "$MAIN_BRANCH" 2>/dev/null) || base= ;;
           esac