Factory docs, home
Page navigation

See the input → responsibility → output diagram.

Branch health watches each project's main branch on GitHub and says, from what GitHub reports, whether it is red, unknown or green.

A slim teal bob studying a potted sapling with one branch.

Meet the gardener. Report what the branch shows. Reads each project's main branch and says red, green or unknown from what GitHub reports. Meet the whole Plumb family.

What it does

Each poll reads the head of the branch, meaning its latest commit, with the checks that ran on it, and each workflow's runs, state and schedule. A project is green only when checks on that exact commit passed and nothing went unread. A failed check makes it red, and anything else leaves it unknown, with the reason. Each failing, stopped or late workflow becomes one episode, recording what was seen, such as "new-head red", never a cause.

No study yet: this module has no plate position.

Limits and status

Honest limits:

  • It has read only a recorded copy of six projects' GitHub data from 29 September 2026, through a stand-in for gh. It has never read GitHub live, and nothing polls on a schedule: live polling waits for the owner's commission.
  • It only reads. It never reruns, pauses or re-enables a workflow, and it never asks gh to show a token.
  • A poll does not read whether a repository is public. A separate read, asked for by the Prevention register, reads only that through the same read-only access; it is a draft awaiting independent review.
  • A signature is an observation, not a cause. "New-head red" means a workflow failed on a new commit after passing on an earlier one, a suspected regression. "Same-head red" means it failed on a commit where it had passed, which suggests something outside the code changed.
  • An episode ends only when its failing jobs pass on the branch's latest commit, or when a person disables or removes the workflow (or removes a late schedule). A passing run that skipped those jobs ends nothing, and neither does a push while a schedule is late. Jobs are matched by their full names, so a job whose name merely looks like the failed one's, cut short or spaced differently, ends nothing. A failure an ended episode already covered never starts another one.
  • If a person turns a workflow back on while its last run still shows the failure, the project stays unknown until the workflow runs again.
  • Anything it could not read keeps a project unknown, never green: a listing cut short, a refused request (401, 403 or a rate limit), a timeout or an unreadable reply. Workflow files it did not read leave a missed schedule undecided. A schedule that has never run keeps the project unknown but is not called late, because nothing dates it.
  • A check that was cancelled, went stale or waits for someone's approval is not a pass. A check from one workflow never hides a failed check of the same name from another.
  • It reads at most five pages of a workflow's runs, so a failing spell that began earlier has an unknown start. When it stops early, it reads each other kind of trigger separately, so an older failure is not missed; such a page that fails or does not add up leaves the project unknown. GitHub does not date disabling a workflow, so that start is unknown too.
  • Each poll reads the workflow's runs back to where the last poll stopped, and to any run that was still going then, so a gap cannot silently pass as complete history, even after an episode closes. A poll that cannot read that far back keeps the project unknown and prevents an episode from ending. It does not notice a rerun of a run older than what it reads.
  • It reads the jobs of every failed run in an episode, 20 runs a poll. Until all are read, the episode cannot end, and a failure that began beyond what it can read never ends on its own.
  • Evidence that names another commit or run, or a listing whose count does not match what it holds, is treated as unread.
  • Its thresholds are proposals. Six failures started by a bot on one commit in a day mark a runaway. A run waiting an hour, or a schedule an hour late, gives no signal.

Status: Accepted local implementation: independent Astra reviews and combined checks passed. No live polling, scheduling or delivery. Acceptance and evidence.

Contract and limits

Run the local commands. Live use remains separately commissioned.

Use it outside Factory

The E29 private package draft accepts your own Product identities, journal, reader and clock, with an optional synchronous blocker mirror. It needs no Portfolio registration or local checkout. The same episode and recovery rules apply. Repeating a poll instant repairs a lost mirror without reading GitHub again for Products already recorded; if your mirror throws mid-poll, Products the poll had not yet reached gain nothing at that instant. One never polled has no record; one polled before keeps its earlier record, so a green state there is an older poll's finding, not this one's: check its last poll instant before trusting it. A retry at the same instant reads them again. Adopt Branch health explains the contract and its limits. Disposable package and legacy-journal checks passed independent Astra review; the draft was merged on 1 October 2026 after an Opus 5.5 review and accepted locally the same day by the owner-designated acceptance reviewer after a Fable 5.1 review. No live polling or scheduling has been added.

Source: docs/guide/branch-health.md