From a1f9aa2eca72b78661acc53cc02cc6c73aa01b31 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Wed, 19 Aug 2026 22:22:39 -0700 Subject: [PATCH 1/3] feat(linear-ticket): rename the status context to "Linear ticket" and drop the slug from its description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GitHub renders the commit-status context verbatim as the check's name in the PR's check list, so `linear-ticket` put a machine slug where a reader expects prose: x linear-ticket — Warn-only: no linked Linear issue (no_candidate) x Linear ticket — Warn-only: no linked Linear issue The category slug leaves the one-liner too. It stays in the marker comment and job summary, which is where triage happens; beside the check name it is noise, and for infra_error it was the second slug in a line that already had one. TIMING IS THE WHOLE POINT. The context is the exact string a consumer lists in its ruleset's required checks, so a rename is free only while no caller requires it — after that it silently retires the required check (the new context is never satisfied, the old one is never reported again) and merges hang pending. Checked all three callers before doing it (repos unnamed — they are private and this repo is public; see vars.LINEAR_TICKET_CALLERS): four rulesets across the three, and none of them lists either context. This is the last cheap moment. A test now pins CONTEXT so a future rename fails loudly and forces that same audit, and pins MARKER as independent of it — the comment marker is not the context, and "tidying" it to match would make the gate stop finding its own comment and start duplicating it. Docs carry a migration note: update the ruleset in the same change if you already required the old context, and expect a stale red `linear-ticket` beside the new status on already-validated open PRs until they take a new commit. The job-vs-status gotcha is now a table, because `Linear ticket` and `Linear Ticket / validate` differ only by case and a suffix in the ruleset's check picker. docs/callers/README.md deliberately untouched: its three `linear-ticket` mentions name the reusable workflow, not the status context. --- .github/workflows/linear-ticket.yml | 10 +++--- README.md | 2 +- docs/callers/linear-ticket.md | 48 ++++++++++++++++++------- scripts/linear-ticket/README.md | 4 +-- scripts/linear-ticket/lib.py | 23 +++++++----- scripts/linear-ticket/tests/test_lib.py | 43 ++++++++++++++++++---- scripts/linear-ticket/validate.py | 8 ++--- 7 files changed, 99 insertions(+), 39 deletions(-) diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index 75cb2903..65bfecca 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -15,11 +15,11 @@ name: Linear Ticket (reusable) # * every PR-derived value (branch, title, body, labels, URL) is untrusted DATA, passed # through env / GraphQL variables, never shell-interpolated. # The job runs on the DEFAULT branch, so its job-level check must NOT be the required merge -# check. Instead validate.sh publishes the `linear-ticket` commit status on the refetched PR +# check. Instead validate.sh publishes the `Linear ticket` commit status on the refetched PR # head SHA; branch protection requires THAT context. See docs/callers/linear-ticket.md. # # REPORTING MODES — how loudly a failure is reported. This workflow NEVER decides whether a PR -# can merge; branch protection does, by requiring the `linear-ticket` context or not: +# can merge; branch protection does, by requiring the `Linear ticket` context or not: # enforce: true red status, job exits nonzero. Gating (once required). # enforce: false red status, job stays green on a failing VERDICT (a # (soft-fail: true, the default) broken run still exits nonzero). Shows on the PR exactly @@ -34,7 +34,7 @@ name: Linear Ticket (reusable) # actions: read # read the triggering workflow_run # contents: read # checkout THIS repo's scripts (no PR code is ever checked out) # pull-requests: write # the one marker diagnostic comment -# statuses: write # publish the `linear-ticket` commit status +# statuses: write # publish the `Linear ticket` commit status # # SECRET: LINEAR_API_TOKEN (required). Store the value exactly as it goes into Linear's # Authorization header — a personal API key raw, an OAuth actor-auth access token prefixed @@ -102,7 +102,7 @@ on: description: >- Warn-only only (ignored when `enforce: true`). true (default) publishes a red `failure` commit status so the PR's check list shows the check failing — loud, but - NON-BLOCKING for as long as `linear-ticket` is not a required status in the repo's + NON-BLOCKING for as long as `Linear ticket` is not a required status in the repo's branch protection, which is exactly what a warn-only pilot means. The marker comment says so. false restores the silent variant: warn-only publishes `success` and only the job summary and comment carry the verdict. @@ -110,7 +110,7 @@ on: warn-only always published `success`, so taking a SHA bump past this commit flips those callers to a red (still non-required) status with no caller-side edit. Set `soft-fail: false` in the caller to keep the old always-green behaviour. - FOOTGUN: `enforce: false` + `soft-fail: true` + `linear-ticket` already required in + FOOTGUN: `enforce: false` + `soft-fail: true` + `Linear ticket` already required in branch protection WOULD block merges. Do not require the context before flipping `enforce: true`. type: boolean diff --git a/README.md b/README.md index 669395e3..6f659b80 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ complete, copy-pasteable caller. | Workflow | Purpose | Setup | |---|---|---| | [`detect-unreviewed-merge.yml`](.github/workflows/detect-unreviewed-merge.yml) | SOC 2 compliance — detects PRs merged without prior approval and opens a tracking issue in [`Comfy-Org/unreviewed-merges`](https://github.com/Comfy-Org/unreviewed-merges). | [detect-unreviewed-merge.md](docs/callers/detect-unreviewed-merge.md) | -| [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR** before it can merge — not a `TEAM-123`-shaped string in author text. The only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) — they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`linear-ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA before every terminal write so a superseded run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only — a failing verdict never exits the job nonzero (a broken run still does), and by default (`soft-fail: true`) it still publishes the **red** status so the pilot is visible on the PR while blocking nothing, since blocking is branch protection requiring the context, not this workflow's call (`soft-fail: false` restores the silent always-green variant); one `exempt-label` (e.g. `linear-exempt`) waives it per-PR, and an opt-in `exempt-actors` list (empty by default) skips bot PRs (e.g. `dependabot[bot]`) with no built-in bypass. Logic + hermetic tests live in [`scripts/linear-ticket/`](scripts/linear-ticket); `workflows_ref` is **required**, shape- and ancestry-checked before checkout. Requires `LINEAR_API_TOKEN` + the two-workflow caller. | [linear-ticket.md](docs/callers/linear-ticket.md) | +| [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR** before it can merge — not a `TEAM-123`-shaped string in author text. The only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) — they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`Linear ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA before every terminal write so a superseded run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only — a failing verdict never exits the job nonzero (a broken run still does), and by default (`soft-fail: true`) it still publishes the **red** status so the pilot is visible on the PR while blocking nothing, since blocking is branch protection requiring the context, not this workflow's call (`soft-fail: false` restores the silent always-green variant); one `exempt-label` (e.g. `linear-exempt`) waives it per-PR, and an opt-in `exempt-actors` list (empty by default) skips bot PRs (e.g. `dependabot[bot]`) with no built-in bypass. Logic + hermetic tests live in [`scripts/linear-ticket/`](scripts/linear-ticket); `workflows_ref` is **required**, shape- and ancestry-checked before checkout. Requires `LINEAR_API_TOKEN` + the two-workflow caller. | [linear-ticket.md](docs/callers/linear-ticket.md) | | [`cursor-review.yml`](.github/workflows/cursor-review.yml) | Label-triggered multi-model code review. A 4-lab × 2-review-type cursor-agent panel runs adversarial + edge-case passes, a judge model consolidates them into one PR review with per-finding severity badges, and the triggerer gets Slack start/complete DMs. Advisory: it posts a review, it does not gate — there is **no `blocking` input** (it shipped in #16 and was deleted by #31; see [the setup guide](docs/callers/cursor-review.md)). Prompts and scripts live in [`.github/cursor-review/`](.github/cursor-review) — the single source of truth, so consumer repos carry only a thin caller. Generated code is excluded from BOTH the diff-size gate and the diff sent to the panel via the shared [`check-pr-size`](scripts/check-pr-size) classifier (base-ref `linguist-generated`, base-blob Go generated markers — a PR cannot self-exempt a file from review, lockfiles, plus `extra_generated_globs` / `extra_lockfiles`) — the same detection as `pr-size.yml`, so codegen never blows the review cap or wastes review signal. Blank and comment-only lines are also discounted from the size count by default (`ignore_comments`) so AI comment volume doesn't trip the cap and skip the review — comments still reach the panel, only the count ignores them. The runner and the panel model list are fixed by the reusable — there are no `runs_on` / `models` inputs (`models` is a job *output*). Requires `CURSOR_API_KEY` (+ optional `SLACK_BOT_TOKEN`). | [cursor-review.md](docs/callers/cursor-review.md) | | [`cursor-review-auto-label.yml`](.github/workflows/cursor-review-auto-label.yml) | Companion to `cursor-review.yml`. On PR assignment, applies the review label for an opted-in reviewer (via the CLOUD_CODE_BOT app token, so the label actually triggers the review). The opt-in roster lives in the caller's `vars.CURSOR_REVIEW_OPTED_IN_LOGINS` — no roster is baked into the workflow. Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`. | [cursor-review-auto-label.md](docs/callers/cursor-review-auto-label.md) | | [`assign-reviewers.yml`](.github/workflows/assign-reviewers.yml) | Auto-requests expertise-aware, load-balanced PR reviewers with new-folk randomization. Matches changed paths against a caller-repo `.github/reviewers.yml` (path-glob → reviewers, plus a `default_pool`), drops the author + `vars.REVIEWER_EXCLUDE`, ranks candidates by open review load (steering off anyone at/over `vars.REVIEWER_LOAD_CAP`), and may swap a slot for a `vars.REVIEWER_GROWTH_POOL` member. Requests go through the CLOUD_CODE_BOT app token so they work on fork PRs. Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`. | [assign-reviewers.md](docs/callers/assign-reviewers.md) | diff --git a/docs/callers/linear-ticket.md b/docs/callers/linear-ticket.md index 9c47bd79..eb754d8c 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -26,9 +26,23 @@ Dependabot PR runs. The fix is the standard **`pull_request` → `workflow_run`* and calls this reusable, which GitHub grants the secret and a write token even for a fork PR. The validate job runs on your **default branch**, so its job-level check is *not* the thing you -require in branch protection. This reusable publishes a commit status named **`linear-ticket`** +require in branch protection. This reusable publishes a commit status named **`Linear ticket`** on the PR head SHA; you require **that context** once warn-only observation is done. +> [!IMPORTANT] +> **The context was renamed from `linear-ticket` to `Linear ticket`.** GitHub renders it verbatim +> as the check's name, so it is prose now rather than a slug. Two consequences when you bump past +> that pin: +> +> - **If your ruleset already requires `linear-ticket`, update it in the same change.** The old +> context is never reported again, so a required check nobody publishes leaves every PR +> pending — which blocks merges exactly as a failure would. (No caller required it at the time +> of the rename, which is why it was done then.) +> - **Open PRs keep the old status too.** Commit statuses are per-context and append-only, so a PR +> whose head was already validated shows a stale red `linear-ticket` beside the new +> `Linear ticket` until it gets a new commit. Nothing consumes the stale one; it ages out with +> the head SHA. + ## Prerequisites | | | @@ -78,7 +92,7 @@ jobs: actions: read # read the triggering workflow_run contents: read # checkout the validator scripts; PR code is never checked out pull-requests: write # the one marker diagnostic comment - statuses: write # publish the `linear-ticket` commit status + statuses: write # publish the `Linear ticket` commit status uses: Comfy-Org/github-workflows/.github/workflows/linear-ticket.yml@ # v1 with: workflows_ref: @@ -125,20 +139,20 @@ job-level detail. | `exempt-actors` | `''` | Comma-separated PR-author logins whose PRs skip the check without a label (e.g. `dependabot[bot],renovate[bot]`) — the non-manual hatch for bot PRs that never carry a ticket. Opt-in; empty means no bypass. Listing an actor means **all** of its PRs merge without a Linear ticket, so keep it to trusted automation accounts. | | `require-open-issue` | `true` | Reject a linked issue whose Linear `state.type` is `completed`/`canceled`. `backlog`/`unstarted`/`started`/`triage` pass. | | `enforce` | `true` | `false` is warn-only: a failing **verdict** never exits the job nonzero. `soft-fail` decides how loudly it is reported; the diagnosis is identical either way. Warn-only is not a promise the job always exits `0` — a broken *run* still does (a failed terminal status write, a missing token/repo, malformed `team-keys`, a non-`pull_request` trigger). | -| `soft-fail` | `true` | Warn-only only (ignored when `enforce: true`). `true` publishes a **red `failure`** status, so the PR's check list shows the check failing — loud, but non-blocking for as long as `linear-ticket` is not a required status in your ruleset. `false` restores the silent variant (warn-only publishes `success`; only the summary and comment carry the verdict). **Do not** require the `linear-ticket` context while `enforce: false` — required + soft-fail would block merges. | +| `soft-fail` | `true` | Warn-only only (ignored when `enforce: true`). `true` publishes a **red `failure`** status, so the PR's check list shows the check failing — loud, but non-blocking for as long as `Linear ticket` is not a required status in your ruleset. `false` restores the silent variant (warn-only publishes `success`; only the summary and comment carry the verdict). **Do not** require the `Linear ticket` context while `enforce: false` — required + soft-fail would block merges. | ## Upgrading an existing `enforce: false` caller `soft-fail` is new, and it defaults to `true`. **If your caller already runs `enforce: false`, taking a SHA bump past the commit that added this input changes what your PRs show:** warn-only -used to publish a green `linear-ticket` status in every outcome, and now publishes a **red** +used to publish a green `Linear ticket` status in every outcome, and now publishes a **red** one. Nothing about *blocking* changes — a status only blocks when your ruleset requires that context — but the PR check list goes from green to red, and anything you have keyed off the status (auto-merge bots, dashboards, other automation) sees `failure` where it saw `success`. Two things to do before you take the bump: -1. **Check your ruleset.** If `linear-ticket` is already a required check while you are still on +1. **Check your ruleset.** If `Linear ticket` is already a required check while you are still on `enforce: false`, the red status *will* block merges. That combination was always a misconfiguration (rollout step 6 is the last step for a reason), but soft-fail is what makes it bite. Remove the required check, or flip `enforce: true` — do not sit in between. @@ -157,18 +171,18 @@ skewed apart, so an older `linear-ticket.yml` is running newer scripts — is tr ## Rollout (warn-only first) -1. Land both caller files with `enforce: false`, and **leave `linear-ticket` out of your +1. Land both caller files with `enforce: false`, and **leave `Linear ticket` out of your ruleset's required checks** — that omission, not the input, is what keeps the pilot non-blocking. Observe for ~a week: attachment latency, URL matching, retry counts, team/state outcomes, fork/Dependabot behaviour, and rate-limit headroom (the validator logs `X-RateLimit-*` headers). With the default `soft-fail: true`, a warn-only failure shows on the PR as a **red - `linear-ticket` check** plus the marker comment, which is what makes authors notice and fix + `Linear ticket` check** plus the marker comment, which is what makes authors notice and fix links during the pilot instead of discovering the requirement on flip day. Nobody is blocked: a non-required failing check leaves the merge button live. If you want the quieter first pass, set `soft-fail: false` and the status stays green. -2. Confirm the `linear-ticket` status publishes on **same-repo, fork, and Dependabot** PR head +2. Confirm the `Linear ticket` status publishes on **same-repo, fork, and Dependabot** PR head SHAs, and that automatic (branch/title/body) and manual links both resolve to the same canonical URL. 3. **Track the stale-link case.** Linking an issue *in Linear* after the check went red produces @@ -182,19 +196,27 @@ skewed apart, so an older `linear-ticket.yml` is running newer scripts — is tr 5. Flip `enforce: true`. Leave the check non-required for a short window — the PR-visible result is unchanged from the soft-fail pilot; what changes is that the validator's own run now goes red too, so a systemic breakage is visible in the Actions tab. -6. Add the **`linear-ticket`** status context to your `main` ruleset as a required check. +6. Add the **`Linear ticket`** status context to your `main` ruleset as a required check. Only now does anything block. Nothing here changes branch protection automatically — the last step is a manual repo-admin action. ## Gotchas -**The required check is a commit *status*, not the job.** Require the `linear-ticket` context in -your ruleset; do not require the `Linear Ticket / validate` job — it runs on the default branch -against the workflow_run event and is not tied to the PR's merge check. +**The required check is a commit *status*, not the job — and the two names now look alike.** +Your ruleset's check picker will offer both of these: + +| pick | name | what it is | +|---|---|---| +| ✅ | `Linear ticket` | the commit status this reusable publishes on the PR head SHA | +| ❌ | `Linear Ticket / validate` | the validator's own job, which runs on your DEFAULT branch | + +They differ only by capitalisation and the ` / validate` suffix, so read carefully. Requiring the +job instead of the status is the classic mistake here: the job is not tied to the PR's head +commit, so the requirement is never satisfied on the PR and every merge hangs pending. **A red check is not the same as a blocked merge.** What blocks is your ruleset requiring the -`linear-ticket` context — nothing this workflow does. That is why warn-only can (and by default +`Linear ticket` context — nothing this workflow does. That is why warn-only can (and by default does) publish a red status: it is a real, visible signal that costs nobody a merge. The corollary is the footgun: do not add the context to your ruleset until you flip `enforce: true`, or the warn-only pilot starts blocking. diff --git a/scripts/linear-ticket/README.md b/scripts/linear-ticket/README.md index 7bd66ef7..cdf04ff8 100644 --- a/scripts/linear-ticket/README.md +++ b/scripts/linear-ticket/README.md @@ -9,7 +9,7 @@ matching this repo's Python convention. | File | Role | |---|---| | `lib.py` | Pure, network-free core — candidate extraction, `team-keys` validation, the attachment **policy gate** (`filter_issues`), Linear error classification, failure-category selection, failure copy, and the batched diagnostic-query builder. Imported by `validate.py` and by the test suite. | -| `validate.py` | The side-effecting orchestration: resolve the PR from the `workflow_run` event, refetch it, publish the `linear-ticket` commit status, query `attachmentsForURL`, apply the gate, run one batched diagnostic query, and maintain the single marker PR comment. GitHub via the `gh` CLI (`subprocess`), Linear via `urllib`. Imports `lib.py`. | +| `validate.py` | The side-effecting orchestration: resolve the PR from the `workflow_run` event, refetch it, publish the `Linear ticket` commit status, query `attachmentsForURL`, apply the gate, run one batched diagnostic query, and maintain the single marker PR comment. GitHub via the `gh` CLI (`subprocess`), Linear via `urllib`. Imports `lib.py`. | | `tests/test_lib.py` | Hermetic `unittest` suite over `lib.py` — no network. | ## The invariant @@ -47,7 +47,7 @@ That is the whole point: a `TEAM-123`-shaped string an author types is not a lin status state, comment headline, and exit code; the diagnosis is identical in every mode. `enforce: true` → red status + nonzero exit. `enforce: false` (warn-only) never exits nonzero *on a verdict* and, with `soft-fail: true`, still publishes a **red** status — loud - on the PR but blocking nothing while `linear-ticket` is not a required context, with a + on the PR but blocking nothing while `Linear ticket` is not a required context, with a category-aware advisory note on the comment. `soft-fail: false` restores the silent always-green warn-only behaviour, and so does an **absent** `SOFT_FAIL` env: the workflow always passes it, so absent means a skewed `workflows_ref`/`uses:` pin, and a caller that diff --git a/scripts/linear-ticket/lib.py b/scripts/linear-ticket/lib.py index 6abf5510..b1f819cc 100644 --- a/scripts/linear-ticket/lib.py +++ b/scripts/linear-ticket/lib.py @@ -29,7 +29,14 @@ # The stable commit-status context branch protection requires. Publishing is done in # validate.py; the name lives here so the tests can pin it. -CONTEXT = "linear-ticket" +# +# HUMAN-FACING, AND A CONTRACT. GitHub renders this verbatim as the check's name in the PR's +# check list, so it is prose, not a slug — but it is also the exact string a consumer puts in +# its ruleset's required-checks list. Renaming it is free only while NO caller requires the +# context: the moment one does, a rename silently retires the required check (the new context +# is never satisfied, the old one is never reported again) and that repo's merges hang on a +# check nobody is publishing. Check every caller's ruleset before touching this. +CONTEXT = "Linear ticket" # The design's case-insensitive identifier shape: [A-Z][A-Z0-9]*-\d+. _CANDIDATE_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*-[0-9]+") @@ -216,7 +223,7 @@ def failure_guidance(category: str) -> str: # ── how a failure is REPORTED (loudness, not diagnosis) ───────────────────────────────── # select_failure_category above says WHY a check is red; the mode below says how loudly it is # reported. Whether a red check BLOCKS a merge is never decided here — that is branch -# protection deciding whether the `linear-ticket` context is required: +# protection deciding whether the `Linear ticket` context is required: # # enforce -> failure status, exit 1. The gating configuration. # warn-only + soft-fail -> failure status, exit 0. Shows on the PR exactly like enforce @@ -246,7 +253,7 @@ def failure_guidance(category: str) -> str: # red X as a merge block (and nobody assumes it will stay non-blocking forever). # # WORDING IS DELIBERATELY HEDGED. This validator never reads the caller's ruleset, so it cannot -# know whether `linear-ticket` is a required context — asserting "this does not block" would be +# know whether `Linear ticket` is a required context — asserting "this does not block" would be # a flat lie in exactly the configuration docs/callers/linear-ticket.md calls a footgun # (warn-only + the context already required), and would send that author to debug the wrong # thing. So the note states what IS knowable (this workflow is not what blocks; a warn-only @@ -255,9 +262,9 @@ def failure_guidance(category: str) -> str: _ADVISORY_BASE = ( "> ⚠️ **Advisory — this check is warn-only.** It is reported as failing so it shows up in " "the PR's check list, but nothing this workflow does blocks a merge: what blocks is your " - "repository's ruleset requiring the `linear-ticket` status context, and a warn-only pilot " + "repository's ruleset requiring the `Linear ticket` status context, and a warn-only pilot " "is meant to run *before* that context is required. If your merge button is actually " - "blocked on `linear-ticket`, then the context is already required while the pilot is still " + "blocked on `Linear ticket`, then the context is already required while the pilot is still " "warn-only — tell the repository owners, because that combination is a misconfiguration." ) _ADVISORY_TAIL = { @@ -330,7 +337,7 @@ def failure_outcome(category: str, enforce: bool, soft_fail: bool) -> FailureOut return FailureOutcome( verdict=f"\u274c fail ({category})", state="failure", - description=f"{headline} ({category})", + description=headline, exit_code=1, advisory=False, ) @@ -338,14 +345,14 @@ def failure_outcome(category: str, enforce: bool, soft_fail: bool) -> FailureOut return FailureOutcome( verdict=f"\u274c fail ({category}) \u2014 warn-only", state="failure", - description=f"Warn-only: {headline[0].lower()}{headline[1:]} ({category})", + description=f"Warn-only: {headline[0].lower()}{headline[1:]}", exit_code=0, advisory=True, ) return FailureOutcome( verdict=f"\u26a0\ufe0f warn-only (would fail: {category})", state="success", - description=f"warn-only: would fail ({category})", + description=f"Warn-only (would fail): {headline[0].lower()}{headline[1:]}", exit_code=0, advisory=False, ) diff --git a/scripts/linear-ticket/tests/test_lib.py b/scripts/linear-ticket/tests/test_lib.py index b476766e..6cce9a8a 100644 --- a/scripts/linear-ticket/tests/test_lib.py +++ b/scripts/linear-ticket/tests/test_lib.py @@ -177,6 +177,25 @@ def test_unknown_category_raises(self): ALL_CATEGORIES = ("no_candidate", "exists_not_linked", "policy_mismatch", "infra_error") +class StatusContext(unittest.TestCase): + def test_context_is_the_human_facing_name_branch_protection_requires(self): + # Pinned deliberately. GitHub renders this verbatim as the check's name in the PR's + # check list, AND it is the exact string a consumer lists in its ruleset's required + # checks. A rename is invisible in CI and silently retires the required check in any + # repo already requiring it, so make the test fail and force the caller audit. + self.assertEqual(lib.CONTEXT, "Linear ticket") + + def test_context_reads_as_prose_not_a_slug(self): + self.assertNotIn("-", lib.CONTEXT) + self.assertNotIn("_", lib.CONTEXT) + + def test_marker_is_independent_of_the_context(self): + # The comment marker is an HTML comment validate.py greps for; it is NOT the status + # context and must not be "tidied" to match a context rename, or the gate stops + # finding the comment it already posted and starts duplicating it. + self.assertEqual(lib.MARKER, "") + + class FailureOutcomeModes(unittest.TestCase): """The reporting-mode table in lib.py. The invariant under all of it: soft-fail changes only how LOUD a red verdict is, never the diagnosis and never the exit code contract.""" @@ -234,17 +253,29 @@ def test_advisory_only_when_red_and_non_gating(self): self.assertEqual(outcome.advisory, not enforce and soft_fail and outcome.state == "failure") - def test_category_is_named_in_every_verdict_and_description(self): + def test_category_is_named_in_every_verdict(self): + # The verdict heads the marker comment and job summary, where the raw category is the + # handle someone quotes when reporting a red check. for category in ALL_CATEGORIES: for enforce in (True, False): for soft_fail in (True, False): - outcome = lib.failure_outcome(category, enforce, soft_fail) - self.assertIn(category, outcome.verdict) - self.assertIn(category, outcome.description) + self.assertIn(category, + lib.failure_outcome(category, enforce, soft_fail).verdict) + + def test_status_description_carries_no_raw_category_slug(self): + # The description is the PR-visible one-liner beside the check name — prose, not a + # slug dump. The category stays in the comment and summary (test above), which is + # where triage happens; `(no_candidate)` next to the check name is just noise. + for category in ALL_CATEGORIES: + for enforce in (True, False): + for soft_fail in (True, False): + desc = lib.failure_outcome(category, enforce, soft_fail).description + self.assertNotIn(category, desc) + self.assertNotIn("_", desc) def test_description_fits_the_github_status_limit(self): # publish_status truncates at 140; a description that only ever survives truncation - # would silently lose the category, so keep every mode's copy inside the limit. + # would silently lose its meaning, so keep every mode's copy inside the limit. for category in ALL_CATEGORIES: for enforce in (True, False): for soft_fail in (True, False): @@ -272,7 +303,7 @@ class AdvisoryNote(unittest.TestCase): def test_never_asserts_flatly_that_nothing_is_blocked(self): # The validator never reads the caller's ruleset, so it cannot know whether the - # `linear-ticket` context is required. In the documented footgun configuration + # `Linear ticket` context is required. In the documented footgun configuration # (warn-only + context already required) the red check IS blocking the author, and a # flat "this does not block the merge" would send them to debug the wrong thing. for category in ALL_CATEGORIES: diff --git a/scripts/linear-ticket/validate.py b/scripts/linear-ticket/validate.py index cfcb7d18..1a52275c 100644 --- a/scripts/linear-ticket/validate.py +++ b/scripts/linear-ticket/validate.py @@ -2,7 +2,7 @@ """Side-effecting orchestration behind linear-ticket.yml. Imports lib.py for every decision and owns only I/O: resolve the PR from the workflow_run -event, refetch it, publish the ``linear-ticket`` commit status, query Linear's +event, refetch it, publish the ``Linear ticket`` commit status, query Linear's attachmentsForURL for the PR's canonical html_url, apply the policy gate, run one batched diagnostic query, and maintain exactly one marker PR comment. @@ -23,7 +23,7 @@ exits nonzero; a broken run still can — see finish_fail and run()) SOFT_FAIL warn-only only: "true" publishes a red `failure` status — loud, and non-blocking for as long as the caller's ruleset does not require the - `linear-ticket` context; "false" (and, deliberately, an ABSENT value) + `Linear ticket` context; "false" (and, deliberately, an ABSENT value) keeps the silent always-green warn-only behaviour RUN_URL html_url of this workflow run, for the status target and comment LINEAR_API_URL optional override (default https://api.linear.app/graphql) @@ -110,7 +110,7 @@ def get(self, path: str, *, paginate: bool = False): def publish_status(self, sha: str, state: str, description: str, target_url: str, *, critical: bool = False) -> bool: - """Publish the ``linear-ticket`` commit status. Returns True on success. + """Publish the ``Linear ticket`` commit status. Returns True on success. A TERMINAL write (success/failure/warn-only) is ``critical=True``: if it fails, the old status stays as the required context — a prior ``success`` could then keep gating @@ -342,7 +342,7 @@ def run(self, event: dict) -> int: # The signal workflow runs only on `pull_request`, so the triggering run's event must # be `pull_request`. The caller's workflow-name + conclusion filters do not prove that; # a miswired caller pointed at a `push` workflow could otherwise resolve an open PR from - # the pushed head SHA and publish `linear-ticket` for it. Fail fast instead. + # the pushed head SHA and publish `Linear ticket` for it. Fail fast instead. wr_event = wr.get("event") or "" if wr_event != "pull_request": error(f"Triggering workflow_run event was '{wr_event}', not 'pull_request'. The " From 12f10295ded59e1129935a7c39f35fafa770f6f9 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Wed, 19 Aug 2026 22:13:54 -0700 Subject: [PATCH 2/3] fix(linear-ticket): keep the two link-failure categories distinguishable, and correct the rename callout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-ups on the `Linear ticket` context rename. Dropping the `(category)` slug from the status description collapsed `no_candidate` and `exists_not_linked` onto one byte-identical string — both mapped to "No linked Linear issue" — even though their remedies are opposite: one means add a link at all, the other means Linear already knows the issue and has not attached it yet (the async-link race rollout step 3 calls the common case, where the fix is a re-run, not an edit). The category still reaches the marker comment, but upsert_marker_comment downgrades a write failure to a warning, so the description can be the only surviving signal. `exists_not_linked` gets its own headline, and a test pins the four descriptions pairwise-distinct in every reporting mode so a future headline edit cannot re-collapse them. Three doc corrections, all in the rename callout and the upgrade guide: * An already-open PR does not gain the new status when the caller's pin moves — the signal workflow fires on `pull_request`, so it carries the old context ALONE until it takes a new commit or the validate run is re-triggered. The bullet described a stale row sitting beside a new one, which never happens; requiring the new context before those PRs are re-validated leaves them pending, so backfill deliberately. * "Nothing consumes the stale one" was wrong twice. Statuses are last-write-wins per context, so the survivor is frequently `success` (any pass, any exemption, every outcome under `soft-fail: false`) — and while `linear-ticket` is still required a stale green keeps satisfying it after the verdict has changed underneath. Either value also counts toward the commit's combined status and statusCheckRollup, which this repo's own grade-pr-risk.sh reads. * The pre-bump ruleset check told the operator to look for `Linear ticket`, which a caller that has not taken the rename bump does not publish — following it literally finds nothing and reports safe while the old requirement is live. Same for the line describing what warn-only "used to publish": that predates the rename. Also fixes the job's real `statuses: write` permission comment, which the header comment's rename had left behind at the old spelling — the block callers copy verbatim. Co-Authored-By: Claude Opus 5 --- .github/workflows/linear-ticket.yml | 2 +- docs/callers/linear-ticket.md | 40 +++++++++++++++++-------- scripts/linear-ticket/lib.py | 11 ++++++- scripts/linear-ticket/tests/test_lib.py | 15 ++++++++++ 4 files changed, 54 insertions(+), 14 deletions(-) diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index 65bfecca..c01405dd 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -144,7 +144,7 @@ jobs: actions: read # read the triggering workflow_run contents: read # checkout the validator scripts; PR code is never checked out pull-requests: write # the one marker diagnostic comment - statuses: write # publish the linear-ticket commit status + statuses: write # publish the `Linear ticket` commit status steps: - name: Require a pinned workflows_ref # workflows_ref runs THIS repo's scripts in a job holding the caller's write token + diff --git a/docs/callers/linear-ticket.md b/docs/callers/linear-ticket.md index eb754d8c..83f30b87 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -31,17 +31,28 @@ on the PR head SHA; you require **that context** once warn-only observation is d > [!IMPORTANT] > **The context was renamed from `linear-ticket` to `Linear ticket`.** GitHub renders it verbatim -> as the check's name, so it is prose now rather than a slug. Two consequences when you bump past -> that pin: +> as the check's name, so it is prose now rather than a slug. Three consequences when you bump +> past that pin: > > - **If your ruleset already requires `linear-ticket`, update it in the same change.** The old > context is never reported again, so a required check nobody publishes leaves every PR > pending — which blocks merges exactly as a failure would. (No caller required it at the time > of the rename, which is why it was done then.) -> - **Open PRs keep the old status too.** Commit statuses are per-context and append-only, so a PR -> whose head was already validated shows a stale red `linear-ticket` beside the new -> `Linear ticket` until it gets a new commit. Nothing consumes the stale one; it ages out with -> the head SHA. +> - **Already-open PRs do not gain the new status on their own.** The signal workflow fires on +> `pull_request`, so moving the pin publishes nothing for a PR that is already open: until it +> takes a new commit, or someone re-runs its validate workflow, it carries the old context +> *alone* — there is no new `Linear ticket` beside it. Require the new context before those PRs +> are re-validated and every one of them sits pending, so backfill deliberately (push or +> re-run) rather than waiting for head SHAs to turn over. +> - **The stale `linear-ticket` status survives, and it is not inert.** Commit statuses are +> per-context and last-write-wins, so whatever value the old context last held stays on that +> head SHA — and it is frequently `success`, not the red you might picture (any pass, any +> exemption, and *every* outcome under `soft-fail: false`). That matters twice over: while +> `linear-ticket` is still required, a stale `success` keeps satisfying the requirement even if +> the verdict has since changed underneath it (issue canceled, attachment removed, exempt label +> pulled, `team-keys` tightened); and either value still counts toward that commit's combined +> status and `statusCheckRollup`, which tooling reads — this repo's own `grade-pr-risk.sh` +> does. Drop `linear-ticket` from the ruleset in the same change rather than letting it age out. ## Prerequisites @@ -145,15 +156,20 @@ job-level detail. `soft-fail` is new, and it defaults to `true`. **If your caller already runs `enforce: false`, taking a SHA bump past the commit that added this input changes what your PRs show:** warn-only -used to publish a green `Linear ticket` status in every outcome, and now publishes a **red** -one. Nothing about *blocking* changes — a status only blocks when your ruleset requires that -context — but the PR check list goes from green to red, and anything you have keyed off the -status (auto-merge bots, dashboards, other automation) sees `failure` where it saw `success`. +used to publish a green status in every outcome, and now publishes a **red** one. (Under its +then-name `linear-ticket` — that bump predates the context rename above, so a caller still on an +older pin is looking for the old spelling.) Nothing about *blocking* changes — a status only +blocks when your ruleset requires that context — but the PR check list goes from green to red, +and anything you have keyed off the status (auto-merge bots, dashboards, other automation) sees +`failure` where it saw `success`. Two things to do before you take the bump: -1. **Check your ruleset.** If `Linear ticket` is already a required check while you are still on - `enforce: false`, the red status *will* block merges. That combination was always a +1. **Check your ruleset — under the name your CURRENT pin publishes.** If the status context is + already a required check while you are still on `enforce: false`, the red status *will* block + merges. Search for `linear-ticket` if you have not yet taken the rename bump and `Linear + ticket` if you have; looking only for the new spelling on a pre-rename caller finds nothing + and reports safe while the old requirement is live. That combination was always a misconfiguration (rollout step 6 is the last step for a reason), but soft-fail is what makes it bite. Remove the required check, or flip `enforce: true` — do not sit in between. 2. **Decide which pilot you want.** Loud (the default) is recommended: authors fix links during diff --git a/scripts/linear-ticket/lib.py b/scripts/linear-ticket/lib.py index b1f819cc..5eed5d7d 100644 --- a/scripts/linear-ticket/lib.py +++ b/scripts/linear-ticket/lib.py @@ -242,9 +242,18 @@ def failure_guidance(category: str) -> str: # A commit status description is the PR-visible one-liner. It must state the DIAGNOSIS this # run actually reached: "no linked Linear issue" is wrong for infra_error, where Linear could # not be queried at all and the run therefore determined nothing about the ticket. +# +# KEEP EVERY HEADLINE DISTINCT. The description no longer carries the `(category)` slug, so +# the headline is the whole of the PR-visible diagnosis — two categories sharing one headline +# renders them byte-identically beside the check name while their remedies differ +# (no_candidate: add a link at all; exists_not_linked: Linear knows the issue but has not +# attached it yet, usually the async-link race, so re-run before touching anything). The +# category still reaches the marker comment and job summary, but upsert_marker_comment +# downgrades a write failure to a warning, so the description can be the only signal that +# survives. A test pins the descriptions pairwise-distinct. _STATUS_HEADLINE = { "no_candidate": "No linked Linear issue", - "exists_not_linked": "No linked Linear issue", + "exists_not_linked": "Referenced Linear issue is not linked yet", "policy_mismatch": "Linked Linear issue fails this repo's policy", "infra_error": "Could not verify — Linear could not be queried", } diff --git a/scripts/linear-ticket/tests/test_lib.py b/scripts/linear-ticket/tests/test_lib.py index 6cce9a8a..5b218e9b 100644 --- a/scripts/linear-ticket/tests/test_lib.py +++ b/scripts/linear-ticket/tests/test_lib.py @@ -273,6 +273,21 @@ def test_status_description_carries_no_raw_category_slug(self): self.assertNotIn(category, desc) self.assertNotIn("_", desc) + def test_each_category_gets_a_distinct_description(self): + # The description no longer carries the `(category)` slug, so the headline is the + # whole PR-visible diagnosis. Two categories collapsing onto one string would render + # byte-identically beside the check name while their remedies differ — which is + # exactly what `no_candidate` and `exists_not_linked` did before the headlines were + # split. The marker comment still carries the category, but its write failure is only + # a warning, so the description can be the only signal that survives. + for enforce in (True, False): + for soft_fail in (True, False): + descriptions = [lib.failure_outcome(c, enforce, soft_fail).description + for c in ALL_CATEGORIES] + self.assertEqual(len(set(descriptions)), len(ALL_CATEGORIES), + f"collapsed descriptions at enforce={enforce} " + f"soft_fail={soft_fail}: {descriptions}") + def test_description_fits_the_github_status_limit(self): # publish_status truncates at 140; a description that only ever survives truncation # would silently lose its meaning, so keep every mode's copy inside the limit. From acdef018ffdfdebead0c59aa82612903ea6b571d Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Wed, 19 Aug 2026 22:30:23 -0700 Subject: [PATCH 3/3] docs(linear-ticket): drop the leading space inside the `/ validate` code span markdownlint MD038 (no-space-in-code) flagged the inline span in the check-picker gotcha. The literal job name is still shown verbatim in the table directly above, so tightening the span loses nothing. Co-Authored-By: Claude Opus 5 --- docs/callers/linear-ticket.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/callers/linear-ticket.md b/docs/callers/linear-ticket.md index 83f30b87..96f31469 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -227,7 +227,7 @@ Your ruleset's check picker will offer both of these: | ✅ | `Linear ticket` | the commit status this reusable publishes on the PR head SHA | | ❌ | `Linear Ticket / validate` | the validator's own job, which runs on your DEFAULT branch | -They differ only by capitalisation and the ` / validate` suffix, so read carefully. Requiring the +They differ only by capitalisation and the `/ validate` suffix, so read carefully. Requiring the job instead of the status is the classic mistake here: the job is not tied to the PR's head commit, so the requirement is never satisfied on the PR and every merge hangs pending.