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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 213 additions & 0 deletions .github/workflows/linear-ticket.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,213 @@
name: Linear Ticket (reusable)

# Reusable gate that requires every PR to carry a Linear issue Linear has LINKED to that
# exact PR before it can merge (design: pr-linear-ticket-enforcement). The only thing that
# passes is an attachment Linear returns for this PR's canonical html_url whose issue meets
# the configured team/state policy — a `TEAM-123`-shaped string in author text never does.
#
# TWO-STAGE, FORK-SAFE EXECUTION. This privileged validator is invoked by a caller that runs
# on `workflow_run: completed` of an unprivileged, no-op signal workflow in the consumer repo.
# GitHub gives THIS run the caller's write token and the Linear secret even when the signal
# run (a fork or Dependabot PR) had neither. Non-negotiable constraints (design §6):
# * the signal workflow checks out nothing, runs no PR content, emits no artifact/cache;
# * this validator never downloads that run's artifacts/caches and never checks out the PR
# branch or merge commit — it reads only GitHub-owned data and Linear's API;
# * every PR-derived value (branch, title, body, labels, URL) is untrusted DATA, passed
# through env / GraphQL variables, never shell-interpolated.
# The job runs on the DEFAULT branch, so its job-level check must NOT be the required merge
# check. Instead validate.sh publishes the `linear-ticket` commit status on the refetched PR
# head SHA; branch protection requires THAT context. See docs/callers/linear-ticket.md.
#
# PERMISSIONS the caller must grant (the single job's union — GitHub validates the grant at
# STARTUP, before any `if:`):
# actions: read # read the triggering workflow_run
# contents: read # checkout THIS repo's scripts (no PR code is ever checked out)
# pull-requests: write # the one marker diagnostic comment
# statuses: write # publish the `linear-ticket` commit status
#
# SECRET: LINEAR_API_TOKEN (required). Store the value exactly as it goes into Linear's
# Authorization header — a personal API key raw, an OAuth actor-auth access token prefixed
# with `Bearer `. Missing/invalid fails the check CLOSED as an infrastructure error, never
# green (design §7).
#
# Caller pattern: docs/callers/linear-ticket.md (the signal + validate pair). Do not use
# `secrets: inherit`; pass only LINEAR_API_TOKEN.

on:
workflow_call:
inputs:
workflows_ref:
description: >-
Full 40-hex commit SHA of THIS repo to load the validator scripts from. Pin to the
SAME SHA as the caller's `uses:` — a floating ref would run new scripts under an old
workflow. Required; validated to be a full lowercase SHA and an ancestor of this
repo's main before checkout.
type: string
required: true
team-keys:
description: >-
Optional comma-separated allow-list of Linear team keys (matched against the
resolved issue's API team.key, never an identifier prefix). Empty (default) accepts
a linked issue from any team visible to the token. Malformed or duplicate entries
fail the run.
type: string
required: false
default: ''
exempt-label:
description: >-
Optional single label that waives the requirement (recommended `linear-exempt`).
Empty disables exemption. Adding/removing it reruns the check.
type: string
required: false
default: ''
exempt-actors:
description: >-
Optional comma-separated PR-author logins whose PRs skip the check without a label
(e.g. `dependabot[bot],renovate[bot]`). The non-manual hatch for bot PRs that never
carry a ticket. Opt-in and EMPTY by default — there is no built-in bot bypass; a
repo that lists an actor here accepts that all of that account's PRs merge without a
Linear ticket.
type: string
required: false
default: ''
require-open-issue:
description: >-
When true (default), reject a linked issue whose Linear state.type is
completed/canceled. backlog/unstarted/started/triage pass.
type: boolean
required: false
default: true
enforce:
description: >-
true (default) fails closed on a missing/invalid link or infrastructure error.
false is warn-only: every outcome publishes success but the summary and marker
comment show the verdict enforce mode would have produced.
type: boolean
required: false
default: true
secrets:
LINEAR_API_TOKEN:
description: >-
Value placed verbatim into Linear's Authorization header (personal key raw, or
`Bearer <oauth-token>`). Required; a missing token fails the check as an
infrastructure error.
required: true

permissions: {}

concurrency:
# One validation per PR branch; a newer push/edit supersedes the in-flight run, and
# validate.sh additionally refetches the head SHA before any terminal status write.
group: linear-ticket-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
cancel-in-progress: true

jobs:
validate:
# Only a completed run of the signal workflow should reach here (the caller filters the
# workflow name + `types: [completed]`); guard the conclusion so a failed/cancelled signal
# run does not trigger a spurious validation.
if: github.event.workflow_run.conclusion == 'success'
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
actions: read # read the triggering workflow_run
contents: read # checkout the validator scripts; PR code is never checked out
pull-requests: write # the one marker diagnostic comment
statuses: write # publish the linear-ticket commit status
steps:
- name: Require a pinned workflows_ref
# workflows_ref runs THIS repo's scripts in a job holding the caller's write token +
# the LINEAR_API_TOKEN secret, so it is a code-execution trust boundary. GitHub does
# NOT enforce `required: true` for workflow_call inputs (an omitted input arrives as ''
# and checkout silently takes the default branch), so validate on TWO axes before
# checkout:
# SHAPE — a full 40-hex lowercase SHA; rejects everything mutable (branch, tag,
# refs/pull/N/head), which could skew between jobs mid-run.
# ANCESTRY — the SHA is reachable from THIS repo's upstream main. Shape proves the
# value is immutable, not WHICH repo authored it: a fork of this PUBLIC
# repo shares the object store and GitHub serves a fork PR's head objects
# from this repo's URL unauthenticated, so a fork-authored 40-hex SHA is
# just as well-shaped and would otherwise run with the caller's token. Only
# merged upstream history may be pinned; no opt-out. Fails CLOSED on infra
# errors. Mirrors pr-area-label.yml / pr-risk.yml. See BE-5546.
env:
WORKFLOWS_REF: ${{ inputs.workflows_ref }}
run: |
set -euo pipefail
# actions/checkout trims `ref`, so strip whitespace before the -z test. Echo only a
# sanitized, bounded form so a multi-line value can't forge ::workflow commands:: in
# this PUBLIC log.
REF="$(printf '%s' "$WORKFLOWS_REF" | tr -d '[:space:]')"
if [ -z "$REF" ]; then
echo "::error::workflows_ref is required; pin it to the same commit SHA as the uses: line (see the caller doc)"
exit 1
fi
safe_ref=$(printf '%s' "$REF" | tr -c 'A-Za-z0-9._/-' '?'); safe_ref=${safe_ref:0:64}
# Length + character-class, not `grep -Eq '^..$'`: grep anchors per LINE, so a
# multi-line value carrying one SHA-shaped line would pass. Lowercase only — the value
# is handed to checkout verbatim and everything that emits a SHA emits lowercase.
if [ "${#REF}" -ne 40 ] || [ -n "${REF//[0-9a-f]/}" ]; then
echo "::error::workflows_ref must be a full 40-hex lowercase commit SHA of Comfy-Org/github-workflows (got '${safe_ref}'). Branches, tags and PR-head refs are mutable and are rejected before checkout."
exit 1
fi
# ANCESTRY. The upstream URL is a LITERAL: inside a reusable workflow no github context
# names this repo, so a variable would be an alias a fork could point at itself. Two
# bounded fetches (--filter=blob:none — no file content): depth-1 proves the SHA is in
# this repo's object network; the second brings main to walk down to the pin. The fetch
# retries (a transient github.com error must not red the fleet); the verdict does not.
scratch=$(mktemp -d) || { echo "::error::ancestry check for workflows_ref (${safe_ref}) could not allocate scratch space; failing closed."; exit 1; }
trap 'rm -rf "$scratch"' EXIT
git init -q "$scratch" || { echo "::error::ancestry check for workflows_ref (${safe_ref}) could not init a scratch repo; failing closed."; exit 1; }
fetch_upstream() {
for attempt in 1 2 3; do
if timeout 40 git -C "$scratch" -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=30 \
fetch --quiet --no-tags --filter=blob:none "$@"; then
return 0
fi
[ "$attempt" -lt 3 ] && sleep $((attempt * 5))
done
return 1
}
if ! fetch_upstream --depth=1 https://github.com/Comfy-Org/github-workflows "$REF"; then
echo "::error::workflows_ref (${safe_ref}) could not be fetched from Comfy-Org/github-workflows after 3 attempts; failing closed."
exit 1
fi
if ! fetch_upstream https://github.com/Comfy-Org/github-workflows +refs/heads/main:refs/heads/upstream-main; then
echo "::error::main of Comfy-Org/github-workflows could not be read after 3 attempts, so workflows_ref (${safe_ref}) cannot be shown merged upstream; failing closed."
exit 1
fi
# --is-ancestor has THREE outcomes: 0 yes, 1 no, >1 git could not answer (infra fault).
# Don't report an infra fault as a hostile pin; both still fail closed, only the message differs.
ancestry_rc=0
GIT_NO_LAZY_FETCH=1 git -C "$scratch" merge-base --is-ancestor "$REF" upstream-main || ancestry_rc=$?
if [ "$ancestry_rc" -gt 1 ]; then
echo "::error::the ancestry test for workflows_ref (${safe_ref}) could not COMPLETE (git error, not a verdict); failing closed."
exit 1
fi
if [ "$ancestry_rc" -ne 0 ]; then
echo "::error::workflows_ref (${safe_ref}) is not an ancestor of Comfy-Org/github-workflows main. A well-shaped SHA can still be fork-authored; only merged upstream commits may be pinned. If this is a genuine just-merged pin, re-run."
exit 1
fi
- name: Checkout validator scripts
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: Comfy-Org/github-workflows
ref: ${{ inputs.workflows_ref }}
path: .linear-ticket-tools
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: '3.12'
- name: Validate the linked Linear ticket
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
LINEAR_API_TOKEN: ${{ secrets.LINEAR_API_TOKEN }}
TEAM_KEYS: ${{ inputs.team-keys }}
EXEMPT_LABEL: ${{ inputs.exempt-label }}
EXEMPT_ACTORS: ${{ inputs.exempt-actors }}
REQUIRE_OPEN_ISSUE: ${{ inputs.require-open-issue }}
ENFORCE: ${{ inputs.enforce }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
run: python3 .linear-ticket-tools/scripts/linear-ticket/validate.py
51 changes: 51 additions & 0 deletions .github/workflows/test-linear-ticket.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# CONTRACT: this is one of THIS repo's own path-filtered script tests, NOT a reusable
# workflow. It is not callable and has no caller pattern:
# TRIGGERS — `pull_request` and `push` to main, both filtered to scripts/linear-ticket/**
# and this file. A change elsewhere in the repo does not run it.
# INPUTS — none. SECRETS — none. Read-only `contents: read`; the suite is hermetic and
# makes no network call.
# The reusable workflow these scripts back is .github/workflows/linear-ticket.yml.

name: Test linear-ticket scripts

# Runs the hermetic lib.py unittest suite for the linear-ticket gate. The gate decides
# whether every consuming repo's PRs can merge, so a regression in the policy filter,
# candidate extraction, or error classification silently passes or blocks PRs — cheap to
# guard with a unit run on change. The real-Linear behaviours (URL canonicalization,
# attachment timing) are proven in the pilot, not here.

on:
pull_request:
paths:
- 'scripts/linear-ticket/**'
- '.github/workflows/test-linear-ticket.yml'
# linear-ticket.yml passes the scripts their whole input contract through env, so a
# change to it can break the suite without touching a file under scripts/linear-ticket/.
- '.github/workflows/linear-ticket.yml'
push:
branches: [main]
paths:
- 'scripts/linear-ticket/**'
- '.github/workflows/test-linear-ticket.yml'
- '.github/workflows/linear-ticket.yml'
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

permissions:
contents: read

jobs:
test:
name: unittest
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
with:
python-version: '3.12'
- name: Compile the validator (syntax gate for validate.py, which the suite does not import)
run: python3 -m py_compile scripts/linear-ticket/lib.py scripts/linear-ticket/validate.py
- name: lib suite
run: python3 -m unittest discover -s scripts/linear-ticket/tests -p 'test_*.py' -v
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ complete, copy-pasteable caller.
| Workflow | Purpose | Setup |
|---|---|---|
| [`detect-unreviewed-merge.yml`](.github/workflows/detect-unreviewed-merge.yml) | SOC 2 compliance — detects PRs merged without prior approval and opens a tracking issue in [`Comfy-Org/unreviewed-merges`](https://github.com/Comfy-Org/unreviewed-merges). | [detect-unreviewed-merge.md](docs/callers/detect-unreviewed-merge.md) |
| [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR** before it can merge — not a `TEAM-123`-shaped string in author text. The only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) — they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`linear-ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA before every terminal write so a superseded run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only (same diagnosis, always-green status); one `exempt-label` (e.g. `linear-exempt`) waives it per-PR, and an opt-in `exempt-actors` list (empty by default) skips bot PRs (e.g. `dependabot[bot]`) with no built-in bypass. Logic + hermetic tests live in [`scripts/linear-ticket/`](scripts/linear-ticket); `workflows_ref` is **required**, shape- and ancestry-checked before checkout. Requires `LINEAR_API_TOKEN` + the two-workflow caller. | [linear-ticket.md](docs/callers/linear-ticket.md) |
| [`cursor-review.yml`](.github/workflows/cursor-review.yml) | Label-triggered multi-model code review. A 4-lab × 2-review-type cursor-agent panel runs adversarial + edge-case passes, a judge model consolidates them into one PR review with per-finding severity badges, and the triggerer gets Slack start/complete DMs. Advisory: it posts a review, it does not gate — there is **no `blocking` input** (it shipped in #16 and was deleted by #31; see [the setup guide](docs/callers/cursor-review.md)). Prompts and scripts live in [`.github/cursor-review/`](.github/cursor-review) — the single source of truth, so consumer repos carry only a thin caller. Generated code is excluded from BOTH the diff-size gate and the diff sent to the panel via the shared [`check-pr-size`](scripts/check-pr-size) classifier (base-ref `linguist-generated`, base-blob Go generated markers — a PR cannot self-exempt a file from review, lockfiles, plus `extra_generated_globs` / `extra_lockfiles`) — the same detection as `pr-size.yml`, so codegen never blows the review cap or wastes review signal. Blank and comment-only lines are also discounted from the size count by default (`ignore_comments`) so AI comment volume doesn't trip the cap and skip the review — comments still reach the panel, only the count ignores them. The runner and the panel model list are fixed by the reusable — there are no `runs_on` / `models` inputs (`models` is a job *output*). Requires `CURSOR_API_KEY` (+ optional `SLACK_BOT_TOKEN`). | [cursor-review.md](docs/callers/cursor-review.md) |
| [`cursor-review-auto-label.yml`](.github/workflows/cursor-review-auto-label.yml) | Companion to `cursor-review.yml`. On PR assignment, applies the review label for an opted-in reviewer (via the CLOUD_CODE_BOT app token, so the label actually triggers the review). The opt-in roster lives in the caller's `vars.CURSOR_REVIEW_OPTED_IN_LOGINS` — no roster is baked into the workflow. Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`. | [cursor-review-auto-label.md](docs/callers/cursor-review-auto-label.md) |
| [`assign-reviewers.yml`](.github/workflows/assign-reviewers.yml) | Auto-requests expertise-aware, load-balanced PR reviewers with new-folk randomization. Matches changed paths against a caller-repo `.github/reviewers.yml` (path-glob → reviewers, plus a `default_pool`), drops the author + `vars.REVIEWER_EXCLUDE`, ranks candidates by open review load (steering off anyone at/over `vars.REVIEWER_LOAD_CAP`), and may swap a slot for a `vars.REVIEWER_GROWTH_POOL` member. Requests go through the CLOUD_CODE_BOT app token so they work on fork PRs. Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`. | [assign-reviewers.md](docs/callers/assign-reviewers.md) |
Expand Down
Loading
Loading