diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml new file mode 100644 index 00000000..ffd76315 --- /dev/null +++ b/.github/workflows/linear-ticket.yml @@ -0,0 +1,213 @@ +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. +# +# 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. +# GitHub gives THIS run the caller's write token and the Linear secret even when the signal +# run (a fork or Dependabot PR) had neither. Non-negotiable constraints (design §6): +# * the signal workflow checks out nothing, runs no PR content, emits no artifact/cache; +# * this validator never downloads that run's artifacts/caches and never checks out the PR +# branch or merge commit — it reads only GitHub-owned data and Linear's API; +# * 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 +# head SHA; branch protection requires THAT context. See docs/callers/linear-ticket.md. +# +# PERMISSIONS the caller must grant (the single job's union — GitHub validates the grant at +# STARTUP, before any `if:`): +# 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 +# +# 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 +# with `Bearer `. Missing/invalid fails the check CLOSED as an infrastructure error, never +# green (design §7). +# +# Caller pattern: docs/callers/linear-ticket.md (the signal + validate pair). Do not use +# `secrets: inherit`; pass only LINEAR_API_TOKEN. + +on: + workflow_call: + inputs: + workflows_ref: + description: >- + Full 40-hex commit SHA of THIS repo to load the validator scripts from. Pin to the + SAME SHA as the caller's `uses:` — a floating ref would run new scripts under an old + workflow. Required; validated to be a full lowercase SHA and an ancestor of this + repo's main before checkout. + type: string + required: true + team-keys: + description: >- + Optional comma-separated allow-list of Linear team keys (matched against the + resolved issue's API team.key, never an identifier prefix). Empty (default) accepts + a linked issue from any team visible to the token. Malformed or duplicate entries + fail the run. + type: string + required: false + default: '' + exempt-label: + description: >- + Optional single label that waives the requirement (recommended `linear-exempt`). + Empty disables exemption. Adding/removing it reruns the check. + type: string + required: false + default: '' + exempt-actors: + description: >- + Optional 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 and EMPTY by default — there is no built-in bot bypass; a + repo that lists an actor here accepts that all of that account's PRs merge without a + Linear ticket. + type: string + required: false + default: '' + require-open-issue: + description: >- + When true (default), reject a linked issue whose Linear state.type is + completed/canceled. backlog/unstarted/started/triage pass. + type: boolean + required: false + default: true + enforce: + description: >- + true (default) fails closed on a missing/invalid link or infrastructure error. + false is warn-only: every outcome publishes success but the summary and marker + comment show the verdict enforce mode would have produced. + type: boolean + required: false + default: true + secrets: + LINEAR_API_TOKEN: + description: >- + Value placed verbatim into Linear's Authorization header (personal key raw, or + `Bearer `). Required; a missing token fails the check as an + infrastructure error. + required: true + +permissions: {} + +concurrency: + # One validation per PR branch; a newer push/edit supersedes the in-flight run, and + # validate.sh additionally refetches the head SHA before any terminal status write. + group: linear-ticket-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }} + cancel-in-progress: true + +jobs: + validate: + # Only a completed run of the signal workflow should reach here (the caller filters the + # workflow name + `types: [completed]`); guard the conclusion so a failed/cancelled signal + # run does not trigger a spurious validation. + if: github.event.workflow_run.conclusion == 'success' + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + 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 + steps: + - name: Require a pinned workflows_ref + # workflows_ref runs THIS repo's scripts in a job holding the caller's write token + + # the LINEAR_API_TOKEN secret, so it is a code-execution trust boundary. GitHub does + # NOT enforce `required: true` for workflow_call inputs (an omitted input arrives as '' + # and checkout silently takes the default branch), so validate on TWO axes before + # checkout: + # SHAPE — a full 40-hex lowercase SHA; rejects everything mutable (branch, tag, + # refs/pull/N/head), which could skew between jobs mid-run. + # ANCESTRY — the SHA is reachable from THIS repo's upstream main. Shape proves the + # value is immutable, not WHICH repo authored it: a fork of this PUBLIC + # repo shares the object store and GitHub serves a fork PR's head objects + # from this repo's URL unauthenticated, so a fork-authored 40-hex SHA is + # just as well-shaped and would otherwise run with the caller's token. Only + # merged upstream history may be pinned; no opt-out. Fails CLOSED on infra + # errors. Mirrors pr-area-label.yml / pr-risk.yml. See BE-5546. + env: + WORKFLOWS_REF: ${{ inputs.workflows_ref }} + run: | + set -euo pipefail + # actions/checkout trims `ref`, so strip whitespace before the -z test. Echo only a + # sanitized, bounded form so a multi-line value can't forge ::workflow commands:: in + # this PUBLIC log. + REF="$(printf '%s' "$WORKFLOWS_REF" | tr -d '[:space:]')" + if [ -z "$REF" ]; then + echo "::error::workflows_ref is required; pin it to the same commit SHA as the uses: line (see the caller doc)" + exit 1 + fi + safe_ref=$(printf '%s' "$REF" | tr -c 'A-Za-z0-9._/-' '?'); safe_ref=${safe_ref:0:64} + # Length + character-class, not `grep -Eq '^..$'`: grep anchors per LINE, so a + # multi-line value carrying one SHA-shaped line would pass. Lowercase only — the value + # is handed to checkout verbatim and everything that emits a SHA emits lowercase. + if [ "${#REF}" -ne 40 ] || [ -n "${REF//[0-9a-f]/}" ]; then + echo "::error::workflows_ref must be a full 40-hex lowercase commit SHA of Comfy-Org/github-workflows (got '${safe_ref}'). Branches, tags and PR-head refs are mutable and are rejected before checkout." + exit 1 + fi + # ANCESTRY. The upstream URL is a LITERAL: inside a reusable workflow no github context + # names this repo, so a variable would be an alias a fork could point at itself. Two + # bounded fetches (--filter=blob:none — no file content): depth-1 proves the SHA is in + # this repo's object network; the second brings main to walk down to the pin. The fetch + # retries (a transient github.com error must not red the fleet); the verdict does not. + scratch=$(mktemp -d) || { echo "::error::ancestry check for workflows_ref (${safe_ref}) could not allocate scratch space; failing closed."; exit 1; } + trap 'rm -rf "$scratch"' EXIT + git init -q "$scratch" || { echo "::error::ancestry check for workflows_ref (${safe_ref}) could not init a scratch repo; failing closed."; exit 1; } + fetch_upstream() { + for attempt in 1 2 3; do + if timeout 40 git -C "$scratch" -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=30 \ + fetch --quiet --no-tags --filter=blob:none "$@"; then + return 0 + fi + [ "$attempt" -lt 3 ] && sleep $((attempt * 5)) + done + return 1 + } + if ! fetch_upstream --depth=1 https://github.com/Comfy-Org/github-workflows "$REF"; then + echo "::error::workflows_ref (${safe_ref}) could not be fetched from Comfy-Org/github-workflows after 3 attempts; failing closed." + exit 1 + fi + if ! fetch_upstream https://github.com/Comfy-Org/github-workflows +refs/heads/main:refs/heads/upstream-main; then + echo "::error::main of Comfy-Org/github-workflows could not be read after 3 attempts, so workflows_ref (${safe_ref}) cannot be shown merged upstream; failing closed." + exit 1 + fi + # --is-ancestor has THREE outcomes: 0 yes, 1 no, >1 git could not answer (infra fault). + # Don't report an infra fault as a hostile pin; both still fail closed, only the message differs. + ancestry_rc=0 + GIT_NO_LAZY_FETCH=1 git -C "$scratch" merge-base --is-ancestor "$REF" upstream-main || ancestry_rc=$? + if [ "$ancestry_rc" -gt 1 ]; then + echo "::error::the ancestry test for workflows_ref (${safe_ref}) could not COMPLETE (git error, not a verdict); failing closed." + exit 1 + fi + if [ "$ancestry_rc" -ne 0 ]; then + echo "::error::workflows_ref (${safe_ref}) is not an ancestor of Comfy-Org/github-workflows main. A well-shaped SHA can still be fork-authored; only merged upstream commits may be pinned. If this is a genuine just-merged pin, re-run." + exit 1 + fi + - name: Checkout validator scripts + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: Comfy-Org/github-workflows + ref: ${{ inputs.workflows_ref }} + path: .linear-ticket-tools + persist-credentials: false + - name: Set up Python + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 + with: + python-version: '3.12' + - name: Validate the linked Linear ticket + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + LINEAR_API_TOKEN: ${{ secrets.LINEAR_API_TOKEN }} + TEAM_KEYS: ${{ inputs.team-keys }} + EXEMPT_LABEL: ${{ inputs.exempt-label }} + EXEMPT_ACTORS: ${{ inputs.exempt-actors }} + REQUIRE_OPEN_ISSUE: ${{ inputs.require-open-issue }} + ENFORCE: ${{ inputs.enforce }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: python3 .linear-ticket-tools/scripts/linear-ticket/validate.py diff --git a/.github/workflows/test-linear-ticket.yml b/.github/workflows/test-linear-ticket.yml new file mode 100644 index 00000000..bc72eda8 --- /dev/null +++ b/.github/workflows/test-linear-ticket.yml @@ -0,0 +1,51 @@ +# CONTRACT: this is one of THIS repo's own path-filtered script tests, NOT a reusable +# workflow. It is not callable and has no caller pattern: +# TRIGGERS — `pull_request` and `push` to main, both filtered to scripts/linear-ticket/** +# and this file. A change elsewhere in the repo does not run it. +# INPUTS — none. SECRETS — none. Read-only `contents: read`; the suite is hermetic and +# makes no network call. +# The reusable workflow these scripts back is .github/workflows/linear-ticket.yml. + +name: Test linear-ticket scripts + +# Runs the hermetic lib.py unittest suite for the linear-ticket gate. The gate decides +# whether every consuming repo's PRs can merge, so a regression in the policy filter, +# candidate extraction, or error classification silently passes or blocks PRs — cheap to +# guard with a unit run on change. The real-Linear behaviours (URL canonicalization, +# attachment timing) are proven in the pilot, not here. + +on: + pull_request: + paths: + - 'scripts/linear-ticket/**' + - '.github/workflows/test-linear-ticket.yml' + # linear-ticket.yml passes the scripts their whole input contract through env, so a + # change to it can break the suite without touching a file under scripts/linear-ticket/. + - '.github/workflows/linear-ticket.yml' + push: + branches: [main] + paths: + - 'scripts/linear-ticket/**' + - '.github/workflows/test-linear-ticket.yml' + - '.github/workflows/linear-ticket.yml' + +permissions: + contents: read + +jobs: + test: + name: unittest + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Set up Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: '3.12' + - name: Compile the validator (syntax gate for validate.py, which the suite does not import) + run: python3 -m py_compile scripts/linear-ticket/lib.py scripts/linear-ticket/validate.py + - name: lib suite + run: python3 -m unittest discover -s scripts/linear-ticket/tests -p 'test_*.py' -v diff --git a/README.md b/README.md index d7e8d3e1..8e3f03e6 100644 --- a/README.md +++ b/README.md @@ -15,6 +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 (same diagnosis, always-green status); 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/README.md b/docs/callers/README.md index 850f48e9..19bc1dbd 100644 --- a/docs/callers/README.md +++ b/docs/callers/README.md @@ -17,6 +17,7 @@ per-workflow pages give you a complete, copy-pasteable caller: | `assign-prs-to-author.yml` | [assign-prs-to-author.md](assign-prs-to-author.md) | nothing | | `stale.yml` | [stale.md](stale.md) | `SLACK_BOT_TOKEN` (optional) | | `detect-unreviewed-merge.yml` | [detect-unreviewed-merge.md](detect-unreviewed-merge.md) | `UNREVIEWED_MERGES_TOKEN` | +| `linear-ticket.yml` | [linear-ticket.md](linear-ticket.md) | `LINEAR_API_TOKEN` + a two-workflow caller | Everything below applies to all of them. Read it once. @@ -110,13 +111,20 @@ validation in CI (`pinact`, `zizmor`) **will fail** a bare tag. ### `workflows_ref` must match your pin -Several workflows (`groom`, `cursor-review`, `pr-size`, `agents-md-integrity`) -load assets — agent briefs, review prompts, checker scripts — from a ref **at run -time**, controlled by the `workflows_ref` input. It defaults to `main`. +Several workflows load assets — agent briefs, review prompts, checker scripts — +from a ref **at run time**, controlled by the `workflows_ref` input. In every +case, set it to the **same SHA** as your `uses:` pin. -That default means a caller pinned to a SHA runs **old workflow + newest -assets**. Usually harmless, occasionally not, and always confusing. Set it -explicitly to the same SHA: +- `groom`, `cursor-review`, `pr-size`, `agents-md-integrity` default it to + `main`. That default means a caller pinned to a SHA runs **old workflow + + newest assets** — usually harmless, occasionally not, and always confusing. +- `pr-risk`, `pr-derisk`, `refresh-reviewers`, and `linear-ticket` make it + **required with no default** and reject any value that is not a full commit SHA + of this repo *before* checkout, so an omitted or mismatched ref fails the run + rather than silently loading `main`. There is nothing to "leave at `main`" — + you must pass the `uses:` SHA. + +Either way, set it explicitly to the same SHA: ```yaml uses: Comfy-Org/github-workflows/.github/workflows/groom.yml@07154fb… diff --git a/docs/callers/linear-ticket.md b/docs/callers/linear-ticket.md new file mode 100644 index 00000000..e4428373 --- /dev/null +++ b/docs/callers/linear-ticket.md @@ -0,0 +1,163 @@ +# `linear-ticket.yml` — require a linked Linear issue on every PR + +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. + +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 +existence + linkage + traceability; **relevance is still a code-review job**. + +### Why two workflows + +The validator needs the Linear secret and a write token, which GitHub withholds from fork and +Dependabot PR runs. The fix is the standard **`pull_request` → `workflow_run`** split: + +- an unprivileged **signal** workflow runs on the PR (`contents: read`, no secret, checks out + nothing), and +- a privileged **validate** workflow runs on `workflow_run: completed` of the signal workflow + 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`** +on the PR head SHA; you require **that context** once warn-only observation is done. + +## Prerequisites + +| | | +|---|---| +| `secrets.LINEAR_API_TOKEN` | **Required.** The value placed verbatim into Linear's `Authorization` header — a personal API key **raw**, or an OAuth actor-auth access token prefixed with `Bearer` followed by one space. Missing/invalid fails the check *closed* as an infrastructure error (never green). | +| A Linear→GitHub integration | The workspace's GitHub integration must be connected so Linear creates the PR attachments this check reads. | + +## Caller — two files + +### 1. `.github/workflows/linear-ticket-signal.yml` (unprivileged, no-op) + +```yaml +name: Linear Ticket Signal # this exact name is referenced by the validate workflow + +on: + pull_request: + types: [opened, edited, reopened, ready_for_review, synchronize, labeled, unlabeled] + +permissions: + contents: read + +jobs: + signal: + runs-on: ubuntu-latest + steps: + - name: Signal + run: echo "Signalling the Linear ticket validator (no PR content is checked out)." +``` + +The `labeled`/`unlabeled` types are required so adding or removing the exemption label reruns +the check. This workflow checks out nothing, runs no PR content, and emits no artifact — that +is what makes the `workflow_run` privilege boundary safe. + +### 2. `.github/workflows/linear-ticket-validate.yml` (privileged, calls this reusable) + +```yaml +name: Linear Ticket + +on: + workflow_run: + workflows: ["Linear Ticket Signal"] # must match the signal workflow's name exactly + types: [completed] + +jobs: + validate: + permissions: + 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 + uses: Comfy-Org/github-workflows/.github/workflows/linear-ticket.yml@ # v1 + with: + workflows_ref: + # team-keys: BE,ENG # optional; LEAVE EMPTY (default) unless you truly want + # # team scoping — a restricted list fails cross-team PRs + # exempt-label: linear-exempt # optional; empty disables exemption + # exempt-actors: dependabot[bot],renovate[bot] # optional; bot PRs skip the check + # require-open-issue: true # default + enforce: false # WARN-ONLY during rollout; flip to true when ready + secrets: + LINEAR_API_TOKEN: ${{ secrets.LINEAR_API_TOKEN }} +``` + +Do **not** use `secrets: inherit` — pass only `LINEAR_API_TOKEN`. + +## Required permissions + +```yaml +actions: read +contents: read +pull-requests: write +statuses: write +``` + +**Grant the whole union.** A reusable workflow can only narrow the caller's token, and GitHub +validates the nested job's declared `permissions:` against this block at **startup** — before +any `if:` runs. A short grant fails the whole run with an opaque "workflow file issue" and no +job-level detail. + +## Inputs + +| Input | Default | Notes | +|---|---|---| +| `workflows_ref` | — (**required**) | Pin to the SAME full commit SHA as `uses:`. Validated to be a full 40-hex lowercase SHA **and an ancestor of this repo's main** before checkout — a branch, tag, short SHA, or fork-authored SHA fails the run. | +| `team-keys` | `''` | Comma-separated allow-list matched against the resolved issue's API `team.key`, never an identifier prefix. **Leave empty (recommended)** unless a repo genuinely wants team scoping — a restricted list fails a cross-team PR on first contact. Malformed or duplicate entries fail the run. | +| `exempt-label` | `''` | Single label that waives the requirement (recommended `linear-exempt`). Empty disables exemption. | +| `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: every outcome publishes success, but the summary and marker comment show the verdict enforce mode would have produced. | + +## Rollout (warn-only first) + +1. Land both caller files with `enforce: false`. 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). +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 + no GitHub event, so the status stays red until someone re-runs the workflow or edits the PR + (the failure comment says this). Count how often that happens during the warn-only week. If + it's rare, the re-run instruction is enough; if it's frequent, the fix is a + `repository_dispatch` driven by a Linear webhook — not a larger retry budget — and is a + deliberate v2 follow-up, out of scope here. +4. Decide bot-PR handling: set `exempt-actors` (e.g. `dependabot[bot],renovate[bot]`) so + dependency PRs pass without hand-labelling each one. +5. Flip `enforce: true`. Leave the check non-required for a short window. +6. Add the **`linear-ticket`** status context to your `main` ruleset as a required check. + +Nothing here changes branch protection automatically — the last step is a manual repo-admin action. + +## Gotchas + +**The required check is a commit *status*, not the job.** Require the `linear-ticket` context in +your ruleset; do not require the `Linear Ticket / validate` job — it runs on the default branch +against the workflow_run event and is not tied to the PR's merge check. + +**A manual link created after a red run does not emit a GitHub event.** After linking in Linear, +either re-run the failed validate workflow or edit the PR title/body to trigger a fresh +`edited` event. The failure comment says exactly this. + +**Snapshot, not continuous.** A green check means the issue was linked and met policy *when that +commit's check ran*. Moving the issue to Done later does not retroactively fail an existing +check; the next PR event re-evaluates against current Linear state. + +**Fails closed on infrastructure errors.** An auth/schema/timeout/rate-limit-exhaustion error is +reported as an infrastructure failure (red in enforce mode), not as an invalid ticket — a broken +credential must not silently disable the org-wide control. Availability is handled by bounded +retry, per-branch concurrency, the warn-only rollout, and the auditable exemption label. + +**Store the token in the right form.** Personal API key → raw. OAuth actor-auth token → prefixed +with `Bearer` followed by one space. The value is dropped straight into the `Authorization` header. diff --git a/scripts/linear-ticket/README.md b/scripts/linear-ticket/README.md new file mode 100644 index 00000000..6fb530af --- /dev/null +++ b/scripts/linear-ticket/README.md @@ -0,0 +1,60 @@ +# `scripts/linear-ticket/` — the linked-Linear-ticket gate + +The scripts behind [`linear-ticket.yml`](../../.github/workflows/linear-ticket.yml). A +consumer repo runs the reusable workflow via a thin two-workflow caller (signal + validate) +and keeps no logic of its own; this directory holds the decision path, loaded from the +`workflows_ref` SHA the caller pins. Standard-library Python only (no third-party deps), +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. | + +## 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: + +- 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 + prefix or a state *name* the author controls. +- Candidate identifiers extracted from branch/title/body (`extract_candidates`) are + **diagnostics only** — capped at 20, resolved in one batched query — and can turn a red + check's *message* from "no candidate found" into "referenced but not linked", never turn it + green. +- "Any issue remains" is the pass rule: a PR linked to several tickets passes when at least + one linked issue satisfies policy. + +## Security & failure model + +- Runs in the **privileged `workflow_run` job**; every PR-derived value is untrusted DATA + passed through `gh api` argument lists / stdin and GraphQL variables. No PR code is checked + out or executed. +- 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. +- **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 + bounded budget (2s, 4s, 8s, 16s over five attempts). +- Comment I/O is **best-effort**: a comment failure is warned, never changes the verdict. +- `enforce: false` is **warn-only** — every outcome publishes success, but the summary and + marker comment show the verdict enforce mode would have produced. + +## Running the tests + +```bash +python3 -m unittest discover -s scripts/linear-ticket/tests -p 'test_*.py' -v +python3 -m py_compile scripts/linear-ticket/lib.py scripts/linear-ticket/validate.py +``` + +The hermetic suite covers the design's acceptance cases that live in pure functions +(extraction/dedup/cap, `team-keys` validation, the policy gate incl. multi-link and +state/team handling, error classification, category selection, the diagnostic-query +builder). The **real-Linear behaviours** — URL canonicalization and attachment timing — are +proven in the pilot, not by mocks (design §11). diff --git a/scripts/linear-ticket/lib.py b/scripts/linear-ticket/lib.py new file mode 100644 index 00000000..d582ec92 --- /dev/null +++ b/scripts/linear-ticket/lib.py @@ -0,0 +1,249 @@ +"""Pure, network-free core of the linear-ticket gate. + +Everything here is a function with no side effect: pull candidate identifiers out of +untrusted PR text, validate the team-key policy input, apply the team/state policy to +Linear's attachment response, classify a Linear error as retryable or terminal, pick a +failure category, and render the copy that explains it. tests/test_lib.py imports this +module and exercises the whole decision path without a single API call. The side-effecting +orchestration (resolve the PR, query Linear, publish the commit status, upsert the comment) +lives in validate.py, which imports this. + +The invariant this file underwrites (design §3): the ONLY thing that turns the check green +is an attachment Linear returns for THIS PR's canonical html_url whose issue satisfies +policy — filter_issues below. Candidate identifiers extracted from branch, title, and body +(extract_candidates) are diagnostics ONLY; they explain why a check is red, they can never +make it green. That is why the extractor is deliberately generic and the policy filter reads +the resolved issue's real API ``team.key`` and ``state.type``, never a prefix the author typed. + +Standard library only (no third-party deps), matching this repo's Python convention. +""" + +from __future__ import annotations + +import re + +# The hidden marker on the single PR comment this gate maintains. validate.py finds its +# existing comment by this exact string, so it must never change casually. +MARKER = "" + +# 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" + +# 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]+") +# A valid Linear team key: uppercase, starts with a letter. +_TEAM_KEY_RE = re.compile(r"^[A-Z][A-Z0-9]*$") + +MAX_CANDIDATES = 20 +_CLOSED_STATE_TYPES = frozenset({"completed", "canceled"}) + + +def extract_candidates(text: str) -> list[str]: + """Up to 20 unique UPPERCASE candidate identifiers, first-seen order. + + Diagnostics only: they let a failure comment say "you referenced BE-1234 but Linear + has not linked it", never a pass. The 20-cap means author-controlled text cannot fan + out into an unbounded diagnostic query. + """ + seen: dict[str, None] = {} + for match in _CANDIDATE_RE.findall(text or ""): + seen.setdefault(match.upper(), None) + if len(seen) >= MAX_CANDIDATES: + break + return list(seen) + + +def normalize_team_keys(raw: str) -> list[str]: + """Parse the caller's comma-separated ``team-keys`` input into normalized keys. + + Empty/whitespace-only input -> ``[]`` (the "accept any visible team" default). Raises + ValueError — rejecting the whole run as a caller misconfiguration — if any non-empty + entry is malformed or a duplicate (design §5.1). Fail closed here rather than silently + dropping a key, because a dropped key would quietly widen the policy the caller asked + to narrow. + """ + if not (raw or "").strip(): + return [] + keys: list[str] = [] + for part in raw.split(","): + part = part.strip().upper() + if not part: + continue # tolerate a stray "BE,,ENG" empty field + if not _TEAM_KEY_RE.match(part): + raise ValueError(f"malformed team key: {part!r}") + if part in keys: + raise ValueError(f"duplicate team key: {part!r}") + keys.append(part) + return keys + + +def parse_actor_list(raw: str) -> list[str]: + """Parse the caller's comma-separated ``exempt-actors`` input into lowercased logins. + + Empty/whitespace-only input -> ``[]`` (no actor is exempt — the secure default; the + design ships no built-in bot bypass). Logins carry ``[bot]`` suffixes and other punctuation + so, unlike team keys, they are not shape-validated — an unknown login simply never matches. + Lowercased because GitHub logins are compared case-insensitively. + """ + return [part.strip().lower() for part in (raw or "").split(",") if part.strip()] + + +def filter_issues(nodes: list[dict], team_keys: list[str], require_open: bool) -> list[str]: + """THE GATE. Identifiers of the linked issues that satisfy policy, sorted unique. + + Not every link is validated: this returns the SUBSET that passes, and the caller treats a + non-empty result as a pass. So a PR linked to one open and one canceled issue passes on the + open one — "any linked issue satisfies policy", by design (below), not "every link is valid". + + ``nodes`` is Linear's ``attachmentsForURL.nodes`` array; each node carries + ``issue{identifier, team{key}, state{type}}``. Empty result == nothing passes. Policy: + + * team — keep an issue iff ``team_keys`` is empty OR its API-returned ``team.key`` is in + the allow-list. Matched against the RESOLVED key, never a prefix. + * state — when ``require_open``, reject ``state.type`` completed/canceled; backlog, + unstarted, started, and triage pass. A missing ``state.type`` does not block. + + "Any issue remains" is the rule: a PR linked to several tickets passes when at least one + linked issue satisfies policy (design §5). + """ + passing: set[str] = set() + for node in nodes or []: + issue = (node or {}).get("issue") + if not issue: + continue + if team_keys: + key = ((issue.get("team") or {}).get("key")) or "" + if key not in team_keys: + continue + if require_open: + state_type = ((issue.get("state") or {}).get("type")) or "" + if state_type in _CLOSED_STATE_TYPES: + continue + identifier = issue.get("identifier") + if identifier: + passing.add(identifier) + return sorted(passing) + + +def count_linked(nodes: list[dict]) -> int: + """How many attachments carry a non-null issue (linked issues, before policy). + + Distinguishes "nothing linked yet" (retry / not-linked copy) from "something linked but + fails policy" (policy_mismatch). + """ + return sum(1 for node in (nodes or []) if (node or {}).get("issue")) + + +def classify_linear_error(http_status: int | None, error_codes: list[str]) -> str: + """"retryable" or "terminal". + + Linear signals rate limiting as HTTP 400 with GraphQL error code RATELIMITED (design + §8), so the codes are checked first. 408/429/5xx are transient. Everything else — auth, + schema, malformed — is terminal and fails closed as an infrastructure error, never as an + invalid ticket. + """ + if "RATELIMITED" in (error_codes or []): + return "retryable" + if http_status in (408, 429, 500, 502, 503, 504): + return "retryable" + return "terminal" + + +def select_failure_category(infra_error: bool, linked: int, referenced: int) -> str: + """The one category that explains a red check, in priority order (design §5 step 6). + + * infra_error — Linear could not be queried (auth/schema/exhausted retries). + * policy_mismatch — issue(s) ARE linked to this PR but every one fails team/state policy. + * exists_not_linked — no link, but an identifier was REFERENCED in branch/title/body. + * no_candidate — no link and no identifier referenced anywhere. + + The boundary between the last two is whether an identifier was referenced at all; the + batched diagnostic lookup (count_resolved_candidates) only enriches the DETAIL line, it + does not move the category — so the copy can never say "no identifier detected" while the + detail lists one. + """ + if infra_error: + return "infra_error" + if linked > 0: + return "policy_mismatch" + if referenced > 0: + return "exists_not_linked" + return "no_candidate" + + +_GUIDANCE = { + "no_candidate": ( + "No linked Linear issue was found for this PR, and no issue identifier was detected " + "in the branch name, title, or body. Link a Linear issue by any supported method — " + "put its identifier (e.g. `BE-1234`) in the branch name, PR title, or body " + "(`Closes BE-1234`), or paste this PR's URL into the issue in Linear." + ), + "exists_not_linked": ( + "An issue identifier was referenced, but Linear has not linked that issue to this PR " + "yet. A referenced identifier in text is not a link. Either use a supported auto-link " + "(identifier in the branch name, title, or a `Closes`/`Fixes`/`Resolves` line in the " + "body) or paste this PR's canonical URL into the issue in Linear. Automatic links are " + "created a few seconds after the PR event, so a brand-new link may just need a re-run." + ), + "policy_mismatch": ( + "A Linear issue is linked to this PR, but no linked issue satisfies this repository's " + "policy — every linked issue is either in a completed/canceled state or belongs to a " + "team this check does not accept. Link an issue from an accepted team that is not " + "closed, or move the existing issue back to an open state." + ), + "infra_error": ( + "This check could not be completed because Linear could not be queried " + "(authentication, schema, timeout, or rate-limit exhaustion). This is an " + "infrastructure error, not a verdict on your ticket — it fails closed on purpose so a " + "broken credential cannot silently disable the control. Re-run the check; if it keeps " + "failing, contact the repository owners." + ), +} + + +def failure_guidance(category: str) -> str: + """The fixed, category-specific paragraph shown in the PR comment and job summary. + + Specifics (identifiers, candidate list, rerun link) are appended by validate.py; this + keeps the reusable copy testable and consistent across repos. Raises KeyError on an + unknown category so a typo fails loudly rather than shipping empty copy. + """ + return _GUIDANCE[category] + + +def build_diagnostic_query(candidates: list[str]) -> str: + """ONE aliased GraphQL query (``c0: issueSearch(...) c1: ...``) resolving all candidates. + + Design §8: at most one batched diagnostic query. Raises ValueError if there are no + candidates. Candidates from extract_candidates are strictly ``[A-Z0-9-]+``, so embedding + them in a double-quoted GraphQL string literal is safe; this re-asserts that invariant so + a future caller cannot smuggle a quote through. + """ + aliases = [] + for i, identifier in enumerate(candidates or []): + if not re.match(r"^[A-Z0-9-]+$", identifier): + continue + aliases.append(f' c{i}: issueSearch(query: "{identifier}", first: 1) {{ nodes {{ identifier }} }}') + if not aliases: + raise ValueError("no candidates to build a diagnostic query from") + return "query {\n" + "\n".join(aliases) + "\n}\n" + + +def count_resolved_candidates(response: dict) -> int: + """How many aliased issueSearch results returned at least one node. + + Best-effort: a malformed/absent ``data`` counts as 0, so a diagnostic hiccup degrades to + the "no_candidate"/"exists_not_linked" copy rather than erroring. + """ + if not isinstance(response, dict): + return 0 + data = response.get("data") or {} + if not isinstance(data, dict): + return 0 + resolved = 0 + for value in data.values(): + nodes = (value or {}).get("nodes") if isinstance(value, dict) else None + if nodes: + resolved += 1 + return resolved diff --git a/scripts/linear-ticket/tests/test_lib.py b/scripts/linear-ticket/tests/test_lib.py new file mode 100644 index 00000000..de777f44 --- /dev/null +++ b/scripts/linear-ticket/tests/test_lib.py @@ -0,0 +1,216 @@ +"""Hermetic tests for lib.py — no network. + +Covers the design's §11 acceptance cases that live in pure functions: candidate +extraction/dedup/cap, team-key input validation, the attachment policy gate (incl. multi- +link and state/team handling), Linear error classification, failure-category selection, the +failure copy, and the batched diagnostic-query builder. The real-Linear behaviours (URL +canonicalization, attachment timing) are proven in the pilot, not here. +""" + +import os +import sys +import unittest + +sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +import lib # noqa: E402 + + +class ExtractCandidates(unittest.TestCase): + def test_uppercases(self): + self.assertEqual(lib.extract_candidates("fixes be-1234 please"), ["BE-1234"]) + + def test_dedupes_case_insensitively_first_seen(self): + self.assertEqual( + lib.extract_candidates("be-1234 ENG-7 BE-1234 eng-7"), ["BE-1234", "ENG-7"] + ) + + def test_reads_multiline_concatenation(self): + self.assertEqual( + lib.extract_candidates("feat/be-1-x\nTitle ENG-2\nCloses OPS-3"), + ["BE-1", "ENG-2", "OPS-3"], + ) + + def test_no_identifier_is_empty(self): + self.assertEqual(lib.extract_candidates("just a normal title"), []) + + def test_caps_at_20(self): + text = " ".join(f"AB-{i}" for i in range(1, 26)) + self.assertEqual(len(lib.extract_candidates(text)), 20) + + def test_none_text_is_empty(self): + self.assertEqual(lib.extract_candidates(None), []) + + +class NormalizeTeamKeys(unittest.TestCase): + def test_empty_accepts_any(self): + self.assertEqual(lib.normalize_team_keys(""), []) + + def test_whitespace_only_accepts_any(self): + self.assertEqual(lib.normalize_team_keys(" "), []) + + def test_trims_and_uppercases(self): + self.assertEqual(lib.normalize_team_keys(" be , eng "), ["BE", "ENG"]) + + def test_tolerates_stray_empty_field(self): + self.assertEqual(lib.normalize_team_keys("BE,,ENG"), ["BE", "ENG"]) + + def test_duplicate_rejected(self): + with self.assertRaises(ValueError): + lib.normalize_team_keys("BE,be") + + def test_malformed_rejected(self): + with self.assertRaises(ValueError): + lib.normalize_team_keys("BE,EN!G") + + def test_leading_digit_rejected(self): + with self.assertRaises(ValueError): + lib.normalize_team_keys("1BE") + + +class ParseActorList(unittest.TestCase): + def test_empty_is_no_exemption(self): + self.assertEqual(lib.parse_actor_list(""), []) + self.assertEqual(lib.parse_actor_list(" "), []) + + def test_lowercases_and_trims(self): + self.assertEqual( + lib.parse_actor_list(" Dependabot[bot] , renovate[bot] "), + ["dependabot[bot]", "renovate[bot]"], + ) + + def test_tolerates_stray_empty_field(self): + self.assertEqual(lib.parse_actor_list("a,,b"), ["a", "b"]) + + +def _issue(identifier, key, state): + return {"issue": {"identifier": identifier, "team": {"key": key}, "state": {"type": state}}} + + +class FilterIssues(unittest.TestCase): + LINKED_OPEN_BE = [_issue("BE-1", "BE", "started")] + LINKED_DONE_BE = [_issue("BE-1", "BE", "completed")] + LINKED_OPEN_OPS = [_issue("OPS-9", "OPS", "backlog")] + MIXED = [{"issue": None}, _issue("BE-2", "BE", "triage")] + MULTI = [_issue("BE-1", "BE", "canceled"), _issue("ENG-5", "ENG", "started")] + + def test_canonical_open_passes_any_team(self): + self.assertEqual(lib.filter_issues(self.LINKED_OPEN_BE, [], True), ["BE-1"]) + + def test_empty_attachments_no_pass(self): + self.assertEqual(lib.filter_issues([], [], True), []) + + def test_completed_rejected_when_require_open(self): + self.assertEqual(lib.filter_issues(self.LINKED_DONE_BE, [], True), []) + + def test_completed_accepted_when_not_require_open(self): + self.assertEqual(lib.filter_issues(self.LINKED_DONE_BE, [], False), ["BE-1"]) + + def test_restricted_accepts_matching_team(self): + self.assertEqual(lib.filter_issues(self.LINKED_OPEN_BE, ["BE", "ENG"], True), ["BE-1"]) + + def test_restricted_rejects_other_team(self): + self.assertEqual(lib.filter_issues(self.LINKED_OPEN_OPS, ["BE", "ENG"], True), []) + + def test_null_issue_ignored_real_one_passes(self): + self.assertEqual(lib.filter_issues(self.MIXED, [], True), ["BE-2"]) + + def test_multi_passes_when_one_satisfies(self): + self.assertEqual(lib.filter_issues(self.MULTI, [], True), ["ENG-5"]) + + def test_multi_empty_when_restricted_excludes_open_one(self): + self.assertEqual(lib.filter_issues(self.MULTI, ["BE"], True), []) + + def test_count_linked(self): + self.assertEqual(lib.count_linked(self.MIXED), 1) + self.assertEqual(lib.count_linked([]), 0) + self.assertEqual(lib.count_linked(self.MULTI), 2) + + +class ClassifyLinearError(unittest.TestCase): + def test_ratelimited_is_retryable_even_on_400(self): + self.assertEqual(lib.classify_linear_error(400, ["RATELIMITED"]), "retryable") + + def test_503_retryable(self): + self.assertEqual(lib.classify_linear_error(503, []), "retryable") + + def test_429_retryable(self): + self.assertEqual(lib.classify_linear_error(429, []), "retryable") + + def test_auth_terminal(self): + self.assertEqual(lib.classify_linear_error(401, ["AUTHENTICATION_ERROR"]), "terminal") + + def test_schema_400_terminal(self): + self.assertEqual(lib.classify_linear_error(400, ["GRAPHQL_VALIDATION_FAILED"]), "terminal") + + +class SelectFailureCategory(unittest.TestCase): + def test_infra_dominates(self): + self.assertEqual(lib.select_failure_category(True, 0, 0), "infra_error") + + def test_infra_dominates_even_with_links(self): + self.assertEqual(lib.select_failure_category(True, 2, 3), "infra_error") + + def test_linked_but_policy(self): + self.assertEqual(lib.select_failure_category(False, 1, 0), "policy_mismatch") + + def test_referenced_is_exists_not_linked(self): + self.assertEqual(lib.select_failure_category(False, 0, 2), "exists_not_linked") + + def test_referenced_count_decides_not_resolution(self): + self.assertEqual(lib.select_failure_category(False, 0, 1), "exists_not_linked") + + def test_nothing_is_no_candidate(self): + self.assertEqual(lib.select_failure_category(False, 0, 0), "no_candidate") + + +class FailureGuidance(unittest.TestCase): + def test_every_category_non_empty(self): + for category in ("no_candidate", "exists_not_linked", "policy_mismatch", "infra_error"): + self.assertTrue(lib.failure_guidance(category).strip()) + + def test_unknown_category_raises(self): + with self.assertRaises(KeyError): + lib.failure_guidance("bogus") + + +class DiagnosticQuery(unittest.TestCase): + def test_empty_raises(self): + with self.assertRaises(ValueError): + lib.build_diagnostic_query([]) + + def test_one_alias_per_candidate(self): + query = lib.build_diagnostic_query(["BE-1", "ENG-2"]) + self.assertEqual(query.count("issueSearch"), 2) + self.assertIn('query: "BE-1"', query) + self.assertIn("c0: issueSearch", query) + self.assertIn("c1: issueSearch", query) + + def test_count_resolved(self): + resp = {"data": {"c0": {"nodes": [{"identifier": "BE-1"}]}, "c1": {"nodes": []}}} + self.assertEqual(lib.count_resolved_candidates(resp), 1) + + def test_count_resolved_malformed_is_zero(self): + self.assertEqual(lib.count_resolved_candidates({}), 0) + self.assertEqual(lib.count_resolved_candidates({"errors": []}), 0) + self.assertEqual(lib.count_resolved_candidates("not a dict"), 0) + + def test_hostile_candidate_skipped(self): + # A candidate carrying a quote / GraphQL syntax must be dropped, never emitted as an + # unescaped literal — this pins the ^[A-Z0-9-]+$ injection guard so a refactor can't + # silently remove it and stay green. (extract_candidates never produces such a value, + # but build_diagnostic_query defends its input independently.) + query = lib.build_diagnostic_query(['BE-1", x: y(q: "', "ENG-2"]) + self.assertEqual(query.count("issueSearch"), 1) + self.assertIn('query: "ENG-2"', query) + self.assertNotIn("x: y(q:", query) + + def test_all_candidates_malformed_raises(self): + # Lowercase never survives extract_candidates, but if every input is unusable the + # builder must raise rather than emit an empty (invalid) query. + with self.assertRaises(ValueError): + lib.build_diagnostic_query(["be-1"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/linear-ticket/validate.py b/scripts/linear-ticket/validate.py new file mode 100644 index 00000000..6d990c1e --- /dev/null +++ b/scripts/linear-ticket/validate.py @@ -0,0 +1,532 @@ +#!/usr/bin/env python3 +"""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 +attachmentsForURL for the PR's canonical html_url, apply the policy gate, run one batched +diagnostic query, and maintain exactly one marker PR comment. + +It runs in the PRIVILEGED workflow_run job, so every value derived from the PR (branch, +title, body, labels, URL) is untrusted DATA: it is passed to Linear through GraphQL +variables and to GitHub through ``gh api`` argument lists / stdin, never interpolated into a +query. No PR code is checked out or executed. + +Contract (all via env, set by linear-ticket.yml): + GH_TOKEN caller GITHUB_TOKEN, for ``gh api`` (statuses:write, pull-requests:write) + GH_REPO owner/repo (github.repository) + LINEAR_API_TOKEN value placed verbatim into Linear's Authorization header + GITHUB_EVENT_PATH workflow_run event payload + TEAM_KEYS raw ``team-keys`` input (comma-separated; empty = any team) + EXEMPT_LABEL exemption label name; empty disables exemption + REQUIRE_OPEN_ISSUE "true"/"false" + ENFORCE "true" (fail closed) / "false" (warn-only: always green, same diagnosis) + 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) + GITHUB_STEP_SUMMARY written with the human-readable outcome + +Standard library only; GitHub via the ``gh`` CLI (as cursor-review's post-review.py does), +Linear via urllib (as refresh-reviewers' generate.py does). +""" + +from __future__ import annotations + +import json +import os +import subprocess +import sys +import time +import urllib.error +import urllib.request + +import lib + +LINEAR_API_URL = os.environ.get("LINEAR_API_URL") or "https://api.linear.app/graphql" +BACKOFF_SECONDS = (2, 4, 8, 16) # between five attempts + +ATTACHMENTS_QUERY = """query PullRequestAttachments($url: String!) { + attachmentsForURL(url: $url, first: 20) { + nodes { id url issue { id identifier team { key } state { type } } } + } +}""" + + +# ── logging (stderr; ::error::/::warning:: are GitHub Actions annotations) ────────────── +def log(msg: str) -> None: + print(msg, file=sys.stderr, flush=True) + + +def error(msg: str) -> None: + print(f"::error::{msg}", file=sys.stderr, flush=True) + + +def warning(msg: str) -> None: + print(f"::warning::{msg}", file=sys.stderr, flush=True) + + +def summary(msg: str) -> None: + path = os.environ.get("GITHUB_STEP_SUMMARY") + if not path: + return + with open(path, "a", encoding="utf-8") as handle: + handle.write(msg + "\n") + + +# ── GitHub via gh ─────────────────────────────────────────────────────────────────────── +class GitHub: + def __init__(self, repo: str): + self.repo = repo + + def _run(self, args: list[str], stdin: str | None = None) -> subprocess.CompletedProcess: + return subprocess.run( + ["gh", "api", *args], + input=stdin, + text=True, + capture_output=True, + ) + + def get(self, path: str, *, paginate: bool = False): + """GET a JSON endpoint; returns the parsed body or None on failure. + + For a paginated array endpoint, ``gh api --paginate`` merges every page's top-level + JSON array into a single flat array, so ``json.loads`` yields one combined list — no + ``--slurp`` or manual flattening is needed (verified against a multi-page endpoint). + """ + args = [path] + if paginate: + args.insert(0, "--paginate") + result = self._run(args) + if result.returncode != 0: + log(f"gh api {path} failed: {result.stderr.strip()}") + return None + try: + return json.loads(result.stdout or "null") + except json.JSONDecodeError: + return None + + 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. + + 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 + open under a run that meant to publish ``failure``. So a failed critical write is an + error the caller turns into a nonzero job exit, not a swallowed warning. A ``pending`` + write is best-effort (``critical=False``).""" + result = self._run([ + "--method", "POST", f"/repos/{self.repo}/statuses/{sha}", + "-f", f"state={state}", + "-f", f"context={lib.CONTEXT}", + "-f", f"description={description[:140]}", + "-f", f"target_url={target_url}", + ]) + if result.returncode != 0: + emit = error if critical else warning + emit(f"Failed to publish '{state}' status on {sha}: {result.stderr.strip()}") + return False + return True + + def find_marker_comment(self, pr: int) -> int | None: + """The gate's OWN marker comment, or None. + + Match on the marker body AND the Actions-bot author: the marker string is public, so + a contributor could paste it into a comment of their own. Without the author check + the gate would PATCH/DELETE that foreign comment (403 → a swallowed warning, so the + real failure comment never lands and a stale one survives a passing run). The gate's + comments are always authored by ``github-actions[bot]`` (the default GITHUB_TOKEN + identity).""" + comments = self.get(f"/repos/{self.repo}/issues/{pr}/comments?per_page=100", + paginate=True) or [] + for comment in comments: + if lib.MARKER not in (comment.get("body") or ""): + continue + user = comment.get("user") or {} + if user.get("type") == "Bot" and user.get("login") == "github-actions[bot]": + return comment.get("id") + return None + + def upsert_marker_comment(self, pr: int, body: str) -> None: + existing = self.find_marker_comment(pr) + if existing is not None: + result = self._run( + ["--method", "PATCH", f"/repos/{self.repo}/issues/comments/{existing}", + "-F", "body=@-"], + stdin=body, + ) + if result.returncode != 0: + warning(f"Failed to update marker comment {existing}: {result.stderr.strip()}") + else: + result = self._run( + ["--method", "POST", f"/repos/{self.repo}/issues/{pr}/comments", + "-F", "body=@-"], + stdin=body, + ) + if result.returncode != 0: + warning(f"Failed to create marker comment: {result.stderr.strip()}") + + def delete_marker_comment(self, pr: int) -> None: + existing = self.find_marker_comment(pr) + if existing is None: + return + result = self._run(["--method", "DELETE", f"/repos/{self.repo}/issues/comments/{existing}"]) + if result.returncode != 0: + warning(f"Failed to delete marker comment {existing}: {result.stderr.strip()}") + + def current_head_sha(self, pr: int) -> str | None: + data = self.get(f"/repos/{self.repo}/pulls/{pr}") + return (data or {}).get("head", {}).get("sha") + + +# ── Linear via urllib ───────────────────────────────────────────────────────────────── +class LinearResult: + def __init__(self, payload, http_status, error_codes, transport_ok): + self.payload = payload + self.http_status = http_status + self.error_codes = error_codes + self.transport_ok = transport_ok + + +def linear_post(query: str, variables: dict | None, token: str) -> LinearResult: + """POST a GraphQL request. transport_ok=False only when the HTTP exchange never + completed; a 4xx/5xx (which Linear uses for RATELIMITED) still returns transport_ok=True + with the parsed error codes for the caller to classify.""" + body = {"query": query} + if variables: + body["variables"] = variables + data = json.dumps(body).encode("utf-8") + # Authorization verbatim: a personal API key raw, an OAuth token as "Bearer ...". The + # header value is set once here; docs tell the caller which form to store. + req = urllib.request.Request( + LINEAR_API_URL, + data=data, + headers={"Authorization": token, "Content-Type": "application/json"}, + method="POST", + ) + try: + with urllib.request.urlopen(req, timeout=30) as resp: + status, raw, headers = resp.status, resp.read().decode("utf-8"), resp.headers + except urllib.error.HTTPError as exc: + status, raw, headers = exc.code, exc.read().decode("utf-8", "replace"), exc.headers + except (urllib.error.URLError, TimeoutError, OSError) as exc: + log(f"Linear request transport failure: {exc}") + return LinearResult(None, None, [], transport_ok=False) + + _log_rate_limit(headers) + try: + payload = json.loads(raw) if raw else {} + except json.JSONDecodeError: + payload = {} + codes = [ + (e.get("extensions") or {}).get("code") + for e in (payload.get("errors") or []) + if (e.get("extensions") or {}).get("code") + ] + return LinearResult(payload, status, codes, transport_ok=True) + + +def _log_rate_limit(headers) -> None: + """Log Linear's rate-limit headroom for the pilot (design §8), best-effort.""" + for name in headers.keys(): + low = name.lower() + if low.startswith("x-ratelimit-requests-") or low.startswith("x-ratelimit-complexity-"): + log(f"{name}: {headers[name]}") + + +# ── orchestration ─────────────────────────────────────────────────────────────────────── +class Validator: + def __init__(self, gh: GitHub, token: str, team_keys, require_open, enforce, run_url): + self.gh = gh + self.token = token + self.team_keys = team_keys + self.require_open = require_open + self.enforce = enforce + self.run_url = run_url + self.exempt_label = os.environ.get("EXEMPT_LABEL", "") + self.exempt_actors = lib.parse_actor_list(os.environ.get("EXEMPT_ACTORS", "")) + self.pr_number: int | None = None + self.validated_sha: 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.") + return False + return True + + def finish_pass(self, identifiers: str) -> int: + summary("## linear-ticket: ✅ pass") + summary("") + summary(f"Linear has linked this PR to: **{identifiers}**") + self.gh.delete_marker_comment(self.pr_number) + if self._guard_supersession(): + if not self.gh.publish_status(self.validated_sha, "success", + f"Linked Linear issue: {identifiers}", self.run_url, + critical=True): + return 1 + return 0 + + def finish_exempt(self, headline: str, status_desc: str) -> int: + summary("## linear-ticket: ✅ exempt") + summary("") + summary(headline) + self.gh.delete_marker_comment(self.pr_number) + if self._guard_supersession(): + if not self.gh.publish_status(self.validated_sha, "success", status_desc, + self.run_url, critical=True): + return 1 + return 0 + + def finish_fail(self, category: str, detail: str) -> int: + guidance = lib.failure_guidance(category) + if self.enforce: + verdict = f"❌ fail ({category})" + state = "failure" + short = f"No linked Linear issue ({category})" + else: + verdict = f"⚠️ warn-only (would fail: {category})" + state = "success" + short = f"warn-only: would fail ({category})" + + body_lines = [ + lib.MARKER, + "", + f"### Linear ticket check — {verdict}", + "", + guidance, + ] + if detail: + body_lines += ["", detail] + body_lines += [ + "", + "---", + (f"After linking an issue, re-run this check from the [workflow run]({self.run_url}) " + "or edit the PR title/body to trigger a fresh run. A repository maintainer can " + f"waive the requirement by applying the `{self.exempt_label or 'linear-exempt'}` label."), + ] + + # Bail before mutating the PR if a newer run already owns the result: otherwise a + # superseded run overwrites the newer run's comment (leaving a stale failure beside a + # green status) even though its status write is suppressed. + if not self._guard_supersession(): + return 0 if not self.enforce else 1 + + self.gh.upsert_marker_comment(self.pr_number, "\n".join(body_lines)) + + summary(f"## linear-ticket: {verdict}") + summary("") + summary(guidance) + if detail: + summary(detail) + + if not self.gh.publish_status(self.validated_sha, state, short, self.run_url, + critical=True): + return 1 + return 0 if not self.enforce else 1 + + # -- the run --------------------------------------------------------------------------- + def run(self, event: dict) -> int: + wr = event.get("workflow_run") or {} + head_sha = wr.get("head_sha") or "" + if not head_sha: + error("workflow_run.head_sha missing from event") + return 1 + + # 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. + wr_event = wr.get("event") or "" + if wr_event != "pull_request": + error(f"Triggering workflow_run event was '{wr_event}', not 'pull_request'. The " + "signal workflow must run on pull_request; refusing to validate.") + return 1 + + self.pr_number = self._resolve_pr(event, head_sha) + if self.pr_number is None: + return 1 # error already reported + + pr = self.gh.get(f"/repos/{self.gh.repo}/pulls/{self.pr_number}") + if not pr: + error(f"Could not fetch PR #{self.pr_number}") + return 1 + html_url = pr.get("html_url") or "" + self.validated_sha = pr.get("head", {}).get("sha") + branch = pr.get("head", {}).get("ref") or "" + title = pr.get("title") or "" + body = pr.get("body") or "" + labels = [lbl.get("name") for lbl in (pr.get("labels") or [])] + 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) + + # 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. + if self.exempt_label and self.exempt_label in labels: + log(f"PR carries the '{self.exempt_label}' label — exempt.") + return self.finish_exempt( + f"PR carries the `{self.exempt_label}` label — the Linear-ticket requirement " + "is waived.", + f"Exempt via {self.exempt_label} label") + if self.exempt_actors and author.lower() in self.exempt_actors: + log(f"PR author @{author} is in exempt-actors — exempt.") + return self.finish_exempt( + f"PR author `@{author}` is in `exempt-actors` — the Linear-ticket requirement " + "is waived for this bot/automation account.", + f"Exempt via exempt-actors (@{author})") + + nodes, infra_error = self._query_attachments(html_url) + + if not infra_error: + passing = lib.filter_issues(nodes, self.team_keys, self.require_open) + if passing: + joined = ", ".join(passing) + log(f"PASS — linked issue(s): {joined}") + return self.finish_pass(joined) + + return self._diagnose_and_fail(nodes, infra_error, branch, title, body) + + def _resolve_pr(self, event: dict, head_sha: str) -> int | None: + """Exactly one open PR. Same-repo runs carry workflow_run.pull_requests; fork runs do + not, so fall back to the commit->PR association (GitHub-owned data either way).""" + wr = event.get("workflow_run") or {} + candidates = [pr.get("number") for pr in (wr.get("pull_requests") or []) if pr.get("number")] + if not candidates: + assoc = self.gh.get(f"/repos/{self.gh.repo}/commits/{head_sha}/pulls") or [] + candidates = [ + pr.get("number") for pr in assoc + if pr.get("state") == "open" + and (pr.get("base") or {}).get("repo", {}).get("full_name") == self.gh.repo + ] + + open_prs: list[int] = [] + for number in dict.fromkeys(candidates): # de-dup, preserve order + data = self.gh.get(f"/repos/{self.gh.repo}/pulls/{number}") + if data and data.get("state") == "open": + open_prs.append(number) + + if len(open_prs) != 1: + error(f"Expected exactly one open PR associated with {head_sha}, found " + f"{len(open_prs)} (event={wr.get('event')}). Refusing to publish an " + "ambiguous result.") + return None + return open_prs[0] + + def _query_attachments(self, html_url: str): + """attachmentsForURL(this PR) with bounded retry for the async-link race (design §5 + step 4). Returns (nodes, infra_error).""" + nodes: list = [] + infra_error = False + queried_ok = False + for attempt in range(5): + result = linear_post(ATTACHMENTS_QUERY, {"url": html_url}, self.token) + if not result.transport_ok: + log(f"Linear request transport failure (attempt {attempt + 1})") + elif result.error_codes or (result.http_status and result.http_status >= 400): + kind = lib.classify_linear_error(result.http_status, result.error_codes) + if kind == "terminal": + error(f"Linear returned a terminal error (HTTP {result.http_status}, " + f"codes: {result.error_codes or 'none'}). Failing closed as an " + "infrastructure error.") + infra_error = True + break + log(f"Linear returned a retryable error (HTTP {result.http_status}, codes: " + f"{result.error_codes or 'none'}) on attempt {attempt + 1}") + else: + queried_ok = True + nodes = (((result.payload or {}).get("data") or {}).get("attachmentsForURL") + or {}).get("nodes") or [] + if lib.count_linked(nodes) > 0: + break # attachments present — evaluate policy, no reason to retry + log(f"No attachment linked to this PR yet (attempt {attempt + 1})") + if attempt < 4: + time.sleep(BACKOFF_SECONDS[attempt]) + # A run that never once reached Linear (all attempts transport/retryable failures) is an + # infrastructure outage, not a missing ticket — fail closed rather than blaming the + # author (or, in warn-only, going green with the wrong diagnosis). Matches lib.py's + # documented infra_error contract. + if not infra_error and not queried_ok: + error("Linear could not be queried after 5 attempts (transport/retryable errors " + "only). Failing closed as an infrastructure error.") + infra_error = True + return nodes, infra_error + + def _diagnose_and_fail(self, nodes, infra_error, branch, title, body) -> int: + """Diagnostics only — never turns red into green.""" + linked_count = lib.count_linked(nodes) + referenced_count = 0 + resolved_count = 0 + detail = "" + + if not infra_error and linked_count == 0: + candidates = lib.extract_candidates("\n".join([branch, title, body])) + if candidates: + referenced_count = len(candidates) + joined = ", ".join(candidates) + try: + diag_query = lib.build_diagnostic_query(candidates) + diag = linear_post(diag_query, None, self.token) + if diag.transport_ok: + resolved_count = lib.count_resolved_candidates(diag.payload) + except ValueError: + pass + if resolved_count > 0: + detail = (f"Referenced identifiers (not linked): {joined} — at least one " + "resolves to a real Linear issue; link it to this PR.") + else: + detail = f"Referenced identifiers (not linked): {joined}" + + category = lib.select_failure_category(infra_error, linked_count, referenced_count) + if category == "policy_mismatch": + linked_ids = ", ".join( + issue["identifier"] + for node in nodes + if (issue := (node or {}).get("issue")) and issue.get("identifier") + ) + detail = f"Linked but not accepted: {linked_ids}" + + log(f"FAIL category={category} linked={linked_count} referenced={referenced_count} " + f"resolved={resolved_count}") + return self.finish_fail(category, detail) + + +def main() -> int: + repo = os.environ.get("GH_REPO") + event_path = os.environ.get("GITHUB_EVENT_PATH") + token = os.environ.get("LINEAR_API_TOKEN") + + if not repo: + error("GH_REPO is required") + return 1 + if not event_path or not os.path.isfile(event_path): + error("GITHUB_EVENT_PATH is required and must point at the event payload") + return 1 + if not token: + error("LINEAR_API_TOKEN secret is not set; failing closed (infrastructure error)") + return 1 + + try: + team_keys = lib.normalize_team_keys(os.environ.get("TEAM_KEYS", "")) + except ValueError as exc: + error(f"Invalid team-keys input: {exc}. Entries must be uppercase alphanumeric team " + "keys, unique, comma-separated.") + return 1 + + with open(event_path, encoding="utf-8") as handle: + event = json.load(handle) + + require_open = os.environ.get("REQUIRE_OPEN_ISSUE", "true") != "false" + enforce = os.environ.get("ENFORCE", "true") != "false" + run_url = os.environ.get("RUN_URL", "") + + validator = Validator(GitHub(repo), token, team_keys, require_open, enforce, run_url) + return validator.run(event) + + +if __name__ == "__main__": + sys.exit(main())