• Standalone scan
• Suppressing false positives

Why

GitHub's default repository settings are optimised for discoverability and flexibility, not security. Every new repo ships with:

• Wiki and Projects enabled (attack surface, even if unused)
• Merge commits allowed (messy history, but not the main concern)
• No branch protection (anyone with write access can push directly to main)
• No Dependabot alerts
• GitHub Actions with write permissions to the repository
• Actions allowed to approve pull requests

Fixing all of this manually takes minutes per repo and is easy to forget. gh-safe-repo applies an opinionated but practical set of defaults in one shot, with a plan preview so you know exactly what will change before anything does.

What It Changes

Repository settings

GitHub Actions

Branch protection (public repos, or any repo on a paid plan)

Branch protection is applied via the Rulesets API by default (use_rulesets = true): a single gh-safe-repo defaults ruleset covers every configured branch and expresses "admins can bypass" through a bypass actor rather than the classic enforce_admins flag. Set use_rulesets = false for the legacy classic per-branch path (kept for one release cycle).

Migrating an existing repo from classic protection: if fix finds classic branch protection on a repo, it refuses to convert it to a ruleset unless you pass --migrate-branch-protection. Classic-only rules have no equivalent in the ruleset this tool builds and would be dropped silently otherwise — known gaps:

• required_status_checks — required CI checks are not modelled in the ruleset body.
• restrictions (push restrictions by user/team) — Rulesets model this differently via bypass actors; not a 1:1 map.
• Per-branch divergence — a single shared-condition ruleset can't express different rules for master vs main.

With the flag, fix creates/updates the ruleset and then deletes the classic protection on each branch so the two layers don't stack.

Tag protection (public repos, or any repo on a paid plan)

Tag protection creates a GitHub Ruleset targeting all tags (* by default, configurable via protected_tags). The following rules are enforced:

Repository admins are on the bypass list (consistent with the branch protection enforce_admins = false default). Only works on public repos or paid GitHub plans (same restriction as branch protection). Free-plan private repos will see this skipped in the plan output.

Security

Requirements

• Python 3.8+
• gh CLI installed and authenticated (gh auth login), or GITHUB_TOKEN set in your environment
• For --local / --from (which push or clone code): your usual git credentials must be set up — either an SSH key loaded into ssh-agent (when gh config get git_protocol is ssh) or an HTTPS credential helper (gh auth setup-git configures one automatically). The OAuth token is not used for git push, so workflow files (.github/workflows/*) push without needing the OAuth workflow scope.
• uv for installation from source (recommended)
• truffleHog v3 (optional — used by the pre-flight scanner; auto-detected from PATH, or run via podman/docker; falls back to regex if neither is available)

Installation

From source with uv (recommended)

This installs gh-safe-repo into uv's tool environment and adds it to your PATH.

Run directly without installing

Verify

Quick Start

CLI Reference

All commands that interact with GitHub require the owner/repo format (e.g. myuser/my-repo). For create, the owner is validated against your authenticated GitHub account to prevent mistakes on multi-account systems. For fix, admin permissions on the target repo are required instead, allowing you to fix repos owned by organizations or other accounts where you have admin access.

create — Create a new repo

A plain create (no --local/--from) initializes the repo so a default branch exists for branch protection, then removes the auto-generated README.md so the new repo starts clean. Set auto_init = true in config to keep the README instead. --local/--from push your own history and never create a README.

fix — Audit and fix an existing repo

scan — Local secret scanning

Exit code is 0 if no critical findings, 1 if criticals are found.

Dry Run / Plan Output

--dry-run shows exactly what gh-safe-repo would do, without making any changes or API calls. Use it before running for real. Combine with --json for machine-readable plan output:

When --json is active, the plan is written to stdout as a JSON object and all other messages (progress, warnings, the "Dry run" footer) go to stderr, so the output is clean for piping or scripting.

Action colours:

JSON output (--json):

summary only includes types that are present in the plan. Consumers should use .get("delete", 0) etc. rather than assuming all four keys are present.

Fix Mode (Audit Existing Repos)

fix compares an existing repo's current settings against the safe defaults and applies any corrections. No secret scanning — fix is purely about repo settings.

Fix mode:

1. Fetches the current value of every setting via the GitHub API
2. Compares against desired safe defaults
3. Shows a plan table with UPDATE for changed settings and SKIP for settings already at the desired value (no-op detection — it never makes API calls that would change nothing)
4. Prompts for confirmation before applying (skip with --yes)

Only real changes are applied — settings already at the desired value are shown as SKIP and generate no API calls.

Mirroring Repos (--from)

--from mirrors an existing repo into a new one with safe defaults. It works for both private and public destinations:

What happens, in order:

1. Your git credentials for github.com are verified up front (SSH probe when gh config get git_protocol is ssh; HTTPS is trusted), so a missing key fails fast before any repo is created
2. The source repo is cloned locally (full clone, no --depth, so truffleHog can walk the full commit history)
3. The pre-flight security scanner runs on the local clone
4. You review findings and confirm (or abort)
5. A new repo is created (private by default, or public with --public)
6. Actions permissions and security settings are applied (Dependabot, secret scanning, push protection)
7. The full history is mirrored: git clone --mirror + git push --mirror
8. Branch and tag protection are applied (after code push, so the target branch exists)

If the scan reveals a problem and you abort, no code is ever copied to GitHub.

Note: --from uses owner/repo format for both the source and destination.

Creating a Repo from a Local Directory (--local)

--local PATH is the local-to-GitHub counterpart to --from. It creates a new GitHub repo and pushes code from a local git repository. PATH must be an initialized git repository (git init or a clone).

What happens, in order:

1. Your git credentials for github.com are verified up front (SSH probe when gh config get git_protocol is ssh; HTTPS is trusted), so a missing key fails fast before any repo is created
2. The pre-flight security scanner runs on the local directory directly (no clone needed)
3. You review findings and confirm (or abort)
4. A new repo is created, and actions permissions and security settings are applied
5. The full history is pushed with push --all --tags (all branches and tags)
6. Branch and tag protection are applied (after code push, so the target branch exists)
7. origin is added to the original local repo pointing at the new GitHub URL, and the current branch's upstream tracking is configured — so git push and git pull work immediately without extra setup.

Both --local and --from work for private and public repos. They are mutually exclusive.

The local default branch (via git -C PATH symbolic-ref HEAD) is used to target branch protection rules, so protection lands on the right branch even if it isn't main.

Tip: Run gh-safe-repo scan PATH first if you want to inspect findings without creating anything.

Pre-flight Security Scanner

The scanner runs locally and never sends code to GitHub. Use it standalone before any push, or it runs automatically as part of the --from and --local workflows.

Standalone scan

Exit code is 0 if no critical findings, 1 if criticals are found — so it composes cleanly with other commands:

The full [pre_flight_scan] config applies: banned_strings, max_file_size_mb, trufflehog_mode, etc.

What it detects

Scanner engine

gh-safe-repo automatically picks the best available scanner using a three-step discovery chain:

1. truffleHog v3 on PATH — runs trufflehog --version, verifies it is v3, and uses it. A v2 install or an unrecognised version prints a warning and falls through to step 2.
2. podman or docker — if no native truffleHog is found, the scanner runs truffleHog in a container (ghcr.io/trufflesecurity/trufflehog:latest) using podman run or docker run, mounting the scan path read-only at the same absolute path so JSON output paths are identical to a native run.
3. Regex fallback — if neither a native install nor a container runtime is available, a warning is printed and the regex scanner runs instead. It also always runs in addition to truffleHog for emails and TODOs, and catches lone key-ID patterns that truffleHog deliberately skips (truffleHog requires both halves of a credential pair, e.g. AWS Key ID and Secret Access Key, before flagging a finding).

The selected scanner is shown in the "Running pre-flight security scan..." header and in the plan table's SCAN entry, e.g.:

Environment variables respected by the container path: CONTAINER_RUNTIME to override runtime selection (e.g. CONTAINER_RUNTIME=docker), and TRUFFLEHOG_IMAGE to pin a specific image tag.

Running truffleHog via podman or Docker (no local install)

No manual setup is required. gh-safe-repo detects podman or docker automatically (step 2 above) and runs truffleHog in a container with the correct volume mounts. CONTAINER_RUNTIME and TRUFFLEHOG_IMAGE environment variables are respected.

A shell wrapper (tools/trufflehog) and a Containerfile for building a pinned local image are provided in tools/ for users who want container-based truffleHog available system-wide, or who need an air-gapped image.

Interactive review

• Critical findings: Default is abort (N). You must explicitly type y to continue.
• Warnings only: Default is continue (Y). Press Enter to proceed or type n to abort.
• No findings: Scan completes silently and the workflow continues.

Secrets are redacted in the output. Email addresses and TODOs show the matching line.

Scan coverage

Build-artifact directories (node_modules, __pycache__, .venv, venv, dist, build) are skipped by default to keep scans fast. In git repos, this skip is conditional: before pruning a directory, the scanner runs git ls-files -- <dir> to check whether any files inside are tracked. If they are, the directory is scanned normally.

This means committed node_modules or dist trees — unusual, but they happen — are not silently missed. Uncommitted directories (the normal case) continue to be skipped as before.

A warning is still printed when SKIP_DIRS subdirectories are found in a cloned source repo, since their presence may indicate that more content than expected is committed.

Suppressing false positives

Two config keys let you suppress known-safe findings without disabling entire check categories.

scan_exclude_paths — skip files or directories entirely. Values are newline/comma-separated regex patterns matched against the relative file path. A matching file is excluded from every check: secrets, emails, TODOs, large files, and AI context file detection. The same patterns are also passed to truffleHog via --exclude-paths, so coverage is consistent regardless of which scanner engine is active.

exclude_emails — suppress email findings for specific addresses or entire domains. Values are newline/comma-separated, case-insensitive. Entries starting with @ match all emails at that domain; otherwise the entry must match the full address exactly. Applies to both working-tree and git history findings.

Scanner configuration

When banned strings or AI context files are found the scanner prints a ready-to-run git filter-repo command to remove them from the source repo's history before re-running.

Configuration

gh-safe-repo looks for configuration in this order (first match wins):

1. --config PATH — explicit override
2. ./gh-safe-repo.ini — current working directory
3. $XDG_CONFIG_HOME/gh-safe-repo/gh-safe-repo.ini — defaults to ~/.config when $XDG_CONFIG_HOME is unset

Bare --config (no path) skips file lookup entirely and uses built-in defaults only. All values have safe defaults — no config file is required to get started.

A fully-annotated example config is included in the repository as gh-safe-repo.ini.example. Copy it to get started:

Full configuration reference

GitHub Plan Limitations

Some features are only available depending on repo visibility and your GitHub plan.

gh-safe-repo detects your plan level and repo visibility at runtime. Unavailable features appear as SKIP in the plan output with a clear reason — the tool never fails silently.

How It Works

Plugin architecture

Each category of settings is a self-contained plugin class (gh_safe_repo/plugins/). Every plugin:

1. Fetches current state from the GitHub API
2. Compares against desired state from config
3. Returns a Plan (list of Change objects: ADD / UPDATE / DELETE / SKIP)
4. Applies only real changes — no API calls for no-ops

This means audit mode and create mode use the same plan/apply path. The only difference is whether current state is fetched from an existing repo or assumed to be GitHub defaults.

Authentication

API calls resolve a token in this order:

1. GITHUB_TOKEN environment variable — lets you target a specific account without switching the active gh session (and is the only credential needed in CI)
2. gh auth token — whatever gh auth login set up
3. Error if neither is available

Tokens are passed to child gh api processes as GH_TOKEN in the subprocess environment and are never logged.

Git operations (--local / --from push and clone) use your own git credentials — SSH key or credential helper — by default, not the API token. In environments with neither (e.g. CI with only GITHUB_TOKEN), the tool falls back to pushing over HTTPS with the token in the URL; the [git_transport] mode config setting controls this (see the configuration reference). Token-bearing URLs are never written to your repo's .git/config and are redacted from all output.

API approach

All GitHub API calls go through gh api via subprocess. This keeps authentication entirely in the gh CLI — no token management code, no OAuth flow, no PyGithub version pinning. JSON request bodies are passed via --input - (stdin), not --field flags.

Development

See tests/README.md for test file descriptions, mocking conventions, and how to add new tests.

Project structure

See gh_safe_repo/README.md for the module map, plugin architecture, and a guide to adding new settings.

Dependency policy

There are no runtime dependencies. Everything uses the Python standard library (argparse, configparser, subprocess, json, re). Do not add third-party packages without discussion.

pytest is the only dev dependency, declared as a UV-native [dependency-groups] entry in pyproject.toml.

Prior Art

These projects were studied during design and influenced the architecture of gh-safe-repo. They are distinct tools with different scope and user models — see docs/LEARNINGS.md for detailed technical notes on how patterns were adapted.

• github/safe-settings — Org-level GitHub App (Node.js/Probot) that enforces repository settings from a central config. Source of the plugin architecture pattern (one class per setting category, fetch → diff → apply) and the mergeDeep comparison approach.

• repository-settings/app — Simpler per-repo variant of safe-settings, also Node.js/Probot. Provided a cleaner reference for the Diffable base plugin pattern.

• nicholasgasior/gh-repo-settings — CLI extension written in Go with a plan/apply workflow. Primary inspiration for the gh api subprocess wrapper pattern and the dry-run plan output design.