docs(automations): fresh clone per run, one comment per PR, cancel the previous run, PR gatekeeper recipe

[sre-helmcode]

Summary

Documents the automation options from helmcode/nan-cloud-api#343 (merged), NaN community only. Ships together with the cloud-ui editor PR that adds the same settings (portal labels taken from it: Repository card, Checkout, Workspace folder, Fresh clone per run, Run pull requests from forks and outside contributors, Keep one comment per pull request, Cancel the previous run, Superseded by run, One comment, updated each run).

Pages

• /docs/automations and /es/docs/automations:
  • Settings table: the three new settings and the third When a run is active option. Folder and Separate branch are marked unused with a fresh clone.
  • When a run is already active: Cancel the previous run (supersede). It cancels queued, working or awaiting runs of the same subject. Events without a subject queue. superseded_by is set, and a stale proposal is never posted.
  • New Fresh clone per run section:
    • Which commit, for PR, workflow_run and anything else, plus pull request head moved.
    • The clone credential: an Agent GITHUB_TOKEN, needed only for private repos and never written into the clone.
    • Caches and TMPDIR live inside the run folder, deleted whatever happens. Limits: 10 min clone, 4 GiB, 500,000 files.
    • No git_push.
    • Forks and outside contributors are ignored by default; the opt-in is the member's decision.
  • New One comment per pull request section: NaN edits only its own marked comment, PR comments only, and the last comment wins.
  • New Recipe: PR gatekeeper section:
    • Tokens: a fine-grained write token with Contents read + Pull requests read/write as Actions only, plus a read-only token as Agent for private repos.
    • Recommended settings: fresh, sticky, supersede, Fully automatic (Custom as a safety net), 30 min.
    • The GitHub webhook setup.
    • Sample instructions without clone or cleanup steps: the agent works in its current folder.
  • A FAQ entry: why was my PR ignored.
• /docs/webhooks and /es/docs/webhooks: a note under Only some GitHub users, and the Ignored by a filter delivery row now covers fork/outsider PRs.
• API reference (src/data/openapi.json):
  • Automation.checkout, sticky_pr_comment, checkout_untrusted_heads, and concurrency_policy supersede.
  • Run.checkout (new RunCheckout schema), superseded_by, sticky_pr_comment.
  • The optional checkout of the started event.
  • Examples updated.

Tests

• Fixtures re-synced from cloud-api internal/handlers/testdata/phase2, including the new automation_get_gatekeeper.json and run_get_gatekeeper.json. Every golden validates against the published schemas. trigger_rotate.json is not copied because rotate is a portal-only write that this reference does not document.
• openapiAutomations.test.ts / openapiRuns.test.ts:
  • Field order matches the handler structs.
  • Enums and descriptions are pinned.
  • New goldens are validated.
  • Known-bad: the validator rejects a bad mode, a bad policy and a non-SHA sha.
• automationsDocs.test.ts, new block per locale:
  • Every new portal label is present.
  • Fresh clone facts, untrusted heads defaults, sticky and supersede semantics.
  • The recipe's settings, token permissions and webhook steps.
  • The sample instructions contain no clone, checkout, rm -rf or token handling.
  • Known-bad verified: reintroducing a clone step fails it.
• npm test: 77 files, 1904 tests green. npm run build: green.

🤖 Generated with Claude Code