/cg-oss-git-hygiene

name: cg-oss-git-hygiene
description: Set up an open source repository for healthy long-term maintenance — branch protection, commit signing, tag immutability, issue and PR templates, CODEOWNERS, CONTRIBUTING.md, SECURITY.md, Dependabot, stale bot, and triage workflow. Use when the user is publishing an open source project, mentions branch protection, rulesets, signed commits, tag protection, issue templates, PR templates, CODEOWNERS, CONTRIBUTING, code of conduct, SECURITY.md, vulnerability disclosure, Dependabot, stale issues, triage, "how do I prevent my repo from being hijacked", or "how do I manage contributors". NOT for code-level security (use cg-security-hardening), CI/CD pipeline construction, or paid GitHub Enterprise features.

cg-oss-git-hygiene

Set up a public repository so it can survive its own success: protected from accidental damage, accidental compromise, and contributor chaos. Targets indie developers and small teams shipping open source projects who do not want to wake up to a hijacked main branch, a thousand spam issues, or a year-old stale PR backlog.

Scope

**This skill covers:**

• Branch protection and rulesets (main branch is sacred)
• Tag protection (releases must be immutable)
• Commit signing (SSH or GPG verification)
• CODEOWNERS for review routing
• Issue templates (bug, feature, question, security)
• Pull request templates with checklists
• Label taxonomy for triage
• CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md
• Vulnerability disclosure policy
• Dependabot / Renovate setup for security updates
• Stale issue and PR management
• Triage workflow for solo or small-team maintainers
• Release tagging and changelog conventions
• Repo settings hardening (force push, deletion, etc.)

**This skill does NOT cover:**

• Application-level security (use `cg-security-hardening`)
• CI/CD pipeline construction itself (a separate concern; this skill assumes CI exists)
• GitHub Enterprise-only features (rulesets are GA but some advanced controls are paid)
• Self-hosted Git platforms (Gitea, Forgejo, GitLab self-managed) — the principles apply but the UI differs
• Monorepo governance with multiple sub-projects
• Maintainer succession planning, project foundations, governance models

If the user runs a hosted Git platform other than GitHub.com, the underlying principles still apply but commands and screenshots will differ.

Required context — gather before generating anything

MUST have answers to these before producing files or settings. Ask the user directly if unclear.

1. **Solo maintainer or small team?** — affects review requirements:

• Solo → cannot require external approvals (you'd block yourself); use other gates (CI, signed commits, ruleset bypass list)
• 2-5 people → require 1 approval, dismiss stale reviews on new commits
• Larger team → require 2 approvals, CODEOWNERS routing

2. **Public or private repo?**

• Public → full hardening matters; spam and drive-by attacks are real
• Private → still set up branch protection, but issue templates and stale bots matter less

3. **Will the project accept external contributions?**

• Yes → CONTRIBUTING.md is mandatory, issue templates are mandatory
• No (read-only OSS) → reduce contribution surface, add a banner explaining this

4. **Does the project have releases?**

• Yes → tag protection is critical, signed tags strongly recommended, changelog convention needed
• No → tag protection still valuable, but lighter setup

5. **Is there sensitive code (security tools, crypto, auth libraries)?**

• Yes → require signed commits, enable secret scanning, write a thorough SECURITY.md, consider private vulnerability reporting
• No → standard hardening is enough

6. **Does the user already have an existing repo with damage?** — affects approach:

• Fresh repo → set everything up at once, no existing PRs/issues to migrate
• Existing repo with mess → incremental cleanup, do not break existing workflows abruptly

The seven pillars of OSS repo hygiene

Ordered by impact-to-effort ratio. Start from pillar 1.

Pillar 1 — Branch protection and rulesets (highest priority)

**Why first**: This is the single setting that prevents the worst outcomes (force-push erasing history, accidental direct commits to main, hijacked main branch via leaked credentials). Set this up before the project gets its first star.

**Use Rulesets, not the legacy "Branch protection rules"** — Rulesets are GitHub's current recommendation, more powerful and composable. Legacy rules still work but are being phased out for new repos.

**Essential ruleset for the default branch (`main` / `master`)**:

| Setting | Recommended value | Why | |---|---|---| | Restrict deletions | ✅ enabled | Nobody accidentally deletes main | | Block force pushes | ✅ enabled | Prevent history rewriting attacks | | Require linear history | ✅ enabled (optional) | Cleaner history, easier to audit | | Require pull request before merging | ✅ enabled | Even solo maintainers benefit from PR audit trail | | Required approvals | 1 (small team), 0 (solo with bypass) | Forces review checkpoint | | Dismiss stale approvals on new commits | ✅ enabled | Prevents approval-then-rewrite attack | | Require review from CODEOWNERS | ✅ enabled (if CODEOWNERS exists) | Subject matter experts review their areas | | Require conversation resolution | ✅ enabled | Forces actual discussion completion before merge | | Require status checks to pass | ✅ enabled (list specific checks) | CI must pass, no broken main | | Require branches to be up to date before merging | ✅ enabled | Catches integration bugs before merge | | Require signed commits | ✅ enabled | See pillar 3 | | Require deployments to succeed | ⚠️ only if you have a staging deploy | Prevents broken prod releases | | Lock branch | ❌ disabled (only for archived branches) | Read-only branches can't be merged into | | Restrict who can push | Solo: bypass list of yourself; Team: empty (PRs only) | Avoids d