Repo Hardening

Repo Hardening

Audit and fix GitHub repository security settings using the bundled scripts/harden.sh.

Prerequisites

Before running the script, ensure:

1. gh CLI is installed and authenticated (gh auth login)
2. jq is installed
3. The user has sufficient access to the target repository:
   • audit can run with read access, with inaccessible endpoints reported as skip
   • fix requires admin access

The script checks prerequisites and exits with a clear error if required tools, authentication, or fix permissions are missing.

Workflow

Always follow this sequence:

1. Resolve the script path — run the bundled script via the path to this skill directory, not the current project directory:

   SKILL_DIR="/path/to/repo-hardening"  # directory containing this SKILL.md
   HARDEN_SCRIPT="$SKILL_DIR/scripts/harden.sh"
   

2. Audit first — run the audit to see current state:

   bash "$HARDEN_SCRIPT" audit --repo OWNER/REPO
   

3. Present findings — summarise the audit results to the user, highlighting fail and warn items grouped by severity (critical > high > medium > low).

4. Dry-run before fixing — ask the user which categories to fix. Use explicit --checks to scope fixes to the confirmed categories, then run --dry-run before any mutation:

   bash "$HARDEN_SCRIPT" fix --repo OWNER/REPO --checks branches,security --dry-run
   

   If branch protection has no existing required status checks, pass each CI context explicitly:

   bash "$HARDEN_SCRIPT" fix --repo OWNER/REPO --checks branches --required-check "test" --dry-run
   

5. Apply the exact approved plan — once confirmed, rerun the exact dry-run command with only --dry-run removed. Keep the same scoped --checks and any --required-check options from the preview:

   bash "$HARDEN_SCRIPT" fix --repo OWNER/REPO --checks branches,security
   
   # If the approved dry-run included required checks:
   bash "$HARDEN_SCRIPT" fix --repo OWNER/REPO --checks branches --required-check "test"
   

6. Verify — run audit again to confirm all checks pass.

Check Categories

Audits run all categories by default. Fixes require an explicit --checks value; use --checks all only when the user has approved changing every category.

Key Options

• --merge-strategy rebase|squash|any — which merge method to enforce (default: rebase)
• --min-reviewers N — minimum required PR reviewers, 1-6 (default: 1)
• --branch BRANCH — branch to protect (default: repo's default branch)
• --required-check NAME — required status check context to add for branch protection; repeat for multiple checks. Existing required contexts and app-backed checks are preserved.
• --format json|text — output format (default: json)

Interpreting Results

Audit statuses:

• pass — meets the hardened policy
• fail — does not meet policy; fixable by the script
• warn — informational; needs human review (e.g. deploy keys, wiki)
• skip — not applicable or insufficient permissions (e.g. GHAS features on private repos)

Severity levels: critical > high > medium > low

For detailed documentation of each check, see references/checks.md.

Multi-Repo Hardening

To audit all repos in an org:

gh repo list ORGNAME --limit 1000 --json nameWithOwner -q '.[].nameWithOwner' | \
  while read -r repo; do bash "$HARDEN_SCRIPT" audit --repo "$repo"; done

Limitations

• GHAS features: Secret scanning push protection requires GitHub Advanced Security on private repos. The script skips these gracefully.
• Org-level overrides: Some settings (Actions policies, required workflows) can be locked at the org level and cannot be changed per-repo.
• CODEOWNERS content: The script checks for the file's existence but does not validate its contents.
• Access checks: Deploy keys and outside collaborators are reported but not modified — they require human judgement.