From 04c0a1f1bd1765f63f01cf8536ee0e756a1f2c7e Mon Sep 17 00:00:00 2001 From: Hunter Senft-Grupp Date: Thu, 20 Aug 2026 04:11:26 +0000 Subject: [PATCH 1/2] feat(linear-ticket): gate protected branches only Amp-Thread-ID: https://ampcode.com/threads/T-01a01d5b-2df4-75d3-8833-ff46b17b212b Co-authored-by: Amp --- .github/workflows/linear-ticket.yml | 9 +- README.md | 2 +- docs/callers/linear-ticket.md | 29 +++-- scripts/linear-ticket/README.md | 17 ++- scripts/linear-ticket/tests/test_validate.py | 128 +++++++++++++++++++ scripts/linear-ticket/validate.py | 47 +++++-- 6 files changed, 205 insertions(+), 27 deletions(-) create mode 100644 scripts/linear-ticket/tests/test_validate.py diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index 75cb2903..3027c741 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -1,9 +1,10 @@ name: Linear Ticket (reusable) -# Reusable gate that requires every PR to carry a Linear issue Linear has LINKED to that -# exact PR before it can merge (design: pr-linear-ticket-enforcement). The only thing that -# passes is an attachment Linear returns for this PR's canonical html_url whose issue meets -# the configured team/state policy — a `TEAM-123`-shaped string in author text never does. +# Reusable gate that requires PRs targeting a protected branch to carry a Linear issue Linear +# has LINKED to that exact PR before they can merge (design: pr-linear-ticket-enforcement). +# PRs targeting an unprotected branch pass without querying Linear. The only thing that passes +# the ticket gate is an attachment Linear returns for this PR's canonical html_url whose issue +# meets the configured team/state policy — a `TEAM-123`-shaped string in author text never does. # # TWO-STAGE, FORK-SAFE EXECUTION. This privileged validator is invoked by a caller that runs # on `workflow_run: completed` of an unprivileged, no-op signal workflow in the consumer repo. diff --git a/README.md b/README.md index 669395e3..a1a5ed34 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 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 pass without querying Linear. 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 9c47bd79..faf3925a 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -1,15 +1,21 @@ -# `linear-ticket.yml` — require a linked Linear issue on every PR +# `linear-ticket.yml` — require a linked Linear issue for protected branches Read [the shared caller contract](README.md) first. ## What it does -Gates a PR on a Linear issue that **Linear has linked to that exact PR** — not merely a -`TEAM-123`-shaped string in the branch, title, or body. The only thing that turns the check -green is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`) -whose issue satisfies the configured team/state policy. Any supported linking method works: -identifier in the branch name, PR title, a `Closes`/`Fixes`/`Resolves` line in the body, or -a manual link pasted into the issue in Linear. +For a PR targeting a **protected base branch**, gates on a Linear issue that **Linear has linked +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 receives a successful `linear-ticket` status without querying +Linear. + +For a protected branch, the only thing that turns the check green is an attachment Linear +returns for the PR's canonical `html_url` (`attachmentsForURL`) whose issue satisfies the +configured team/state policy. Any supported linking method works: identifier in the branch +name, PR title, a `Closes`/`Fixes`/`Resolves` line in the body, or a manual link pasted into the +issue in Linear. Identifiers extracted from PR text are used **only** to explain a red check ("you referenced `BE-1234` but Linear has not linked it") — they can never make it green. Automated checks buy @@ -182,8 +188,9 @@ 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. - Only now does anything block. +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. Nothing here changes branch protection automatically — the last step is a manual repo-admin action. @@ -193,6 +200,10 @@ Nothing here changes branch protection automatically — the last step is a manu 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. +**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 a successful “not required” status and no Linear API query. + **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 does) publish a red status: it is a real, visible signal that costs nobody a merge. The diff --git a/scripts/linear-ticket/README.md b/scripts/linear-ticket/README.md index 7bd66ef7..06fa7437 100644 --- a/scripts/linear-ticket/README.md +++ b/scripts/linear-ticket/README.md @@ -9,14 +9,16 @@ 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`. | -| `tests/test_lib.py` | Hermetic `unittest` suite over `lib.py` — no network. | +| `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 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`. -That is the whole point: a `TEAM-123`-shaped string an author types is not a link. So: +This invariant applies when the PR targets a protected branch; an unprotected target is outside +the gate and passes without a 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. - The policy reads the resolved issue's **API `team.key`** and **`state.type`**, never a @@ -36,8 +38,13 @@ That is the whole point: a `TEAM-123`-shaped string an author types is not a lin - The PR is resolved from **GitHub-owned** `workflow_run.pull_requests` (same-repo) or the commit→PR association (fork), requiring **exactly one open PR**; ambiguous associations are refused. -- Before every terminal status write, the PR head SHA is **refetched**; if it advanced, the - run exits without publishing so a superseded validation can't overwrite a newer result. +- The PR's current base branch is read from GitHub and its `protected` property determines + whether the ticket gate applies. This covers any number of branches protected by classic + branch protection or rulesets without a caller-maintained branch list. An unreadable + protection state fails closed. +- Before every terminal status write, the PR head SHA and base branch are **refetched**; if + either changed, the run exits without publishing so a superseded validation can't overwrite + a newer result. The base check matters when a retarget keeps the same head commit. - **Fails closed**: auth, schema, malformed-response, timeout, and rate-limit-exhaustion are reported as an *infrastructure* error (red in enforce mode), never as an invalid ticket. Linear signals rate limiting as HTTP 400 + GraphQL `RATELIMITED`, which is retried within a diff --git a/scripts/linear-ticket/tests/test_validate.py b/scripts/linear-ticket/tests/test_validate.py new file mode 100644 index 00000000..789ad950 --- /dev/null +++ b/scripts/linear-ticket/tests/test_validate.py @@ -0,0 +1,128 @@ +"""Hermetic orchestration tests for validate.py.""" + +import os +import sys +import unittest + +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +import validate # noqa: E402 + + +class FakeGitHub: + repo = "Comfy-Org/example" + + def __init__(self, protected): + self.protected = protected + self.current_base = "release/next" + self.statuses = [] + self.deleted_comments = [] + + def get(self, path, *, paginate=False): + if path.endswith("/pulls/17"): + return { + "number": 17, + "state": "open", + "html_url": "https://github.com/Comfy-Org/example/pull/17", + "head": {"sha": "abc123", "ref": "feature/be-123"}, + "base": {"ref": "release/next"}, + "title": "Change something", + "body": "", + "labels": [], + "user": {"login": "octocat"}, + } + raise AssertionError(f"unexpected GitHub request: {path}") + + def branch_is_protected(self, branch): + self.requested_branch = branch + return self.protected + + def publish_status(self, sha, state, description, target_url, *, critical=False): + self.statuses.append((sha, state, description, critical)) + return True + + def delete_marker_comment(self, pr): + self.deleted_comments.append(pr) + + def current_pr_target(self, pr): + return "abc123", self.current_base + + +def event(): + return { + "workflow_run": { + "event": "pull_request", + "head_sha": "abc123", + "pull_requests": [{"number": 17}], + } + } + + +class ProtectedBaseBranch(unittest.TestCase): + def validator(self, github): + return validate.Validator(github, "token", [], True, True, False, "run-url") + + def test_unprotected_base_skips_linear_and_publishes_success(self): + github = FakeGitHub(protected=False) + validator = self.validator(github) + validator._query_attachments = lambda _url: self.fail("Linear must not be queried") + + self.assertEqual(validator.run(event()), 0) + + self.assertEqual(github.requested_branch, "release/next") + self.assertEqual([status[1] for status in github.statuses], ["pending", "success"]) + self.assertIn("unprotected branch", github.statuses[-1][2]) + self.assertEqual(github.deleted_comments, [17]) + + def test_protected_base_runs_linear_validation(self): + github = FakeGitHub(protected=True) + validator = self.validator(github) + queries = [] + validator._query_attachments = lambda url: ( + queries.append(url) or + ([{"issue": {"identifier": "BE-123", "team": {"key": "BE"}, + "state": {"type": "started"}}}], False) + ) + + self.assertEqual(validator.run(event()), 0) + + self.assertEqual(queries, ["https://github.com/Comfy-Org/example/pull/17"]) + self.assertEqual([status[1] for status in github.statuses], ["pending", "success"]) + self.assertIn("BE-123", github.statuses[-1][2]) + + def test_unknown_protection_state_fails_closed_without_querying_linear(self): + github = FakeGitHub(protected=None) + validator = self.validator(github) + validator._query_attachments = lambda _url: self.fail("Linear must not be queried") + + self.assertEqual(validator.run(event()), 1) + self.assertEqual([status[1] for status in github.statuses], ["pending"]) + + def test_retargeted_pr_does_not_publish_stale_terminal_status(self): + github = FakeGitHub(protected=False) + github.current_base = "main" + validator = self.validator(github) + validator._query_attachments = lambda _url: self.fail("Linear must not be queried") + + self.assertEqual(validator.run(event()), 0) + self.assertEqual([status[1] for status in github.statuses], ["pending"]) + + +class BranchProtectionLookup(unittest.TestCase): + def test_encodes_branch_names_and_returns_boolean(self): + github = validate.GitHub("Comfy-Org/example") + paths = [] + github.get = lambda path: paths.append(path) or {"protected": True} + + self.assertTrue(github.branch_is_protected("release/next")) + self.assertEqual(paths, ["/repos/Comfy-Org/example/branches/release%2Fnext"]) + + def test_missing_protected_field_is_unknown(self): + github = validate.GitHub("Comfy-Org/example") + github.get = lambda _path: {} + + self.assertIsNone(github.branch_is_protected("main")) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/linear-ticket/validate.py b/scripts/linear-ticket/validate.py index cfcb7d18..089b6aae 100644 --- a/scripts/linear-ticket/validate.py +++ b/scripts/linear-ticket/validate.py @@ -41,6 +41,7 @@ import sys import time import urllib.error +import urllib.parse import urllib.request import lib @@ -176,9 +177,18 @@ def delete_marker_comment(self, pr: int) -> None: if result.returncode != 0: warning(f"Failed to delete marker comment {existing}: {result.stderr.strip()}") - def current_head_sha(self, pr: int) -> str | None: + def current_pr_target(self, pr: int) -> tuple[str | None, str | None]: data = self.get(f"/repos/{self.repo}/pulls/{pr}") - return (data or {}).get("head", {}).get("sha") + return ( + (data or {}).get("head", {}).get("sha"), + (data or {}).get("base", {}).get("ref"), + ) + + def branch_is_protected(self, branch: str) -> bool | None: + encoded = urllib.parse.quote(branch, safe="") + data = self.get(f"/repos/{self.repo}/branches/{encoded}") + protected = (data or {}).get("protected") + return protected if isinstance(protected, bool) else None # ── Linear via urllib ───────────────────────────────────────────────────────────────── @@ -251,15 +261,19 @@ def __init__(self, gh: GitHub, token: str, team_keys, require_open, enforce, sof self.exempt_actors = lib.parse_actor_list(os.environ.get("EXEMPT_ACTORS", "")) self.pr_number: int | None = None self.validated_sha: str | None = None + self.validated_base_branch: str | None = None # -- terminal outcomes ----------------------------------------------------------------- def _guard_supersession(self) -> bool: - """True to proceed with the terminal write; False to bail because the PR head - advanced past the SHA we validated (a newer run owns the result now).""" - now = self.gh.current_head_sha(self.pr_number) - if now and now != self.validated_sha: - log(f"PR head moved {self.validated_sha} -> {now}; a newer run supersedes this " - "one. Not writing a terminal status.") + """True unless the PR head or base changed after the validated snapshot.""" + now_sha, now_base = self.gh.current_pr_target(self.pr_number) + if now_sha and now_sha != self.validated_sha: + log(f"PR head moved {self.validated_sha} -> {now_sha}; a newer run supersedes " + "this one. Not writing a terminal status.") + return False + if now_base and now_base != self.validated_base_branch: + log(f"PR base moved {self.validated_base_branch} -> {now_base}; a newer run " + "supersedes this one. Not writing a terminal status.") return False return True @@ -360,6 +374,8 @@ def run(self, event: dict) -> int: html_url = pr.get("html_url") or "" self.validated_sha = pr.get("head", {}).get("sha") branch = pr.get("head", {}).get("ref") or "" + base_branch = pr.get("base", {}).get("ref") or "" + self.validated_base_branch = base_branch title = pr.get("title") or "" body = pr.get("body") or "" labels = [lbl.get("name") for lbl in (pr.get("labels") or [])] @@ -369,6 +385,21 @@ def run(self, event: dict) -> int: self.gh.publish_status(self.validated_sha, "pending", "Checking for a linked Linear issue…", self.run_url) + if not base_branch: + error(f"PR #{self.pr_number} has no base branch; refusing to validate.") + return 1 + protected = self.gh.branch_is_protected(base_branch) + if protected is None: + error(f"Could not determine whether base branch '{base_branch}' is protected; " + "failing closed.") + return 1 + if not protected: + log(f"PR targets unprotected branch '{base_branch}' — Linear ticket not required.") + return self.finish_exempt( + f"PR targets the unprotected `{base_branch}` branch — the Linear-ticket " + "requirement does not apply.", + f"Not required for unprotected branch: {base_branch}") + # Exemptions short-circuit before the Linear query. The actor allow-list is the # non-manual hatch for bot PRs (Dependabot/Renovate never carry a ticket); it is # opt-in and defaults empty, so there is still no built-in bypass. From 1d769e32585ee8a7ebe0dcbffac7265a6e7a9e23 Mon Sep 17 00:00:00 2001 From: Hunter Senft-Grupp Date: Thu, 20 Aug 2026 04:16:04 +0000 Subject: [PATCH 2/2] fix(linear-ticket): avoid shared status bypass Amp-Thread-ID: https://ampcode.com/threads/T-01a01d5b-2df4-75d3-8833-ff46b17b212b Co-authored-by: Amp --- .github/workflows/linear-ticket.yml | 7 ++++--- README.md | 2 +- docs/callers/linear-ticket.md | 8 +++++--- scripts/linear-ticket/README.md | 8 +++++--- scripts/linear-ticket/tests/test_validate.py | 10 +++++----- scripts/linear-ticket/validate.py | 20 +++++++++++++------- 6 files changed, 33 insertions(+), 22 deletions(-) diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index 3027c741..e1dc4516 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -2,9 +2,10 @@ name: Linear Ticket (reusable) # Reusable gate that requires PRs targeting a protected branch to carry a Linear issue Linear # has LINKED to that exact PR before they can merge (design: pr-linear-ticket-enforcement). -# PRs targeting an unprotected branch pass without querying Linear. The only thing that passes -# the ticket gate is an attachment Linear returns for this PR's canonical html_url whose issue -# meets the configured team/state policy — a `TEAM-123`-shaped string in author text never does. +# PRs targeting an unprotected branch skip without querying Linear or publishing this context. +# The only thing that passes the ticket gate is an attachment Linear returns for this PR's +# canonical html_url whose issue meets the configured team/state policy — a `TEAM-123`-shaped +# string in author text never does. # # TWO-STAGE, FORK-SAFE EXECUTION. This privileged validator is invoked by a caller that runs # on `workflow_run: completed` of an unprivileged, no-op signal workflow in the consumer repo. diff --git a/README.md b/README.md index a1a5ed34..148ba6dd 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 pass without querying Linear. 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 faf3925a..a70c1d6d 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -8,8 +8,8 @@ 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 receives a successful `linear-ticket` status without querying -Linear. +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 returns for the PR's canonical `html_url` (`attachmentsForURL`) whose issue satisfies the @@ -202,7 +202,9 @@ against the workflow_run event and is not tied to the PR's merge check. **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 a successful “not required” status and no Linear API query. +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 diff --git a/scripts/linear-ticket/README.md b/scripts/linear-ticket/README.md index 06fa7437..5d06cd97 100644 --- a/scripts/linear-ticket/README.md +++ b/scripts/linear-ticket/README.md @@ -17,8 +17,8 @@ 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 passes without a Linear query. A `TEAM-123`-shaped string an author types is not a -link. So: +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. - The policy reads the resolved issue's **API `team.key`** and **`state.type`**, never a @@ -41,7 +41,9 @@ link. So: - The PR's current base branch is read from GitHub and its `protected` property determines whether the ticket gate applies. This covers any number of branches protected by classic branch protection or rulesets without a caller-maintained branch list. An unreadable - protection state fails closed. + protection state fails closed. An unprotected target publishes no commit status because + statuses are SHA-scoped rather than PR-scoped; publishing success could overwrite a protected + PR's failure when both PRs share a commit. - Before every terminal status write, the PR head SHA and base branch are **refetched**; if either changed, the run exits without publishing so a superseded validation can't overwrite a newer result. The base check matters when a retarget keeps the same head commit. diff --git a/scripts/linear-ticket/tests/test_validate.py b/scripts/linear-ticket/tests/test_validate.py index 789ad950..f4678917 100644 --- a/scripts/linear-ticket/tests/test_validate.py +++ b/scripts/linear-ticket/tests/test_validate.py @@ -62,7 +62,7 @@ class ProtectedBaseBranch(unittest.TestCase): def validator(self, github): return validate.Validator(github, "token", [], True, True, False, "run-url") - def test_unprotected_base_skips_linear_and_publishes_success(self): + def test_unprotected_base_skips_linear_without_publishing_status(self): github = FakeGitHub(protected=False) validator = self.validator(github) validator._query_attachments = lambda _url: self.fail("Linear must not be queried") @@ -70,8 +70,7 @@ def test_unprotected_base_skips_linear_and_publishes_success(self): self.assertEqual(validator.run(event()), 0) self.assertEqual(github.requested_branch, "release/next") - self.assertEqual([status[1] for status in github.statuses], ["pending", "success"]) - self.assertIn("unprotected branch", github.statuses[-1][2]) + self.assertEqual(github.statuses, []) self.assertEqual(github.deleted_comments, [17]) def test_protected_base_runs_linear_validation(self): @@ -96,7 +95,7 @@ def test_unknown_protection_state_fails_closed_without_querying_linear(self): validator._query_attachments = lambda _url: self.fail("Linear must not be queried") self.assertEqual(validator.run(event()), 1) - self.assertEqual([status[1] for status in github.statuses], ["pending"]) + self.assertEqual(github.statuses, []) def test_retargeted_pr_does_not_publish_stale_terminal_status(self): github = FakeGitHub(protected=False) @@ -105,7 +104,8 @@ def test_retargeted_pr_does_not_publish_stale_terminal_status(self): validator._query_attachments = lambda _url: self.fail("Linear must not be queried") self.assertEqual(validator.run(event()), 0) - self.assertEqual([status[1] for status in github.statuses], ["pending"]) + self.assertEqual(github.statuses, []) + self.assertEqual(github.deleted_comments, []) class BranchProtectionLookup(unittest.TestCase): diff --git a/scripts/linear-ticket/validate.py b/scripts/linear-ticket/validate.py index 089b6aae..98c426e8 100644 --- a/scripts/linear-ticket/validate.py +++ b/scripts/linear-ticket/validate.py @@ -300,6 +300,15 @@ def finish_exempt(self, headline: str, status_desc: str) -> int: return 1 return 0 + def finish_not_required(self, base_branch: str) -> int: + if not self._guard_supersession(): + return 0 + summary("## linear-ticket: not required") + summary("") + summary(f"PR targets the unprotected `{base_branch}` branch.") + self.gh.delete_marker_comment(self.pr_number) + return 0 + def finish_fail(self, category: str, detail: str) -> int: guidance = lib.failure_guidance(category) outcome = lib.failure_outcome(category, self.enforce, self.soft_fail) @@ -382,9 +391,6 @@ def run(self, event: dict) -> int: author = (pr.get("user") or {}).get("login") or "" log(f"Validating PR #{self.pr_number} ({html_url}) at head {self.validated_sha}") - self.gh.publish_status(self.validated_sha, "pending", - "Checking for a linked Linear issue…", self.run_url) - if not base_branch: error(f"PR #{self.pr_number} has no base branch; refusing to validate.") return 1 @@ -395,10 +401,10 @@ def run(self, event: dict) -> int: return 1 if not protected: log(f"PR targets unprotected branch '{base_branch}' — Linear ticket not required.") - return self.finish_exempt( - f"PR targets the unprotected `{base_branch}` branch — the Linear-ticket " - "requirement does not apply.", - f"Not required for unprotected branch: {base_branch}") + return self.finish_not_required(base_branch) + + self.gh.publish_status(self.validated_sha, "pending", + "Checking for a linked Linear issue…", self.run_url) # Exemptions short-circuit before the Linear query. The actor allow-list is the # non-manual hatch for bot PRs (Dependabot/Renovate never carry a ticket); it is