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
38 changes: 35 additions & 3 deletions .github/workflows/linear-ticket.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,17 @@ name: Linear Ticket (reusable)
# 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.
#
# REPORTING MODES β€” how loudly a failure is reported. This workflow NEVER decides whether a PR
# can merge; branch protection does, by requiring the `linear-ticket` context or not:
# enforce: true red status, job exits nonzero. Gating (once required).
# enforce: false red status, job stays green on a failing VERDICT (a
# (soft-fail: true, the default) broken run still exits nonzero). Shows on the PR exactly
# like enforce does but blocks nothing while the context is
# not required β€” the loud pilot rung, since a green check
# nobody reads teaches the repo nothing during observation.
# enforce: false, soft-fail: false green status; only the job summary and the marker comment
# carry the verdict. The silent variant.
#
# 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
Expand Down Expand Up @@ -79,9 +90,29 @@ on:
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.
true (default) fails closed on a missing/invalid link or infrastructure error, and
the job itself exits nonzero. false is warn-only: a failing VERDICT never exits the
job nonzero, and `soft-fail` decides how loudly it is reported. Warn-only is not a
promise the job always exits 0 β€” a broken run still does (a failed terminal status
write, a missing token/repo, malformed `team-keys`, a non-`pull_request` trigger).
type: boolean
required: false
default: true
soft-fail:
Comment thread
mattmillerai marked this conversation as resolved.
Resolved
description: >-
Warn-only only (ignored when `enforce: true`). true (default) publishes a red
`failure` commit status so the PR's check list shows the check failing β€” loud, but
NON-BLOCKING for as long as `linear-ticket` is not a required status in the repo's
branch protection, which is exactly what a warn-only pilot means. The marker comment
says so. false restores the silent variant: warn-only publishes `success` and only
the job summary and comment carry the verdict.
BEHAVIOUR CHANGE for callers already on `enforce: false`: before this input existed
warn-only always published `success`, so taking a SHA bump past this commit flips
those callers to a red (still non-required) status with no caller-side edit. Set
`soft-fail: false` in the caller to keep the old always-green behaviour.
FOOTGUN: `enforce: false` + `soft-fail: true` + `linear-ticket` already required in
branch protection WOULD block merges. Do not require the context before flipping
`enforce: true`.
type: boolean
required: false
default: true
Comment thread
mattmillerai marked this conversation as resolved.
Resolved
Expand Down Expand Up @@ -209,5 +240,6 @@ jobs:
EXEMPT_ACTORS: ${{ inputs.exempt-actors }}
REQUIRE_OPEN_ISSUE: ${{ inputs.require-open-issue }}
ENFORCE: ${{ inputs.enforce }}
SOFT_FAIL: ${{ inputs.soft-fail }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
run: python3 .linear-ticket-tools/scripts/linear-ticket/validate.py
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ complete, copy-pasteable caller.
| Workflow | Purpose | Setup |
|---|---|---|
| [`detect-unreviewed-merge.yml`](.github/workflows/detect-unreviewed-merge.yml) | SOC 2 compliance β€” detects PRs merged without prior approval and opens a tracking issue in [`Comfy-Org/unreviewed-merges`](https://github.com/Comfy-Org/unreviewed-merges). | [detect-unreviewed-merge.md](docs/callers/detect-unreviewed-merge.md) |
| [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR** before it can merge β€” not a `TEAM-123`-shaped string in author text. The only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) β€” they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`linear-ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA before every terminal write so a superseded run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only (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) |
| [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR** before it can merge β€” not a `TEAM-123`-shaped string in author text. The only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) β€” they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`linear-ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA before every terminal write so a superseded run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only β€” a failing verdict never exits the job nonzero (a broken run still does), and by default (`soft-fail: true`) it still publishes the **red** status so the pilot is visible on the PR while blocking nothing, since blocking is branch protection requiring the context, not this workflow's call (`soft-fail: false` restores the silent always-green variant); one `exempt-label` (e.g. `linear-exempt`) waives it per-PR, and an opt-in `exempt-actors` list (empty by default) skips bot PRs (e.g. `dependabot[bot]`) with no built-in bypass. Logic + hermetic tests live in [`scripts/linear-ticket/`](scripts/linear-ticket); `workflows_ref` is **required**, shape- and ancestry-checked before checkout. Requires `LINEAR_API_TOKEN` + the two-workflow caller. | [linear-ticket.md](docs/callers/linear-ticket.md) |
| [`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
58 changes: 53 additions & 5 deletions docs/callers/linear-ticket.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,8 @@ jobs:
# 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
# soft-fail: true # default; warn-only still shows a RED (non-blocking)
# # check. Set false for a silent always-green pilot.
secrets:
LINEAR_API_TOKEN: ${{ secrets.LINEAR_API_TOKEN }}
```
Expand Down Expand Up @@ -122,13 +124,50 @@ job-level detail.
| `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. |
| `enforce` | `true` | `false` is warn-only: a failing **verdict** never exits the job nonzero. `soft-fail` decides how loudly it is reported; the diagnosis is identical either way. Warn-only is not a promise the job always exits `0` β€” a broken *run* still does (a failed terminal status write, a missing token/repo, malformed `team-keys`, a non-`pull_request` trigger). |
| `soft-fail` | `true` | Warn-only only (ignored when `enforce: true`). `true` publishes a **red `failure`** status, so the PR's check list shows the check failing β€” loud, but non-blocking for as long as `linear-ticket` is not a required status in your ruleset. `false` restores the silent variant (warn-only publishes `success`; only the summary and comment carry the verdict). **Do not** require the `linear-ticket` context while `enforce: false` β€” required + soft-fail would block merges. |

## Upgrading an existing `enforce: false` caller

`soft-fail` is new, and it defaults to `true`. **If your caller already runs `enforce: false`,
taking a SHA bump past the commit that added this input changes what your PRs show:** warn-only
used to publish a green `linear-ticket` status in every outcome, and now publishes a **red**
one. Nothing about *blocking* changes β€” a status only blocks when your ruleset requires that
context β€” but the PR check list goes from green to red, and anything you have keyed off the
status (auto-merge bots, dashboards, other automation) sees `failure` where it saw `success`.

Two things to do before you take the bump:

1. **Check your ruleset.** If `linear-ticket` is already a required check while you are still on
`enforce: false`, the red status *will* block merges. That combination was always a
misconfiguration (rollout step 6 is the last step for a reason), but soft-fail is what makes
it bite. Remove the required check, or flip `enforce: true` β€” do not sit in between.
2. **Decide which pilot you want.** Loud (the default) is recommended: authors fix links during
the pilot instead of discovering the requirement on flip day. If you want the old behaviour,
add one line to your caller:

```yaml
enforce: false
soft-fail: false # keep the pre-soft-fail behaviour: warn-only stays green
```

An **absent** `SOFT_FAIL` β€” which only happens if your `uses:` pin and `workflows_ref` have
skewed apart, so an older `linear-ticket.yml` is running newer scripts β€” is treated as
`false`, so pin skew alone can never flip you to red. Keep both pins on the same SHA anyway.

## 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).
1. Land both caller files with `enforce: false`, and **leave `linear-ticket` out of your
ruleset's required checks** β€” that omission, not the input, is what keeps the pilot
non-blocking. 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).

With the default `soft-fail: true`, a warn-only failure shows on the PR as a **red
`linear-ticket` check** plus the marker comment, which is what makes authors notice and fix
links during the pilot instead of discovering the requirement on flip day. Nobody is
blocked: a non-required failing check leaves the merge button live. If you want the quieter
first pass, set `soft-fail: false` and the status stays green.
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.
Expand All @@ -140,8 +179,11 @@ job-level detail.
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.
5. Flip `enforce: true`. Leave the check non-required for a short window β€” the PR-visible
result is unchanged from the soft-fail pilot; what changes is that the validator's own run
now goes red too, so a systemic breakage is visible in the Actions tab.
6. Add the **`linear-ticket`** status context to your `main` ruleset as a required check.
Only now does anything block.

Nothing here changes branch protection automatically β€” the last step is a manual repo-admin action.

Expand All @@ -151,6 +193,12 @@ Nothing here changes branch protection automatically β€” the last step is a manu
your ruleset; do not require the `Linear Ticket / validate` job β€” it runs on the default branch
against the workflow_run event and is not tied to the PR's merge check.

**A red check is not the same as a blocked merge.** What blocks is your ruleset requiring the
`linear-ticket` context β€” nothing this workflow does. That is why warn-only can (and by default
does) publish a red status: it is a real, visible signal that costs nobody a merge. The
corollary is the footgun: do not add the context to your ruleset until you flip `enforce: true`,
or the warn-only pilot starts blocking.

**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.
Expand Down
Loading
Loading