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:

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

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

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

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

1. 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 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 bash "$HARDEN_SCRIPT" fix --repo OWNER/REPO --checks branches --required-check "test" --dry-run ``

1. 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 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" ```

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

Check Categories

| Category | Flag | What it covers | |------------|--------------------|-----------------------------------------------------------------| | repo | --checks repo | Auto-delete branches, suggest PR updates, wiki/projects | | branches | --checks branches| Branch protection: require PRs, reviews, code owners, checks | | security | --checks security| Dependabot, secret scanning, push protection | | merge | --checks merge | Merge strategy enforcement (rebase by default) | | actions | --checks actions | Actions permissions, workflow token, PR approval restrictions | | access | --checks access | CODEOWNERS, deploy keys, outside collaborators (report only) |

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](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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: forjd
• Source: forjd/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.