Maintainers

The runbook: releases, review policy, drift watch, security response. Edit on GitHub

CLI specArchitectureScaffold flowsCI & agentsStabilityRoadmapExpansionMaintainers

Maintainer runbook

Operational guide for groot maintainers. Contributors don't need this; see CONTRIBUTING.md.

One-time repository setup

Most settings are automated — run once with the GitHub CLI authenticated as the repo admin:

./scripts/setup-repo.sh

It configures: repo description/topics, merge hygiene (squash-only, delete branches, auto-merge), labels, Actions default token permissions (read-only), Dependabot alerts, secret scanning + push protection, private vulnerability reporting, and the main branch ruleset (PRs only, required status checks, no force pushes).

UI-only toggles (GitHub has no API for these — do them once by hand):

  1. Settings → General → Features: enable Discussions (the setup script attempts this too) and create a Q&A category.
  2. Settings → Moderation options → Reported content: enable "Accept content reports from collaborators and prior contributors" — the last item on the Community Standards checklist.
  3. Insights → Community Standards: verify everything is green.

npm: claiming and securing create-groot

Do this early — unclaimed names can be squatted.

The Bun-only exception. groot's Bun-only rule governs development workflows. npm registry administration — the one-time first publish and token management below — legitimately uses the npm CLI, because it is the registry's own tooling (2FA login sessions, trusted-publisher bootstrap). Day-to-day publishing never happens on a laptop: CI runs changeset publish via the release workflow.

  1. First publish (manual, one time). npm's trusted publishing is configured on an existing package, so bootstrap with: ``sh cd packages/cli npm login # 2FA session (npm's 2025+ auth model) npm publish --access public ` Publishing 0.0.x` of the skeleton is exactly what v0.1 is for.
  2. Configure Trusted Publishing (OIDC) at npmjs.com → create-groot → Settings → Trusted Publisher → GitHub Actions:
  1. Fallback only if OIDC is unavailable: create a granular access token (write, 90-day max — classic tokens no longer exist), save as the NPM_TOKEN repository secret, and note the rotation date. Prefer OIDC; delete the token once OIDC works.

Release flow (fully automated after setup)

  1. PRs with changesets merge into main.
  2. The Release workflow maintains a chore: version packages PR (changelog + version bumps).

Nudge required: GitHub intentionally does not run pull_request workflows on PRs created by a workflow's own GITHUB_TOKEN, so the version PR arrives with no CI checks. Close and reopen it (or push an empty commit to changeset-release/main) to fire the required checks, and comment @greptileai if the review didn't start automatically.

  1. Merging that PR triggers: changeset publish → npm publish (provenance) → git tag create-groot@X.Y.Z → GitHub Release → the binaries job compiles groot for linux-x64/arm64, darwin-x64/arm64, windows-x64, generates SHA256SUMS.txt and an SPDX SBOM (groot-sbom.spdx.json), signs build-provenance attestations for every artifact (Sigstore, GitHub attestation store), and uploads everything to the release.
  2. Verify: release page shows 7 assets (5 binaries + checksums + SBOM; releases before 2026-07-11 have 6); bun info create-groot version matches; gh attestation verify <downloaded asset> --repo bloxy-studios/groot passes; run the installer end-to-end on one platform.

macOS notarization is the one signing step that stays manual-gated: it requires an Apple Developer account (certificates + notarytool credentials as repo secrets). Until the owner provisions those, macOS users rely on checksum + attestation verification; Gatekeeper prompts on first run are expected.

Greptile review loop (policy)

Upstream drift watch

Two scheduled jobs keep groot honest against its moving upstream targets:

Intentional pin lags (e.g. scaffolded packages staying on TypeScript 5 while this repo builds with 7) live in the script's allowlist, each with a written reason; they're reported in the issue's collapsed "allowlisted" section rather than as findings. When the drift issue opens: re-verify the named section against upstream, bump the pin in its adapter, refresh scaffold-flows.md (facts, sources, date), and land it all in one PR.

Security response

Reports arrive via private vulnerability reporting. Per SECURITY.md: acknowledge ≤ 48h, assess ≤ 7 days, coordinate disclosure ≤ 90 days. Develop fixes in a temporary private fork (GitHub advisory workflow), publish the advisory with credit, ship via the normal release flow.

Ongoing hygiene