[PR #183] [MERGED] feat(linear-ticket): require a linked Linear issue on every PR #194

New issue

Closed

opened 2026-10-26 22:37:13 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:37:13 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/github-workflows/pull/183
Author: @luke-mino-altherr
Created: 8/18/2026
Status: ✅ Merged
Merged: 8/19/2026
Merged by: @luke-mino-altherr

Base: main ← Head: luke/linear-ticket-enforcement

📝 Commits (4)

d9d6882 feat(linear-ticket): require a linked Linear issue on every PR
96db157 refactor(linear-ticket): implement in Python instead of shell
c58b7e6 fix(linear-ticket): address CodeRabbit review
ebb68c8 feat(linear-ticket): add opt-in exempt-actors for bot PRs; address Wei's review

📊 Changes

9 files changed (+1499 additions, -6 deletions)

View changed files

➕ .github/workflows/linear-ticket.yml (+213 -0)
➕ .github/workflows/test-linear-ticket.yml (+51 -0)
📝 README.md (+1 -0)
📝 docs/callers/README.md (+14 -6)
➕ docs/callers/linear-ticket.md (+163 -0)
➕ scripts/linear-ticket/README.md (+60 -0)
➕ scripts/linear-ticket/lib.py (+249 -0)
➕ scripts/linear-ticket/tests/test_lib.py (+216 -0)
➕ scripts/linear-ticket/validate.py (+532 -0)

📄 Description

What

Adds a reusable workflow that requires every PR to carry a Linear issue Linear has linked to that exact PR before it can merge — flexible about the linking method, resistant to spoofing. Implements the pr-linear-ticket-enforcement design.

The only thing that turns the check green 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/state policy. A TEAM-123-shaped string in author-controlled text never passes; identifiers mined from branch/title/body are diagnostics only (20-cap, one batched lookup).

Shape

Same split as the risk-grader/area-label reusables — logic here, a thin caller in each consumer repo. Implemented in stdlib Python to match this repo's convention (groom, refresh-reviewers, agents-md-integrity, cursor-review).

.github/workflows/linear-ticket.yml — on: workflow_call validator. Inputs workflows_ref (required, shape+ancestry-guarded), team-keys, exempt-label, require-open-issue, enforce; secret LINEAR_API_TOKEN; min job permissions actions:read, contents:read, pull-requests:write, statuses:write. Sets up Python 3.12 and runs validate.py.
scripts/linear-ticket/lib.py — pure, network-free core (candidate extraction, team-keys validation, the filter_issues policy gate, error classification, failure-category selection, copy, diagnostic-query builder).
scripts/linear-ticket/validate.py — orchestration: resolve exactly one open PR from the workflow_run event (same-repo pull_requests or fork commit→PR association), refetch, publish the linear-ticket commit status, query with bounded backoff (2/4/8/16s ×5), apply the gate, run one batched diagnostic query, maintain one marker comment, recheck the head SHA before every terminal write, fail closed on infra errors, warn-only mode. GitHub via the gh CLI (subprocess), Linear via urllib.
Tests: scripts/linear-ticket/tests/test_lib.py (40-case unittest suite) + path-filtered test-linear-ticket.yml (unittest discover + a py_compile gate for validate.py).
Docs: docs/callers/linear-ticket.md (the two consumer workflows, permissions, rollout, footguns), scripts/linear-ticket/README.md, README + callers-index rows.

Fork/Dependabot safety

The pull_request → workflow_run split: an unprivileged signal workflow (checks out nothing, no secret) triggers a privileged validator on workflow_run: completed, which GitHub grants the secret + write token. The validator runs on the default branch, so its job check is not the merge gate — branch protection requires the linear-ticket commit status it publishes on the refetched PR head SHA.

Verification

Local gates all green: python3 -m unittest discover (40 tests), py_compile, the workflow-pins lint (workflows_ref required, no default, guarded), YAML parse. Also smoke-tested validate.py end-to-end against a local HTTP server standing in for Linear + a stub gh on PATH, across pass / fail / warn-only / policy-mismatch paths.

Rollout (per the design)

Land here with tests → add pinned callers with enforce: false → observe ~a week → flip enforce: true → add the linear-ticket status to the main ruleset as required. No bump-caller fleet yet (deliberate: the pilot pins callers manually, repo-by-repo).

Requires the org secret LINEAR_API_TOKEN (being provisioned separately).

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Comfy-Org/github-workflows/pull/183 **Author:** [@luke-mino-altherr](https://github.com/luke-mino-altherr) **Created:** 8/18/2026 **Status:** ✅ Merged **Merged:** 8/19/2026 **Merged by:** [@luke-mino-altherr](https://github.com/luke-mino-altherr) **Base:** `main` ← **Head:** `luke/linear-ticket-enforcement` --- ### 📝 Commits (4) - [`d9d6882`](https://github.com/Comfy-Org/github-workflows/commit/d9d6882f238c2f44336293fcc4db3473fa13bc1c) feat(linear-ticket): require a linked Linear issue on every PR - [`96db157`](https://github.com/Comfy-Org/github-workflows/commit/96db1575a4fcedded0fc8c892d4c607639e660f4) refactor(linear-ticket): implement in Python instead of shell - [`c58b7e6`](https://github.com/Comfy-Org/github-workflows/commit/c58b7e6f92d40f92a7794d4ff8c9b45416e8b3af) fix(linear-ticket): address CodeRabbit review - [`ebb68c8`](https://github.com/Comfy-Org/github-workflows/commit/ebb68c870e577fe8926bc5fb202da94546f01dc6) feat(linear-ticket): add opt-in exempt-actors for bot PRs; address Wei's review ### 📊 Changes **9 files changed** (+1499 additions, -6 deletions) <details> <summary>View changed files</summary> ➕ `.github/workflows/linear-ticket.yml` (+213 -0) ➕ `.github/workflows/test-linear-ticket.yml` (+51 -0) 📝 `README.md` (+1 -0) 📝 `docs/callers/README.md` (+14 -6) ➕ `docs/callers/linear-ticket.md` (+163 -0) ➕ `scripts/linear-ticket/README.md` (+60 -0) ➕ `scripts/linear-ticket/lib.py` (+249 -0) ➕ `scripts/linear-ticket/tests/test_lib.py` (+216 -0) ➕ `scripts/linear-ticket/validate.py` (+532 -0) </details> ### 📄 Description ## What Adds a reusable workflow that requires every PR to carry a **Linear issue Linear has linked to that exact PR** before it can merge — flexible about the linking method, resistant to spoofing. Implements the `pr-linear-ticket-enforcement` design. The only thing that turns the check green 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/state policy. A `TEAM-123`-shaped string in author-controlled text never passes; identifiers mined from branch/title/body are **diagnostics only** (20-cap, one batched lookup). ## Shape Same split as the risk-grader/area-label reusables — logic here, a thin caller in each consumer repo. Implemented in **stdlib Python** to match this repo's convention (`groom`, `refresh-reviewers`, `agents-md-integrity`, `cursor-review`). - **`.github/workflows/linear-ticket.yml`** — `on: workflow_call` validator. Inputs `workflows_ref` (required, shape+ancestry-guarded), `team-keys`, `exempt-label`, `require-open-issue`, `enforce`; secret `LINEAR_API_TOKEN`; min job permissions `actions:read`, `contents:read`, `pull-requests:write`, `statuses:write`. Sets up Python 3.12 and runs `validate.py`. - **`scripts/linear-ticket/lib.py`** — pure, network-free core (candidate extraction, `team-keys` validation, the `filter_issues` policy gate, error classification, failure-category selection, copy, diagnostic-query builder). - **`scripts/linear-ticket/validate.py`** — orchestration: resolve exactly one open PR from the `workflow_run` event (same-repo `pull_requests` or fork commit→PR association), refetch, publish the `linear-ticket` commit status, query with bounded backoff (2/4/8/16s ×5), apply the gate, run one batched diagnostic query, maintain one marker comment, recheck the head SHA before every terminal write, fail closed on infra errors, warn-only mode. GitHub via the `gh` CLI (`subprocess`), Linear via `urllib`. - **Tests**: `scripts/linear-ticket/tests/test_lib.py` (40-case `unittest` suite) + path-filtered `test-linear-ticket.yml` (`unittest discover` + a `py_compile` gate for `validate.py`). - **Docs**: `docs/callers/linear-ticket.md` (the two consumer workflows, permissions, rollout, footguns), `scripts/linear-ticket/README.md`, README + callers-index rows. ## Fork/Dependabot safety The `pull_request` → `workflow_run` split: an unprivileged signal workflow (checks out nothing, no secret) triggers a privileged validator on `workflow_run: completed`, which GitHub grants the secret + write token. The validator runs on the default branch, so its job check is **not** the merge gate — branch protection requires the `linear-ticket` commit **status** it publishes on the refetched PR head SHA. ## Verification Local gates all green: `python3 -m unittest discover` (40 tests), `py_compile`, the `workflow-pins` lint (`workflows_ref` required, no default, guarded), YAML parse. Also smoke-tested `validate.py` end-to-end against a local HTTP server standing in for Linear + a stub `gh` on PATH, across pass / fail / warn-only / policy-mismatch paths. ## Rollout (per the design) Land here with tests → add pinned callers with `enforce: false` → observe ~a week → flip `enforce: true` → add the `linear-ticket` status to the `main` ruleset as required. No bump-caller fleet yet (deliberate: the pilot pins callers manually, repo-by-repo). Requires the org secret `LINEAR_API_TOKEN` (being provisioned separately). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 22:37:13 +00:00