gh-safe-repo

安全なデフォルト設定を自動適用してGitHubリポジトリを作成します。作成後の5分間の設定チェックリストを1つのコマンドに置き換えます。``` gh-safe-repo create <owner/repo>

Branch protection、immutable tags、Dependabot、制限されたActions権限、push protection付きのsecret scanning、無効化されたwikiとprojects — これらはすべて、最初のコードを書く前に設定されます。

gh-safe-repoは活発に開発中です。新しいリポジトリを安全なデフォルト設定で作成するユースケースには適しています。CLIオプションをユーザーの期待に沿うよう改良中です。リリースを実施し、CI/CDを確立するまでは、破壊的な変更がある可能性があります。✌️

---

## Table of Contents

- [なぜ](#why)
- [変更内容](#what-it-changes)
- [必要条件](#requirements)
- [インストール](#installation)
- [クイックスタート](#quick-start)
- [CLIリファレンス](#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のデフォルトのリポジトリ設定は、発見可能性と柔軟性のために最適化されており、セキュリティは考慮されていません。新しいリポジトリは、以下の設定で作成されます：

- WikiとProjectsが有効（未使用でも攻撃対象になる）
- マージコミットが許可（履歴が乱れるが、主な懸念ではない）
- ブランチ保護なし（書き込み権限のある人は誰でも`main`に直接プッシュ可能）
- Dependabotアラートなし
- リポジトリへの書き込み権限を持つGitHub Actions
- Actionsがプルリクエストを承認可能

これらを手動で修正するにはリポジトリごとに数分かかり、忘れがちです。`gh-safe-repo`は、意見が反映された実用的なデフォルト設定を一度に適用し、計画のプレビューで何が変更されるかを事前に確認できます。

---

## 変更内容

### リポジトリ設定

| 設定 | GitHubデフォルト | 安全なデフォルト | 備考 |
|---|---|---|---|
| 可視性 | Public | **Private** | `--public` で上書き可能 |
| Wiki | 有効 | **無効** | |
| Projects | 有効 | **無効** | |
| Issues | 有効 | 有効 | |
| マージ時にブランチを削除 | オフ | オフ | 自動クリーンアップには設定で`true`に設定 |
| マージコミットを許可 | オン | オン | スカッシュのみにするには設定で`false`に設定 |
| スカッシュマージを許可 | オン | オン | |
| リベースマージを許可 | オン | オン | |

### GitHub Actions

| 設定 | GitHubデフォルト | 安全なデフォルト |
|---|---|---|
| 許可されるアクション | すべて | **選択済み**（GitHub所有＋確認済み作成者；カスタマイズ可能） |
| デフォルトのワークフロー権限 | 読み取り/書き込み | **読み取り専用** |
| ActionsがPRを承認可能 | はい | **いいえ** |
| SHAピン留めを要求 | いいえ | **はい**（ワークフローはアクションをコミットSHAにピン留めする必要があり、可変タグは不可） |
| フォークPR承認ポリシー | GitHub初めてのコントリビューター | **すべての外部コントリビューター** — フォークPRのワークフローがCIを実行する前に承認が必要。オプション：GitHubアカウントのみ新規（GitHubデフォルト）、リポジトリ初めてのコントリビューター、またはすべてのフォークPR（最も安全） |

### ブランチ保護（パブリックリポジトリ、または有料プランのリポジトリ）

| ルール | 値 |
|---|---|
| マージ前にプルリクエストを要求 | はい |
| 必須の承認レビュー | 1 |
| プッシュ時に古いレビューを却下 | はい |
| 会話の解決を要求 | はい |
| フォースプッシュを許可 | いいえ |
| ブランチ削除を許可 | いいえ |
| 管理者に強制 | いいえ（オーナーツールのプッシュを許可） |

ブランチ保護は、デフォルトでは**Rulesets API**を介して適用されます（`use_rulesets = true`）：単一の`gh-safe-repo defaults`ルールセットがすべての設定済みブランチをカバーし、「管理者はバイパス可能」を従来の`enforce_admins`フラグではなくバイパスアクターで表現します。従来のクラシックなブランチごとのパスには`use_rulesets = false`を設定します（1リリースサイクル維持）。

**既存リポジトリのクラシック保護からの移行：** `fix`がリポジトリにクラシックブランチ保護を検出した場合、`--migrate-branch-protection`を指定しない限り、ルールセットへの変換を拒否します。クラシックのみのルールには、このツールが構築するルールセットに相当するものがないため、サイレントに削除されます。既知のギャップ：

- `required_status_checks` — 必須CIチェックはルールセット本体でモデル化されていません。
- `restrictions`（ユーザー/チームによるプッシュ制限）— Rulesetsはバイパスアクターを介して異なる方法でモデル化します。1:1のマッピングではありません。
- ブランチごとの差異 — 単一の共有条件ルールセットでは、`master`と`main`で異なるルールを表現できません。

このフラグを使用すると、`fix`はルールセットを作成/更新し、各ブランチのクラシック保護を削除して、2つのレイヤーが重ならないようにします。

### タグ保護（パブリックリポジトリ、または有料プランのリポジトリ）

タグ保護は、すべてのタグを対象とするGitHubルールセットを作成します（デフォルトは`*`、`protected_tags`で設定可能）。以下のルールが適用されます：

| ルールセットルール | 適用？ | 備考 |
|---|---|---|
| 作成の制限 | いいえ | |
| **更新の制限** | **はい** | タグの書き換え/フォースプッシュを防止 |
| **削除の制限** | **はい** | タグの `git push --delete` を防止 |
| 線形履歴を要求 | いいえ | |
| デプロイの成功を要求 | いいえ | |
| 署名付きコミットを要求 | いいえ | |
| ステータスチェックの合格を要求 | いいえ | |
| フォースプッシュをブロック | いいえ | |

リポジトリ管理者はバイパスリストに含まれます（ブランチ保護の`enforce_admins = false`デフォルトと一致）。パブリックリポジトリまたは有料GitHubプランでのみ機能します（ブランチ保護と同じ制限）。無料プランのプライベートリポジトリでは、プラン出力でスキップされます。

### セキュリティ

| 機能 | 動作 |
|---|---|
| Dependabotアラート | 有効（パブリックリポジトリ/有料プラン） |
| Dependabotセキュリティ更新 | 有効（脆弱性のある依存関係のPRを自動で開く） |
| シークレットスキャニング | パブリックリポジトリでは自動；プライベート有料プランでは有効 |
| プッシュ保護 | 有効（サポートされているシークレットを含むコミットをブロック） |
| プライベート脆弱性報告 | 有効（セキュリティ研究者が非公開で報告可能） |
| 依存関係グラフ | パブリックリポジトリでは自動；プライベートではREST APIなし（UIのみ） |

---

## 必要条件

- Python 3.8+
- `gh` CLIがインストールされ認証済み（`gh auth login`）、**または**環境変数`GITHUB_TOKEN`が設定されていること
- `--local` / `--from`（コードをプッシュまたはクローンする場合）の場合、通常のgit認証情報が設定されている必要があります。`gh config get git_protocol`が`ssh`の場合は`ssh-agent`にロードされたSSHキー、またはHTTPSクレデンシャルヘルパー（`gh auth setup-git`で自動設定）を使用します。OAuthトークンはgit pushには使用されないため、ワークフローファイル（`.github/workflows/*`）のプッシュにOAuthの`workflow`スコープは不要です。
- ソースからのインストールには`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を削除して、新しいリポジトリをクリーンな状態で開始します。代わりに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 オブジェクトとして stdout に書き込まれ、その他のメッセージ（進捗、警告、"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` には、プランに存在するタイプのみが含まれます。利用者は、4つのキーすべてが存在すると仮定するのではなく、`.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. `github.com` に対する git 認証情報が事前に検証されます（`gh config get git_protocol` が `ssh` の場合は SSH プローブによる確認、HTTPS は信頼されます）。そのため、キーが存在しない場合はリポジトリ作成前に迅速に失敗します。
2. ソースリポジトリがローカルにクローンされます（完全クローン、`--depth` は指定しないため、truffleHog が全コミット履歴を辿れます）。
3. ローカルクローンに対して[事前セキュリティスキャナー](#pre-flight-security-scanner)が実行されます。
4. あなたが結果を確認し、承認（または中断）します。
5. 新しいリポジトリが作成されます（デフォルトはプライベート、`--public` でパブリックになります）。
6. Actions の権限とセキュリティ設定が適用されます（Dependabot、シークレットスキャン、プッシュ保護）。
7. 完全な履歴がミラーリングされます: `git clone --mirror` + `git push --mirror`
8. ブランチとタグの保護が適用されます（コードプッシュ後に行われるため、対象ブランチが存在します）。

スキャンで問題が発見され中止した場合、コードが GitHub にコピーされることはありません。

> **注:** `--from` はソースとデスティネーションの両方で `owner/repo` 形式を使用します。

---

## ローカルディレクトリからリポジトリを作成する (`--local`)

`--local PATH` は `--from` のローカルから GitHub への対応版です。新しい 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. github.com の Git 認証情報が事前に確認されます（gh config get git_protocol が ssh の場合は SSH プローブ、HTTPS は信頼されます）。そのため、キーがない場合はリポジトリが作成される前に迅速に失敗します。
2. フライト前のセキュリティスキャナー がローカルディレクトリ上で直接実行されます（クローンは不要）。
3. 調査結果を確認し、確認（または中止）します。
4. 新しいリポジトリが作成され、アクションの権限とセキュリティ設定が適用されます。
5. 完全な履歴が push --all --tags でプッシュされます（すべてのブランチとタグ）。
6. ブランチとタグの保護が適用されます（コードプッシュ後、対象ブランチが存在する状態になります）。
7. origin が 元の ローカルリポジトリに追加され、新しい GitHub URL を指すように設定され、現在のブランチの上流トラッキングが構成されます。これにより、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 は3段階の探索チェーンを使用して、利用可能な最適なスキャナーを自動的に選択します：

1. PATH上のtruffleHog v3 — trufflehog --versionを実行し、v3であることを確認して使用します。v2のインストールまたは認識されないバージョンは警告を表示し、ステップ2にフォールスルーします。
2. podman または docker — ネイティブなtruffleHogが見つからない場合、スキャナーはコンテナ（ghcr.io/trufflesecurity/trufflehog:latest）内でtruffleHogを実行し、podman run または docker run を使用して、スキャンパスを読み取り専用で同じ絶対パスにマウントするため、JSON出力パスはネイティブ実行と同一になります。
3. Regexフォールバック — ネイティブインストールもコンテナランタイムも利用できない場合、警告が表示され、代わりに正規表現スキャナーが実行されます。また、メールやTODOに対してはtruffleHogに加えて常に実行され、truffleHogが意図的にスキップする単独のキーIDパターンをキャッチします（truffleHogはクレデンシャルペアの両方、例えばAWSキーID および シークレットアクセスキーが必要です）。

選択されたスキャナーは、「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)

コンテナパスで認識される環境変数: `CONTAINER_RUNTIME` でランタイム選択を上書き（例 `CONTAINER_RUNTIME=docker`）、`TRUFFLEHOG_IMAGE` で特定のイメージタグを固定できます。

### podman または Docker 経由で truffleHog を実行する（ローカルインストール不要）

手動セットアップは不要です。`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 をシステム全体で利用したいユーザーや、エアギャップ環境用のイメージが必要なユーザー向けです。

### 対話型レビュー```
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 と入力して中止します。
• 発見なし: スキャンは静かに完了し、ワークフローは続行します。

シークレットは出力で編集されます。メールアドレスと TODO は一致する行を表示します。

スキャン範囲

ビルド成果物ディレクトリ (node_modules, __pycache__, .venv, venv, dist, build) は、スキャンを高速に保つためにデフォルトでスキップされます。Git リポジトリでは、このスキップは条件付きです。ディレクトリをスキップする前に、スキャナーは git ls-files -- <dir> を実行して、内部のファイルが追跡されているかどうかを確認します。追跡されている場合は、ディレクトリは通常通りスキャンされます。

つまり、コミットされた node_modules や dist ツリー（珍しいですが発生します）は、見落とされることはありません。コミットされていないディレクトリ（通常のケース）は、以前と同様にスキップされ続けます。

クローンされたソースリポジトリで SKIP_DIRS サブディレクトリが見つかった場合、警告が引き続き表示されます。それらの存在は、予想以上のコンテンツがコミットされている可能性があるためです。

誤検知の抑制

2 つの設定キーを使用すると、チェックカテゴリ全体を無効にせずに、既知の安全な発見を抑制できます。

scan_exclude_paths — ファイルまたはディレクトリを完全にスキップします。値は、相対ファイルパスと照合される改行/カンマ区切りの正規表現パターンです。一致するファイルは、すべてのチェック（シークレット、メール、TODO、大規模ファイル、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/

**`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

禁止文字列やAIコンテキストファイルが見つかった場合、スキャナーは再実行前にソースリポジトリの履歴からそれらを削除するための、すぐに実行可能な `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`** — `$XDG_CONFIG_HOME` が設定されていない場合は `~/.config` がデフォルト

単独の `--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 プランに応じてのみ利用可能です。

| 機能 | 無料 + 公開 | 無料 + 非公開 | Pro/Team + 非公開 |
|---|---|:---:|:---:|
| ブランチ保護 / ルールセット | はい | いいえ | はい |
| タグ保護 (ルールセット) | はい | いいえ | はい |
| 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オブジェクトのリスト: 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のプッシュとクローン）は、デフォルトではAPIトークンではなく、自身のgit認証情報（SSHキーまたはcredential helper）を使用します。どちらもない環境（例：GITHUB_TOKENのみを持つCI）では、ツールはURL内のトークンを使用したHTTPS経由のプッシュにフォールバックします。[git_transport] mode設定オプションがこれを制御します（設定リファレンスを参照）。トークンを含むURLがリポジトリの.git/configに書き込まれることはなく、すべての出力から削除されます。

APIアプローチ

すべてのGitHub API呼び出しは、subprocess経由でgh apiを通じて行われます。これにより、認証は完全にgh CLIに委ねられます — トークン管理コード、OAuthフロー、PyGithubのバージョン固定はありません。JSONリクエストボディは、--fieldフラグではなく、--input -（stdin）を介して渡されます。

開発```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/

See gh_safe_repo/README.md を参照してください。モジュールマップ、プラグインアーキテクチャ、新しい設定の追加ガイドについて説明しています。

依存関係ポリシー

ランタイム依存関係はありません。すべて Python 標準ライブラリ (argparse, configparser, subprocess, json, re) を使用しています。議論なしにサードパーティパッケージを追加しないでください。

pytest は唯一の開発依存関係であり、pyproject.toml の UV ネイティブな [dependency-groups] エントリとして宣言されています。

先行事例

これらのプロジェクトは設計時に研究され、gh-safe-repo のアーキテクチャに影響を与えました。これらはスコープとユーザーモデルが異なる独自のツールです。パターンがどのように適応されたかの詳細な技術ノートは、docs/LEARNINGS.md を参照してください。

• github/safe-settings — 中央設定からリポジトリ設定を強制する組織レベルの GitHub App (Node.js/Probot)。プラグインアーキテクチャパターン（設定カテゴリごとに1つのクラス、fetch → diff → apply）および mergeDeep 比較アプローチのソース。
• repository-settings/app — safe-settings のよりシンプルなリポジトリ単位のバリアント、こちらも Node.js/Probot。Diffable ベースプラグインパターンのよりクリーンなリファレンスを提供。
• nicholasgasior/gh-repo-settings — Go で書かれた CLI 拡張で、plan/apply ワークフローを持つ。gh api サブプロセスラッパーパターンとドライランプラン出力設計の主なインスピレーション。