imonirulislam/plumbline

plumbline

A plumbline is the reference a builder trues their work against. plumbline audits your repositories against a policy — the same standard, every repo, across git hosts.

Point it at a GitHub user or org and it reports, per repo, whether the default branch is what you expect, whether it's protected, whether CI exists, and whether dependency automation is set up. The policy is configurable, and the git host is a pluggable connector — GitHub today, Gitea and GitLab next.

$ plumbline audit --owner acme
REPO             default-branch  branch-protection  ci      dependency-automation
acme/api         ✓ pass          ✓ pass             ✓ pass  ✗ FAIL
acme/website     ✓ pass          ✗ FAIL             ✓ pass  ✓ pass
acme/legacy      ✗ FAIL          ✗ FAIL             ✗ FAIL  ✗ FAIL

1/3 repos fully compliant.
  branch-protection         1/3
  ci                        2/3
  default-branch            2/3
  dependency-automation     1/3

Why

Keeping a fleet of repositories consistent is tedious and easy to let slide. plumbline makes the standard explicit and checkable, so drift is visible instead of discovered later. It is read-only by default; remediation (opening PRs to fix drift) is planned and will always be opt-in.

Install

go install github.com/imonirulislam/plumbline/cmd/plumbline@latest

Or grab a binary from the releases.

Usage

export GITHUB_TOKEN=<a token with repo:read>
plumbline audit --owner <user-or-org>

plumbline audit --owner acme --json          # machine-readable
plumbline audit --owner acme --config policy.json
plumbline audit --owner acme --fail-on-issues # exit 1 on any failure (CI gate)

# Gitea / Forgejo (self-hosted — base URL required):
export PLUMBLINE_TOKEN=<a gitea token>
plumbline audit --provider gitea --base-url https://gitea.example.com --owner acme

# GitLab (gitlab.com, or --base-url for self-hosted):

plumbline audit --provider gitlab --owner mygroup # a group or a username

### Flags

| Flag               | Default  | Meaning                                            |
| ------------------ | -------- | -------------------------------------------------- |
| `--owner`          | —        | User or org to audit (required)                    |
| `--provider`       | `github` | Connector to use                                   |
| `--config`         | —        | JSON policy file (defaults if omitted)             |
| `--base-url`       | —        | API base URL, for self-hosted instances            |
| `--json`           | off      | Emit JSON instead of a table                       |
| `--out-dir`        | —        | Also write `report.md`, `report.csv`, `summary.json` |
| `--fail-on-issues` | off      | Exit 1 if any check fails (for CI)                 |

| --notify | off | Send a summary to enabled notifiers (Slack / webhook via env) | | --workers | 8 | Concurrent repo inspections |

Token is read from GITHUBTOKEN, GHTOKEN, or PLUMBLINETOKEN.

Policy

Checks and their expected values are configurable. Defaults:

{
  "default_branch": "main",
  "require_branch_protection": true,
  "require_ci": true,
  "require_dependency_automation": true
}