diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index e1dc4516..f225d2bc 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -17,11 +17,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 @@ -36,7 +36,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 @@ -104,7 +104,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. @@ -112,7 +112,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 @@ -146,7 +146,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/README.md b/README.md index aaa265ec..eef1f382 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 when the PR targets a protected base branch** — not a `TEAM-123`-shaped string in author text. The validator reads GitHub's branch `protected` property, so any number of branches protected by branch protection or rulesets are covered without a caller-maintained list; unprotected targets publish no `linear-ticket` status and do not query Linear (a success status would be unsafe because GitHub scopes statuses to a SHA, not a PR). For protected targets, 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 and base branch before every terminal write so a superseded or retargeted run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on unreadable branch protection or Linear 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 when the PR targets a protected base branch** — not a `TEAM-123`-shaped string in author text. The validator reads GitHub's branch `protected` property, so any number of branches protected by branch protection or rulesets are covered without a caller-maintained list; unprotected targets publish no `Linear ticket` status and do not query Linear (a success status would be unsafe because GitHub scopes statuses to a SHA, not a PR). For protected targets, 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 and base branch before every terminal write so a superseded or retargeted run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on unreadable branch protection or Linear 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 a70c1d6d..6eea91f9 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -8,7 +8,7 @@ For a PR targeting a **protected base branch**, gates on a Linear issue that **L to that exact PR** — not merely a `TEAM-123`-shaped string in the branch, title, or body. The validator reads GitHub's `protected` property for the current base branch, so repositories can have any number of protected branches without duplicating a branch list in the caller. A PR -targeting an unprotected branch skips without querying Linear or publishing a `linear-ticket` +targeting an unprotected branch skips without querying Linear or publishing a `Linear ticket` status. For a protected branch, the only thing that turns the check green is an attachment Linear @@ -32,9 +32,34 @@ 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. 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.) +> - **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 | | | @@ -84,7 +109,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: @@ -131,21 +156,26 @@ 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** -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 @@ -163,18 +193,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 @@ -188,7 +218,7 @@ 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 as a required check in every ruleset that protects +6. Add the **`Linear ticket`** status context as a required check in every ruleset that protects a branch where tickets are required. Only now does anything block. The validator discovers every protected base branch dynamically; no branch list belongs in the workflow caller. @@ -196,18 +226,26 @@ Nothing here changes branch protection automatically — the last step is a manu ## 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. **Protection is evaluated for the PR's current base branch.** GitHub's branch response reports protection from branch protection rules or rulesets. Retargeting a PR triggers a fresh run; an -unprotected target gets no `linear-ticket` status and no Linear API query. The status must be +unprotected target gets no `Linear ticket` status and no Linear API query. The status must be absent rather than successful because GitHub scopes commit statuses to a SHA, not a PR: success from an unprotected PR could otherwise overwrite failure on a protected PR sharing that commit. **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 5d06cd97..553cecc8 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, skip unprotected base branches, 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, skip unprotected base branches, 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/` | Hermetic `unittest` suites over the pure core and protected-branch orchestration — no network. | ## The invariant @@ -17,7 +17,7 @@ matching this repo's Python convention. The **only** thing that turns the check green is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`) whose issue satisfies policy — `filter_issues`. This invariant applies when the PR targets a protected branch; an unprotected target is outside -the gate and publishes no `linear-ticket` status or Linear query. A `TEAM-123`-shaped string an +the gate and publishes no `Linear ticket` status or Linear query. A `TEAM-123`-shaped string an author types is not a link. So: - The PR URL is passed to Linear as a **GraphQL variable**, never interpolated into the query. @@ -56,7 +56,7 @@ author types is not a link. So: 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..5eed5d7d 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 @@ -235,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", } @@ -246,7 +262,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 +271,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 +346,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 +354,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..5b218e9b 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,44 @@ 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_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 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 +318,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 98c426e8..105be819 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) @@ -111,7 +111,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 @@ -365,7 +365,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 "