From 664c1b0335cb0a55bbfd35450f392bdb0f0f6bac Mon Sep 17 00:00:00 2001 From: lex00 Date: Fri, 19 Jun 2026 15:27:12 -0600 Subject: [PATCH] docs(readme): status badges + clearer setup-expectations intro MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add ci / nightly-e2e / npm badges. Rewrite the intro to orient newcomers: a one-line "Terraform for GitHub admin" framing, and a new "What you need to run it" section that states the two prerequisites up front (auth — token or a GitHub App; and a config file) and that dry-run is the safe default. Co-Authored-By: Claude Opus 4.8 --- README.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5b1f70f..9fcbb81 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,39 @@ # github-warden -Keep your GitHub org and repos in declared state — reconcile, guardrails, drift correction. +[![ci](https://github.com/intentius/github-warden/actions/workflows/ci.yml/badge.svg)](https://github.com/intentius/github-warden/actions/workflows/ci.yml) +[![e2e (nightly)](https://github.com/intentius/github-warden/actions/workflows/e2e.yml/badge.svg)](https://github.com/intentius/github-warden/actions/workflows/e2e.yml) +[![npm](https://img.shields.io/npm/v/@intentius/github-warden)](https://www.npmjs.com/package/@intentius/github-warden) -github-warden is a CLI (and GitHub Action) for GitHub **org and repository -governance**. You declare desired state in a YAML/JSON config; the tool computes -the diff between desired and live state, runs safety **guardrails**, and either -reports the plan (`dry-run`) or applies it (`apply`). +**Keep your GitHub org and repos in a declared state — reconcile, guardrails, drift correction.** -It is **selective-by-omission** at every level: anything you don't declare is -never read, diffed, or changed. Deletes are **ownership-gated** — warden won't -remove a live resource unless you explicitly mark it owned. +Think of it as Terraform for GitHub administration. You write desired state for +your org and repos in **one YAML file**; warden diffs it against live GitHub, +runs **safety guardrails**, and either prints the plan (`dry-run`, the default) +or applies it. It is **selective-by-omission** — anything you don't declare is +never read, diffed, or touched — and deletes are **ownership-gated**, so it +won't remove a resource unless you mark it owned. Run it locally, on a schedule, +or as a GitHub Action. + +## What you need to run it + +Before warden does anything useful you provide two things: + +1. **Auth** — either a pre-minted installation **token** (simplest; good for + repo-level reconcile and `audit`) **or** a **GitHub App** installed on your + org (App ID + installation ID + private key). An App is **required** for + org-level cycles (org settings, members, teams) and the token cycles — see + [Auth](#auth). +2. **A config file** — a YAML/JSON file declaring the desired state you want + managed (see [Config format](#config-format)). Declare only what you want + warden to own. + +Nothing is mutated until you ask: the default mode is `dry-run`, which only +reads and prints a plan. Start there. ## Install ```bash +# Dry-run against your org — reads only, prints a plan, changes nothing. npx @intentius/github-warden reconcile --config .github/governance.yml --token-env GH_TOKEN --mode dry-run ```