From a35f441cbff92e13fc414a06d854e273af098aa3 Mon Sep 17 00:00:00 2001
From: Nils Lehnen <30603423+iderex@users.noreply.github.com>
Date: Wed, 2 Sep 2026 12:07:03 +0200
Subject: [PATCH] Say what a pulled lever leaves on the commit the branch was
 at (#90)

The header of `.github/workflows/branch-health-lever.yml` says how to take the
reading and what the lever costs the registry, and it did not say what a run of
it leaves behind. A check-run is reported against whatever commit the default
branch pointed at when the workflow was dispatched, and one is not replaced by a
later run of the same name, so the pull that asks for `failure` marks that commit
permanently and the pull that asks for `success` adds a second check-run beside
the first rather than clearing it.

That was found by reading the merge commit this workflow landed on after both
pulls, and the commit carries both conclusions under one name.

The failure it prevents is somebody pulling the lever while the default branch is
at a commit they care about. The report itself reads each workflow's run listing
and takes the newest conclusion, so it saw the recovery and its verdict is
unaffected; anything that asks a COMMIT for its check-runs and treats a failure
among them as the verdict reads it the other way, which is how a merge button and
most dashboards read one. The paragraph names both readings rather than leaving
the second to be discovered.

Nothing else changes. The workflow's triggers, its input, its default and its
step are untouched, and no run was taken for this change.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
---
 .github/workflows/branch-health-lever.yml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/.github/workflows/branch-health-lever.yml b/.github/workflows/branch-health-lever.yml
index 882b603..bb9e092 100644
--- a/.github/workflows/branch-health-lever.yml
+++ b/.github/workflows/branch-health-lever.yml
@@ -47,6 +47,25 @@
 # which names this workflow as recovered and opens nothing. The issue stays open
 # until a person closes it, because the report does not close what it opened.
 #
+# WHAT A PULL LEAVES BEHIND, WHICH IS NOT THE CONCLUSION IT WAS ASKED FOR. A run
+# of this workflow reports a check-run against whatever commit the default branch
+# pointed at when it was dispatched, and a check-run is not replaced by a later
+# one of the same name. So a pull for `failure` stamps that commit permanently,
+# and the second pull for `success` adds a second check-run beside the first
+# rather than clearing it. Measured on the commit this file landed on:
+#
+#     H=f13c5e341b8d4d3e5eeaf8d2309bef973ea42adc
+#     gh api "repos/Flowfin/core/commits/$H/check-runs?per_page=100" --jq '.check_runs[] | select(.name=="branch-health-lever") | "\(.conclusion) \(.started_at)"'
+#     success 2026-09-02T09:57:46Z
+#     failure 2026-09-02T09:54:16Z
+#
+# The report is unaffected, and that is a fact about the report rather than a
+# reason the stamp does not matter: it reads each workflow's run listing and
+# takes the newest conclusion, so it saw the recovery. What does read badly is
+# anything that asks a commit for its check-runs and treats any failure among
+# them as the verdict, which is how a merge button and most dashboards read one.
+# Pull this when the branch is at a commit you are willing to leave marked.
+
 # NO TOOLCHAIN IS INSTALLED AND NOTHING IS CHECKED OUT. The conclusion is the
 # whole product of this run, so it reads neither the tree nor the platform.
 name: branch-health-lever