Add GitHub repo setup workflow and best practices skill

[markcallen]

Summary

Add a GitHub Actions workflow (github-repo-setup.yml) that enforces repository hygiene on demand, and a companion Ballast skill (github-repo-setup.skill) that audits a repo against best practices for both public and private repos.

---

Proposed GitHub Action: .github/workflows/github-repo-setup.yml

Triggered via workflow_dispatch with inputs:

• visibility — public or private (changes which rules are applied)
• required_checks — comma-separated list of status check names to require (default: key CI jobs from lint.yaml and test.yml)
• dry_run — report what would change without making changes

What it configures

Branch protection on main:

• Require pull requests before merging (minimum 1 approving review)
• Dismiss stale reviews when new commits are pushed
• Require conversation resolution before merging
• Require status checks to pass before merging (strict — branch must be up to date)
• Required checks: typescript-lint, python-lint, go-pack-lint, cli-lint, typescript-tests, python-tests, go-pack-tests, cli-tests
• Prevent force pushes
• Prevent branch deletion
• Enforce rules for admins

Dependabot:

• Verify .github/dependabot.yml exists and covers all detected ecosystems (npm, pip/uv, gomod, github-actions)
• If missing, create a minimal baseline config

Repo settings:

• Enable vulnerability alerts
• Enable automated security fixes (Dependabot auto-PRs for security)
• Configure merge settings: allow squash merge, delete head branches on merge, disable merge commits
• Require signed commits (public repos)

Public repo extras:

• Enable secret scanning
• Enable push protection (block commits containing secrets)
• Recommend enabling CodeQL via a separate workflow

Permissions needed

permissions:
  contents: write
  administration: write

The GITHUB_TOKEN with administration: write can set branch protection rules from within a workflow in a repo where the workflow has admin rights.

---

Proposed Skill: .claude/skills/github-repo-setup.skill

A skill that:

1. Reads the current repo's branch protection, Dependabot config, and security settings
2. Scores the repo against the best practices checklist below
3. Prints a gap report and recommended actions
4. Optionally triggers gh workflow run github-repo-setup.yml to apply fixes

---

Best Practices: Private vs Public Repos

Both (shared baseline)

Practice	Why
Branch protection on default branch	Prevents accidental direct pushes and force-pushes
Required PR reviews (≥1)	Ensures a second set of eyes before code lands
Required status checks (CI must pass)	Prevents broken code from merging
strict status checks (branch must be up to date)	Prevents merge-order bugs
Dismiss stale reviews on new commits	Review approval should reflect latest code
Require conversation resolution	Ensures review comments are addressed, not silently ignored
No force pushes on main	Preserves linear history; prevents history rewriting
No branch deletion of main	Catastrophic mistake prevention
Dependabot version updates	Keeps dependencies current; reduces known-vuln surface
Dependabot security updates	Auto-PRs for CVE fixes without waiting for weekly runs
CODEOWNERS	Routes review requests to the right people automatically
PR template	Consistent PR descriptions; checklist reduces reviewer cognitive load
Signed commits (recommended)	Proof that commits came from the claimed author
Squash merge strategy	Keeps main history readable; one commit per PR
Delete head branch on merge	Reduces branch clutter automatically
Secret scanning	Catches leaked credentials before they spread
.github/dependabot.yml covers all ecosystems	npm, Go, Python, and github-actions all update automatically
SECURITY.md	Tells reporters how to disclose vulnerabilities responsibly

Public repos (additional)

Practice	Why
Push protection (block secret commits)	Prevents secrets from ever reaching the remote
CodeQL / code scanning	SAST: catches known vulnerability patterns in code
Require code owner review	Ensures domain experts approve changes to their area
LICENSE file	Required for open-source reuse; without it the repo is legally all-rights-reserved
Topics and description in repo settings	Discoverability in GitHub search
Dependabot grouped PRs	Reduces PR noise for popular deps (eslint, typescript, aws-sdk)
Community health files (CONTRIBUTING.md, CODE_OF_CONDUCT.md)	Sets expectations for external contributors
Pinned GitHub Actions to commit SHAs	Prevents supply-chain attacks via compromised action tags

Private repos (different priorities)

Practice	Why
Enforce admin rules	Prevents repo owners from bypassing protection in a hurry
Restrict who can push to main	Limit blast radius for compromised accounts
Org-level branch protection (if org repo)	Consistent policy across all repos without per-repo config
Internal visibility over private (GitHub Enterprise)	Reduces friction for internal contributors while keeping code off the internet
Audit log review	Track who changed what; important for compliance

---

Implementation Notes

• The workflow should be idempotent: running it twice should produce no errors and no unnecessary changes.
• Use gh api --method PUT for branch protection (replaces entire ruleset atomically).
• Use GitHub's newer Repository Rulesets API (/repos/{owner}/{repo}/rulesets) as an alternative — rulesets survive branch renames and can be org-scoped.
• The skill should follow the same report structure as github-health-check.skill for consistency.
• Required status check names must exactly match the job names in the workflow files (e.g. typescript-lint, not Lint / typescript-lint).

Related

• .claude/skills/github-health-check.skill — existing read-only health check skill
• .github/dependabot.yml — already configured for this repo
• .github/CODEOWNERS — already in place