gh-safe-repo

إنشاء مستودعات GitHub مع إعدادات افتراضية آمنة تُطبق تلقائيًا. يستبدل قائمة التحقق من الإعدادات بعد الإنشاء التي تستغرق خمس دقائق بأمر واحد.``` gh-safe-repo create <owner/repo>

حماية الفرع، العلامات غير القابلة للتغيير، Dependabot، صلاحيات الإجراءات المقيدة، فحص الأسرار مع حماية الدفع، وتعطيل الويكي والمشاريع — كلها تم تكوينها قبل كتابة أول سطر من الكود الخاص بك.

gh-safe-repo قيد التطوير النشط. يعمل بشكل جيد لحالة الاستخدام المتمثلة في إنشاء مستودع جديد بإعدادات افتراضية آمنة. أعمل على تحسين خيارات واجهة سطر الأوامر لتتوافق بشكل أفضل مع توقعات المستخدمين. توقع تغييرات جوهرية حتى نصل إلى نقطة أقوم فيها بإصدار الإصدارات وتكون التكامل المستمر/النشر المستمر مستقرة. ✌️

---

## جدول المحتويات

- [لماذا](#why)
- [ما الذي يغيره](#what-it-changes)
- [المتطلبات](#requirements)
- [التثبيت](#installation)
- [بدء سريع](#quick-start)
- [مرجع واجهة سطر الأوامر](#cli-reference)
- [مخرجات التشغيل التجريبي / الخطة](#dry-run--plan-output)
- [وضع الإصلاح (تدقيق المستودعات الموجودة)](#fix-mode-audit-existing-repos)
- [نسخ المستودعات (`--from`)](#mirroring-repos---from)
- [إنشاء مستودع من دليل محلي (`--local`)](#creating-a-repo-from-a-local-directory---local)
- [ماسح الأمان قبل التشغيل](#pre-flight-security-scanner)
  - [فحص مستقل](#standalone-scan)
  - [إخفاء النتائج الإيجابية الكاذبة](#suppressing-false-positives)
- [التكوين](#configuration)
- [قيود خطة GitHub](#github-plan-limitations)
- [كيف يعمل](#how-it-works)
- [التطوير](#development)

---

## لماذا

إعدادات المستودع الافتراضية في GitHub محسّنة من أجل سهولة الاكتشاف والمرونة، وليس الأمان. كل مستودع جديد يأتي مع:

- تمكين الويكي والمشاريع (سطح هجوم، حتى لو لم يتم استخدامها)
- السماح بعمليات الدمج (تاريخ فوضوي، لكن ليس القلق الرئيسي)
- لا توجد حماية للفرع (أي شخص لديه صلاحيات كتابة يمكنه الدفع مباشرة إلى `main`)
- لا توجد تنبيهات Dependabot
- إجراءات GitHub بصلاحيات كتابة إلى المستودع
- الإجراءات مسموح لها بالموافقة على طلبات السحب

إصلاح كل هذا يدويًا يستغرق دقائق لكل مستودع ويسهل نسيانه. يطبق `gh-safe-repo` مجموعة افتراضية رأيوية ولكنها عملية في دفعة واحدة، مع معاينة للخطة حتى تعرف بالضبط ما الذي سيتغير قبل حدوث أي شيء.

---

## ما الذي يغيره

### إعدادات المستودع

| الإعداد | الافتراضي في GitHub | الافتراضي الآمن | ملاحظات |
|---|---|---|---|
| الرؤية | عام | **خاص** | استخدم `--public` للتجاوز |
| الويكي | ممكّن | **معطل** | |
| المشاريع | ممكّن | **معطل** | |
| المشكلات | ممكّن | ممكّن | |
| حذف الفرع عند الدمج | غير مفعل | غير مفعل | اضبط على `true` في التكوين للتنظيف التلقائي |
| السماح بعمليات دمج الدمج | مفعل | مفعل | اضبط على `false` في التكوين لـ squash-only |
| السماح بعملية دمج squash | مفعل | مفعل | |
| السماح بعملية دمج rebase | مفعل | مفعل | |

### إجراءات GitHub

| الإعداد | الافتراضي في GitHub | الافتراضي الآمن |
|---|---|---|
| الإجراءات المسموح بها | الكل | **محدد** (المملوكة من GitHub + المنشئين الموثوقين؛ قابل للتخصيص) |
| صلاحيات سير العمل الافتراضية | قراءة/كتابة | **للقراءة فقط** |
| يمكن للإجراءات الموافقة على طلبات السحب | نعم | **لا** |
| طلب تثبيت SHA | لا | **نعم** (يجب أن تثبت سير العمل الإجراءات إلى SHA commit، وليس علامة قابلة للتغيير) |
| سياسة الموافقة على طلبات سحب الفروع المتفرعة | المساهمون الجدد لأول مرة في GitHub | **جميع المساهمين الخارجيين** — طلب الموافقة قبل تشغيل CI لسير العمل الخاص بطلبات السحب المتفرعة. الخيارات: حسابات GitHub الجديدة فقط (الإعداد الافتراضي لـ GitHub)، المساهمون الجدد في المستودع، أو جميع طلبات السحب المتفرعة (الأكثر أمانًا) |

### حماية الفرع (المستودعات العامة، أو أي مستودع على خطة مدفوعة)

| القاعدة | القيمة |
|---|---|
| طلب طلب سحب قبل الدمج | نعم |
| عدد المراجعات المعتمدة المطلوبة | 1 |
| تجاهل المراجعات القديمة عند الدفع | نعم |
| طلب حل المحادثات | نعم |
| السماح بدفع القوي | لا |
| السماح بحذف الفرع | لا |
| تطبيق على المسؤولين | لا (يسمح لأدوات المالك بالدفع) |

يتم تطبيق حماية الفرع عبر **واجهة برمجة تطبيقات Rulesets** افتراضيًا (`use_rulesets = true`): قاعدة واحدة `gh-safe-repo defaults` تغطي كل فرع مُكوّن وتعبر عن "يمكن للمسؤولين التجاوز" من خلال ممثل تجاوز بدلاً من علم `enforce_admins` الكلاسيكي. اضبط `use_rulesets = false` للمسار الكلاسيكي القديم لكل فرع (يُحتفظ به لدورة إصدار واحدة).

**ترحيل مستودع موجود من الحماية الكلاسيكية:** إذا اكتشف `fix` حماية فرع كلاسيكية على مستودع، فإنه يرفض تحويلها إلى قاعدة ruleset ما لم تمرر `--migrate-branch-protection`. القواعد الكلاسيكية فقط ليس لها ما يعادلها في قاعدة ruleset التي تبنيها هذه الأداة وسيتم إسقاطها بصمت خلاف ذلك — الفجوات المعروفة:

- `required_status_checks` — فحوصات CI المطلوبة ليست نموذجية في جسم قاعدة ruleset.
- `restrictions` (قيود الدفع حسب المستخدم/الفريق) — تتعامل Rulesets مع هذا بشكل مختلف عبر ممثلين تجاوز؛ ليست خريطة 1:1.
- الاختلاف لكل فرع — لا يمكن لقاعدة ruleset ذات شرط مشترك واحد التعبير عن قواعد مختلفة لـ `master` مقابل `main`.

مع العلم، يقوم `fix` بإنشاء/تحديث قاعدة ruleset ثم يحذف الحماية الكلاسيكية على كل فرع بحيث لا تتراكم الطبقتان.

### حماية العلامات (المستودعات العامة، أو أي مستودع على خطة مدفوعة)

تنشئ حماية العلامات قاعدة Ruleset في GitHub تستهدف جميع العلامات (`*` افتراضيًا، قابل للتكوين عبر `protected_tags`). يتم فرض القواعد التالية:

| قاعدة قاعدة Ruleset | مفروضة؟ | ملاحظات |
|---|---|---|
| تقييد الإنشاءات | لا | |
| **تقييد التحديثات** | **نعم** | يمنع إعادة كتابة / دفع القوي للعلامات |
| **تقييد الحذف** | **نعم** | يمنع `git push --delete` للعلامات |
| طلب تاريخ خطي | لا | |
| طلب نجاح النشر | لا | |
| طلب التوقيع على الالتزامات | لا | |
| طلب اجتياز فحوصات الحالة | لا | |
| حظر دفع القوي | لا | |

مسؤولو المستودع موجودون في قائمة التجاوز (متسق مع الإعداد الافتراضي `enforce_admins = false` لحماية الفرع). يعمل فقط على المستودعات العامة أو خطط GitHub المدفوعة (نفس القيد مثل حماية الفرع). المستودعات الخاصة ذات الخطة المجانية سترى هذا مُتجاهلاً في مخرجات الخطة.

### الأمان

| الميزة | السلوك |
|---|---|
| تنبيهات Dependabot | ممكّنة (المستودعات العامة / الخطط المدفوعة) |
| تحديثات أمان Dependabot | ممكّنة (تفتح تلقائيًا طلبات سحب للتبعيات الضعيفة) |
| فحص الأسرار | تلقائي على المستودعات العامة؛ ممكّن على الخطط الخاصة المدفوعة |
| حماية الدفع | ممكّنة (تمنع الالتزامات التي تحتوي على أسرار مدعومة) |
| الإبلاغ عن الثغرات الخاصة | ممكّن (يسمح لباحثي الأمن بالإبلاغ بشكل خاص) |
| رسم بياني للتبعيات | تلقائي على المستودعات العامة؛ لا توجد واجهة برمجة تطبيقات REST للخاص (واجهة مستخدم فقط) |

---

## المتطلبات

- Python 3.8+
- [`gh` CLI](https://cli.github.com/) مثبت ومصدق (`gh auth login`)، **أو** `GITHUB_TOKEN` مضبوط في بيئتك
- لـ `--local` / `--from` (التي تدفع أو تستنسخ الكود): يجب إعداد بيانات اعتماد git الخاصة بك — إما مفتاح SSH محمل في `ssh-agent` (عندما يكون `gh config get git_protocol` هو `ssh`) أو مساعد بيانات اعتماد HTTPS (`gh auth setup-git` يكوّن واحدًا تلقائيًا). لا يتم استخدام رمز OAuth لـ git push، لذا يتم دفع ملفات سير العمل (`.github/workflows/*`) دون الحاجة إلى نطاق `workflow` في OAuth.
- [`uv`](https://docs.astral.sh/uv/) للتثبيت من المصدر (موصى به)
- `truffleHog` v3 (اختياري — يستخدمه الماسح قبل التشغيل؛ يتم اكتشافه تلقائيًا من PATH، أو يعمل عبر podman/docker؛ يتراجع إلى التعبيرات العادية إذا لم يكن أي منهما متاحًا)

---

## التثبيت

### من المصدر باستخدام uv (موصى به)```bash
git clone https://github.com/your-username/gh-safe-repo
cd gh-safe-repo
uv tool install .

هذا يقوم بتثبيت 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
gh-safe-repo --help

البدء السريع```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

## مرجع CLI```
gh-safe-repo create <owner/repo> [OPTIONS]
gh-safe-repo fix <owner/repo> [OPTIONS]
gh-safe-repo scan <path> [OPTIONS]

تتطلب جميع الأوامر التي تتفاعل مع 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` نشطًا، يتم كتابة الخطة إلى stdout ككائن JSON وتذهب جميع الرسائل الأخرى (التقدم، التحذيرات، تذييل "Dry run") إلى stderr، بحيث يكون الإخراج نظيفًا للأنابيب أو البرمجة النصية.```
$ gh-safe-repo create <owner/repo> --dry-run

  Plan for my-project (private)

  Category            Action  Setting                          Value
  ──────────────────────────────────────────────────────────────────
  Repository          ADD     repository                       my-project (private)
  Repository          ADD     has_wiki                         false
  Repository          ADD     has_projects                     false
  Actions             ADD     default_workflow_permissions     read
  Actions             ADD     can_approve_pull_request_reviews false
  Branch Protection   SKIP    branch_protection                Not available for private repos on free plan
  Security            SKIP    dependabot_alerts                Not available for private repos on free plan
  1 setting skipped (GitHub plan limitation).
  Dry run — no changes made.

ألوان الإجراءات:

مخرجات 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 } }

`summary` يتضمن فقط الأنواع الموجودة في الخطة. يجب على المستهلكين استخدام `.get("delete", 0)` إلخ. بدلاً من افتراض وجود جميع المفاتيح الأربعة.

---

## وضع الإصلاح (تدقيق المستودعات الحالية)

يقارن `fix` الإعدادات الحالية لمستودع موجود مع الإعدادات الافتراضية الآمنة ويطبق أي تصحيحات. لا يوجد فحص للأسرار — `fix` هو فقط حول إعدادات المستودع.```bash
# See what's out of compliance
gh-safe-repo fix <owner/repo> --dry-run

# Apply missing safe defaults
gh-safe-repo fix <owner/repo>

# Apply without confirmation prompt (scripting/batch use)
gh-safe-repo fix <owner/repo> --yes

وضع الإصلاح:

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. يتم استنساخ المستودع المصدر محليًا (استنساخ كامل، بدون `--depth`، حتى يتمكن truffleHog من تجاوز سجل الالتزامات الكامل)
3. يتم تشغيل [الماسح الضوئي الأمني الأولي](#pre-flight-security-scanner) على الاستنساخ المحلي
4. تقوم بمراجعة النتائج والتأكيد (أو الإنهاء)
5. يتم إنشاء مستودع جديد (خاص افتراضيًا، أو عام مع `--public`)
6. يتم تطبيق أذونات الإجراءات والإعدادات الأمنية (Dependabot، فحص الأسرار، حماية الدفع)
7. يتم عكس السجل الكامل: `git clone --mirror` + `git push --mirror`
8. يتم تطبيق حماية الفرع والعلامة (بعد دفع الكود، حتى يكون الفرع الهدف موجودًا)

إذا كشف الفحص عن مشكلة وقمت بالإنهاء، فلن يتم نسخ أي كود إلى GitHub.

> **ملاحظة:** يستخدم `--from` تنسيق `owner/repo` لكل من المصدر والوجهة.

---

## إنشاء مستودع من دليل محلي (`--local`)

`--local PATH` هو النظير المحلي إلى GitHub لـ `--from`. يقوم بإنشاء مستودع GitHub جديد ويدفع الكود من مستودع git محلي. يجب أن يكون `PATH` مستودع git مهيأ (`git init` أو استنساخ).```bash
gh-safe-repo create <owner/repo> --local ~/projects/myapp
gh-safe-repo create <owner/repo> --local ~/projects/myapp --public

ما يحدث، بالترتيب:

1. يتم التحقق من بيانات اعتماد git الخاصة بك لـ github.com مقدمًا (فحص SSH عندما يكون gh config get git_protocol هو ssh؛ ويتم الوثوق بـ HTTPS)، لذا فإن المفتاح المفقود يفشل بسرعة قبل إنشاء أي مستودع
2. يعمل ماسح الأمان الأولي على الدليل المحلي مباشرة (لا حاجة للاستنساخ)
3. تقوم بمراجعة النتائج وتأكيدها (أو الإلغاء)
4. يتم إنشاء مستودع جديد، وتطبيق أذونات الإجراءات وإعدادات الأمان
5. يتم دفع السجل الكامل باستخدام push --all --tags (جميع الفروع والوسوم)
6. يتم تطبيق حماية الفرع والوسم (بعد دفع الكود، بحيث يكون الفرع الهدف موجودًا)
7. تتم إضافة origin إلى المستودع المحلي الأصلي مشيرًا إلى رابط 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

رمز الخروج هو `0` إذا لم يتم العثور على نتائج حرجة، و `1` إذا تم العثور على نتائج حرجة — بحيث يتكامل بسلاسة مع الأوامر الأخرى:```bash
gh-safe-repo scan . && git push

التكوين الكامل لـ [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. البديل Regex — إذا لم يكن التثبيت المحلي ولا بيئة الحاويات متاحة، يتم طباعة تحذير ويتم تشغيل ماسح regex الضوئي بدلاً من ذلك. كما يعمل دائماً بالإضافة إلى truffleHog للبريد الإلكتروني و TODOs، ويلتقط أنماط معرف المفتاح الفردي التي يتجاوزها truffleHog عمداً (يتطلب truffleHog كلا نصفي زوج الاعتماد، مثلاً معرف مفتاح AWS و مفتاح الوصول السري، قبل الإبلاغ عن اكتشاف).

يظهر الماسح الضوئي المختار في رأس "تشغيل الفحص الأمني قبل الرحلة..." وفي إدخال 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)

متغيرات البيئة التي يحترمها مسار الحاوية: `CONTAINER_RUNTIME` لتجاوز اختيار وقت التشغيل (مثل `CONTAINER_RUNTIME=docker`)، و`TRUFFLEHOG_IMAGE` لتثبيت علامة صورة محددة.

### تشغيل truffleHog عبر podman أو Docker (بدون تثبيت محلي)

لا يلزم إعداد يدوي. يكتشف `gh-safe-repo` podman أو docker تلقائيًا (الخطوة 2 أعلاه) ويشغل truffleHog في حاوية مع عمليات تحميل الحجم الصحيحة. يتم احترام متغيرات البيئة `CONTAINER_RUNTIME` و`TRUFFLEHOG_IMAGE`.

يتم توفير غلاف شل (`tools/trufflehog`) و`Containerfile` لبناء صورة محلية مثبتة في [`tools/`](https://github.com/ariesq/gh-safe-repo/blob/HEAD/tools/README.md) للمستخدمين الذين يرغبون في توفر truffleHog المستند إلى الحاوية على مستوى النظام، أو الذين يحتاجون إلى صورة معزولة (air-gapped).

### المراجعة التفاعلية```
Pre-flight scan: my-private-project

  CRITICAL  my_private_project/config.py:12  AWS Access Key ID
            [redacted]

  WARNING   my_private_project/setup.py:3    Email address
            author_email="[email protected]"

  1 critical finding, 1 warning.

  Critical findings detected. Continue anyway? [y/N]:

• النتائج الحرجة: الإعداد الافتراضي هو الإجهاض (N). يجب عليك كتابة y صراحةً للمتابعة.
• التحذيرات فقط: الإعداد الافتراضي هو المتابعة (Y). اضغط Enter للمتابعة أو اكتب n للإجهاض.
• لا نتائج: يكتمل الفحص بصمت وتستمر سير العمل.

يتم حذف الأسرار في المخرجات. تظهر عناوين البريد الإلكتروني والـ TODOs السطر المطابق.

تغطية الفحص

يتم تخطي أدلة القطع الأثرية للبناء (node_modules, __pycache__, .venv, venv, dist, build) افتراضيًا للحفاظ على سرعة الفحص. في مستودعات git، يكون هذا التخطي مشروطًا: قبل حذف دليل، يقوم الماسح بتشغيل git ls-files -- <dir> للتحقق مما إذا كانت أي ملفات بداخله متعقبة. إذا كانت كذلك، يتم فحص الدليل بشكل طبيعي.

هذا يعني أن أشجار node_modules أو dist الملتزمة — غير معتادة، ولكنها تحدث — لا يتم تفويتها بصمت. تستمر الأدلة غير الملتزمة (الحالة الطبيعية) في التخطي كما كان من قبل.

لا يزال يتم طباعة تحذير عند العثور على أدلة فرعية SKIP_DIRS في مستودع مصدر مستنسخ، لأن وجودها قد يشير إلى أن محتوى أكثر من المتوقع قد تم التزامه.

قمع النتائج الإيجابية الخاطئة

يسمح لك مفتاحا تكوين بقمع النتائج المعروفة بأنها آمنة دون تعطيل فئات الفحص بأكملها.

scan_exclude_paths — تخطي الملفات أو الأدلة بالكامل. القيم هي أنماط regex مفصولة بسطر جديد/فاصلة مطابقة لمسار الملف النسبي. يتم استبعاد الملف المطابق من كل فحص: الأسرار، رسائل البريد الإلكتروني، TODOs، الملفات الكبيرة، واكتشاف ملفات سياق الذكاء الاصطناعي. يتم أيضًا تمرير نفس الأنماط إلى 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/

**`exclude_emails`** — قم بإخفاء نتائج البريد الإلكتروني لعناوين أو نطاقات محددة. القيم مفصولة بأسطر جديدة أو فواصل، غير حساسة لحالة الأحرف. المدخلات التي تبدأ بـ `@` تطابق جميع رسائل البريد الإلكتروني في ذلك النطاق؛ وإلا يجب أن يطابق المدخل العنوان الكامل تمامًا. ينطبق على نتائج شجرة العمل وتاريخ git معًا.```ini
[pre_flight_scan]
# Suppress bot addresses and placeholder domains
exclude_emails = [email protected], [email protected], @example.com

تكوين الماسح الضوئي```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

عند العثور على سلاسل محظورة أو ملفات سياق الذكاء الاصطناعي، يقوم الماسح الضوئي بطباعة أمر `git filter-repo` جاهز للتشغيل لإزالتها من تاريخ المستودع المصدر قبل إعادة التشغيل.

---

## الإعدادات

يبحث `gh-safe-repo` عن الإعدادات بهذا الترتيب (أول تطابق يفوز):

1.  **`--config PATH`** — تجاوز صريح
2.  **`./gh-safe-repo.ini`** — دليل العمل الحالي
3.  **`$XDG_CONFIG_HOME/gh-safe-repo/gh-safe-repo.ini`** — الافتراضي هو `~/.config` عندما لا يتم تعيين `$XDG_CONFIG_HOME`

`--config` المجرد (بدون مسار) يتجاوز البحث عن الملف بالكامل ويستخدم الإعدادات الافتراضية المضمنة فقط.
جميع القيم لها إعدادات افتراضية آمنة — لا حاجة لملف إعدادات للبدء.

يتم تضمين مثال إعدادات مشروح بالكامل في المستودع باسم `gh-safe-repo.ini.example`. انسخه للبدء:```bash
# User-level config (XDG)
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/gh-safe-repo"
cp gh-safe-repo.ini.example "${XDG_CONFIG_HOME:-$HOME/.config}/gh-safe-repo/gh-safe-repo.ini"

# Or project-level config (current directory)
cp gh-safe-repo.ini.example ./gh-safe-repo.ini

مرجع التكوين الكامل```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

---

## قيود خطة GitHub

بعض الميزات متاحة فقط حسب رؤية المستودع وخطة GitHub الخاصة بك.

| الميزة | Free + Public | Free + Private | Pro/Team + Private |
|---|:---:|:---:|:---:|
| حماية الفرع / مجموعات القواعد | نعم | لا | نعم |
| حماية العلامات (مجموعات القواعد) | نعم | لا | نعم |
| تنبيهات Dependabot | نعم | لا | نعم |
| تحديثات الأمان من Dependabot | نعم | لا | نعم |
| فحص الأسرار | تلقائي | لا | نعم |
| حماية الدفع | نعم | لا | نعم |
| الإبلاغ الخاص عن الثغرات | نعم | نعم | نعم |
| رسم بياني للتبعيات | تلقائي | لا | نعم |

يكتشف `gh-safe-repo` مستوى خطتك ورؤية المستودع في وقت التشغيل. تظهر الميزات غير المتاحة كـ `SKIP` في مخرجات الخطة مع سبب واضح — لا تفشل الأداة بصمت.

---

## كيف يعمل```
gh-safe-repo create <owner/repo>
      │
      ├─ Parse owner/repo, validate owner matches authenticated user (create only)
      ├─ Load config (./gh-safe-repo.ini or $XDG_CONFIG_HOME/gh-safe-repo/gh-safe-repo.ini)
      ├─ Apply CLI flag overrides (--public, etc.)
      ├─ Authenticate via gh CLI or GITHUB_TOKEN
      ├─ GET /user → owner login + plan level  (single cached call)
      │
      ├─ Build plan (each plugin compares desired vs. current state)
      │   ├─ RepositoryPlugin  → repo creation + basic settings
      │   ├─ ActionsPlugin     → allowed actions, workflow permissions, SHA pinning
      │   ├─ BranchProtectionPlugin → Rulesets API (default; classic if use_rulesets = false)
      │   ├─ SecurityPlugin    → Dependabot, secret scanning, push protection, private vuln reporting
      │   └─ TagProtectionPlugin → immutable tags via Rulesets API
      │
      ├─ Print plan table
      │
      └─ Apply (unless --dry-run)
          ├─ POST /user/repos
          ├─ PATCH /repos/{owner}/{repo}       (settings)
          ├─ PUT  /repos/{owner}/{repo}/actions/permissions/workflow
          ├─ POST/PATCH /repos/{owner}/{repo}/rulesets  (branch protection; default)
          │   or PUT /repos/{owner}/{repo}/branches/main/protection (if use_rulesets = false)
          ├─ PUT  /repos/{owner}/{repo}/vulnerability-alerts
          ├─ PUT  /repos/{owner}/{repo}/automated-security-fixes
          ├─ PUT  /repos/{owner}/{repo}/private-vulnerability-reporting
          ├─ PATCH /repos/{owner}/{repo}  (security_and_analysis: push protection)
          ├─ POST /repos/{owner}/{repo}/rulesets  (tag protection ruleset)
          ├─ git clone --mirror + git push --mirror (if --from)
          └─ git clone <local> + git push --all --tags (if --local, git repo)
              or git init + add -A + commit + push (if --local, plain dir)

بنية الإضافات

كل فئة من الإعدادات هي فئة إضافة مستقلة بذاتها (gh_safe_repo/plugins/). كل إضافة:

1. تجلب الحالة الحالية من واجهة GitHub API
2. تقارنها بالحالة المرغوبة من الإعدادات
3. تعيد Plan (قائمة من كائنات Change: إضافة / تحديث / حذف / تخطي)
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 واستنساخ) تستخدم بيانات اعتماد Git الخاصة بك — مفتاح SSH أو مساعد بيانات الاعتماد — افتراضيًا، وليس رمز API. في البيئات التي لا تحتوي على أي منهما (مثل CI باستخدام GITHUB_TOKEN فقط)، ترجع الأداة إلى الدفع عبر HTTPS باستخدام الرمز المميز في عنوان URL؛ يُتحكم في هذا بواسطة إعداد [git_transport] mode (راجع مرجع الإعدادات). لا تتم كتابة عناوين URL التي تحمل رموزًا مميزة أبدًا في ملف .git/config الخاص بمستودعك ويتم حجبها من جميع المخرجات.

نهج API

جميع استدعاءات GitHub API تتم عبر gh api باستخدام subprocess. هذا يحافظ على المصادقة بالكامل داخل CLI gh — لا رمز إدارة الرمز المميز، لا تدفق OAuth، لا تثبيت إصدار PyGithub. يتم تمرير نصوص طلبات JSON عبر --input - (التيار القياسي)، وليس عبر علامات --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 .

انظر [`tests/README.md`](https://github.com/ariesq/gh-safe-repo/blob/HEAD/tests/README.md) للحصول على أوصاف ملفات الاختبار، واتفاقيات المحاكاة، وكيفية إضافة اختبارات جديدة.

### هيكل المشروع```
gh-safe-repo/
├── gh-safe-repo          # Thin launcher (entry point for direct use)
├── gh_safe_repo/         # Package — see gh_safe_repo/README.md for internals
│   ├── cli.py            # Subparser dispatch (create, fix, scan)
│   ├── commands/         # Subcommand implementations
│   │   ├── _common.py    # Shared helpers, CLIContext, plan formatting
│   │   ├── create.py     # create subcommand
│   │   ├── fix.py        # fix subcommand
│   │   └── scan.py       # scan subcommand
│   └── plugins/          # Settings plugins (one per category)
├── pyproject.toml        # Build config, entry points
├── gh-safe-repo.ini.example  # Fully annotated example config
└── tests/

أنظر إلى gh_safe_repo/README.md للحصول على خريطة الوحدة، وهندسة الإضافات، ودليل لإضافة إعدادات جديدة.

سياسة التبعيات

لا توجد تبعيات وقت التشغيل. كل شيء يستخدم مكتبة Python القياسية (argparse, configparser, subprocess, json, re). لا تقم بإضافة حزم طرف ثالث دون مناقشة.

pytest هي التبعية الوحيدة للتطوير، معلنة كمدخل [dependency-groups] أصلي لـ UV في pyproject.toml.

الأعمال السابقة

تمت دراسة هذه المشاريع أثناء التصميم وأثرت على بنية gh-safe-repo. إنها أدوات متميزة بنطاق ونماذج مستخدم مختلفة — راجع docs/LEARNINGS.md للحصول على ملاحظات فنية مفصلة حول كيفية تكييف الأنماط.

• github/safe-settings — تطبيق GitHub على مستوى المؤسسة (Node.js/Probot) يفرض إعدادات المستودع من تكوين مركزي. مصدر نمط هندسة الإضافات (فئة واحدة لكل فئة إعداد، جلب → فرق → تطبيق) ونهج المقارنة mergeDeep.

• repository-settings/app — متغير أبسط لكل مستودع من safe-settings، أيضًا Node.js/Probot. قدم مرجعًا أنظف لنمط الإضافة الأساسي Diffable.

• nicholasgasior/gh-repo-settings — امتداد لسطر الأوامر مكتوب بلغة Go مع سير عمل plan/apply. الإلهام الأساسي لنمط غلاف العملية الفرعية gh api وتصميم مخرجات خطة التشغيل الجاف.