Это устанавливает gh-safe-repo в среду инструментов uv и добавляет его в ваш PATH.

Запуск напрямую без установки```bash

git clone https://github.com/your-username/gh-safe-repo cd gh-safe-repo uv sync # creates .venv ./gh-safe-repo create <owner/repo>

Быстрый старт```bash

Create a private repo with all safe defaults

gh-safe-repo create <owner/repo>

Preview what would happen — no changes made

gh-safe-repo create <owner/repo> --dry-run

Create a public repo (branch protection + security scanning applied)

gh-safe-repo create <owner/repo> --public

Mirror an existing repo into a new private repo (with pre-flight scan)

gh-safe-repo create <owner/repo> --from <owner/source>

Mirror a private repo to a new public repo (with pre-flight scan)

gh-safe-repo create <owner/pub> --from <owner/priv> --public

Create a repo from a local directory (with pre-flight scan)

gh-safe-repo create <owner/repo> --local ~/projects/myapp

Same, but make it public (branch protection applied before push)

gh-safe-repo create <owner/repo> --local ~/projects/myapp --public

Audit an existing repo and apply any missing safe defaults

gh-safe-repo fix <owner/repo>

Audit without making changes

gh-safe-repo fix <owner/repo> --dry-run

Apply fixes without confirmation prompt (scripting/batch use)

gh-safe-repo fix <owner/repo> --yes

Scan a local repo for secrets before pushing anywhere

gh-safe-repo scan . gh-safe-repo scan ~/projects/myapp

Все команды, взаимодействующие с GitHub, требуют формат owner/repo (например, myuser/my-repo). Для create владелец проверяется по вашему аутентифицированному аккаунту GitHub, чтобы предотвратить ошибки в системах с несколькими аккаунтами. Для fix вместо этого требуются права администратора на целевой репозиторий, что позволяет вам исправлять репозитории, принадлежащие организациям или другим аккаунтам, где у вас есть административный доступ.

create — Создание нового репозитория

Простой create (без --local/--from) инициализирует репозиторий, чтобы существовала ветка по умолчанию для защиты веток, а затем удаляет автоматически сгенерированный README.md, чтобы новый репозиторий начинался чистым. Установите auto_init = true в конфигурации, чтобы сохранить README. --local/--from отправляют вашу собственную историю и никогда не создают README.

fix — Аудит и исправление существующего репозитория

scan — Локальное сканирование секретов

Код выхода — 0, если критических находок нет, 1, если найдены критические.

Сухой прогон / Вывод плана

--dry-run показывает точно, что сделал бы gh-safe-repo, без внесения изменений или вызовов API. Используйте перед реальным запуском. Комбинируйте с --json для вывода плана в машиночитаемом формате:```bash gh-safe-repo create <owner/repo> --dry-run --json gh-safe-repo fix <owner/repo> --dry-run --json

Цвета действий:

Вывод JSON (--json):```json { "changes": [ { "type": "add", "category": "repository", "key": "has_wiki", "old": null, "new": false, "reason": null }, { "type": "skip", "category": "branch_protection", "key": "branch_protection", "old": null, "new": null, "reason": "Not available for private repos on free plan" } ], "summary": { "add": 5, "skip": 2 } }

Режим исправления:

1. Получает текущее значение каждого параметра через GitHub API
2. Сравнивает с желаемыми безопасными значениями по умолчанию
3. Показывает таблицу плана с UPDATE для изменённых параметров и SKIP для параметров, уже имеющих нужное значение (обнаружение бездействия — он никогда не совершает вызовы API, которые ничего не меняют)
4. Запрашивает подтверждение перед применением (пропустить с помощью --yes)

Применяются только реальные изменения — параметры, уже имеющие нужное значение, отображаются как SKIP и не генерируют вызовов API.

Зеркалирование репозиториев (--from)

--from зеркалирует существующий репозиторий в новый с безопасными значениями по умолчанию. Работает как для частных, так и для публичных целевых репозиториев:```bash

Mirror into a new private repo (default)

gh-safe-repo create <owner/repo> --from <owner/source>

Mirror a private repo to a new public repo (riskiest operation — scanned thoroughly)

gh-safe-repo create <owner/pub> --from <owner/priv> --public

Что происходит по порядку:

1. Ваши учетные данные git для github.com проверяются заранее (SSH-зонд, когда gh config get git_protocol равно ssh; HTTPS считается доверенным), поэтому отсутствующий ключ быстро приводит к ошибке до создания любого репозитория
2. Предварительный сканер безопасности запускается непосредственно в локальной директории (клонирование не требуется)
3. Вы просматриваете результаты и подтверждаете (или отменяете)
4. Создается новый репозиторий, и применяются разрешения действий и настройки безопасности
5. Полная история отправляется с помощью push --all --tags (все ветки и теги)
6. Применяется защита веток и тегов (после отправки кода, чтобы целевая ветка существовала)
7. origin добавляется в исходный локальный репозиторий, указывая на новый URL GitHub, и настраивается отслеживание текущей ветки вверх по потоку — так что git push и git pull работают сразу без дополнительной настройки.

Оба параметра --local и --from работают для частных и публичных репозиториев. Они взаимно исключают друг друга.

Локальная ветка по умолчанию (через git -C PATH symbolic-ref HEAD) используется для нацеливания правил защиты ветки, поэтому защита применяется к правильной ветке, даже если это не main.

Совет: Сначала выполните gh-safe-repo scan PATH, если хотите просмотреть результаты без создания чего-либо.

Предварительный сканер безопасности

Сканер запускается локально и никогда не отправляет код на GitHub. Используйте его отдельно перед любой отправкой, или он запускается автоматически в рамках рабочих процессов --from и --local.

Автономное сканирование```bash

Scan the current directory

gh-safe-repo scan .

Scan an explicit path

gh-safe-repo scan ~/projects/myapp

Полная конфигурация [pre_flight_scan] применяется: banned_strings, max_file_size_mb, trufflehog_mode и т.д.

Что обнаруживает

Механизм сканирования

gh-safe-repo автоматически выбирает лучший доступный сканер, используя трёхэтапную цепочку обнаружения:

1. truffleHog v3 на PATH — выполняет trufflehog --version, проверяет, что это v3, и использует его. Установка v2 или нераспознанная версия выводят предупреждение и переходят к шагу 2.
2. podman или docker — если нативный truffleHog не найден, сканер запускает truffleHog в контейнере (ghcr.io/trufflesecurity/trufflehog:latest) с помощью podman run или docker run, монтируя путь сканирования только для чтения по тому же абсолютному пути, чтобы пути JSON-вывода были идентичны нативному запуску.
3. Регулярное выражение (запасной вариант) — если ни нативная установка, ни среда выполнения контейнера недоступны, выводится предупреждение и запускается сканер на основе регулярных выражений. Он также всегда запускается в дополнение к truffleHog для почтовых адресов и TODO, и перехватывает одиночные шаблоны идентификаторов ключей, которые truffleHog намеренно пропускает (truffleHog требует обе половины пары учётных данных, например, идентификатор ключа AWS и секретный ключ доступа, прежде чем пометить находку).

Выбранный сканер отображается в заголовке "Running pre-flight security scan..." и в записи SCAN таблицы плана, например:``` Running pre-flight security scan... (truffleHog v3.93.4) Running pre-flight security scan... (truffleHog via podman) Running pre-flight security scan... (regex only — see warning above)

• Критические находки: По умолчанию — прерывание (N). Вы должны явно ввести y, чтобы продолжить.
• Только предупреждения: По умолчанию — продолжение (Y). Нажмите Enter, чтобы продолжить, или введите n, чтобы прервать.
• Находок нет: Сканирование завершается без вывода, и рабочий процесс продолжается.

Секреты скрыты в выводе. Адреса электронной почты и TODO показывают соответствующую строку.

Охват сканирования

Директории с артефактами сборки (node_modules, __pycache__, .venv, venv, dist, build) по умолчанию пропускаются для ускорения сканирования. В git-репозиториях этот пропуск является условным: перед удалением директории из сканирования сканер выполняет git ls-files -- <dir>, чтобы проверить, отслеживаются ли какие-либо файлы внутри. Если да, директория сканируется обычным образом.

Это означает, что зафиксированные в репозитории деревья node_modules или dist — необычно, но бывает — не пропускаются незаметно. Незафиксированные директории (обычный случай) по-прежнему пропускаются, как и раньше.

Предупреждение всё равно выводится, когда поддиректории SKIP_DIRS найдены в клонированном исходном репозитории, поскольку их наличие может указывать на то, что было зафиксировано больше контента, чем ожидалось.

Подавление ложных срабатываний

Два ключа конфигурации позволяют подавлять известные безопасные находки без отключения целых категорий проверок.

scan_exclude_paths — полностью пропускать файлы или директории. Значения — разделённые новой строкой или запятой regex-шаблоны, сопоставляемые с относительным путём файла. Соответствующий файл исключается из всех проверок: секреты, email-адреса, TODO, большие файлы и обнаружение файлов контекста ИИ. Те же шаблоны также передаются truffleHog через --exclude-paths, поэтому охват остаётся согласованным независимо от того, какой движок сканирования активен.```ini [pre_flight_scan]

Exclude the GitHub API spec (example tokens) and all test fixtures

scan_exclude_paths = docs/api.github.com.json tests/fixtures/

Конфигурация сканера```ini

[pre_flight_scan] scan_for_secrets = true scan_for_emails = true scan_for_todos = true max_file_size_mb = 100

Scan git history for email addresses (requires scan_for_emails = true)

scan_email_history = true

Scanner selection: auto | native | docker | off

auto — try native truffleHog, fall back to container (podman/docker), then regex (default)

native — native truffleHog only; no container fallback

docker — container only; skip native PATH check

off — regex scanner only, no truffleHog attempt

trufflehog_mode = auto

Flag AI context files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) as critical findings.

Their git history may contain more sensitive content than the current version.

warn_ai_context_files = true

Literal strings to flag as critical findings (case-insensitive).

Comma-separated or one per line (continuation lines must be indented).

banned_strings = secret

password

credential

Exclude files/directories from all scan checks (regex patterns, comma/newline separated).

The same patterns are passed to truffleHog via --exclude-paths.

scan_exclude_paths = docs/api.github.com.json

tests/fixtures/

Suppress email findings for specific addresses or entire domains (case-insensitive).

Entries starting with @ match all emails at that domain; otherwise exact address match.

exclude_emails = [email protected], [email protected], @example.com

Полная справка по конфигурации```ini

[repo]

Whether new repos are private by default

private = true

Disable features that create clutter if unused

has_wiki = false has_projects = false has_issues = true

Auto-delete head branches after merge (default: off, matching GitHub)

delete_branch_on_merge = false

Merge strategies (all enabled by default, matching GitHub)

Set allow_merge_commit = false for squash-only workflows

allow_squash_merge = true allow_merge_commit = true allow_rebase_merge = true

Whether a plain create leaves an initialized README in the new repo.

false (default): the repo still gets a default branch (needed for branch

protection), but the auto-generated README.md is removed afterward.

true: keep the initialized README.

(Ignored for --local/--from, which always push your own history instead.)

auto_init = false

[actions]

Which actions are allowed to run: all | local_only | selected

allowed_actions = selected

When allowed_actions = selected, control which external actions are permitted:

github_owned_allowed = true # actions maintained by GitHub (e.g. actions/checkout) verified_allowed = true # actions from Marketplace verified creators

patterns_allowed = myorg/* # comma-separated allowlist (wildcards OK)

Principle of least privilege: read-only by default

Options: read | write

default_workflow_permissions = read

Prevent Actions from self-approving pull requests

can_approve_pull_request_reviews = false

Require workflows to pin actions to a specific commit SHA instead of a mutable tag

sha_pinning_required = true

[branch_protection]

Applied to public repos on any plan, and private repos on paid plans.

Branch to protect

protected_branch = main

Require a pull request before merging

require_pull_request = true

Number of approvals required

required_approving_reviews = 1

Dismiss existing approvals when new commits are pushed

dismiss_stale_reviews = true

Require all review comments to be resolved before merging

require_conversation_resolution = true

Do not enforce rules on administrators

false = repo owner can still push directly (needed for --from mirror workflow)

enforce_admins = false

Block force-pushes

allow_force_pushes = false

Block branch deletion

allow_deletions = false

Use the Rulesets API (default) instead of the legacy classic branch-protection

path. A single ruleset covers all configured branches, supports bypass actors,

and is GitHub's forward direction (new rule types are Rulesets-only). Set false

to fall back to the classic per-branch API, which is kept for one release cycle.

use_rulesets = true

[tag_protection]

Immutable tags via Rulesets API.

Only works on public repos or paid GitHub plans (same restriction as branch protection).

Glob pattern(s) for tags to protect — comma-separated.

protected_tags = *

Prevent deletion of matching tags (git tag -d / git push --delete)

prevent_tag_deletion = true

Prevent rewriting matching tags (git tag -f / force-push)

prevent_tag_update = true

[security]

Enable Dependabot vulnerability alerts

enable_dependabot_alerts = true

Auto-open PRs to fix vulnerable dependencies

enable_dependabot_security_updates = true

Let security researchers report vulnerabilities privately

enable_private_vulnerability_reporting = true

Block commits that contain supported secrets

enable_secret_scanning_push_protection = true

Note: The following features have no REST API and must be configured via UI or dependabot.yml:

- Grouped security updates: use dependabot.yml groups with applies-to: security-updates

- Automatic dependency submission: enable via repository settings UI

- Dependency graph: automatic for public repos; enable via UI for private repos

[pre_flight_scan] scan_for_secrets = true scan_for_emails = true scan_for_todos = true

Flag files larger than this threshold

max_file_size_mb = 100

Scan git history for email addresses (requires scan_for_emails = true)

scan_email_history = true

Scanner selection: auto | native | docker | off

auto = try native truffleHog, fall back to container (podman/docker), then regex

native = native PATH only

docker = container only

off = regex only

trufflehog_mode = auto

Flag AI context files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) as critical findings.

warn_ai_context_files = true

Literal strings to flag as critical findings (case-insensitive).

Comma-separated, or one per line with continuation indentation.

banned_strings = secret

password

credential

Exclude files/directories from all scan checks (regex patterns, comma/newline separated).

Passed to truffleHog via --exclude-paths as well as applied to the regex walk.

scan_exclude_paths = docs/api.github.com.json

tests/fixtures/

Suppress email findings for specific addresses or entire domains (case-insensitive).

Entries starting with @ match all emails at that domain; otherwise exact address match.

exclude_emails = [email protected], [email protected], @example.com

[git_transport]

How git push/clone authenticates when using --local or --from: auto | user_creds | token

auto — use your own git credentials (SSH key or credential helper) when a

path exists; fall back to pushing over HTTPS with the API token in

the URL only when there is no SSH setup and no credential helper

(e.g. CI with just GITHUB_TOKEN). (default)

user_creds — never use the API token for git. Pushes with your own credentials

only; this avoids needing the workflow token scope to push

.github/workflows files.

token — always push over HTTPS with the API token in the URL. For CI where

the token was granted the workflow scope intentionally.

mode = auto

Архитектура плагинов

Каждая категория настроек представляет собой самодостаточный класс плагина (gh_safe_repo/plugins/). Каждый плагин:

1. Получает текущее состояние из GitHub API
2. Сравнивает с желаемым состоянием из конфига
3. Возвращает Plan (список объектов Change: ADD / UPDATE / DELETE / SKIP)
4. Применяет только реальные изменения — никаких вызовов API для холостых операций

Это означает, что режим аудита и режим создания используют один и тот же путь планирования/применения. Единственное отличие — получается ли текущее состояние из существующего репозитория или предполагается, что оно соответствует настройкам GitHub по умолчанию.

Аутентификация

API-вызовы разрешают токен в следующем порядке:

1. Переменная окружения GITHUB_TOKEN — позволяет нацелиться на определённую учётную запись без переключения активного сеанса gh (и это единственные учётные данные, необходимые в CI)
2. gh auth token — то, что настроено с помощью gh auth login
3. Ошибка, если ни одно из них недоступно

Токены передаются дочерним процессам gh api как GH_TOKEN в окружении подпроцесса и никогда не логируются.

Git-операции (--local / --from push и clone) по умолчанию используют ваши собственные учётные данные git — SSH-ключ или помощник ввода учётных данных, а не токен API. В средах, где нет ни того, ни другого (например, CI только с GITHUB_TOKEN), инструмент понижает уровень до отправки по HTTPS с токеном в URL; настройка конфига [git_transport] mode управляет этим (см. справочник по конфигурации). URL-адреса, содержащие токен, никогда не записываются в .git/config вашего репозитория и скрыты из всего вывода.

Подход к API

Все вызовы GitHub API выполняются через gh api с помощью subprocess. Это полностью выносит аутентификацию в gh CLI — никакого кода управления токенами, OAuth-потока, привязки к версии PyGithub. Тела JSON-запросов передаются через --input - (stdin), а не через флаги --field.

Разработка```bash

Clone and set up

git clone https://github.com/your-username/gh-safe-repo cd gh-safe-repo uv sync # creates .venv, installs pytest

Run tests

uv run pytest tests/ -v

Run the tool directly (without installing)

./gh-safe-repo create <owner/repo> --dry-run

Install globally (picks up the current source)

uv tool install .

См. gh_safe_repo/README.md для карты модулей, архитектуры плагинов и руководства по добавлению новых настроек.

Политика зависимостей

Нет зависимостей времени выполнения. Всё использует стандартную библиотеку Python (argparse, configparser, subprocess, json, re). Не добавляйте сторонние пакеты без обсуждения.

pytest — единственная зависимость для разработки, объявленная как UV-native запись [dependency-groups] в pyproject.toml.

Предшествующие проекты

Эти проекты были изучены при проектировании и повлияли на архитектуру gh-safe-repo. Это отдельные инструменты с разной областью применения и моделями пользователей — см. docs/LEARNINGS.md для подробных технических заметок о том, как были адаптированы шаблоны.

• github/safe-settings — Приложение GitHub уровня организации (Node.js/Probot), которое применяет настройки репозитория из центральной конфигурации. Источник паттерна архитектуры плагинов (один класс на категорию настроек, fetch → diff → apply) и подхода сравнения mergeDeep.

• repository-settings/app — Более простой вариант safe-settings для каждого репозитория, также на Node.js/Probot. Предоставил более чистый эталон для базового паттерна плагина Diffable.

• nicholasgasior/gh-repo-settings — Расширение для CLI, написанное на Go с рабочим процессом plan/apply. Основное вдохновение для паттерна обёртки подпроцесса gh api и дизайна вывода плана в режиме пробного запуска.