From d9d6882f238c2f44336293fcc4db3473fa13bc1c Mon Sep 17 00:00:00 2001 From: Luke Mino-Altherr Date: Tue, 18 Aug 2026 09:58:44 -0700 Subject: [PATCH 1/4] feat(linear-ticket): require a linked Linear issue on every PR Add a reusable workflow that gates a PR on a Linear issue Linear has LINKED to that exact PR (attachmentsForURL(html_url)), not a TEAM-123-shaped string in author text. Fork/Dependabot-safe via the pull_request -> workflow_run split: an unprivileged signal workflow, then a privileged validator that publishes the required `linear-ticket` commit status on the refetched PR head SHA. Logic lives in scripts/linear-ticket/ (pure lib.sh + validate.sh orchestration) loaded from a shape- and ancestry-checked workflows_ref; team/state policy reads the resolved API team.key/state.type; extracted identifiers are diagnostics only. Fails closed on infra errors, bounded retry for Linear's async-link race, one marker comment, head-SHA supersession recheck, warn-only mode. Ships a hermetic test suite + path-filtered test workflow and a caller setup guide. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/linear-ticket.yml | 198 ++++++++++++ .github/workflows/test-linear-ticket.yml | 50 +++ README.md | 1 + docs/callers/README.md | 1 + docs/callers/linear-ticket.md | 152 ++++++++++ scripts/linear-ticket/README.md | 60 ++++ scripts/linear-ticket/lib.sh | 204 +++++++++++++ scripts/linear-ticket/tests/test_lib.sh | 121 ++++++++ scripts/linear-ticket/validate.sh | 367 +++++++++++++++++++++++ 9 files changed, 1154 insertions(+) create mode 100644 .github/workflows/linear-ticket.yml create mode 100644 .github/workflows/test-linear-ticket.yml create mode 100644 docs/callers/linear-ticket.md create mode 100644 scripts/linear-ticket/README.md create mode 100644 scripts/linear-ticket/lib.sh create mode 100644 scripts/linear-ticket/tests/test_lib.sh create mode 100644 scripts/linear-ticket/validate.sh diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml new file mode 100644 index 00000000..a48b209c --- /dev/null +++ b/.github/workflows/linear-ticket.yml @@ -0,0 +1,198 @@ +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: '' + 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: 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 }} + REQUIRE_OPEN_ISSUE: ${{ inputs.require-open-issue }} + ENFORCE: ${{ inputs.enforce }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: bash .linear-ticket-tools/scripts/linear-ticket/validate.sh diff --git a/.github/workflows/test-linear-ticket.yml b/.github/workflows/test-linear-ticket.yml new file mode 100644 index 00000000..50f81224 --- /dev/null +++ b/.github/workflows/test-linear-ticket.yml @@ -0,0 +1,50 @@ +# 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 shellcheck + the hermetic lib 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: shellcheck + suite + runs-on: ubuntu-latest + defaults: + run: + working-directory: scripts/linear-ticket + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: shellcheck + run: shellcheck -x lib.sh validate.sh tests/test_lib.sh + - name: lib suite + run: bash tests/test_lib.sh diff --git a/README.md b/README.md index d7e8d3e1..f5e04488 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. 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..3e0508b7 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. diff --git a/docs/callers/linear-ticket.md b/docs/callers/linear-ticket.md new file mode 100644 index 00000000..ecc7a280 --- /dev/null +++ b/docs/callers/linear-ticket.md @@ -0,0 +1,152 @@ +# `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 `. 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; empty (default) accepts any visible team + # exempt-label: linear-exempt # optional; empty disables exemption + # 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. Empty accepts any team the token can see. Malformed or duplicate entries fail the run. | +| `exempt-label` | `''` | Single label that waives the requirement (recommended `linear-exempt`). Empty disables exemption. | +| `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. Flip `enforce: true`. Leave the check non-required for a short window. +4. Add the **`linear-ticket`** status context to your `main` ruleset as a required check. + +Nothing here changes branch protection automatically — step 4 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 `. 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..5e5aab1b --- /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. + +| File | Role | +|---|---| +| `lib.sh` | 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. Sourced by `validate.sh` and by the test suite. | +| `validate.sh` | 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. Sources `lib.sh`. | +| `tests/test_lib.sh` | Hermetic suite over `lib.sh` — 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 + or a shell word. +- 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 env / jq args / 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 +cd scripts/linear-ticket +shellcheck -x lib.sh validate.sh tests/test_lib.sh +bash tests/test_lib.sh +``` + +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.sh b/scripts/linear-ticket/lib.sh new file mode 100644 index 00000000..65f714ea --- /dev/null +++ b/scripts/linear-ticket/lib.sh @@ -0,0 +1,204 @@ +#!/usr/bin/env bash +# lib.sh — the pure, network-free core of the linear-ticket gate: 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. Everything +# here is a function with no side effect beyond stdout, so tests/test_lib.sh can source +# this file and exercise the whole decision path against fixtures without a single API +# call. The side-effecting orchestration (resolve the PR, query Linear, publish the commit +# status, upsert the comment) lives in validate.sh, which sources 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. +# +# Requires jq. No yq (there is no YAML to parse here) and no network. + +# The hidden marker on the single PR comment this gate maintains. validate.sh finds its +# existing comment by this exact string, so it must never change casually. +# shellcheck disable=SC2034 # consumed by validate.sh, which sources this file +LINEAR_TICKET_MARKER='' + +# The stable commit-status context branch protection requires. Publishing is done in +# validate.sh; the name lives here so the tests can pin it. +# shellcheck disable=SC2034 # consumed by validate.sh, which sources this file +LINEAR_TICKET_CONTEXT='linear-ticket' + +# extract_candidates — read untrusted text on stdin, print up to 20 unique UPPERCASE +# candidate identifiers (one per line, first-seen order). The pattern is the design's +# case-insensitive [A-Z][A-Z0-9]*-\d+. These are 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. +extract_candidates() { + # grep exits 1 on no match; that is not an error here, so swallow it. tr upper-cases + # (so `be-1` and `BE-1` dedupe together), awk keeps first-seen order, head enforces the + # cap. The leading letter class is spelled out rather than relying on grep -i so the + # intent is explicit and locale-independent. + { grep -oE '[A-Za-z][A-Za-z0-9]*-[0-9]+' || true; } \ + | tr '[:lower:]' '[:upper:]' \ + | awk '!seen[$0]++' \ + | head -n 20 +} + +# normalize_team_keys — parse the caller's comma-separated `team-keys` input into a +# normalized, uppercase, de-duplicated comma string on stdout. rc 0 with EMPTY output for +# an empty/whitespace-only input (the "accept any visible team" default). rc 1 — 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. +normalize_team_keys() { + local raw="$1" + local collapsed + collapsed="$(printf '%s' "$raw" | tr -d '[:space:]')" + [ -z "$collapsed" ] && { printf ''; return 0; } + local seen="" part + local IFS=',' + for part in $raw; do + part="$(printf '%s' "$part" | tr -d '[:space:]' | tr '[:lower:]' '[:upper:]')" + [ -z "$part" ] && continue # tolerate a stray "BE,,ENG" empty field + printf '%s' "$part" | grep -qE '^[A-Z][A-Z0-9]*$' || return 1 + case ",$seen," in *,"$part",*) return 1 ;; esac # duplicate -> reject + seen="${seen:+$seen,}$part" + done + printf '%s' "$seen" +} + +# filter_issues — THE GATE. Given the +# attachmentsForURL `.nodes` array (each node carries `.issue{identifier,team{key}, +# state{type}}`), print the identifiers of issues that satisfy policy, one per line, sorted +# unique. Empty output == nothing passes. Policy: +# * team — keep an issue iff team-keys is empty OR its API-returned team.key is in the +# allow-list. The list is matched against the RESOLVED key, never a prefix. +# * state — when require-open == "true", 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). +filter_issues() { + local nodes="$1" keys="$2" require_open="$3" + local keys_json='[]' + [ -n "$keys" ] && keys_json="$(printf '%s' "$keys" | jq -R 'split(",")')" + printf '%s' "$nodes" | jq -r \ + --argjson keys "$keys_json" \ + --arg require_open "$require_open" ' + [ (.[]? | .issue) | select(. != null) + | select( ($keys | length) == 0 or ((.team.key // "") as $k | $keys | index($k)) ) + | select( $require_open != "true" + or ((.state.type // "") | (. != "completed" and . != "canceled")) ) + | .identifier ] + | unique[]' +} + +# count_linked — how many attachments carry a non-null issue, i.e. how many +# real Linear issues are linked to this PR (before policy). Distinguishes "nothing is +# linked yet" (retry / not-linked copy) from "something is linked but fails policy". +count_linked() { + printf '%s' "$1" | jq '[ (.[]? | .issue) | select(. != null) ] | length' +} + +# classify_linear_error — "retryable" or "terminal". +# Linear signals rate limiting as HTTP 400 with GraphQL error code RATELIMITED (design +# §8), so the code string is checked first. 408/429/5xx are transient transport/server +# faults. Everything else — auth, schema, malformed — is terminal and fails closed as an +# infrastructure error, never as an invalid ticket. +classify_linear_error() { + local http="$1" codes="$2" + case "$codes" in *RATELIMITED*) echo retryable; return 0 ;; esac + case "$http" in + 408 | 429 | 500 | 502 | 503 | 504) echo retryable; return 0 ;; + esac + echo terminal +} + +# select_failure_category — pick 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 ("…and +# at least one resolves to a real Linear issue"), it does not move the category — so the copy +# can never say "no identifier detected" while the detail lists one. +select_failure_category() { + local infra="$1" linked="$2" referenced="$3" + if [ "$infra" = "true" ]; then echo infra_error; return 0; fi + if [ "$linked" -gt 0 ]; then echo policy_mismatch; return 0; fi + if [ "$referenced" -gt 0 ]; then echo exists_not_linked; return 0; fi + echo no_candidate +} + +# failure_guidance — the fixed, category-specific paragraph shown in the PR +# comment and job summary. Specifics (identifiers, candidate list, rerun link) are appended +# by validate.sh; this keeps the reusable copy testable and consistent across repos. +failure_guidance() { + case "$1" in + no_candidate) + cat <<'EOF' +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. +EOF + ;; + exists_not_linked) + cat <<'EOF' +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. +EOF + ;; + policy_mismatch) + cat <<'EOF' +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. +EOF + ;; + infra_error) + cat <<'EOF' +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. +EOF + ;; + *) + echo "Unknown failure category: $1" >&2 + return 1 + ;; + esac +} + +# build_diagnostic_query — read newline candidate identifiers on stdin, emit ONE aliased +# GraphQL query (`c0: issueSearch(...) c1: ...`) that resolves them all in a single request +# (design §8: at most one batched diagnostic query). rc 1 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; the tr/grep below re-assert that invariant +# so a future caller cannot smuggle a quote through. +build_diagnostic_query() { + local aliases="" id i=0 + while IFS= read -r id; do + [ -z "$id" ] && continue + printf '%s' "$id" | grep -qE '^[A-Z0-9-]+$' || continue + aliases="${aliases} c${i}: issueSearch(query: \"${id}\", first: 1) { nodes { identifier } }"$'\n' + i=$((i + 1)) + done + [ "$i" -eq 0 ] && return 1 + printf 'query {\n%s}\n' "$aliases" +} + +# count_resolved_candidates — 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" copy rather than erroring. +count_resolved_candidates() { + printf '%s' "$1" | jq ' + (.data // {}) | [ to_entries[] | select(.value.nodes | (. // []) | length > 0) ] | length + ' 2>/dev/null || echo 0 +} diff --git a/scripts/linear-ticket/tests/test_lib.sh b/scripts/linear-ticket/tests/test_lib.sh new file mode 100644 index 00000000..73e3d408 --- /dev/null +++ b/scripts/linear-ticket/tests/test_lib.sh @@ -0,0 +1,121 @@ +#!/usr/bin/env bash +# test_lib.sh — hermetic tests for lib.sh. No network: sources the library and exercises +# candidate extraction, team-key input validation, the attachment policy gate, error +# classification, failure-category selection, and the diagnostic-query builder against +# fixtures. jq only. These cover the design's §11 acceptance cases that live in pure +# functions; the real-Linear behaviours (URL canonicalization, attachment timing) are +# proven in the pilot, not here. + +set -uo pipefail + +SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +LIB="$SELF_DIR/../lib.sh" +[ -f "$LIB" ] || { echo "FATAL: $LIB not found" >&2; exit 1; } +command -v jq >/dev/null 2>&1 || { echo "FATAL: jq not found on PATH" >&2; exit 2; } +# shellcheck source-path=SCRIPTDIR +# shellcheck source=../lib.sh +. "$LIB" + +PASS=0; FAIL=0 +ok() { PASS=$((PASS+1)); printf 'ok %s\n' "$1"; } +bad() { FAIL=$((FAIL+1)); printf 'FAIL %s\n got: %s\n' "$1" "${2:-}"; } +eq() { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (expected '$2')" "$3"; fi; } +DESC="" +pass_rc() { if "$@" >/dev/null 2>&1; then ok "$DESC"; else bad "$DESC" "rc=$?"; fi; } +fail_rc() { if "$@" >/dev/null 2>&1; then bad "$DESC" "rc=0 (expected non-zero)"; else ok "$DESC"; fi; } + +# ── extract_candidates ──────────────────────────────────────────────────────── +echo "— extract_candidates —" +eq "uppercases lowercase identifiers" "BE-1234" "$(printf 'fixes be-1234 please' | extract_candidates)" +eq "dedupes case-insensitively, first-seen order" \ + $'BE-1234\nENG-7' \ + "$(printf 'be-1234 ENG-7 BE-1234 eng-7' | extract_candidates)" +eq "reads branch/title/body concatenation" \ + $'BE-1\nENG-2\nOPS-3' \ + "$(printf 'luke/be-1-x\nTitle ENG-2\nCloses OPS-3' | extract_candidates)" +eq "no identifier yields empty" "" "$(printf 'just a normal title' | extract_candidates)" +# 20-candidate cap: feed 25 distinct ids, expect exactly 20 lines. +gen25="$(for i in $(seq 1 25); do printf 'AB-%s ' "$i"; done)" +eq "caps at 20 candidates" "20" "$(printf '%s' "$gen25" | extract_candidates | wc -l | tr -d ' ')" + +# ── normalize_team_keys ─────────────────────────────────────────────────────── +echo "— normalize_team_keys —" +eq "empty input -> empty (accept any)" "" "$(normalize_team_keys '')" +eq "whitespace-only -> empty (accept any)" "" "$(normalize_team_keys ' ')" +eq "trims and uppercases" "BE,ENG" "$(normalize_team_keys ' be , eng ')" +eq "tolerates stray empty field" "BE,ENG" "$(normalize_team_keys 'BE,,ENG')" +DESC="duplicate key rejected"; fail_rc normalize_team_keys 'BE,be' +DESC="malformed key (punctuation) rejected"; fail_rc normalize_team_keys 'BE,EN!G' +DESC="key starting with digit rejected"; fail_rc normalize_team_keys '1BE' +DESC="valid single key passes"; pass_rc normalize_team_keys 'BE' + +# ── filter_issues (THE GATE) ────────────────────────────────────────────────── +echo "— filter_issues —" +# Attachment to THIS PR whose issue is open and on team BE. +LINKED_OPEN_BE='[{"issue":{"identifier":"BE-1","team":{"key":"BE"},"state":{"type":"started"}}}]' +# Same shape but completed. +LINKED_DONE_BE='[{"issue":{"identifier":"BE-1","team":{"key":"BE"},"state":{"type":"completed"}}}]' +# Attachment whose issue belongs to a different team. +LINKED_OPEN_OPS='[{"issue":{"identifier":"OPS-9","team":{"key":"OPS"},"state":{"type":"backlog"}}}]' +# An attachment with no issue (e.g. a non-issue attachment) plus a passing one. +MIXED='[{"issue":null},{"issue":{"identifier":"BE-2","team":{"key":"BE"},"state":{"type":"triage"}}}]' +# Two linked issues, only the second satisfies an open+BE policy. +MULTI='[{"issue":{"identifier":"BE-1","team":{"key":"BE"},"state":{"type":"canceled"}}},{"issue":{"identifier":"ENG-5","team":{"key":"ENG"},"state":{"type":"started"}}}]' + +eq "canonical open attachment passes (any team)" "BE-1" "$(filter_issues "$LINKED_OPEN_BE" '' true)" +eq "empty attachments -> no pass" "" "$(filter_issues '[]' '' true)" +eq "completed issue rejected when require-open" "" "$(filter_issues "$LINKED_DONE_BE" '' true)" +eq "completed issue accepted when NOT require-open" "BE-1" "$(filter_issues "$LINKED_DONE_BE" '' false)" +eq "restricted team-keys accepts matching team" "BE-1" "$(filter_issues "$LINKED_OPEN_BE" 'BE,ENG' true)" +eq "restricted team-keys rejects other team" "" "$(filter_issues "$LINKED_OPEN_OPS" 'BE,ENG' true)" +eq "null-issue attachment ignored, real one passes" "BE-2" "$(filter_issues "$MIXED" '' true)" +eq "multi-link passes when at least one satisfies policy" "ENG-5" "$(filter_issues "$MULTI" '' true)" +eq "multi-link empty when restricted team excludes the open one" "" "$(filter_issues "$MULTI" 'BE' true)" + +# count_linked +eq "count_linked counts non-null issues" "1" "$(count_linked "$MIXED")" +eq "count_linked zero for empty" "0" "$(count_linked '[]')" +eq "count_linked counts both linked issues" "2" "$(count_linked "$MULTI")" + +# ── classify_linear_error ───────────────────────────────────────────────────── +echo "— classify_linear_error —" +eq "RATELIMITED code is retryable (even on HTTP 400)" "retryable" "$(classify_linear_error 400 'RATELIMITED')" +eq "HTTP 503 is retryable" "retryable" "$(classify_linear_error 503 '')" +eq "HTTP 429 is retryable" "retryable" "$(classify_linear_error 429 '')" +eq "auth error is terminal" "terminal" "$(classify_linear_error 401 'AUTHENTICATION_ERROR')" +eq "schema/400 without ratelimit is terminal" "terminal" "$(classify_linear_error 400 'GRAPHQL_VALIDATION_FAILED')" + +# ── select_failure_category ─────────────────────────────────────────────────── +echo "— select_failure_category —" +eq "infra error dominates" "infra_error" "$(select_failure_category true 0 0)" +eq "infra error dominates even with links" "infra_error" "$(select_failure_category true 2 3)" +eq "linked-but-policy -> policy_mismatch" "policy_mismatch" "$(select_failure_category false 1 0)" +eq "no link, identifier referenced -> exists_not_linked" "exists_not_linked" "$(select_failure_category false 0 2)" +eq "referenced count decides, not resolution -> exists_not_linked" "exists_not_linked" "$(select_failure_category false 0 1)" +eq "no link, nothing referenced -> no_candidate" "no_candidate" "$(select_failure_category false 0 0)" + +# ── failure_guidance ────────────────────────────────────────────────────────── +echo "— failure_guidance —" +for cat in no_candidate exists_not_linked policy_mismatch infra_error; do + DESC="guidance for $cat is non-empty" + if [ -n "$(failure_guidance "$cat")" ]; then ok "$DESC"; else bad "$DESC" ""; fi +done +DESC="unknown category fails"; fail_rc failure_guidance bogus + +# ── build_diagnostic_query / count_resolved_candidates ──────────────────────── +echo "— build_diagnostic_query —" +DESC="empty candidate list -> rc1"; fail_rc build_diagnostic_query < /dev/null +Q="$(printf 'BE-1\nENG-2\n' | build_diagnostic_query)" +eq "builds one alias per candidate" "2" "$(printf '%s' "$Q" | grep -cE '^\s*c[0-9]+: issueSearch')" +eq "embeds the identifier as a query literal" "1" "$(printf '%s' "$Q" | grep -c 'query: "BE-1"')" + +echo "— count_resolved_candidates —" +RESP='{"data":{"c0":{"nodes":[{"identifier":"BE-1"}]},"c1":{"nodes":[]}}}' +eq "counts aliases with at least one node" "1" "$(count_resolved_candidates "$RESP")" +eq "malformed response counts as 0" "0" "$(count_resolved_candidates 'not json')" +eq "absent data counts as 0" "0" "$(count_resolved_candidates '{"errors":[]}')" + +# ── summary ─────────────────────────────────────────────────────────────────── +echo +echo "PASS=$PASS FAIL=$FAIL" +[ "$FAIL" -eq 0 ] diff --git a/scripts/linear-ticket/validate.sh b/scripts/linear-ticket/validate.sh new file mode 100644 index 00000000..01ec39ae --- /dev/null +++ b/scripts/linear-ticket/validate.sh @@ -0,0 +1,367 @@ +#!/usr/bin/env bash +# validate.sh — the side-effecting orchestration behind linear-ticket.yml. Sources lib.sh +# 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 jq/curl through argument +# arrays and GraphQL variables, never interpolated into a query or a shell word. 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 +set -uo pipefail + +SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +# shellcheck source=./lib.sh +. "$SELF_DIR/lib.sh" + +LINEAR_API_URL="${LINEAR_API_URL:-https://api.linear.app/graphql}" +SUMMARY_FILE="${GITHUB_STEP_SUMMARY:-/dev/null}" + +# ── logging ────────────────────────────────────────────────────────────────── +log() { printf '%s\n' "$*" >&2; } +err() { printf '::error::%s\n' "$*" >&2; } +warn() { printf '::warning::%s\n' "$*" >&2; } +summary() { printf '%s\n' "$*" >>"$SUMMARY_FILE"; } + +# ── GraphQL queries (static; the URL is the only variable) ──────────────────── +# shellcheck disable=SC2016 # $url is a GraphQL variable, not a shell expansion +ATTACHMENTS_QUERY='query PullRequestAttachments($url: String!) { + attachmentsForURL(url: $url, first: 20) { + nodes { id url issue { id identifier team { key } state { type } } } + } +}' + +# linear_post — POST a JSON GraphQL request. Writes the response body to +# stdout and sets globals LINEAR_HTTP (status) and LINEAR_ERR_CODES (space-joined GraphQL +# error `extensions.code`s). rc 0 on any completed HTTP exchange (even a 4xx/5xx — the +# caller classifies it), rc 1 only on a transport failure (curl could not complete). +LINEAR_HTTP=""; LINEAR_ERR_CODES="" +linear_post() { + local body_file="$1" + local hdr_file; hdr_file="$(mktemp)" + local out + # --Authorization verbatim: a personal API key goes raw, an OAuth token as "Bearer ...". + # The header value is set once here; docs tell the caller which form to store. + out="$(curl -sS --max-time 30 -D "$hdr_file" -X POST "$LINEAR_API_URL" \ + -H "Authorization: ${LINEAR_API_TOKEN}" \ + -H 'Content-Type: application/json' \ + --data-binary "@${body_file}" 2>/dev/null)" + local curl_rc=$? + if [ "$curl_rc" -ne 0 ]; then + rm -f "$hdr_file" + LINEAR_HTTP=""; LINEAR_ERR_CODES="" + return 1 + fi + LINEAR_HTTP="$(awk 'toupper($1) ~ /^HTTP/ {code=$2} END {print code}' "$hdr_file")" + # Log rate-limit headroom for the pilot (design §8), best-effort. + grep -iE '^x-ratelimit-(requests|complexity)-(remaining|reset):' "$hdr_file" >&2 || true + rm -f "$hdr_file" + LINEAR_ERR_CODES="$(printf '%s' "$out" | jq -r '[.errors[]?.extensions.code // empty] | join(" ")' 2>/dev/null || true)" + printf '%s' "$out" +} + +# build_graphql_body [] — a GraphQL request body with the PR URL passed as a +# VARIABLE, never interpolated into the query text (design §4). +build_graphql_body() { + local query="$1" + if [ "$#" -ge 2 ]; then + jq -n --arg q "$query" --arg url "$2" '{query: $q, variables: {url: $url}}' + else + jq -n --arg q "$query" '{query: $q}' + fi +} + +# ── commit status ───────────────────────────────────────────────────────────── +# publish_status +publish_status() { + local sha="$1" state="$2" description="$3" + gh api -X POST "repos/${GH_REPO}/statuses/${sha}" \ + -f "state=${state}" \ + -f "context=${LINEAR_TICKET_CONTEXT}" \ + -f "description=${description}" \ + -f "target_url=${RUN_URL:-}" >/dev/null 2>&1 \ + || warn "Failed to publish '${state}' status on ${sha}" +} + +# ── marker comment ───────────────────────────────────────────────────────────── +# find_marker_comment — echo the id of the existing marker comment, or empty. +find_marker_comment() { + gh api --paginate "repos/${GH_REPO}/issues/${1}/comments" \ + --jq ".[] | select(.body | contains(\"${LINEAR_TICKET_MARKER}\")) | .id" 2>/dev/null \ + | head -n1 +} + +# upsert_marker_comment — create or update the single marker +# comment. Comment I/O is best-effort: a failure is warned, never fatal (design §6). +upsert_marker_comment() { + local pr="$1" body_file="$2" existing + existing="$(find_marker_comment "$pr")" + if [ -n "$existing" ]; then + gh api -X PATCH "repos/${GH_REPO}/issues/comments/${existing}" \ + -F "body=@${body_file}" >/dev/null 2>&1 || warn "Failed to update marker comment ${existing}" + else + gh api -X POST "repos/${GH_REPO}/issues/${pr}/comments" \ + -F "body=@${body_file}" >/dev/null 2>&1 || warn "Failed to create marker comment" + fi +} + +# delete_marker_comment — remove the marker comment after a pass/exempt run. +delete_marker_comment() { + local pr="$1" existing + existing="$(find_marker_comment "$pr")" + [ -z "$existing" ] && return 0 + gh api -X DELETE "repos/${GH_REPO}/issues/comments/${existing}" >/dev/null 2>&1 \ + || warn "Failed to delete marker comment ${existing}" +} + +# current_head_sha — the PR's head SHA right now, for the supersession recheck. +current_head_sha() { + gh api "repos/${GH_REPO}/pulls/${1}" --jq '.head.sha' 2>/dev/null +} + +# ── terminal outcomes ────────────────────────────────────────────────────────── +# In warn-only mode every outcome publishes SUCCESS but the summary/comment still show the +# verdict enforce mode would have produced (design §7). Before any terminal status write we +# refetch the PR head SHA and bail if it moved — a newer run must win (design §6). +VALIDATED_SHA=""; PR_NUMBER="" + +finish_pass() { + local identifiers="$1" + summary "## linear-ticket: ✅ pass" + summary "" + summary "Linear has linked this PR to: **${identifiers}**" + delete_marker_comment "$PR_NUMBER" + guard_supersession || return 0 + publish_status "$VALIDATED_SHA" success "Linked Linear issue: ${identifiers}" + exit 0 +} + +finish_exempt() { + summary "## linear-ticket: ✅ exempt" + summary "" + summary "PR carries the \`${EXEMPT_LABEL}\` label — the Linear-ticket requirement is waived." + delete_marker_comment "$PR_NUMBER" + guard_supersession || return 0 + publish_status "$VALIDATED_SHA" success "Exempt via ${EXEMPT_LABEL} label" + exit 0 +} + +# finish_fail +finish_fail() { + local category="$1" detail="$2" + local guidance; guidance="$(failure_guidance "$category")" + local verdict state short + if [ "$ENFORCE" = "false" ]; then + verdict="⚠️ warn-only (would fail: ${category})"; state="success"; short="warn-only: would fail (${category})" + else + verdict="❌ fail (${category})"; state="failure"; short="No linked Linear issue (${category})" + fi + + # One marker comment carrying the same diagnosis in both modes. + local body_file; body_file="$(mktemp)" + { + printf '%s\n\n' "$LINEAR_TICKET_MARKER" + printf '### Linear ticket check — %s\n\n' "$verdict" + printf '%s\n' "$guidance" + [ -n "$detail" ] && printf '\n%s\n' "$detail" + printf '\n---\n' + printf 'After linking an issue, re-run this check from the [workflow run](%s) or edit the PR title/body to trigger a fresh run. ' "${RUN_URL:-}" + # shellcheck disable=SC2016 # backticks are literal markdown for the label name, not a subshell + printf 'A repository maintainer can waive the requirement by applying the `%s` label.\n' "${EXEMPT_LABEL:-linear-exempt}" + } >"$body_file" + upsert_marker_comment "$PR_NUMBER" "$body_file" + rm -f "$body_file" + + summary "## linear-ticket: ${verdict}" + summary "" + summary "$guidance" + [ -n "$detail" ] && summary "$detail" + + guard_supersession || return 0 + publish_status "$VALIDATED_SHA" "$state" "$short" + [ "$ENFORCE" = "false" ] && exit 0 + exit 1 +} + +# guard_supersession — rc 0 to proceed with the terminal write, rc 1 to bail because the PR +# head advanced past the SHA we validated (a newer run owns the result now). +guard_supersession() { + local now; now="$(current_head_sha "$PR_NUMBER")" + if [ -n "$now" ] && [ "$now" != "$VALIDATED_SHA" ]; then + log "PR head moved ${VALIDATED_SHA} -> ${now}; a newer run supersedes this one. Not writing a terminal status." + return 1 + fi + return 0 +} + +# ── main ─────────────────────────────────────────────────────────────────────── +main() { + for tool in gh jq curl; do + command -v "$tool" >/dev/null 2>&1 || { err "$tool not found on PATH"; exit 1; } + done + [ -n "${GH_REPO:-}" ] || { err "GH_REPO is required"; exit 1; } + [ -n "${GITHUB_EVENT_PATH:-}" ] || { err "GITHUB_EVENT_PATH is required"; exit 1; } + [ -f "$GITHUB_EVENT_PATH" ] || { err "event payload not found at GITHUB_EVENT_PATH"; exit 1; } + [ -n "${LINEAR_API_TOKEN:-}" ] || { err "LINEAR_API_TOKEN secret is not set; failing closed (infrastructure error)"; exit 1; } + + # team-keys is a caller-config input: a malformed value is a misconfiguration, so fail the + # run loudly rather than silently widening policy (design §5.1). + local team_keys + if ! team_keys="$(normalize_team_keys "${TEAM_KEYS:-}")"; then + err "Invalid team-keys input '${TEAM_KEYS:-}': entries must be uppercase alphanumeric team keys, unique, comma-separated." + exit 1 + fi + + # Only a completed run of the signal workflow should reach here; the caller's `if:` gates + # this, but re-assert it so a mis-wired caller fails safe rather than validating garbage. + local event="$GITHUB_EVENT_PATH" + local wr_event; wr_event="$(jq -r '.workflow_run.event // ""' "$event")" + local head_sha; head_sha="$(jq -r '.workflow_run.head_sha // ""' "$event")" + [ -n "$head_sha" ] || { err "workflow_run.head_sha missing from event"; exit 1; } + + # Resolve 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). We + # require exactly one OPEN PR, refetched through the API before any status write. + local -a candidates=() + local n + while IFS= read -r n; do [ -n "$n" ] && candidates+=("$n"); done < <( + jq -r '.workflow_run.pull_requests[]?.number // empty' "$event" + ) + if [ "${#candidates[@]}" -eq 0 ]; then + while IFS= read -r n; do [ -n "$n" ] && candidates+=("$n"); done < <( + gh api "repos/${GH_REPO}/commits/${head_sha}/pulls" \ + --jq ".[] | select(.state==\"open\") | select(.base.repo.full_name==\"${GH_REPO}\") | .number" 2>/dev/null + ) + fi + + # De-dup + keep only currently-open PRs. + local -a open_prs=() + local seen_pr="" + for n in "${candidates[@]}"; do + case " $seen_pr " in *" $n "*) continue ;; esac + seen_pr="$seen_pr $n" + local st; st="$(gh api "repos/${GH_REPO}/pulls/${n}" --jq '.state' 2>/dev/null || true)" + [ "$st" = "open" ] && open_prs+=("$n") + done + + if [ "${#open_prs[@]}" -ne 1 ]; then + err "Expected exactly one open PR associated with ${head_sha}, found ${#open_prs[@]} (event=${wr_event}). Refusing to publish an ambiguous result." + exit 1 + fi + PR_NUMBER="${open_prs[0]}" + + # Refetch the PR: canonical html_url, current head SHA (the status target), labels, and the + # untrusted text we mine for diagnostic candidates. + local pr_json; pr_json="$(gh api "repos/${GH_REPO}/pulls/${PR_NUMBER}" 2>/dev/null)" \ + || { err "Could not fetch PR #${PR_NUMBER}"; exit 1; } + local html_url; html_url="$(printf '%s' "$pr_json" | jq -r '.html_url')" + VALIDATED_SHA="$(printf '%s' "$pr_json" | jq -r '.head.sha')" + local pr_branch; pr_branch="$(printf '%s' "$pr_json" | jq -r '.head.ref // ""')" + local pr_title; pr_title="$(printf '%s' "$pr_json" | jq -r '.title // ""')" + local pr_body; pr_body="$(printf '%s' "$pr_json" | jq -r '.body // ""')" + + log "Validating PR #${PR_NUMBER} (${html_url}) at head ${VALIDATED_SHA}" + publish_status "$VALIDATED_SHA" pending "Checking for a linked Linear issue…" + + # Exemption short-circuit. + if [ -n "${EXEMPT_LABEL:-}" ]; then + if printf '%s' "$pr_json" | jq -e --arg l "$EXEMPT_LABEL" '.labels[]?.name == $l | select(.)' >/dev/null 2>&1; then + log "PR carries the '${EXEMPT_LABEL}' label — exempt." + finish_exempt + fi + fi + + # ── the gate: attachmentsForURL(this PR), with bounded retry for the async-link race ── + local body_file; body_file="$(mktemp)" + build_graphql_body "$ATTACHMENTS_QUERY" "$html_url" >"$body_file" + + local -a backoff=(2 4 8 16) # between five attempts + local infra_error=false + local nodes='[]' + local attempt + for attempt in 0 1 2 3 4; do + local resp; resp="$(linear_post "$body_file")"; local post_rc=$? + if [ "$post_rc" -ne 0 ]; then + log "Linear request transport failure (attempt $((attempt+1)))" + elif [ -n "$LINEAR_ERR_CODES" ] || { [ -n "$LINEAR_HTTP" ] && [ "$LINEAR_HTTP" -ge 400 ] 2>/dev/null; }; then + local kind; kind="$(classify_linear_error "${LINEAR_HTTP:-0}" "${LINEAR_ERR_CODES:-}")" + if [ "$kind" = "terminal" ]; then + err "Linear returned a terminal error (HTTP ${LINEAR_HTTP:-?}, codes: ${LINEAR_ERR_CODES:-none}). Failing closed as an infrastructure error." + infra_error=true + break + fi + log "Linear returned a retryable error (HTTP ${LINEAR_HTTP:-?}, codes: ${LINEAR_ERR_CODES:-none}) on attempt $((attempt+1))" + else + # A clean response. Extract the attachment nodes. + nodes="$(printf '%s' "$resp" | jq -c '.data.attachmentsForURL.nodes // []' 2>/dev/null || echo '[]')" + local linked; linked="$(count_linked "$nodes")" + if [ "$linked" -gt 0 ]; then + break # attachments present — evaluate policy, no reason to retry + fi + log "No attachment linked to this PR yet (attempt $((attempt+1)))" + fi + # Retry with backoff unless this was the last attempt. + if [ "$attempt" -lt 4 ]; then + sleep "${backoff[$attempt]}" + fi + done + rm -f "$body_file" + + if [ "$infra_error" = false ]; then + local passing; passing="$(filter_issues "$nodes" "$team_keys" "${REQUIRE_OPEN_ISSUE:-true}")" + if [ -n "$passing" ]; then + local joined; joined="$(printf '%s' "$passing" | paste -sd ',' - | sed 's/,/, /g')" + log "PASS — linked issue(s): ${joined}" + finish_pass "$joined" + fi + fi + + # ── failure path: diagnostics only (never turns red into green) ── + local linked_count; linked_count="$(count_linked "$nodes")" + local referenced_count=0 resolved_count=0 + local candidate_detail="" + if [ "$infra_error" = false ] && [ "$linked_count" -eq 0 ]; then + local candidates_list; candidates_list="$(printf '%s\n%s\n%s' "$pr_branch" "$pr_title" "$pr_body" | extract_candidates)" + if [ -n "$candidates_list" ]; then + referenced_count="$(printf '%s\n' "$candidates_list" | grep -c .)" + local joined_candidates; joined_candidates="$(printf '%s' "$candidates_list" | paste -sd ',' - | sed 's/,/, /g')" + local diag_query; if diag_query="$(printf '%s' "$candidates_list" | build_diagnostic_query)"; then + local diag_file; diag_file="$(mktemp)" + build_graphql_body "$diag_query" >"$diag_file" + local diag_resp; diag_resp="$(linear_post "$diag_file")" + rm -f "$diag_file" + resolved_count="$(count_resolved_candidates "$diag_resp")" + fi + if [ "$resolved_count" -gt 0 ] 2>/dev/null; then + candidate_detail="Referenced identifiers (not linked): ${joined_candidates} — at least one resolves to a real Linear issue; link it to this PR." + else + candidate_detail="Referenced identifiers (not linked): ${joined_candidates}" + fi + fi + fi + + local category; category="$(select_failure_category "$infra_error" "$linked_count" "$referenced_count")" + local detail="$candidate_detail" + if [ "$category" = "policy_mismatch" ]; then + local linked_ids; linked_ids="$(printf '%s' "$nodes" | jq -r '[ (.[]? | .issue) | select(.!=null) | .identifier ] | join(", ")')" + detail="Linked but not accepted: ${linked_ids}" + fi + log "FAIL category=${category} linked=${linked_count} resolved=${resolved_count}" + finish_fail "$category" "$detail" +} + +main "$@" From 96db1575a4fcedded0fc8c892d4c607639e660f4 Mon Sep 17 00:00:00 2001 From: Luke Mino-Altherr Date: Tue, 18 Aug 2026 10:08:18 -0700 Subject: [PATCH 2/4] refactor(linear-ticket): implement in Python instead of shell MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port lib.sh/validate.sh/test_lib.sh to lib.py/validate.py/test_lib.py to match this repo's stdlib-Python convention (groom, refresh-reviewers, agents-md-integrity, cursor-review). GitHub via the gh CLI (subprocess, as cursor-review's post-review.py); Linear GraphQL via urllib (as refresh-reviewers' generate.py). Behaviour is unchanged — same policy gate, bounded retry, marker comment, head-SHA supersession recheck, warn-only mode, and fail-closed semantics — and the hermetic suite now runs under unittest. The reusable workflow sets up Python 3.12 and runs validate.py; the test workflow runs `python3 -m unittest discover` plus a py_compile gate for validate.py (which the suite does not import). Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/linear-ticket.yml | 6 +- .github/workflows/test-linear-ticket.yml | 17 +- scripts/linear-ticket/README.md | 20 +- scripts/linear-ticket/lib.py | 234 ++++++++++++ scripts/linear-ticket/lib.sh | 204 ---------- scripts/linear-ticket/tests/test_lib.py | 185 +++++++++ scripts/linear-ticket/tests/test_lib.sh | 121 ------ scripts/linear-ticket/validate.py | 459 +++++++++++++++++++++++ scripts/linear-ticket/validate.sh | 367 ------------------ 9 files changed, 902 insertions(+), 711 deletions(-) create mode 100644 scripts/linear-ticket/lib.py delete mode 100644 scripts/linear-ticket/lib.sh create mode 100644 scripts/linear-ticket/tests/test_lib.py delete mode 100644 scripts/linear-ticket/tests/test_lib.sh create mode 100644 scripts/linear-ticket/validate.py delete mode 100644 scripts/linear-ticket/validate.sh diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index a48b209c..86e215b7 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -185,6 +185,10 @@ jobs: 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 }} @@ -195,4 +199,4 @@ jobs: REQUIRE_OPEN_ISSUE: ${{ inputs.require-open-issue }} ENFORCE: ${{ inputs.enforce }} RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} - run: bash .linear-ticket-tools/scripts/linear-ticket/validate.sh + 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 index 50f81224..bc72eda8 100644 --- a/.github/workflows/test-linear-ticket.yml +++ b/.github/workflows/test-linear-ticket.yml @@ -8,7 +8,7 @@ name: Test linear-ticket scripts -# Runs shellcheck + the hermetic lib suite for the linear-ticket gate. The gate decides +# 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, @@ -34,17 +34,18 @@ permissions: jobs: test: - name: shellcheck + suite + name: unittest runs-on: ubuntu-latest - defaults: - run: - working-directory: scripts/linear-ticket steps: - name: Checkout uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: shellcheck - run: shellcheck -x lib.sh validate.sh tests/test_lib.sh + - 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: bash tests/test_lib.sh + run: python3 -m unittest discover -s scripts/linear-ticket/tests -p 'test_*.py' -v diff --git a/scripts/linear-ticket/README.md b/scripts/linear-ticket/README.md index 5e5aab1b..6fb530af 100644 --- a/scripts/linear-ticket/README.md +++ b/scripts/linear-ticket/README.md @@ -3,13 +3,14 @@ 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. +`workflows_ref` SHA the caller pins. Standard-library Python only (no third-party deps), +matching this repo's Python convention. | File | Role | |---|---| -| `lib.sh` | 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. Sourced by `validate.sh` and by the test suite. | -| `validate.sh` | 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. Sources `lib.sh`. | -| `tests/test_lib.sh` | Hermetic suite over `lib.sh` — no network. | +| `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 @@ -17,8 +18,7 @@ The **only** thing that turns the check green is an attachment Linear returns fo 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 - or a shell word. +- 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 @@ -31,7 +31,8 @@ That is the whole point: a `TEAM-123`-shaped string an author types is not a lin ## Security & failure model - Runs in the **privileged `workflow_run` job**; every PR-derived value is untrusted DATA - passed through env / jq args / GraphQL variables. No PR code is checked out or executed. + 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. @@ -48,9 +49,8 @@ That is the whole point: a `TEAM-123`-shaped string an author types is not a lin ## Running the tests ```bash -cd scripts/linear-ticket -shellcheck -x lib.sh validate.sh tests/test_lib.sh -bash tests/test_lib.sh +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 diff --git a/scripts/linear-ticket/lib.py b/scripts/linear-ticket/lib.py new file mode 100644 index 00000000..98110f40 --- /dev/null +++ b/scripts/linear-ticket/lib.py @@ -0,0 +1,234 @@ +"""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 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. + + ``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/lib.sh b/scripts/linear-ticket/lib.sh deleted file mode 100644 index 65f714ea..00000000 --- a/scripts/linear-ticket/lib.sh +++ /dev/null @@ -1,204 +0,0 @@ -#!/usr/bin/env bash -# lib.sh — the pure, network-free core of the linear-ticket gate: 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. Everything -# here is a function with no side effect beyond stdout, so tests/test_lib.sh can source -# this file and exercise the whole decision path against fixtures without a single API -# call. The side-effecting orchestration (resolve the PR, query Linear, publish the commit -# status, upsert the comment) lives in validate.sh, which sources 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. -# -# Requires jq. No yq (there is no YAML to parse here) and no network. - -# The hidden marker on the single PR comment this gate maintains. validate.sh finds its -# existing comment by this exact string, so it must never change casually. -# shellcheck disable=SC2034 # consumed by validate.sh, which sources this file -LINEAR_TICKET_MARKER='' - -# The stable commit-status context branch protection requires. Publishing is done in -# validate.sh; the name lives here so the tests can pin it. -# shellcheck disable=SC2034 # consumed by validate.sh, which sources this file -LINEAR_TICKET_CONTEXT='linear-ticket' - -# extract_candidates — read untrusted text on stdin, print up to 20 unique UPPERCASE -# candidate identifiers (one per line, first-seen order). The pattern is the design's -# case-insensitive [A-Z][A-Z0-9]*-\d+. These are 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. -extract_candidates() { - # grep exits 1 on no match; that is not an error here, so swallow it. tr upper-cases - # (so `be-1` and `BE-1` dedupe together), awk keeps first-seen order, head enforces the - # cap. The leading letter class is spelled out rather than relying on grep -i so the - # intent is explicit and locale-independent. - { grep -oE '[A-Za-z][A-Za-z0-9]*-[0-9]+' || true; } \ - | tr '[:lower:]' '[:upper:]' \ - | awk '!seen[$0]++' \ - | head -n 20 -} - -# normalize_team_keys — parse the caller's comma-separated `team-keys` input into a -# normalized, uppercase, de-duplicated comma string on stdout. rc 0 with EMPTY output for -# an empty/whitespace-only input (the "accept any visible team" default). rc 1 — 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. -normalize_team_keys() { - local raw="$1" - local collapsed - collapsed="$(printf '%s' "$raw" | tr -d '[:space:]')" - [ -z "$collapsed" ] && { printf ''; return 0; } - local seen="" part - local IFS=',' - for part in $raw; do - part="$(printf '%s' "$part" | tr -d '[:space:]' | tr '[:lower:]' '[:upper:]')" - [ -z "$part" ] && continue # tolerate a stray "BE,,ENG" empty field - printf '%s' "$part" | grep -qE '^[A-Z][A-Z0-9]*$' || return 1 - case ",$seen," in *,"$part",*) return 1 ;; esac # duplicate -> reject - seen="${seen:+$seen,}$part" - done - printf '%s' "$seen" -} - -# filter_issues — THE GATE. Given the -# attachmentsForURL `.nodes` array (each node carries `.issue{identifier,team{key}, -# state{type}}`), print the identifiers of issues that satisfy policy, one per line, sorted -# unique. Empty output == nothing passes. Policy: -# * team — keep an issue iff team-keys is empty OR its API-returned team.key is in the -# allow-list. The list is matched against the RESOLVED key, never a prefix. -# * state — when require-open == "true", 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). -filter_issues() { - local nodes="$1" keys="$2" require_open="$3" - local keys_json='[]' - [ -n "$keys" ] && keys_json="$(printf '%s' "$keys" | jq -R 'split(",")')" - printf '%s' "$nodes" | jq -r \ - --argjson keys "$keys_json" \ - --arg require_open "$require_open" ' - [ (.[]? | .issue) | select(. != null) - | select( ($keys | length) == 0 or ((.team.key // "") as $k | $keys | index($k)) ) - | select( $require_open != "true" - or ((.state.type // "") | (. != "completed" and . != "canceled")) ) - | .identifier ] - | unique[]' -} - -# count_linked — how many attachments carry a non-null issue, i.e. how many -# real Linear issues are linked to this PR (before policy). Distinguishes "nothing is -# linked yet" (retry / not-linked copy) from "something is linked but fails policy". -count_linked() { - printf '%s' "$1" | jq '[ (.[]? | .issue) | select(. != null) ] | length' -} - -# classify_linear_error — "retryable" or "terminal". -# Linear signals rate limiting as HTTP 400 with GraphQL error code RATELIMITED (design -# §8), so the code string is checked first. 408/429/5xx are transient transport/server -# faults. Everything else — auth, schema, malformed — is terminal and fails closed as an -# infrastructure error, never as an invalid ticket. -classify_linear_error() { - local http="$1" codes="$2" - case "$codes" in *RATELIMITED*) echo retryable; return 0 ;; esac - case "$http" in - 408 | 429 | 500 | 502 | 503 | 504) echo retryable; return 0 ;; - esac - echo terminal -} - -# select_failure_category — pick 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 ("…and -# at least one resolves to a real Linear issue"), it does not move the category — so the copy -# can never say "no identifier detected" while the detail lists one. -select_failure_category() { - local infra="$1" linked="$2" referenced="$3" - if [ "$infra" = "true" ]; then echo infra_error; return 0; fi - if [ "$linked" -gt 0 ]; then echo policy_mismatch; return 0; fi - if [ "$referenced" -gt 0 ]; then echo exists_not_linked; return 0; fi - echo no_candidate -} - -# failure_guidance — the fixed, category-specific paragraph shown in the PR -# comment and job summary. Specifics (identifiers, candidate list, rerun link) are appended -# by validate.sh; this keeps the reusable copy testable and consistent across repos. -failure_guidance() { - case "$1" in - no_candidate) - cat <<'EOF' -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. -EOF - ;; - exists_not_linked) - cat <<'EOF' -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. -EOF - ;; - policy_mismatch) - cat <<'EOF' -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. -EOF - ;; - infra_error) - cat <<'EOF' -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. -EOF - ;; - *) - echo "Unknown failure category: $1" >&2 - return 1 - ;; - esac -} - -# build_diagnostic_query — read newline candidate identifiers on stdin, emit ONE aliased -# GraphQL query (`c0: issueSearch(...) c1: ...`) that resolves them all in a single request -# (design §8: at most one batched diagnostic query). rc 1 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; the tr/grep below re-assert that invariant -# so a future caller cannot smuggle a quote through. -build_diagnostic_query() { - local aliases="" id i=0 - while IFS= read -r id; do - [ -z "$id" ] && continue - printf '%s' "$id" | grep -qE '^[A-Z0-9-]+$' || continue - aliases="${aliases} c${i}: issueSearch(query: \"${id}\", first: 1) { nodes { identifier } }"$'\n' - i=$((i + 1)) - done - [ "$i" -eq 0 ] && return 1 - printf 'query {\n%s}\n' "$aliases" -} - -# count_resolved_candidates — 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" copy rather than erroring. -count_resolved_candidates() { - printf '%s' "$1" | jq ' - (.data // {}) | [ to_entries[] | select(.value.nodes | (. // []) | length > 0) ] | length - ' 2>/dev/null || echo 0 -} diff --git a/scripts/linear-ticket/tests/test_lib.py b/scripts/linear-ticket/tests/test_lib.py new file mode 100644 index 00000000..1f5e964c --- /dev/null +++ b/scripts/linear-ticket/tests/test_lib.py @@ -0,0 +1,185 @@ +"""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("luke/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") + + +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) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/linear-ticket/tests/test_lib.sh b/scripts/linear-ticket/tests/test_lib.sh deleted file mode 100644 index 73e3d408..00000000 --- a/scripts/linear-ticket/tests/test_lib.sh +++ /dev/null @@ -1,121 +0,0 @@ -#!/usr/bin/env bash -# test_lib.sh — hermetic tests for lib.sh. No network: sources the library and exercises -# candidate extraction, team-key input validation, the attachment policy gate, error -# classification, failure-category selection, and the diagnostic-query builder against -# fixtures. jq only. These cover the design's §11 acceptance cases that live in pure -# functions; the real-Linear behaviours (URL canonicalization, attachment timing) are -# proven in the pilot, not here. - -set -uo pipefail - -SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -LIB="$SELF_DIR/../lib.sh" -[ -f "$LIB" ] || { echo "FATAL: $LIB not found" >&2; exit 1; } -command -v jq >/dev/null 2>&1 || { echo "FATAL: jq not found on PATH" >&2; exit 2; } -# shellcheck source-path=SCRIPTDIR -# shellcheck source=../lib.sh -. "$LIB" - -PASS=0; FAIL=0 -ok() { PASS=$((PASS+1)); printf 'ok %s\n' "$1"; } -bad() { FAIL=$((FAIL+1)); printf 'FAIL %s\n got: %s\n' "$1" "${2:-}"; } -eq() { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (expected '$2')" "$3"; fi; } -DESC="" -pass_rc() { if "$@" >/dev/null 2>&1; then ok "$DESC"; else bad "$DESC" "rc=$?"; fi; } -fail_rc() { if "$@" >/dev/null 2>&1; then bad "$DESC" "rc=0 (expected non-zero)"; else ok "$DESC"; fi; } - -# ── extract_candidates ──────────────────────────────────────────────────────── -echo "— extract_candidates —" -eq "uppercases lowercase identifiers" "BE-1234" "$(printf 'fixes be-1234 please' | extract_candidates)" -eq "dedupes case-insensitively, first-seen order" \ - $'BE-1234\nENG-7' \ - "$(printf 'be-1234 ENG-7 BE-1234 eng-7' | extract_candidates)" -eq "reads branch/title/body concatenation" \ - $'BE-1\nENG-2\nOPS-3' \ - "$(printf 'luke/be-1-x\nTitle ENG-2\nCloses OPS-3' | extract_candidates)" -eq "no identifier yields empty" "" "$(printf 'just a normal title' | extract_candidates)" -# 20-candidate cap: feed 25 distinct ids, expect exactly 20 lines. -gen25="$(for i in $(seq 1 25); do printf 'AB-%s ' "$i"; done)" -eq "caps at 20 candidates" "20" "$(printf '%s' "$gen25" | extract_candidates | wc -l | tr -d ' ')" - -# ── normalize_team_keys ─────────────────────────────────────────────────────── -echo "— normalize_team_keys —" -eq "empty input -> empty (accept any)" "" "$(normalize_team_keys '')" -eq "whitespace-only -> empty (accept any)" "" "$(normalize_team_keys ' ')" -eq "trims and uppercases" "BE,ENG" "$(normalize_team_keys ' be , eng ')" -eq "tolerates stray empty field" "BE,ENG" "$(normalize_team_keys 'BE,,ENG')" -DESC="duplicate key rejected"; fail_rc normalize_team_keys 'BE,be' -DESC="malformed key (punctuation) rejected"; fail_rc normalize_team_keys 'BE,EN!G' -DESC="key starting with digit rejected"; fail_rc normalize_team_keys '1BE' -DESC="valid single key passes"; pass_rc normalize_team_keys 'BE' - -# ── filter_issues (THE GATE) ────────────────────────────────────────────────── -echo "— filter_issues —" -# Attachment to THIS PR whose issue is open and on team BE. -LINKED_OPEN_BE='[{"issue":{"identifier":"BE-1","team":{"key":"BE"},"state":{"type":"started"}}}]' -# Same shape but completed. -LINKED_DONE_BE='[{"issue":{"identifier":"BE-1","team":{"key":"BE"},"state":{"type":"completed"}}}]' -# Attachment whose issue belongs to a different team. -LINKED_OPEN_OPS='[{"issue":{"identifier":"OPS-9","team":{"key":"OPS"},"state":{"type":"backlog"}}}]' -# An attachment with no issue (e.g. a non-issue attachment) plus a passing one. -MIXED='[{"issue":null},{"issue":{"identifier":"BE-2","team":{"key":"BE"},"state":{"type":"triage"}}}]' -# Two linked issues, only the second satisfies an open+BE policy. -MULTI='[{"issue":{"identifier":"BE-1","team":{"key":"BE"},"state":{"type":"canceled"}}},{"issue":{"identifier":"ENG-5","team":{"key":"ENG"},"state":{"type":"started"}}}]' - -eq "canonical open attachment passes (any team)" "BE-1" "$(filter_issues "$LINKED_OPEN_BE" '' true)" -eq "empty attachments -> no pass" "" "$(filter_issues '[]' '' true)" -eq "completed issue rejected when require-open" "" "$(filter_issues "$LINKED_DONE_BE" '' true)" -eq "completed issue accepted when NOT require-open" "BE-1" "$(filter_issues "$LINKED_DONE_BE" '' false)" -eq "restricted team-keys accepts matching team" "BE-1" "$(filter_issues "$LINKED_OPEN_BE" 'BE,ENG' true)" -eq "restricted team-keys rejects other team" "" "$(filter_issues "$LINKED_OPEN_OPS" 'BE,ENG' true)" -eq "null-issue attachment ignored, real one passes" "BE-2" "$(filter_issues "$MIXED" '' true)" -eq "multi-link passes when at least one satisfies policy" "ENG-5" "$(filter_issues "$MULTI" '' true)" -eq "multi-link empty when restricted team excludes the open one" "" "$(filter_issues "$MULTI" 'BE' true)" - -# count_linked -eq "count_linked counts non-null issues" "1" "$(count_linked "$MIXED")" -eq "count_linked zero for empty" "0" "$(count_linked '[]')" -eq "count_linked counts both linked issues" "2" "$(count_linked "$MULTI")" - -# ── classify_linear_error ───────────────────────────────────────────────────── -echo "— classify_linear_error —" -eq "RATELIMITED code is retryable (even on HTTP 400)" "retryable" "$(classify_linear_error 400 'RATELIMITED')" -eq "HTTP 503 is retryable" "retryable" "$(classify_linear_error 503 '')" -eq "HTTP 429 is retryable" "retryable" "$(classify_linear_error 429 '')" -eq "auth error is terminal" "terminal" "$(classify_linear_error 401 'AUTHENTICATION_ERROR')" -eq "schema/400 without ratelimit is terminal" "terminal" "$(classify_linear_error 400 'GRAPHQL_VALIDATION_FAILED')" - -# ── select_failure_category ─────────────────────────────────────────────────── -echo "— select_failure_category —" -eq "infra error dominates" "infra_error" "$(select_failure_category true 0 0)" -eq "infra error dominates even with links" "infra_error" "$(select_failure_category true 2 3)" -eq "linked-but-policy -> policy_mismatch" "policy_mismatch" "$(select_failure_category false 1 0)" -eq "no link, identifier referenced -> exists_not_linked" "exists_not_linked" "$(select_failure_category false 0 2)" -eq "referenced count decides, not resolution -> exists_not_linked" "exists_not_linked" "$(select_failure_category false 0 1)" -eq "no link, nothing referenced -> no_candidate" "no_candidate" "$(select_failure_category false 0 0)" - -# ── failure_guidance ────────────────────────────────────────────────────────── -echo "— failure_guidance —" -for cat in no_candidate exists_not_linked policy_mismatch infra_error; do - DESC="guidance for $cat is non-empty" - if [ -n "$(failure_guidance "$cat")" ]; then ok "$DESC"; else bad "$DESC" ""; fi -done -DESC="unknown category fails"; fail_rc failure_guidance bogus - -# ── build_diagnostic_query / count_resolved_candidates ──────────────────────── -echo "— build_diagnostic_query —" -DESC="empty candidate list -> rc1"; fail_rc build_diagnostic_query < /dev/null -Q="$(printf 'BE-1\nENG-2\n' | build_diagnostic_query)" -eq "builds one alias per candidate" "2" "$(printf '%s' "$Q" | grep -cE '^\s*c[0-9]+: issueSearch')" -eq "embeds the identifier as a query literal" "1" "$(printf '%s' "$Q" | grep -c 'query: "BE-1"')" - -echo "— count_resolved_candidates —" -RESP='{"data":{"c0":{"nodes":[{"identifier":"BE-1"}]},"c1":{"nodes":[]}}}' -eq "counts aliases with at least one node" "1" "$(count_resolved_candidates "$RESP")" -eq "malformed response counts as 0" "0" "$(count_resolved_candidates 'not json')" -eq "absent data counts as 0" "0" "$(count_resolved_candidates '{"errors":[]}')" - -# ── summary ─────────────────────────────────────────────────────────────────── -echo -echo "PASS=$PASS FAIL=$FAIL" -[ "$FAIL" -eq 0 ] diff --git a/scripts/linear-ticket/validate.py b/scripts/linear-ticket/validate.py new file mode 100644 index 00000000..857bd852 --- /dev/null +++ b/scripts/linear-ticket/validate.py @@ -0,0 +1,459 @@ +#!/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.""" + 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) -> None: + 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: + warning(f"Failed to publish '{state}' status on {sha}: {result.stderr.strip()}") + + def find_marker_comment(self, pr: int) -> int | None: + comments = self.get(f"/repos/{self.repo}/issues/{pr}/comments", paginate=True) or [] + for comment in comments: + if lib.MARKER in (comment.get("body") or ""): + 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.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(): + self.gh.publish_status(self.validated_sha, "success", + f"Linked Linear issue: {identifiers}", self.run_url) + return 0 + + def finish_exempt(self) -> int: + summary("## linear-ticket: ✅ exempt") + summary("") + summary(f"PR carries the `{self.exempt_label}` label — the Linear-ticket requirement " + "is waived.") + self.gh.delete_marker_comment(self.pr_number) + if self._guard_supersession(): + self.gh.publish_status(self.validated_sha, "success", + f"Exempt via {self.exempt_label} label", self.run_url) + 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."), + ] + 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 self._guard_supersession(): + self.gh.publish_status(self.validated_sha, state, short, self.run_url) + return 0 if not self.enforce else 1 + + # -- the run --------------------------------------------------------------------------- + def run(self, event: dict) -> int: + head_sha = (event.get("workflow_run") or {}).get("head_sha") or "" + if not head_sha: + error("workflow_run.head_sha missing from event") + 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 [])] + + 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 self.exempt_label and self.exempt_label in labels: + log(f"PR carries the '{self.exempt_label}' label — exempt.") + return self.finish_exempt() + + 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 + 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: + 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]) + 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()) diff --git a/scripts/linear-ticket/validate.sh b/scripts/linear-ticket/validate.sh deleted file mode 100644 index 01ec39ae..00000000 --- a/scripts/linear-ticket/validate.sh +++ /dev/null @@ -1,367 +0,0 @@ -#!/usr/bin/env bash -# validate.sh — the side-effecting orchestration behind linear-ticket.yml. Sources lib.sh -# 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 jq/curl through argument -# arrays and GraphQL variables, never interpolated into a query or a shell word. 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 -set -uo pipefail - -SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -# shellcheck source=./lib.sh -. "$SELF_DIR/lib.sh" - -LINEAR_API_URL="${LINEAR_API_URL:-https://api.linear.app/graphql}" -SUMMARY_FILE="${GITHUB_STEP_SUMMARY:-/dev/null}" - -# ── logging ────────────────────────────────────────────────────────────────── -log() { printf '%s\n' "$*" >&2; } -err() { printf '::error::%s\n' "$*" >&2; } -warn() { printf '::warning::%s\n' "$*" >&2; } -summary() { printf '%s\n' "$*" >>"$SUMMARY_FILE"; } - -# ── GraphQL queries (static; the URL is the only variable) ──────────────────── -# shellcheck disable=SC2016 # $url is a GraphQL variable, not a shell expansion -ATTACHMENTS_QUERY='query PullRequestAttachments($url: String!) { - attachmentsForURL(url: $url, first: 20) { - nodes { id url issue { id identifier team { key } state { type } } } - } -}' - -# linear_post — POST a JSON GraphQL request. Writes the response body to -# stdout and sets globals LINEAR_HTTP (status) and LINEAR_ERR_CODES (space-joined GraphQL -# error `extensions.code`s). rc 0 on any completed HTTP exchange (even a 4xx/5xx — the -# caller classifies it), rc 1 only on a transport failure (curl could not complete). -LINEAR_HTTP=""; LINEAR_ERR_CODES="" -linear_post() { - local body_file="$1" - local hdr_file; hdr_file="$(mktemp)" - local out - # --Authorization verbatim: a personal API key goes raw, an OAuth token as "Bearer ...". - # The header value is set once here; docs tell the caller which form to store. - out="$(curl -sS --max-time 30 -D "$hdr_file" -X POST "$LINEAR_API_URL" \ - -H "Authorization: ${LINEAR_API_TOKEN}" \ - -H 'Content-Type: application/json' \ - --data-binary "@${body_file}" 2>/dev/null)" - local curl_rc=$? - if [ "$curl_rc" -ne 0 ]; then - rm -f "$hdr_file" - LINEAR_HTTP=""; LINEAR_ERR_CODES="" - return 1 - fi - LINEAR_HTTP="$(awk 'toupper($1) ~ /^HTTP/ {code=$2} END {print code}' "$hdr_file")" - # Log rate-limit headroom for the pilot (design §8), best-effort. - grep -iE '^x-ratelimit-(requests|complexity)-(remaining|reset):' "$hdr_file" >&2 || true - rm -f "$hdr_file" - LINEAR_ERR_CODES="$(printf '%s' "$out" | jq -r '[.errors[]?.extensions.code // empty] | join(" ")' 2>/dev/null || true)" - printf '%s' "$out" -} - -# build_graphql_body [] — a GraphQL request body with the PR URL passed as a -# VARIABLE, never interpolated into the query text (design §4). -build_graphql_body() { - local query="$1" - if [ "$#" -ge 2 ]; then - jq -n --arg q "$query" --arg url "$2" '{query: $q, variables: {url: $url}}' - else - jq -n --arg q "$query" '{query: $q}' - fi -} - -# ── commit status ───────────────────────────────────────────────────────────── -# publish_status -publish_status() { - local sha="$1" state="$2" description="$3" - gh api -X POST "repos/${GH_REPO}/statuses/${sha}" \ - -f "state=${state}" \ - -f "context=${LINEAR_TICKET_CONTEXT}" \ - -f "description=${description}" \ - -f "target_url=${RUN_URL:-}" >/dev/null 2>&1 \ - || warn "Failed to publish '${state}' status on ${sha}" -} - -# ── marker comment ───────────────────────────────────────────────────────────── -# find_marker_comment — echo the id of the existing marker comment, or empty. -find_marker_comment() { - gh api --paginate "repos/${GH_REPO}/issues/${1}/comments" \ - --jq ".[] | select(.body | contains(\"${LINEAR_TICKET_MARKER}\")) | .id" 2>/dev/null \ - | head -n1 -} - -# upsert_marker_comment — create or update the single marker -# comment. Comment I/O is best-effort: a failure is warned, never fatal (design §6). -upsert_marker_comment() { - local pr="$1" body_file="$2" existing - existing="$(find_marker_comment "$pr")" - if [ -n "$existing" ]; then - gh api -X PATCH "repos/${GH_REPO}/issues/comments/${existing}" \ - -F "body=@${body_file}" >/dev/null 2>&1 || warn "Failed to update marker comment ${existing}" - else - gh api -X POST "repos/${GH_REPO}/issues/${pr}/comments" \ - -F "body=@${body_file}" >/dev/null 2>&1 || warn "Failed to create marker comment" - fi -} - -# delete_marker_comment — remove the marker comment after a pass/exempt run. -delete_marker_comment() { - local pr="$1" existing - existing="$(find_marker_comment "$pr")" - [ -z "$existing" ] && return 0 - gh api -X DELETE "repos/${GH_REPO}/issues/comments/${existing}" >/dev/null 2>&1 \ - || warn "Failed to delete marker comment ${existing}" -} - -# current_head_sha — the PR's head SHA right now, for the supersession recheck. -current_head_sha() { - gh api "repos/${GH_REPO}/pulls/${1}" --jq '.head.sha' 2>/dev/null -} - -# ── terminal outcomes ────────────────────────────────────────────────────────── -# In warn-only mode every outcome publishes SUCCESS but the summary/comment still show the -# verdict enforce mode would have produced (design §7). Before any terminal status write we -# refetch the PR head SHA and bail if it moved — a newer run must win (design §6). -VALIDATED_SHA=""; PR_NUMBER="" - -finish_pass() { - local identifiers="$1" - summary "## linear-ticket: ✅ pass" - summary "" - summary "Linear has linked this PR to: **${identifiers}**" - delete_marker_comment "$PR_NUMBER" - guard_supersession || return 0 - publish_status "$VALIDATED_SHA" success "Linked Linear issue: ${identifiers}" - exit 0 -} - -finish_exempt() { - summary "## linear-ticket: ✅ exempt" - summary "" - summary "PR carries the \`${EXEMPT_LABEL}\` label — the Linear-ticket requirement is waived." - delete_marker_comment "$PR_NUMBER" - guard_supersession || return 0 - publish_status "$VALIDATED_SHA" success "Exempt via ${EXEMPT_LABEL} label" - exit 0 -} - -# finish_fail -finish_fail() { - local category="$1" detail="$2" - local guidance; guidance="$(failure_guidance "$category")" - local verdict state short - if [ "$ENFORCE" = "false" ]; then - verdict="⚠️ warn-only (would fail: ${category})"; state="success"; short="warn-only: would fail (${category})" - else - verdict="❌ fail (${category})"; state="failure"; short="No linked Linear issue (${category})" - fi - - # One marker comment carrying the same diagnosis in both modes. - local body_file; body_file="$(mktemp)" - { - printf '%s\n\n' "$LINEAR_TICKET_MARKER" - printf '### Linear ticket check — %s\n\n' "$verdict" - printf '%s\n' "$guidance" - [ -n "$detail" ] && printf '\n%s\n' "$detail" - printf '\n---\n' - printf 'After linking an issue, re-run this check from the [workflow run](%s) or edit the PR title/body to trigger a fresh run. ' "${RUN_URL:-}" - # shellcheck disable=SC2016 # backticks are literal markdown for the label name, not a subshell - printf 'A repository maintainer can waive the requirement by applying the `%s` label.\n' "${EXEMPT_LABEL:-linear-exempt}" - } >"$body_file" - upsert_marker_comment "$PR_NUMBER" "$body_file" - rm -f "$body_file" - - summary "## linear-ticket: ${verdict}" - summary "" - summary "$guidance" - [ -n "$detail" ] && summary "$detail" - - guard_supersession || return 0 - publish_status "$VALIDATED_SHA" "$state" "$short" - [ "$ENFORCE" = "false" ] && exit 0 - exit 1 -} - -# guard_supersession — rc 0 to proceed with the terminal write, rc 1 to bail because the PR -# head advanced past the SHA we validated (a newer run owns the result now). -guard_supersession() { - local now; now="$(current_head_sha "$PR_NUMBER")" - if [ -n "$now" ] && [ "$now" != "$VALIDATED_SHA" ]; then - log "PR head moved ${VALIDATED_SHA} -> ${now}; a newer run supersedes this one. Not writing a terminal status." - return 1 - fi - return 0 -} - -# ── main ─────────────────────────────────────────────────────────────────────── -main() { - for tool in gh jq curl; do - command -v "$tool" >/dev/null 2>&1 || { err "$tool not found on PATH"; exit 1; } - done - [ -n "${GH_REPO:-}" ] || { err "GH_REPO is required"; exit 1; } - [ -n "${GITHUB_EVENT_PATH:-}" ] || { err "GITHUB_EVENT_PATH is required"; exit 1; } - [ -f "$GITHUB_EVENT_PATH" ] || { err "event payload not found at GITHUB_EVENT_PATH"; exit 1; } - [ -n "${LINEAR_API_TOKEN:-}" ] || { err "LINEAR_API_TOKEN secret is not set; failing closed (infrastructure error)"; exit 1; } - - # team-keys is a caller-config input: a malformed value is a misconfiguration, so fail the - # run loudly rather than silently widening policy (design §5.1). - local team_keys - if ! team_keys="$(normalize_team_keys "${TEAM_KEYS:-}")"; then - err "Invalid team-keys input '${TEAM_KEYS:-}': entries must be uppercase alphanumeric team keys, unique, comma-separated." - exit 1 - fi - - # Only a completed run of the signal workflow should reach here; the caller's `if:` gates - # this, but re-assert it so a mis-wired caller fails safe rather than validating garbage. - local event="$GITHUB_EVENT_PATH" - local wr_event; wr_event="$(jq -r '.workflow_run.event // ""' "$event")" - local head_sha; head_sha="$(jq -r '.workflow_run.head_sha // ""' "$event")" - [ -n "$head_sha" ] || { err "workflow_run.head_sha missing from event"; exit 1; } - - # Resolve 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). We - # require exactly one OPEN PR, refetched through the API before any status write. - local -a candidates=() - local n - while IFS= read -r n; do [ -n "$n" ] && candidates+=("$n"); done < <( - jq -r '.workflow_run.pull_requests[]?.number // empty' "$event" - ) - if [ "${#candidates[@]}" -eq 0 ]; then - while IFS= read -r n; do [ -n "$n" ] && candidates+=("$n"); done < <( - gh api "repos/${GH_REPO}/commits/${head_sha}/pulls" \ - --jq ".[] | select(.state==\"open\") | select(.base.repo.full_name==\"${GH_REPO}\") | .number" 2>/dev/null - ) - fi - - # De-dup + keep only currently-open PRs. - local -a open_prs=() - local seen_pr="" - for n in "${candidates[@]}"; do - case " $seen_pr " in *" $n "*) continue ;; esac - seen_pr="$seen_pr $n" - local st; st="$(gh api "repos/${GH_REPO}/pulls/${n}" --jq '.state' 2>/dev/null || true)" - [ "$st" = "open" ] && open_prs+=("$n") - done - - if [ "${#open_prs[@]}" -ne 1 ]; then - err "Expected exactly one open PR associated with ${head_sha}, found ${#open_prs[@]} (event=${wr_event}). Refusing to publish an ambiguous result." - exit 1 - fi - PR_NUMBER="${open_prs[0]}" - - # Refetch the PR: canonical html_url, current head SHA (the status target), labels, and the - # untrusted text we mine for diagnostic candidates. - local pr_json; pr_json="$(gh api "repos/${GH_REPO}/pulls/${PR_NUMBER}" 2>/dev/null)" \ - || { err "Could not fetch PR #${PR_NUMBER}"; exit 1; } - local html_url; html_url="$(printf '%s' "$pr_json" | jq -r '.html_url')" - VALIDATED_SHA="$(printf '%s' "$pr_json" | jq -r '.head.sha')" - local pr_branch; pr_branch="$(printf '%s' "$pr_json" | jq -r '.head.ref // ""')" - local pr_title; pr_title="$(printf '%s' "$pr_json" | jq -r '.title // ""')" - local pr_body; pr_body="$(printf '%s' "$pr_json" | jq -r '.body // ""')" - - log "Validating PR #${PR_NUMBER} (${html_url}) at head ${VALIDATED_SHA}" - publish_status "$VALIDATED_SHA" pending "Checking for a linked Linear issue…" - - # Exemption short-circuit. - if [ -n "${EXEMPT_LABEL:-}" ]; then - if printf '%s' "$pr_json" | jq -e --arg l "$EXEMPT_LABEL" '.labels[]?.name == $l | select(.)' >/dev/null 2>&1; then - log "PR carries the '${EXEMPT_LABEL}' label — exempt." - finish_exempt - fi - fi - - # ── the gate: attachmentsForURL(this PR), with bounded retry for the async-link race ── - local body_file; body_file="$(mktemp)" - build_graphql_body "$ATTACHMENTS_QUERY" "$html_url" >"$body_file" - - local -a backoff=(2 4 8 16) # between five attempts - local infra_error=false - local nodes='[]' - local attempt - for attempt in 0 1 2 3 4; do - local resp; resp="$(linear_post "$body_file")"; local post_rc=$? - if [ "$post_rc" -ne 0 ]; then - log "Linear request transport failure (attempt $((attempt+1)))" - elif [ -n "$LINEAR_ERR_CODES" ] || { [ -n "$LINEAR_HTTP" ] && [ "$LINEAR_HTTP" -ge 400 ] 2>/dev/null; }; then - local kind; kind="$(classify_linear_error "${LINEAR_HTTP:-0}" "${LINEAR_ERR_CODES:-}")" - if [ "$kind" = "terminal" ]; then - err "Linear returned a terminal error (HTTP ${LINEAR_HTTP:-?}, codes: ${LINEAR_ERR_CODES:-none}). Failing closed as an infrastructure error." - infra_error=true - break - fi - log "Linear returned a retryable error (HTTP ${LINEAR_HTTP:-?}, codes: ${LINEAR_ERR_CODES:-none}) on attempt $((attempt+1))" - else - # A clean response. Extract the attachment nodes. - nodes="$(printf '%s' "$resp" | jq -c '.data.attachmentsForURL.nodes // []' 2>/dev/null || echo '[]')" - local linked; linked="$(count_linked "$nodes")" - if [ "$linked" -gt 0 ]; then - break # attachments present — evaluate policy, no reason to retry - fi - log "No attachment linked to this PR yet (attempt $((attempt+1)))" - fi - # Retry with backoff unless this was the last attempt. - if [ "$attempt" -lt 4 ]; then - sleep "${backoff[$attempt]}" - fi - done - rm -f "$body_file" - - if [ "$infra_error" = false ]; then - local passing; passing="$(filter_issues "$nodes" "$team_keys" "${REQUIRE_OPEN_ISSUE:-true}")" - if [ -n "$passing" ]; then - local joined; joined="$(printf '%s' "$passing" | paste -sd ',' - | sed 's/,/, /g')" - log "PASS — linked issue(s): ${joined}" - finish_pass "$joined" - fi - fi - - # ── failure path: diagnostics only (never turns red into green) ── - local linked_count; linked_count="$(count_linked "$nodes")" - local referenced_count=0 resolved_count=0 - local candidate_detail="" - if [ "$infra_error" = false ] && [ "$linked_count" -eq 0 ]; then - local candidates_list; candidates_list="$(printf '%s\n%s\n%s' "$pr_branch" "$pr_title" "$pr_body" | extract_candidates)" - if [ -n "$candidates_list" ]; then - referenced_count="$(printf '%s\n' "$candidates_list" | grep -c .)" - local joined_candidates; joined_candidates="$(printf '%s' "$candidates_list" | paste -sd ',' - | sed 's/,/, /g')" - local diag_query; if diag_query="$(printf '%s' "$candidates_list" | build_diagnostic_query)"; then - local diag_file; diag_file="$(mktemp)" - build_graphql_body "$diag_query" >"$diag_file" - local diag_resp; diag_resp="$(linear_post "$diag_file")" - rm -f "$diag_file" - resolved_count="$(count_resolved_candidates "$diag_resp")" - fi - if [ "$resolved_count" -gt 0 ] 2>/dev/null; then - candidate_detail="Referenced identifiers (not linked): ${joined_candidates} — at least one resolves to a real Linear issue; link it to this PR." - else - candidate_detail="Referenced identifiers (not linked): ${joined_candidates}" - fi - fi - fi - - local category; category="$(select_failure_category "$infra_error" "$linked_count" "$referenced_count")" - local detail="$candidate_detail" - if [ "$category" = "policy_mismatch" ]; then - local linked_ids; linked_ids="$(printf '%s' "$nodes" | jq -r '[ (.[]? | .issue) | select(.!=null) | .identifier ] | join(", ")')" - detail="Linked but not accepted: ${linked_ids}" - fi - log "FAIL category=${category} linked=${linked_count} resolved=${resolved_count}" - finish_fail "$category" "$detail" -} - -main "$@" From c58b7e6f92d40f92a7794d4ff8c9b45416e8b3af Mon Sep 17 00:00:00 2001 From: Luke Mino-Altherr Date: Tue, 18 Aug 2026 19:24:34 -0700 Subject: [PATCH 3/4] fix(linear-ticket): address CodeRabbit review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Correctness/security fixes on validate.py: - find_marker_comment now requires the Actions-bot author, not just the public marker string, so a contributor's squatted marker can't hijack (and 403) the gate's PATCH/DELETE and suppress the failure comment. - Reject a triggering workflow_run whose event is not pull_request; a miswired caller can otherwise resolve an open PR from a push head SHA and publish linear-ticket for it. - Exhausted retries (all transport/retryable) now set infra_error and fail closed, matching lib.py's documented contract, instead of blaming the author (or going green in warn-only) on a Linear outage. - Terminal commit-status writes are critical: a failed publish is an error that fails the job, so a prior success can't keep gating open under a run that meant to publish failure. pending stays best-effort. - Guard supersession before writing the failure comment, not just the status. - Add per_page=100 to the comment fetch; make get()'s paginate keyword-only. Tests/docs: - Pin the build_diagnostic_query injection guard with a hostile-candidate test and an all-malformed→raise test (42 tests total). - Neutral branch fixture in the extract test (public repo). - Fix MD038 trailing-space `Bearer` code spans in the caller guide. - Extend the shared workflows_ref guidance to cover the required-no-default workflows (pr-risk, pr-derisk, refresh-reviewers, linear-ticket). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/callers/README.md | 21 ++++-- docs/callers/linear-ticket.md | 4 +- scripts/linear-ticket/tests/test_lib.py | 18 ++++- scripts/linear-ticket/validate.py | 87 +++++++++++++++++++++---- 4 files changed, 107 insertions(+), 23 deletions(-) diff --git a/docs/callers/README.md b/docs/callers/README.md index 3e0508b7..19bc1dbd 100644 --- a/docs/callers/README.md +++ b/docs/callers/README.md @@ -111,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`. - -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: +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. + +- `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 index ecc7a280..b49f2d7c 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -33,7 +33,7 @@ on the PR head SHA; you require **that context** once warn-only observation is d | | | |---|---| -| `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 `. Missing/invalid fails the check *closed* as an infrastructure error (never green). | +| `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 @@ -149,4 +149,4 @@ credential must not silently disable the org-wide control. Availability is handl 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 `. The value is dropped straight into the `Authorization` header. +with `Bearer` followed by one space. The value is dropped straight into the `Authorization` header. diff --git a/scripts/linear-ticket/tests/test_lib.py b/scripts/linear-ticket/tests/test_lib.py index 1f5e964c..969be5cc 100644 --- a/scripts/linear-ticket/tests/test_lib.py +++ b/scripts/linear-ticket/tests/test_lib.py @@ -27,7 +27,7 @@ def test_dedupes_case_insensitively_first_seen(self): def test_reads_multiline_concatenation(self): self.assertEqual( - lib.extract_candidates("luke/be-1-x\nTitle ENG-2\nCloses OPS-3"), + lib.extract_candidates("feat/be-1-x\nTitle ENG-2\nCloses OPS-3"), ["BE-1", "ENG-2", "OPS-3"], ) @@ -180,6 +180,22 @@ def test_count_resolved_malformed_is_zero(self): 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 index 857bd852..7931e21c 100644 --- a/scripts/linear-ticket/validate.py +++ b/scripts/linear-ticket/validate.py @@ -84,8 +84,13 @@ def _run(self, args: list[str], stdin: str | None = None) -> subprocess.Complete capture_output=True, ) - def get(self, path: str, paginate: bool = False): - """GET a JSON endpoint; returns the parsed body or None on failure.""" + 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") @@ -98,7 +103,15 @@ def get(self, path: str, paginate: bool = False): except json.JSONDecodeError: return None - def publish_status(self, sha: str, state: str, description: str, target_url: str) -> 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}", @@ -107,12 +120,27 @@ def publish_status(self, sha: str, state: str, description: str, target_url: str "-f", f"target_url={target_url}", ]) if result.returncode != 0: - warning(f"Failed to publish '{state}' status on {sha}: {result.stderr.strip()}") + 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: - comments = self.get(f"/repos/{self.repo}/issues/{pr}/comments", paginate=True) or [] + """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 in (comment.get("body") or ""): + 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 @@ -233,8 +261,10 @@ def finish_pass(self, identifiers: str) -> int: summary(f"Linear has linked this PR to: **{identifiers}**") self.gh.delete_marker_comment(self.pr_number) if self._guard_supersession(): - self.gh.publish_status(self.validated_sha, "success", - f"Linked Linear issue: {identifiers}", self.run_url) + 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) -> int: @@ -244,8 +274,10 @@ def finish_exempt(self) -> int: "is waived.") self.gh.delete_marker_comment(self.pr_number) if self._guard_supersession(): - self.gh.publish_status(self.validated_sha, "success", - f"Exempt via {self.exempt_label} label", self.run_url) + if not self.gh.publish_status(self.validated_sha, "success", + f"Exempt via {self.exempt_label} label", self.run_url, + critical=True): + return 1 return 0 def finish_fail(self, category: str, detail: str) -> int: @@ -275,6 +307,13 @@ def finish_fail(self, category: str, detail: str) -> int: "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}") @@ -283,17 +322,29 @@ def finish_fail(self, category: str, detail: str) -> int: if detail: summary(detail) - if self._guard_supersession(): - self.gh.publish_status(self.validated_sha, state, short, self.run_url) + 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: - head_sha = (event.get("workflow_run") or {}).get("head_sha") or "" + 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 @@ -359,6 +410,7 @@ def _query_attachments(self, html_url: str): 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: @@ -374,6 +426,7 @@ def _query_attachments(self, html_url: str): 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: @@ -381,6 +434,14 @@ def _query_attachments(self, html_url: str): 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: From ebb68c870e577fe8926bc5fb202da94546f01dc6 Mon Sep 17 00:00:00 2001 From: Luke Mino-Altherr Date: Tue, 18 Aug 2026 19:31:52 -0700 Subject: [PATCH 4/4] feat(linear-ticket): add opt-in exempt-actors for bot PRs; address Wei's review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wei (wei-hai) review on #183: - exempt-actors input (comma-separated PR-author logins, e.g. dependabot[bot],renovate[bot]) checked before the Linear query — the non-manual hatch for bot PRs that never carry a ticket. Opt-in and EMPTY by default, so the design's "no built-in bypass" posture is preserved: a repo that lists an actor explicitly accepts that all of its PRs merge without a ticket. lib.parse_actor_list + tests; finish_exempt now carries the reason. - Doc the stale-link case (link made in Linear after a red check emits no GitHub event) as an explicit warn-only-week tracking step, with the Linear-webhook repository_dispatch fix flagged as a deliberate v2 follow-up. - Recommend leaving team-keys empty unless a repo wants team scoping (a restricted list fails cross-team PRs on first contact). - Sharpen filter_issues docstring: it returns the passing SUBSET ("any linked issue satisfies policy"), not "every link is validated". Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/linear-ticket.yml | 11 +++++++++++ README.md | 2 +- docs/callers/linear-ticket.md | 23 ++++++++++++++++------ scripts/linear-ticket/lib.py | 15 ++++++++++++++ scripts/linear-ticket/tests/test_lib.py | 15 ++++++++++++++ scripts/linear-ticket/validate.py | 26 ++++++++++++++++++------- 6 files changed, 78 insertions(+), 14 deletions(-) diff --git a/.github/workflows/linear-ticket.yml b/.github/workflows/linear-ticket.yml index 86e215b7..ffd76315 100644 --- a/.github/workflows/linear-ticket.yml +++ b/.github/workflows/linear-ticket.yml @@ -60,6 +60,16 @@ on: 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 @@ -196,6 +206,7 @@ jobs: 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 }} diff --git a/README.md b/README.md index f5e04488..8e3f03e6 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 (same diagnosis, always-green status); one `exempt-label` (e.g. `linear-exempt`) waives it. Logic + hermetic tests live in [`scripts/linear-ticket/`](scripts/linear-ticket); `workflows_ref` is **required**, shape- and ancestry-checked before checkout. Requires `LINEAR_API_TOKEN` + the two-workflow caller. | [linear-ticket.md](docs/callers/linear-ticket.md) | +| [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR** before it can merge — not a `TEAM-123`-shaped string in author text. The only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) — they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`linear-ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA before every terminal write so a superseded run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only (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/linear-ticket.md b/docs/callers/linear-ticket.md index b49f2d7c..e4428373 100644 --- a/docs/callers/linear-ticket.md +++ b/docs/callers/linear-ticket.md @@ -82,8 +82,10 @@ jobs: uses: Comfy-Org/github-workflows/.github/workflows/linear-ticket.yml@ # v1 with: workflows_ref: - # team-keys: BE,ENG # optional; empty (default) accepts any visible team + # 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: @@ -111,8 +113,9 @@ job-level detail. | 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. Empty accepts any team the token can see. Malformed or duplicate entries fail 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. | @@ -124,10 +127,18 @@ job-level detail. 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. Flip `enforce: true`. Leave the check non-required for a short window. -4. Add the **`linear-ticket`** status context to your `main` ruleset as a required check. - -Nothing here changes branch protection automatically — step 4 is a manual repo-admin action. +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 diff --git a/scripts/linear-ticket/lib.py b/scripts/linear-ticket/lib.py index 98110f40..d582ec92 100644 --- a/scripts/linear-ticket/lib.py +++ b/scripts/linear-ticket/lib.py @@ -78,9 +78,24 @@ def normalize_team_keys(raw: str) -> list[str]: 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: diff --git a/scripts/linear-ticket/tests/test_lib.py b/scripts/linear-ticket/tests/test_lib.py index 969be5cc..de777f44 100644 --- a/scripts/linear-ticket/tests/test_lib.py +++ b/scripts/linear-ticket/tests/test_lib.py @@ -68,6 +68,21 @@ def test_leading_digit_rejected(self): 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}}} diff --git a/scripts/linear-ticket/validate.py b/scripts/linear-ticket/validate.py index 7931e21c..6d990c1e 100644 --- a/scripts/linear-ticket/validate.py +++ b/scripts/linear-ticket/validate.py @@ -241,6 +241,7 @@ def __init__(self, gh: GitHub, token: str, team_keys, require_open, enforce, run 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 @@ -267,16 +268,14 @@ def finish_pass(self, identifiers: str) -> int: return 1 return 0 - def finish_exempt(self) -> int: + def finish_exempt(self, headline: str, status_desc: str) -> int: summary("## linear-ticket: ✅ exempt") summary("") - summary(f"PR carries the `{self.exempt_label}` label — the Linear-ticket requirement " - "is waived.") + summary(headline) self.gh.delete_marker_comment(self.pr_number) if self._guard_supersession(): - if not self.gh.publish_status(self.validated_sha, "success", - f"Exempt via {self.exempt_label} label", self.run_url, - critical=True): + if not self.gh.publish_status(self.validated_sha, "success", status_desc, + self.run_url, critical=True): return 1 return 0 @@ -359,14 +358,27 @@ def run(self, event: dict) -> int: 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() + 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)