[PR #80] [MERGED] docs(callers): per-workflow setup guides, README restructure, public-repo hygiene (BE-4680) #88

New issue

Closed

opened 2026-10-26 22:36:06 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 22:36:06 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Comfy-Org/github-workflows/pull/80
Author: @mattmillerai
Created: 7/27/2026
Status: ✅ Merged
Merged: 8/4/2026
Merged by: @mattmillerai

Base: main ← Head: docs/caller-setup-guides-and-public-hygiene

📝 Commits (8)

66b2189 docs(callers): per-workflow setup guides, README restructure, public-repo hygiene (BE-4680)
d194f2c docs(callers): correct phantom capabilities in the setup guides (BE-4680)
d1b6a51 docs(callers): fix the blocking-gate regression trail + Dependabot guards (BE-4680)
4fec27c docs(callers): correct four input defaults + the concurrency and default_pool traps (BE-4680)
2c18629 Merge remote-tracking branch 'origin/main' into docs/caller-setup-guides-and-public-hygiene
b440c9e Merge remote-tracking branch 'origin/main' into docs/caller-setup-guides-and-public-hygiene
6c97df0 docs(callers): address review round 2 — roster notes, Dependabot guard, workflows_ref emphasis (BE-4680)
49d282c Merge remote-tracking branch 'origin/main' into docs/caller-setup-guides-and-public-hygiene

📊 Changes

20 files changed (+1753 additions, -81 deletions)

View changed files

📝 .github/cursor-review/README.md (+27 -39)
📝 .github/workflows/detect-unreviewed-merge.yml (+9 -1)
📝 .gitignore (+10 -0)
📝 AGENTS.md (+21 -5)
➕ CONTRIBUTING.md (+101 -0)
➕ LICENSE (+21 -0)
📝 README.md (+106 -36)
➕ SECURITY.md (+66 -0)
➕ docs/callers/README.md (+236 -0)
➕ docs/callers/agents-md-integrity.md (+88 -0)
➕ docs/callers/assign-prs-to-author.md (+69 -0)
➕ docs/callers/assign-reviewers.md (+139 -0)
➕ docs/callers/cursor-review-auto-label.md (+104 -0)
➕ docs/callers/cursor-review.md (+180 -0)
➕ docs/callers/detect-unreviewed-merge.md (+89 -0)
➕ docs/callers/groom.md (+189 -0)
➕ docs/callers/pr-risk.md (+112 -0)
➕ docs/callers/pr-size.md (+92 -0)
➕ docs/callers/stale.md (+94 -0)
➖ scripts/check-pr-size/check-pr-size (+0 -0)

📄 Description

Prep for broadening groom adoption. The catalog documented what each workflow does very well and was near-silent on how to wire one up, deferring to "each workflow file's header comment" — which for groom.yml is a 105 KB YAML.

Adoption in this repo tracks documentation quality almost exactly:

Workflow	Caller YAML in its docs	Repos enrolled
cursor-review	yes (2 blocks, 5 `uses:`)	14
detect-unreviewed-merge	yes (header example)	11
agents-md-integrity	no	7
groom	none — 174-line README, 0 yaml blocks	2
pr-size	header only	1
assign-reviewers	header only	1

Measured gaps

The only copy-pasteable example was 9 lines of placeholders. Grep counts against the old README:

on: — 0 hits. No trigger block at all, so copy-pasting it produced a workflow that never fires. cron also 0 — for the two schedule-driven workflows the README never showed the line that makes them run.
concurrency — 0 hits. groom.yml declares concurrency: groom-${{ github.repository }} with cancel-in-progress: false. A caller that duplicates that group deadlocks the run until timeout — documented only inside a comment in a different file.
CALLERS — 0 hits. Enrollment is two steps: the caller PR plus a vars.<NAME>_CALLERS roster entry. The second was undocumented, and a repo absent from the roster keeps its original SHA forever.
The example's permissions are short for groom. It shows contents: read + pull-requests: read; groom needs issues: write. That is exactly the grant that yields a zero-job startup_failure with no logs.

Three phantom inputs

The README advertised blocking, runs_on, and models on cursor-review.yml. None are declared — blocking and runs_on have zero occurrences in the file, and models exists only as an internal step output (:310). GitHub rejects an unknown input at startup, so anyone following that row got an invalid workflow. AGENTS.md repeated the blocking: claim.

(runs_on is real — on cursor-review-auto-label.yml. The row conflated two workflows.)

One path that 404s

detect-unreviewed-merge.yml's header example pointed at Comfy-Org/unreviewed-merges/.github/workflows/detector.yml@v1, which does not exist. The live path — used by every real caller — is this repo's own. The same example showed pull_request where all live callers use push to the default branch.

Changes

docs/callers/ — a shared contract page (pinning, the startup-time permission rule, workflows_ref lock-step, the concurrency deadlock, the roster step) plus one page per workflow. Each carries a complete caller including on: and the exact permission grant, generated against each workflow's real workflow_call inputs rather than from prose.

README — restructured into a scannable index: one line and a setup link per workflow, with the essay-length cells relocated into the guides. Phantom inputs removed.

Public-repo hygiene

LICENSE — MIT. The repo had none, so despite the README inviting outside use, nobody outside the org legally had any. (Aside: gh repo list --json licenseInfo reports NONE for all 64 public Comfy-Org repos and is unreliable — the license API shows GPL-3.0 on the core repos and MIT on Comfy-Desktop. GPL was considered and rejected as a poor fit for CI glue that private repos uses:.)
SECURITY.md — disclosure path, scope, and the agent credential boundary written down as an explicit security property: model steps hold no write token, a separate job does the writing.
CONTRIBUTING.md — the test commands, the "every change here is live-fire" framing, what counts as breaking (adding a required input/secret, or a new nested-job permission — breaking even though no caller YAML changes), and two-step enrollment.
Deleted a tracked 3.36 MB binary (scripts/check-pr-size/check-pr-size). Mach-O arm64, swept in accidentally by #51. It was larger than every other file in the repo combined, pr-size.yml:201 rebuilds it from source on every run, and it cannot execute on the ubuntu-latest runners all 31 jobs use. Now gitignored.

AGENTS.md — phantom blocking removed, docs/callers/ added to layout + deeper docs, two cross-references fixed for the renamed README sections, and one new convention: document only inputs that exist.

Deliberately not included

No CODEOWNERS. agents-md-integrity.yml ships a require_codeowners knob and this repo trips its own warn-only check. But adding one auto-requests review from named colleagues and stands up a second routing mechanism alongside the existing assign-reviewers.yml assignee routing. That is a team decision, not a docs PR's — happy to add it in a follow-up if wanted.

Verification

117 tests green — groom 59, cursor-review 40, agents-md-integrity 18 — plus go vet and go test clean
check_agents_md.py --root . passes (1 warning: the CODEOWNERS DRI above). AGENTS.md is 141 lines, under the 200 ceiling it enforces
Every relative link and heading anchor across all 12 markdown files resolves
No secret-shaped literals in any tracked file; private repo names kept out of the docs per the AGENTS.md public-repo convention

Unblocks the tier-1 groom rollout.

BE-4680

🤖 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/80 **Author:** [@mattmillerai](https://github.com/mattmillerai) **Created:** 7/27/2026 **Status:** ✅ Merged **Merged:** 8/4/2026 **Merged by:** [@mattmillerai](https://github.com/mattmillerai) **Base:** `main` ← **Head:** `docs/caller-setup-guides-and-public-hygiene` --- ### 📝 Commits (8) - [`66b2189`](https://github.com/Comfy-Org/github-workflows/commit/66b218954aab85fbb269d05e8470f0788fcf1829) docs(callers): per-workflow setup guides, README restructure, public-repo hygiene (BE-4680) - [`d194f2c`](https://github.com/Comfy-Org/github-workflows/commit/d194f2c088b00bbeb6953bfce65992b4845e6328) docs(callers): correct phantom capabilities in the setup guides (BE-4680) - [`d1b6a51`](https://github.com/Comfy-Org/github-workflows/commit/d1b6a51d266858eefc6d154772c055a4b94a938e) docs(callers): fix the blocking-gate regression trail + Dependabot guards (BE-4680) - [`4fec27c`](https://github.com/Comfy-Org/github-workflows/commit/4fec27ce8c3d42427e10fe502309eb3ee1e3ed12) docs(callers): correct four input defaults + the concurrency and default_pool traps (BE-4680) - [`2c18629`](https://github.com/Comfy-Org/github-workflows/commit/2c1862910b83e3face318a7c6d99974b4b5c54c9) Merge remote-tracking branch 'origin/main' into docs/caller-setup-guides-and-public-hygiene - [`b440c9e`](https://github.com/Comfy-Org/github-workflows/commit/b440c9e2471bfad78ed147fea8fe1e6c82876bce) Merge remote-tracking branch 'origin/main' into docs/caller-setup-guides-and-public-hygiene - [`6c97df0`](https://github.com/Comfy-Org/github-workflows/commit/6c97df06de79e4395483a34154a510904295ea6d) docs(callers): address review round 2 — roster notes, Dependabot guard, workflows_ref emphasis (BE-4680) - [`49d282c`](https://github.com/Comfy-Org/github-workflows/commit/49d282c8552ae95815c07cd6e96d7f4cc284545a) Merge remote-tracking branch 'origin/main' into docs/caller-setup-guides-and-public-hygiene ### 📊 Changes **20 files changed** (+1753 additions, -81 deletions) <details> <summary>View changed files</summary> 📝 `.github/cursor-review/README.md` (+27 -39) 📝 `.github/workflows/detect-unreviewed-merge.yml` (+9 -1) 📝 `.gitignore` (+10 -0) 📝 `AGENTS.md` (+21 -5) ➕ `CONTRIBUTING.md` (+101 -0) ➕ `LICENSE` (+21 -0) 📝 `README.md` (+106 -36) ➕ `SECURITY.md` (+66 -0) ➕ `docs/callers/README.md` (+236 -0) ➕ `docs/callers/agents-md-integrity.md` (+88 -0) ➕ `docs/callers/assign-prs-to-author.md` (+69 -0) ➕ `docs/callers/assign-reviewers.md` (+139 -0) ➕ `docs/callers/cursor-review-auto-label.md` (+104 -0) ➕ `docs/callers/cursor-review.md` (+180 -0) ➕ `docs/callers/detect-unreviewed-merge.md` (+89 -0) ➕ `docs/callers/groom.md` (+189 -0) ➕ `docs/callers/pr-risk.md` (+112 -0) ➕ `docs/callers/pr-size.md` (+92 -0) ➕ `docs/callers/stale.md` (+94 -0) ➖ `scripts/check-pr-size/check-pr-size` (+0 -0) </details> ### 📄 Description Prep for broadening groom adoption. The catalog documented **what** each workflow does very well and was near-silent on **how to wire one up**, deferring to *"each workflow file's header comment"* — which for `groom.yml` is a 105 KB YAML. Adoption in this repo tracks documentation quality almost exactly: | Workflow | Caller YAML in its docs | Repos enrolled | |---|---|---| | cursor-review | yes (2 blocks, 5 `uses:`) | **14** | | detect-unreviewed-merge | yes (header example) | 11 | | agents-md-integrity | no | 7 | | **groom** | **none** — 174-line README, 0 yaml blocks | **2** | | pr-size | header only | 1 | | assign-reviewers | header only | 1 | ## Measured gaps The only copy-pasteable example was 9 lines of placeholders. Grep counts against the old README: - **`on:` — 0 hits.** No trigger block at all, so copy-pasting it produced a workflow that never fires. `cron` also 0 — for the two schedule-driven workflows the README never showed the line that makes them run. - **`concurrency` — 0 hits.** `groom.yml` declares `concurrency: groom-${{ github.repository }}` with `cancel-in-progress: false`. A caller that duplicates that group **deadlocks the run until timeout** — documented only inside a comment in a different file. - **`CALLERS` — 0 hits.** Enrollment is *two* steps: the caller PR **plus** a `vars.<NAME>_CALLERS` roster entry. The second was undocumented, and a repo absent from the roster keeps its original SHA forever. - **The example's permissions are short for groom.** It shows `contents: read` + `pull-requests: read`; groom needs `issues: write`. That is exactly the grant that yields a zero-job `startup_failure` with no logs. ### Three phantom inputs The README advertised `blocking`, `runs_on`, and `models` on `cursor-review.yml`. None are declared — `blocking` and `runs_on` have **zero** occurrences in the file, and `models` exists only as an internal step output (`:310`). GitHub rejects an unknown input at startup, so anyone following that row got an invalid workflow. `AGENTS.md` repeated the `blocking:` claim. (`runs_on` *is* real — on `cursor-review-auto-label.yml`. The row conflated two workflows.) ### One path that 404s `detect-unreviewed-merge.yml`'s header example pointed at `Comfy-Org/unreviewed-merges/.github/workflows/detector.yml@v1`, which does not exist. The live path — used by every real caller — is this repo's own. The same example showed `pull_request` where all live callers use `push` to the default branch. ## Changes **`docs/callers/`** — a shared contract page (pinning, the startup-time permission rule, `workflows_ref` lock-step, the concurrency deadlock, the roster step) plus one page per workflow. Each carries a complete caller including `on:` and the exact permission grant, generated against each workflow's real `workflow_call` inputs rather than from prose. **README** — restructured into a scannable index: one line and a setup link per workflow, with the essay-length cells relocated into the guides. Phantom inputs removed. **Public-repo hygiene** - **`LICENSE` — MIT.** The repo had none, so despite the README inviting outside use, nobody outside the org legally had any. (Aside: `gh repo list --json licenseInfo` reports `NONE` for all 64 public Comfy-Org repos and is unreliable — the license API shows GPL-3.0 on the core repos and MIT on Comfy-Desktop. GPL was considered and rejected as a poor fit for CI glue that private repos `uses:`.) - **`SECURITY.md`** — disclosure path, scope, and the agent credential boundary written down as an explicit security property: model steps hold no write token, a separate job does the writing. - **`CONTRIBUTING.md`** — the test commands, the "every change here is live-fire" framing, what counts as breaking (adding a required input/secret, or a new nested-job permission — breaking even though no caller YAML changes), and two-step enrollment. - **Deleted a tracked 3.36 MB binary** (`scripts/check-pr-size/check-pr-size`). Mach-O **arm64**, swept in accidentally by #51. It was larger than every other file in the repo combined, `pr-size.yml:201` rebuilds it from source on every run, and it cannot execute on the `ubuntu-latest` runners all 31 jobs use. Now gitignored. **`AGENTS.md`** — phantom `blocking` removed, `docs/callers/` added to layout + deeper docs, two cross-references fixed for the renamed README sections, and one new convention: *document only inputs that exist*. ## Deliberately not included **No CODEOWNERS.** `agents-md-integrity.yml` ships a `require_codeowners` knob and this repo trips its own warn-only check. But adding one auto-requests review from named colleagues and stands up a second routing mechanism alongside the existing `assign-reviewers.yml` assignee routing. That is a team decision, not a docs PR's — happy to add it in a follow-up if wanted. ## Verification - **117 tests green** — groom 59, cursor-review 40, agents-md-integrity 18 — plus `go vet` and `go test` clean - `check_agents_md.py --root .` passes (1 warning: the CODEOWNERS DRI above). AGENTS.md is 141 lines, under the 200 ceiling it enforces - Every relative link **and heading anchor** across all 12 markdown files resolves - No secret-shaped literals in any tracked file; private repo names kept out of the docs per the AGENTS.md public-repo convention Unblocks the tier-1 groom rollout. BE-4680 🤖 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:36:06 +00:00