Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions .github/workflows/linear-ticket.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
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 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.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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) |
Expand Down
31 changes: 22 additions & 9 deletions docs/callers/linear-ticket.md
Original file line number Diff line number Diff line change
@@ -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 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
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
Expand Down Expand Up @@ -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.

Expand All @@ -193,6 +200,12 @@ 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 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
does) publish a red status: it is a real, visible signal that costs nobody a merge. The
Expand Down
19 changes: 14 additions & 5 deletions scripts/linear-ticket/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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
Expand All @@ -36,8 +38,15 @@ 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. 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.
- **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
Expand Down
Loading
Loading