feat: the Nyuchi App's backend — release tagging, review and triage

[bryanfawcett]

Part of nyuchi/.github#90. The design is in this comment.

What

nyuchi-github-app is the Cloudflare Worker behind the Nyuchi GitHub App (id 4980118). It covers every org in the bundu-labs enterprise.

Trigger	Action
push to staging	Next PATCH tag and a pre-release vX (beta)
push to the default branch	Next MINOR tag and a release. Never MAJOR
nightly cron 01:17 UTC	Backfills untagged merges since BACKFILL_SINCE, grouped by PR, oldest first, at most 10 per repo per run
pull_request, or @nyuchi in a PR comment	Code review with the shared Shamwari engine (git dependency pinned to shamwari-ai/github-app@ae94b6a), Workers AI through fundi
issues opened	Labels chosen only from the repo's existing labels. It never creates labels, closes, assigns or comments

Rules it keeps

• Policy is not forked. src/policy/next-version.mjs is nyuchi/.github's file at a0d2d79, copied byte-for-byte. CI runs scripts/check-policy.sh, which fails on any drift.
• Never publishes by accident. A tag or release made by an App starts workflows, unlike one made by GITHUB_TOKEN. So a repo with a workflow that starts on push: tags, release or create is reported and never tagged.
• No racing per-repo workflows. These are not removed yet. On push, the app skips a channel the repo still tags itself (reusable-staging-release, reusable-auto-tag, reusable-release). The nightly pass fills gaps.
• Org allowlist ALLOWED_ORGS: the 7 enterprise orgs. nyuchiGOV is never in it, and tests cover that.
• Skipped repos: sandbox-*, archive-*, archived repos, forks, empty repos, and repos with non-v tag schemes.
• Secrets come from the Cloudflare Secrets Store (NYUCHI_GITHUB_APP_PRIVATE_KEY, NYUCHI_GITHUB_WEBHOOK_SECRET). The Worker fails closed (503) without them. GET / reports whether each one is bound, as true or false only.
• No Anthropic API.
• Ships in TAGGING_MODE = "dry-run". Going live is a separate PR.
• This repo dogfoods the app: it has no per-repo tagging workflow.

Verification

• npm run build (tsc on src and tests): clean. npm test: 42 pass, 0 fail. vp check: formatted, 0 errors. scripts/check-policy.sh: matches nyuchi/.github@a0d2d79. wrangler deploy --dry-run: bundles at 268 KiB, with the Secrets Store bindings listed.
• Runtime, local workerd (wrangler dev):
  • GET / returns the health JSON.
  • /webhook with no secret returns 503. With a local-only test secret:
    • ping returns 200 pong;
    • a nyuchiGOV push returns "organisation not allowed";
    • a feature-branch push returns "ref not released";
    • a bot issue is skipped;
    • a @nyuchi/platform team mention is skipped;
    • a bad signature returns 401.
  • __scheduled fails closed with "APP_PRIVATE_KEY is not bound".
  • The first run caught a real bug, fixed here: the vendored policy imports node:url, so the Worker needs nodejs_compat.
• Real GitHub, read-only (scripts/plan.ts, my token, dry-run) across all 7 orgs, 83 repos:
  • The query and plan work.
  • nyuchi-licence-server and api-gateway are up to date, so the hand backfill (v0.1.0..v0.3.0) is recognised.
  • 9 repos are skipped as publishing on tags (auto-seo-manager, mongodb-mcp, nyuchi-docs, nyuchi-travel-addons, mukoko-events-mcp, bundu-labs/marketing, openNTL/ntl, siafudb, and similar).
  • Most repos without a staging flow would get many backfilled minors since 2026-10-04. Two examples: nyuchi/.github +45 and mukoko-weather +50. Whether that is wanted is an owner question on #90.

Code review: see the comment below.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GHjaH1Vt2dVLWU68iz8tFq

[bryanfawcett]

Security review findings: both fixed in 8775b8c

The background commit security review flagged two merge-gate blockers. /code-review (high) independently found the same two, plus eight more.

1. Publish-guard bypass (src/tagging.ts, security-control-bypass).
The guard stops the app creating tags or releases that would start a publish workflow. Unlike GITHUB_TOKEN tags, App-made tags do start workflows. The guard had two gaps:

• It counted push: tags, release and create only. It missed:
  • on: push, [push], a bare push:, and push: {paths: ...}, all of which GitHub runs for tag pushes because there is no branches filter. A publish job behind if: startsWith(github.ref, 'refs/tags/') is a common shape.
  • workflow_run, which can chain off a tag-started run.
• It read only HEAD:.github/workflows, the default branch. A tag push runs the workflows at the tagged commit. So a staging branch, or an old backfilled merge, with a tag-triggered workflow got tagged anyway.

Reproduced by tests:

• finding 1: triggers that run on a tag push...
• publish guard: a tag-triggered workflow only on the tagged commit (not HEAD) blocks tagging
• publish guard: an old merge whose workflows published on tags is not backfilled

All three fail on the old code.

Fix:

• The trigger list is conservative: an unrecognised on: also counts.
• publishingCommits() reads .github/workflows at every commit about to be tagged (one GraphQL query). If any of them publishes, the channel is not tagged.

On real GitHub (read-only dry run, 83 repos) 27 repos are now left alone, up from 9.

2. TOCTOU between plan and write (src/scan.ts).
The next version and "is this commit already tagged" were decided from one snapshot and written later. Meanwhile a repo's own workflow, another push, or the nightly run could tag the same commit or take a higher version, giving a second version on one commit or a version below the highest.

Fix:

• assertStillValid() re-reads the live tags immediately before each write. It refuses if the name is taken, the commit now carries a version tag, or the highest version is no longer the one the tag was planned on top of (PlannedTag.after).
• Ref creation stays the atomic last guard (422 if it exists), and no release is created without its tag.

Reproduced by tests:

• TOCTOU: a version tag that lands on the commit after planning stops the write
• TOCTOU: a higher version appearing elsewhere after planning stops the write
• TOCTOU: the ref create is the atomic last guard

These use a stateful fake GitHub where the race happens between plan and write.

Residual: GitHub has no compare-and-swap for "create tag only if the commit has none". A different-name tag created in the milliseconds between the re-read and the ref creation is still possible. The next run sees both, and tag protection forbids deleting either.

Other /code-review findings fixed in the same commit:

• triage spending gate (author_association);
• the team-mention guard now uses the engine's left boundary, so emails are not counted;
• the PR merged into this branch wins over an open release PR;
• a failed release is repaired on the next run;
• history is paginated, and fails closed rather than stranding older merges;
• a nightly tag budget, subrequests = 50000, and the org order rotated daily.

Answered rather than fixed:

• Fast-forward of main onto a staging-tagged commit: it only happens with a ruleset bypass. Documented in the README.
• The near-copy of the engine's review dispatch, and the team-mention patch: upstream asks are in Engine reuse by the Nyuchi App: team mentions, export the review dispatch, worker attribution shamwari-ai/github-app#7, with TODOs in code.

Tests: 54 pass. tsc clean, vp check 0 errors, policy drift check passes, wrangler bundle builds. Re-review is running.

[bryanfawcett]

Security review findings 3–5 (and the convergence that followed)

Records 1 and 2 are in the earlier comment. All five are fixed on #1, and each has a test that fails on the old code.

3. Fail-open validation (src/scan.ts)

• Found: several checks let tagging go ahead on missing or odd data:
  • an unset or non-ISO BACKFILL_SINCE widened the window to all history (new Date("1") is the year 2001);
  • a null per-commit workflow tree counted as "no workflows" even when the commit itself could not be found;
  • truncated workflow blobs were parsed as if complete;
  • a mistyped limit fell back to its default.
• Fix: strict ISO and strict integers; one treeFacts validator for every tree; Commit-typed checks; nested tag peeling, where an unresolved version tag skips the repo; scanRepo never throws, so the reason ends up in the report.
• This also caught a real bug: scripts/plan.ts never parsed [vars], so the first dry-run numbers covered all history. They have been re-run.

4. Parser differential (.github/actions/next-version/read-version.mjs, and the App)

• Found: the reader, the policy and the App could read the same version differently (v, whitespace, suffixes, duplicate keys).
• Fix, feat(workflows): release-version-check, the enterprise required version check (#90) .github#91: ONE strict parser, isStrictVersion in next-version.mjs (MAJOR.MINOR.PATCH, each 0..999, nothing else). Every reader goes through it. TOML is read with tomllib and JSON with json in one isolated python3 -I run, and duplicate root version keys are invalid.
• App side: it uses the vendored isStrictVersion and runs every shared version-fixtures.json entry through all its readers (differential test).

5. Provenance regression (src/scan.ts)

• Found: the release-repair ledger recorded only tag names, after the fact. A tag deleted and re-made by someone else could be treated as ours, and a crash could strand a tag with no release.
• Fix:
  • Tags are written only on branches GitHub reports as protected (deletion, non-fast-forward and linear-history rules), from the App's own reads.
  • Every commit is re-proven reachable from refs/heads/<branch> just before its write.
  • The ledger is written ahead: it records {tag, tag-object sha, commit, prerelease, latest, PR} before the ref is created.
  • Repair trusts an entry only while the REST ref still points at that exact object.
  • Tags are annotated, with the App as tagger, and carry Pull-request: #N; the release links the PR.
  • Test: a commit not reachable from the protected branch head is never tagged.

Since then: /code-review (high) re-ran on the whole PR after each round, until it found no confirmed medium or higher defects.

• App (40c3e2a, delta 574138b): clean.
• Notable later fixes:
  • a per-repo TagLock Durable Object, keyed by repository id;
  • an hour's grace before tagging commits whose PR GitHub has not indexed yet, read from GitHub's activity record for the ref;
  • bounded, classified repair retries;
  • drafts no longer count as releases;
  • batched GraphQL.

[bryanfawcett]

Merge gate: met

• Scope complete: the App's backend covers release tagging (push to staging and to the default branch), the nightly backfill, review and triage, and the security hardening from five security findings and the review rounds.

• CI green at 8f8e627: test, Org lint and vite-plus all pass. The test job runs build, 165 tests, npm run check, the policy drift check (pinned to nyuchi/.github@93d089f, the merge of #91, on staging) and the wrangler bundle.

• Verified at runtime:

  • local workerd (wrangler dev) against a fake GitHub:
    • two concurrent pushes under the TagLock make v0.1.0 and v0.2.0 once, even under a repo rename;
    • failed releases are repaired by the nightly cron;
    • every webhook gate answers as designed (503 without a secret, 401 on a bad signature, nyuchiGOV refused);
  • a read-only dry-run plan against real GitHub across all 7 orgs (scripts/plan.ts).

• /code-review:

  • the full high-effort review was clean at 40c3e2a, with no confirmed defects of medium or higher severity;
  • the delta reviews of 574138b and 8f8e627 were clean too.

  Every earlier finding was fixed or answered. They are listed in the comments above and on Enterprise Nyuchi App: release tagging, code review and triage from the bundu-labs enterprise .github#90.

The Worker ships in TAGGING_MODE = "dry-run". Owner steps (app transfer, secrets, first deploy, installs) are on #90.