fleet-sync: designed, deliberately not built — the evidence, so the option keeps its cost at zero

[bdelanghe]

The dependabot.yml fan-out (#10) took 57 repos, one at a time: add_repo → clone → branch → PR → merge, in batches of five to ten. That is exactly the shape that should be a workflow, and the question came up mid-sweep. Recording the design and the reasons it was not built, so choosing it later costs a decision rather than a rediscovery.

The design

An org-var-driven sync lane in ci-workflows:

• desired state — templates/* (already true)
• target set — an org variable (FLEET_REPOS), or derived dynamically from the caller-pins census, which already computes "repos containing .github/workflows/deps.yml"
• actuator — a workflow that pushes a branch and opens a PR per repo where the file differs
• credential — a new pinned GH_APPS broker entry

Same OpenTofu decomposition as caller-pins (desired / plan / apply), one layer up: instead of converging pins, it converges files.

What's already in place — this is smaller than it looks

Everything except the entry itself exists:

• vars.CF_BROKER_URL is an org variable, visible to every repo.
• .github/actions/broker-gh-token is a reusable composite action that mints a scoped App token from it, with a require: scope assertion that fails loudly rather than 403-ing a step later (.github#87, #93).
• bounded-systems-front-desk (appId 4072076) is installed on all repos, deliberately.
• front-desk-pin is an existing broker entry at exactly contents:write, pull_requests:write, metadata:read, pinned by workflowRef to .github's org-defaults.yml — the precedent, doing the identical push-a-branch-and-open-a-PR job for one repo.

So the build is one wrangler.jsonc entry through the reviewer-gated broker-deploy lane, plus the workflow. No new App, no standing PAT, no new secret.

The boundary that decides how useful it is

.github/dependabot.yml is not a workflow file, so distributing it needs only contents:write. But templates/deps.yml is, and GitHub rejects pushes touching .github/workflows/* from tokens lacking the workflows permission. So fleet-sync is either:

• narrow — non-workflow files only (dependabot configs, community-health files). Cheap, safe, and less useful than it sounds.
• broad — includes workflow files, which needs the workflows escalation and makes this repo's main able to mint org-wide write. That is the posture change SHA pins exist to prevent, and it was declined once already (#10).

That fork is the actual decision. It is not answerable by "would automation be nice".

Why it wasn't built tonight

1. The arithmetic didn't favour it. 25 repos remained when the question was asked — fewer than the build plus a broker deploy plus a review cycle. It only pays off on the next fleet file, and that frequency is unmeasured. Three appeared this week because the org is mid-buildout; steady state might be quarterly.
2. It is the bespoke actor we declined twice. The stated criterion is automation, config-as-code, nothing to maintain later. Dependabot is now the org's only standing actuator, which is a clean property to keep.
3. The manual pass was the requirements-gathering. Each thing the sweep found would have been a bot bug shipped to 57 repos:
   • deps: PR titles are rejected by semantic-PR gates; ci: is required.
   • guest-room and prx already had dependabot.yml — prx with bun + docker + github-actions ecosystems. A blind copy would have destroyed all three; the append-vs-clobber guard skipped both correctly.
   • Dependabot resolves via tags, so the untagged ci-workflows was invisible to the applier — found only by inspecting a live Dependabot PR (release-tag: name the desired state — Dependabot cannot see an untagged repo #23), and fixed by release-tag.yml.
   • Three repos ci-workflows#2 recorded as empty (gh-action-brand-checks, -contracts, -node-uniqueness) are populated and carry current callers.

When to build it

When a third fleet file needs distributing, or when a template bump needs to reach callers faster than Dependabot's weekly cycle. Until then this issue is the whole cost.

Verified end state of the fan-out

.github/dependabot.yml present on 58/58 — 55 merged tonight, guest-room and prx already configured, plus ci-workflows self-adopted.

[bdelanghe]

The trigger condition in this issue fired within the hour — and the right answer is still no

This issue says: build fleet-sync "when a third fleet file needs distributing, or when a template bump needs to reach callers faster than Dependabot's weekly cycle."

Counting honestly, both halves fired almost immediately. deps.yml was the first distribution, dependabot.yml the second, and the osv-scan pin lift to v0.1.0 (#25) is the third — a one-line edit needed in all 58 callers, which is exactly the shape this issue was written to catch.

So the condition I set is met. I still think building fleet-sync is wrong, but the reason is now better than the one recorded above.

Why "not often enough" was the weaker argument

The original case rested on frequency: three fleet files appeared in one week because the org is mid-buildout, steady state might be quarterly, so don't build for a rate you haven't measured. That reasoning was fine and is now moot — the rate turned out to be high.

The durable reason is that the work decomposes into two halves, and neither wants a central writer. The partition is forced by one fact: GITHUB_TOKEN cannot write .github/workflows/*.

• Workflow files (deps.yml and its pin) → Dependabot, which GitHub privileges specially. Nothing else moves them without the workflows escalation, which is the posture change declined on #10.
• Everything else (lockfiles, and any non-workflow config) → a reusable lane each repo calls on itself, where the repo's own GITHUB_TOKEN already has exactly the authority needed, scoped to one repo by construction rather than by downscoping a broader grant. Detail on #18.

A central fleet-sync sits in neither half. For workflow files it needs the escalation; for everything else it is strictly more authority than the self-acting alternative, to do the same job.

What that leaves

The pin lift is genuinely a one-time bridge — after it, Dependabot maintains pins tag-to-tag, which it demonstrably already does for mint (@v0.3.1 → @v0.5.0, bumped cleanly in the same PRs that skipped every # main-commented osv-scan pin). It is being done tonight by a scheduled session under explicit merge gates.

So the honest revision to this issue: fleet-sync is not deferred pending frequency evidence — it is superseded. Reopen it only if something needs distributing that is both a workflow file and outside what Dependabot resolves, which is a narrower case than "a third fleet file appears" and may never occur.

---

Generated by Claude Code