यह 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 के लिए, मालिक (owner) आपके प्रमाणित GitHub खाते के विरुद्ध मान्य किया जाता है ताकि मल्टी-अकाउंट सिस्टम पर गलतियों से बचा जा सके। fix के लिए, इसके बजाय लक्ष्य रिपो पर व्यवस्थापक (admin) अनुमतियाँ आवश्यक हैं, जिससे आप उन रिपो को ठीक कर सकते हैं जो संगठनों या अन्य खातों के स्वामित्व में हैं जहाँ आपके पास व्यवस्थापक पहुँच है।

create — एक नई रिपो बनाएँ

एक सादा create (बिना --local/--from) रिपो को आरंभ करता है ताकि ब्रैंच प्रोटेक्शन के लिए एक डिफ़ॉल्ट ब्रैंच मौजूद रहे, फिर ऑटो-जनरेटेड README.md को हटा देता है ताकि नई रिपो साफ़ शुरू हो। README को बनाए रखने के लिए कॉन्फ़िग में auto_init = true सेट करें। --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 } }

Fix mode:

1. GitHub API के माध्यम से प्रत्येक सेटिंग का वर्तमान मान प्राप्त करता है
2. वांछित सुरक्षित डिफ़ॉल्ट मानों से तुलना करता है
3. एक योजना तालिका दिखाता है जिसमें बदली गई सेटिंग्स के लिए UPDATE और उन सेटिंग्स के लिए SKIP दिखाया जाता है जो पहले से वांछित मान पर हैं (no-op पहचान — यह कभी भी 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. github.com के लिए आपके git क्रेडेंशियल की पहले से जाँच की जाती है (SSH प्रोब जब gh config get git_protocol ssh हो; HTTPS विश्वसनीय है), इसलिए गुम कुंजी किसी भी रेपो बनने से पहले तुरंत विफल हो जाती है
2. प्री-फ़्लाइट सुरक्षा स्कैनर स्थानीय निर्देशिका पर सीधे चलता है (क्लोन की आवश्यकता नहीं)
3. आप निष्कर्षों की समीक्षा करते हैं और पुष्टि करते हैं (या रद्द करते हैं)
4. एक नया रेपो बनाया जाता है, और क्रियाएँ अनुमतियाँ और सुरक्षा सेटिंग्स लागू की जाती हैं
5. पूरा इतिहास push --all --tags (सभी शाखाएँ और टैग) के साथ पुश किया जाता है
6. शाखा और टैग सुरक्षा लागू की जाती है (कोड पुश के बाद, ताकि लक्ष्य शाखा मौजूद हो)
7. origin मूल स्थानीय रेपो में जोड़ा जाता है जो नए GitHub URL की ओर इंगित करता है, और वर्तमान शाखा का अपस्ट्रीम ट्रैकिंग कॉन्फ़िगर किया जाता है — ताकि git push और git pull बिना अतिरिक्त सेटअप के तुरंत काम करें।

--local और --from दोनों निजी और सार्वजनिक रेपो के लिए काम करते हैं। ये परस्पर अनन्य हैं।

स्थानीय डिफ़ॉल्ट शाखा (via 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. PATH पर truffleHog v3 — trufflehog --version चलाता है, सत्यापित करता है कि यह v3 है, और इसका उपयोग करता है। v2 इंस्टॉल या अपरिचित संस्करण एक चेतावनी प्रिंट करता है और चरण 2 पर जाता है।
2. podman या docker — यदि कोई मूल truffleHog नहीं मिलता है, तो स्कैनर podman run या docker run का उपयोग करके एक कंटेनर (ghcr.io/trufflesecurity/trufflehog:latest) में truffleHog चलाता है, स्कैन पथ को उसी पूर्ण पथ पर केवल-पढ़ने के लिए माउंट करता है ताकि JSON आउटपुट पथ मूल रन के समान हों।
3. Regex फ़ॉलबैक — यदि न तो मूल इंस्टॉल और न ही कंटेनर रनटाइम उपलब्ध है, तो एक चेतावनी प्रिंट होती है और इसके बजाय regex स्कैनर चलता है। यह ईमेल और TODO के लिए truffleHog के अतिरिक्त हमेशा चलता है, और अकेले key-ID पैटर्न को पकड़ता है जिन्हें truffleHog जानबूझकर छोड़ देता है (truffleHog को फ़ाइंडिंग फ़्लैग करने से पहले क्रेडेंशियल जोड़ी के दोनों हिस्सों की आवश्यकता होती है, जैसे AWS Key ID और Secret Access Key)।

चयनित स्कैनर "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 टाइप करें।
• कोई निष्कर्ष नहीं: स्कैन चुपचाप पूर्ण होता है और वर्कफ़्लो जारी रहता है।

गुप्त जानकारी आउटपुट में संपादित (redact) की जाती है। ईमेल पते और TODOs मिलान वाली पंक्ति दिखाते हैं।

स्कैन कवरेज

बिल्ड-आर्टिफैक्ट निर्देशिकाएँ (node_modules, __pycache__, .venv, venv, dist, build) स्कैन को तेज़ रखने के लिए डिफ़ॉल्ट रूप से छोड़ दी जाती हैं। Git रिपॉजिटरी में, यह छोड़ना सशर्त है: किसी निर्देशिका को हटाने से पहले, स्कैनर यह जाँचने के लिए git ls-files -- <dir> चलाता है कि अंदर कोई फ़ाइल ट्रैक की गई है या नहीं। यदि वे हैं, तो निर्देशिका सामान्य रूप से स्कैन की जाती है।

इसका मतलब है कि प्रतिबद्ध (committed) node_modules या dist ट्री — असामान्य, लेकिन होते हैं — चुपचाप नहीं छोड़े जाते। अपरिवर्तित (uncommitted) निर्देशिकाएँ (सामान्य मामला) पहले की तरह छोड़ी जाती रहती हैं।

जब क्लोन किए गए स्रोत रिपॉजिटरी में SKIP_DIRS उपनिर्देशिकाएँ पाई जाती हैं, तब भी एक चेतावनी मुद्रित की जाती है, क्योंकि उनकी उपस्थिति यह संकेत दे सकती है कि अपेक्षा से अधिक सामग्री प्रतिबद्ध है।

गलत सकारात्मक (false positives) को दबाना

दो कॉन्फ़िग कुंजियाँ आपको संपूर्ण जाँच श्रेणियों को अक्षम किए बिना ज्ञात-सुरक्षित निष्कर्षों को दबाने की अनुमति देती हैं।

scan_exclude_paths — फ़ाइलों या निर्देशिकाओं को पूरी तरह से छोड़ें। मान नई पंक्ति/अल्पविराम से अलग किए गए regex पैटर्न हैं जो सापेक्ष फ़ाइल पथ से मिलान किए जाते हैं। एक मिलान वाली फ़ाइल प्रत्येक जाँच से बाहर रखी जाती है: गुप्त जानकारी, ईमेल, TODOs, बड़ी फ़ाइलें, और AI संदर्भ फ़ाइल का पता लगाना। वही पैटर्न --exclude-paths के माध्यम से truffleHog को भी पास किए जाते हैं, ताकि कोई भी स्कैनर इंजन सक्रिय हो, कवरेज सुसंगत रहे।```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_TOKEN के रूप में चाइल्ड gh api प्रक्रियाओं को पास किया जाता है और कभी लॉग नहीं किया जाता है।

Git ऑपरेशन (--local / --from push और clone) डिफ़ॉल्ट रूप से API टोकन का नहीं, बल्कि आपके अपने git क्रेडेंशियल — SSH कुंजी या क्रेडेंशियल हेल्पर — का उपयोग करते हैं। ऐसे वातावरण में जहां कोई भी नहीं है (जैसे केवल GITHUB_TOKEN के साथ CI), उपकरण URL में टोकन के साथ HTTPS पर पुश करने पर वापस आ जाता है; [git_transport] mode कॉन्फ़िग सेटिंग इसे नियंत्रित करती है (कॉन्फ़िगरेशन संदर्भ देखें)। टोकन-असर वाले URL कभी भी आपके रेपो के .git/config में नहीं लिखे जाते हैं और सभी आउटपुट से संपादित किए जाते हैं।

API दृष्टिकोण

सभी GitHub API कॉल subprocess के माध्यम से gh api से होकर जाते हैं। यह प्रमाणीकरण को पूरी तरह से 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 देखें जहां मॉड्यूल मैप, प्लगइन आर्किटेक्चर और नई सेटिंग्स जोड़ने का मार्गदर्शन दिया गया है।

निर्भरता नीति

कोई रनटाइम निर्भरता नहीं है। सब कुछ पायथन मानक लाइब्रेरी (argparse, configparser, subprocess, json, re) का उपयोग करता है। चर्चा के बिना तृतीय-पक्ष पैकेज न जोड़ें।

pytest एकमात्र डेव निर्भरता है, जिसे pyproject.toml में UV-मूल [dependency-groups] प्रविष्टि के रूप में घोषित किया गया है।

पूर्व कला

डिज़ाइन के दौरान इन परियोजनाओं का अध्ययन किया गया और इन्होंने 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 — Go में लिखा गया CLI एक्सटेंशन जिसमें plan/apply वर्कफ़्लो है। gh api सबप्रोसेस रैपर पैटर्न और ड्राई-रन प्लान आउटपुट डिज़ाइन के लिए प्राथमिक प्रेरणा।