Skip to main content
Back to the lab
GitHub Actions bot

Repo Steward

Deterministic repo-health bot

View source
Node.jsGitHub ActionsBot

The problem

Repo hygiene decays silently: env vars used in code but missing from .env.example, docs drifting from the code they describe, API routes without validation, TODO debt piling up. AI review bots can catch this — at a per-call price, forever.

The build

A free, deterministic GitHub Actions maintenance bot. No LLM calls at all: TypeScript scanner scripts compare changed files, check patterns, and post findings as a markdown report or PR comment — env drift, doc drift, missing validation keywords, AI usage without cost guardrails, risky files touched, large files creeping in.

Stack & choices

  • GitHub ActionsTwo workflows: scheduled repo health plus per-PR checks
  • TypeScript · Node.jsDeterministic scanner scripts — the entire analysis engine
  • maintainer.config.jsonPer-repo tuning of which checks run and how strict

Process notes

  1. 1

    V1 is intentionally boring: useful with zero model usage and zero API credits, which also makes every finding reproducible.

  2. 2

    Install is copy-paste — two workflow files, the scanner source, and a config — no hosted service to trust.

  3. 3

    One check watches for AI-provider usage missing cost guardrails (timeouts, rate limits, max input length) — a lesson from the AI builds, encoded as a lint.

  4. 4

    V2 may add AI strictly as an explanation layer on top of deterministic findings, never as the detector.