GitHub リポジトリ複製・組み込み・ブランチ運用の全体マップ
Fork / Template / Clone / Submodule / Subtree / Branch など、GitHub でリポジトリを複製・組み込み・派生させる全機能を一覧比較し、使用シーン・作成削除方法・CI/CD統合・セキュリティ観点・よくある失敗を整理する。
概観
GitHub / Git には「既存リポジトリをベースに何かを始める」機能が多数存在する。それぞれ繋がりの強さ・双方向性・目的が異なるため、選択を誤ると後で運用コスト・セキュリティリスクが跳ね上がる。本記事はその全体像と判断基準、運用の落とし穴までまとめる。
一覧表: 複製・組み込み・派生の全機能
| 機能 | レイヤー | 履歴の繋がり | GitHub 表示 | 双方向性 | 主用途 |
|---|---|---|---|---|---|
Fork | GitHub | あり | 「forked from」 | 双方向(PR可) | OSS貢献、実験改変 |
Template | GitHub | なし | 「generated from」 | 片方向 | Starter、ボイラープレート |
Clone | Git | あり(ローカル) | なし | 片方向 | ローカル作業起点 |
Import repository | GitHub | あり | なし | 片方向 | 他VCSからの移行 |
Duplicate (mirror push) | Git | あり | なし | 片方向 | 完全複製、履歴ごと移設 |
Mirror repository | GitHub | あり | なし | 片方向自動 | バックアップ、多重ホスト |
Submodule | Git | 参照保持 | 別リポへのリンク付フォルダ | 独立管理 | 外部リポを子として埋込 |
Subtree | Git | 統合 | 普通のフォルダ | 双方向(複雑) | 外部リポを本体に取込 |
Symlink | OS/Git | ─ | 斜め矢印アイコン | 片方向参照 | 同一ファイルの別名参照 |
Branch | Git | 同一リポ内分岐 | ブランチセレクタ | 双方向(merge) | 並行開発、機能分離 |
Worktree | Git | 同一リポ複数チェックアウト | なし | ─ | 複数ブランチ同時作業 |
Package (npm/pip等) | 配布 | なし | Packages タブ | 片方向 | ライブラリ配布 |
Monorepo (workspaces) | 構成 | 単一リポ内 | なし | ─ | 密結合な複数パッケージ管理 |
Release / Tag | Git | スナップショット | Releases タブ | 片方向 | バージョン固定配布 |
Gist | GitHub | 独立ミニリポ | Gist として別領域 | Fork可 | スニペット共有 |
Pugh Matrix: 「他プロジェクトに組み込む」ときの選択
ベースラインを Submodule として、代表的な組み込み手段を比較する。
| 案 | 導入容易性 | 更新追随性 | バージョン固定 | CI複雑度低 | 利用者知識要求少 | 独立配布 | 合計 |
|---|---|---|---|---|---|---|---|
| Baseline (Submodule) | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| Subtree | + | 0 | 0 | ++ | ++ | - | +4 |
| Package (npm等) | - | ++ | ++ | + | ++ | ++ | +8 |
| Monorepo | — | ++ | + | - | + | — | -1 |
| Copy & paste | ++ | — | — | ++ | ++ | — | 0 |
読み取り:
- Package 化が可能なら最強(+8)。ただしパッケージ化の初期コストが -1
- 利用者が Git 初心者を含むなら Subtree(+4)
- Submodule は「厳格なバージョン固定+独立開発」の要件が強い時のみ選ぶ
- Monorepo は組み込みではなく「そもそも一体管理」の選択肢
判断フローチャート
flowchart TD Q1{他リポの内容を持ってきたい?} Q1 -->|No| BR[Branch / Worktreeで十分] Q1 -->|Yes| Q2{上流にPR送信する?} Q2 -->|Yes| FORK[Fork] Q2 -->|No| Q3{履歴を保ちたい?} Q3 -->|No| TMPL[Template] Q3 -->|Yes| Q4{独立扱い?子として埋込?} Q4 -->|独立| CLONE[Clone→新規リポ<br/>or Duplicate] Q4 -->|子埋込| Q5{パッケージ化可能?} Q5 -->|Yes| PKG[Package化推奨] Q5 -->|No| Q6{利用者にGit中級知識あり?} Q6 -->|Yes| SUB[Submodule] Q6 -->|No| SUBT[Subtree]Mermaid 未対応環境ではテキスト版:
Q1: 他リポの内容を持ってきたい?├─ No → Branch / Worktree└─ Yes → Q2
Q2: 上流に貢献(PR送信)する?├─ Yes → Fork└─ No → Q3
Q3: 履歴・繋がりを保ちたい?├─ No → Template(スターター用途)└─ Yes → Q4
Q4: 独立プロジェクト?子として埋込?├─ 独立 → Clone → 新規リポ or Duplicate└─ 子埋込 → Q5
Q5: パッケージ化可能?├─ Yes → Package化を強く推奨└─ No → Q6
Q6: 利用者に Git 中級知識を要求できる?├─ Yes → Submodule└─ No → Subtreeコピーボタン表示のバグあり。閉じてないコードブロックが始めあった。要経過観察: 2026/9/25
各機能の詳細
Fork
目的: 他人のリポジトリを自アカウントに複製し、Pull Request を送る権利を得る。
使用シーン:
- OSS プロジェクトへのバグ修正・機能追加提案
- 一時的な実験的改変
- アーカイブされたプロジェクトの引き継ぎ
他者との関係:
- 上流(upstream)作者からは fork 数として可視化
- 誰が fork したかはリスト表示されるが、内部での作業内容は追われない
- PR を送ると初めて明示的な関与になる
メリット:
- 上流への還元パスが確立
- 「Compare」で差分が常に見える
デメリット:
- 履歴が完全に紐づくため、私的プロジェクトには不向き
- 上流が消えると fork 側の位置付けが曖昧に
- ネットワーク上に永続記録される(削除しても検索キャッシュに残る場合あり)
影響範囲: 自アカウント配下に1リポジトリ増える。上流には影響しない。
作り方:
- Web GUI: 対象リポ右上「Fork」ボタン → 名前確認 → 「Create fork」
- CLI:
gh repo fork owner/repo --clone
消し方:
- Web GUI: Settings → Danger Zone → Delete this repository
- CLI:
gh repo delete yourname/repo --yes
見分け方: リポ名下に「forked from owner/repo」表記。
CI/CD の落とし穴:
- Fork からの PR では secrets が渡らない(セキュリティ仕様)
pull_request_targetイベントを安易に使うと secret 漏洩リスク- 対策: 信頼できる contributor の PR のみ label で明示的トリガー
セキュリティ観点:
- Public fork は元リポが private 化されても 既に fork された内容は残る
- 機密を含むリポは fork 許可の Organization 設定で制限すべき
よくある失敗:
- Fork したまま長期放置 → upstream との乖離が大きくなり merge 困難
- 対策: 定期的に
git fetch upstream && git rebase upstream/main
Template
目的: 履歴を切り離した新規リポジトリを、既存構造から生成する。
使用シーン:
- Astro / Next.js などのスターターテーマ利用
- 社内標準プロジェクト構成の展開
- 個人ブログの立ち上げ
他者との関係:
- 「generated from」表示は残るが、履歴紐付けはない
- 元テンプレの更新は自動反映されない
- 作者からは利用者数が把握しにくい
メリット:
- クリーンな履歴で始められる
- 元プロジェクトの都合に縛られない
- 「Include all branches」で全ブランチ複製可能
デメリット:
- 元テンプレの改善を後から取り込む標準手段がない
- テンプレ側で「Template repository」設定が必要
作り方:
- 前提: テンプレ側 Settings → 「Template repository」チェック
- Web GUI: テンプレリポの「Use this template」→「Create a new repository」
- CLI:
gh repo create myproject --template owner/template-repo
消し方: 通常のリポ削除と同様。
見分け方: リポ名下「generated from owner/template」表記。
セキュリティ観点:
- テンプレリポに過去コミットで秘密情報が含まれていた場合、履歴は切れるが最新スナップショットに秘密が残っていれば当然引き継がれる
- Template 化前に
git-secrets/trufflehogでスキャン推奨
よくある失敗:
- Template 化を忘れて Fork を勧めてしまう → 利用者側で
forked from表示が残る - 対策: Starter リポは必ず Template 化する
Clone
目的: リモートリポジトリをローカルに複製し、作業環境を作る。
使用シーン: あらゆるローカル開発の起点。
他者との関係: リモートに影響なし。認証情報が残る点のみ注意。
メリット: 全履歴・全ブランチが手元に来る、オフライン作業可能。
デメリット: 大規模リポでは時間・容量を消費。
作り方:
# 通常git clone https://github.com/owner/repo.git
# 浅いクローン(履歴を最新N件のみ)git clone --depth 1 https://github.com/owner/repo.git
# submodule も同時取得git clone --recurse-submodules https://github.com/owner/repo.git
# 特定ブランチのみgit clone -b branch-name --single-branch https://github.com/owner/repo.git消し方: フォルダを削除するだけ (rm -rf repo)。
見分け方: .git フォルダの存在。git remote -v で origin URL 確認。
よくある失敗:
--depth 1した shallow clone に対しgit rebaseやgit log --allを実行 → 履歴不足で失敗- 対策:
git fetch --unshallowで完全履歴に戻す
Import repository
目的: 他の VCS(SVN, Mercurial, TFS)や別ホスティングから GitHub へ移行。
作り方: GitHub Web → 右上 + → 「Import repository」→ 元URL・認証情報を入力。
消し方: 通常のリポ削除。
見分け方: 特別な表示はなし。commit author 履歴で判断。
Duplicate (mirror push)
目的: あるリポジトリの完全な複製(全ブランチ・全タグ)を別リポとして作る。Fork のような紐付けは残らない。
作り方:
git clone --bare https://github.com/owner/original.gitcd original.gitgit push --mirror https://github.com/yourname/new-copy.gitcd ..rm -rf original.git使用シーン: プロジェクト引き継ぎ、組織移管、履歴保全付きコピー。
見分け方: 特別な表示なし。commit 履歴が丸ごと一致することで判別。
セキュリティ観点: 元リポの全履歴の秘密情報が新リポにも複製される。BFG Repo-Cleaner 等で事前除去を検討。
Mirror repository
目的: 別ホスティング(GitLab等)との自動同期。
作り方: GitHub Actions や外部ツール(例: pixta-dev/repository-mirroring-action)で実装。
使用シーン: 冗長化、社内外での並行公開。
Submodule
目的: 外部リポジトリを「特定コミットへの参照」として親リポに埋め込む。
使用シーン:
- 共通ライブラリの参照(バージョン固定必須)
- コードエージェント用ルール集の複数プロジェクト共有
- ベンダーコードの取り込み
他者との関係:
- 親リポと子リポは独立管理
- 子リポの更新は親リポで明示的に「参照コミットを進める」操作が必要
メリット:
- 子リポの独立性が完全に保たれる
- バージョン(コミット)が親側で厳格に固定
デメリット:
--recurse-submodulesを忘れると空フォルダになる- CI/CD 設定が煩雑
- 学習コスト高
影響範囲: 親リポに .gitmodules 追加、指定パスに子リポマウント。
作り方:
git submodule add https://github.com/you/methodology.git tools/methodologygit commit -m "chore: add methodology submodule"初回取得:
git clone --recurse-submodules <repo># または後からgit submodule update --init --recursive更新(子リポの最新を取り込む):
git submodule update --remote tools/methodologygit add tools/methodologygit commit -m "chore: bump methodology submodule"消し方:
git submodule deinit -f tools/methodologygit rm -f tools/methodologyrm -rf .git/modules/tools/methodologygit commit -m "chore: remove methodology submodule"見分け方:
- ルートに
.gitmodulesファイル - GitHub 上でフォルダアイコンが特殊、クリックで別リポへ遷移
- コミットハッシュが
@ xxxxxxx形式で表示
CI/CD の落とし穴:
GitHub Actions で submodule を含むリポをビルドする場合:
- uses: actions/checkout@v4 with: submodules: recursive # または true token: ${{ secrets.GITHUB_TOKEN }}private submodule を参照する場合は追加で PAT(Personal Access Token)が必要:
- uses: actions/checkout@v4 with: submodules: recursive token: ${{ secrets.SUBMODULE_PAT }}セキュリティ観点:
- Submodule の URL 改ざん攻撃:
.gitmodulesの URL を悪意あるリポに書き換える PR に注意 - 対策:
.gitmodules変更は必ずレビュー、CODEOWNERS で保護 - HTTPS より SSH URL は認証情報漏洩リスクが低い
よくある失敗:
- 子リポ側で commit & push を忘れ、親リポだけ更新 → 他の環境で参照コミットが取得できずビルド失敗
- 対策:
git push --recurse-submodules=on-demandを習慣化
Subtree
目的: 外部リポの内容を親リポに統合して取り込む。利用者からは通常フォルダに見える。
使用シーン:
- Submodule の複雑さを避けたい
- 利用者に Git 中級知識を要求できない
メリット:
- clone 時に特別操作不要
- 通常のフォルダとして扱える
デメリット:
- 履歴が肥大化しやすい
- 上流への還元コマンドがやや複雑
作り方:
git subtree add --prefix=tools/methodology \ https://github.com/you/methodology.git main --squash上流の更新取り込み:
git subtree pull --prefix=tools/methodology \ https://github.com/you/methodology.git main --squash自分の変更を上流に還元:
git subtree push --prefix=tools/methodology \ https://github.com/you/methodology.git main消し方: フォルダ削除 (git rm -rf tools/methodology && git commit)。
見分け方: 表示上は通常フォルダ。.gitmodules なし。コミット履歴に git-subtree-dir: を含むメッセージ。
よくある失敗:
--squashで追加した subtree に対し、--squashなしで pull → 履歴が二重化して大混乱- 対策: 一貫して
--squashを使うか、一貫して使わない subtree pushは subtree の history が squash されていると失敗しやすい → 別リポで clone → cherry-pick → push が実用的
Symlink(シンボリックリンク)
目的: 同一ファイル・フォルダに複数名でアクセスできる OS 機能。Git も保持できる。
使用シーン:
AGENTS.mdとCLAUDE.mdを同一内容として扱う(複数エージェント対応)- 設定ファイルの複数配置
メリット: 実体1つ、更新が同期される。
デメリット:
- Windows では作成に管理者権限か Developer Mode 必要
git config core.symlinks trueを設定していないとテキストファイルとして clone される
作り方:
ln -s CLAUDE.md AGENTS.mdgit add AGENTS.mdgit commit -m "chore: link AGENTS.md to CLAUDE.md"消し方: rm AGENTS.md(通常のファイル削除と同様)。
見分け方:
- GitHub 上でファイル名横に斜め矢印アイコン
- クリックでリンク先ファイルへ遷移
- ローカルでは
ls -laでAGENTS.md -> CLAUDE.mdと表示
よくある失敗:
- Windows ユーザーが clone → symlink がリンク先パスのテキストファイルになる
- 対策: リポの README に
git config core.symlinks trueの指示を明記
Branch(ブランチ)
目的: 同一リポ内で並行開発の系統を分ける。
使用シーン:
- 機能開発 (
feature/*) - バグ修正 (
fix/*) - リリース準備 (
release/*) - 個人作業 (
user/name/*)
他者との関係:
- 同リポにアクセス権を持つ全員が閲覧・チェックアウト可能
- Pull Request でメインブランチへの merge を提案
メリット:
- 軽量、瞬時に切り替え可能
- Fork と違い1つのリポで完結
デメリット:
- リポの書き込み権限が必要(外部貢献者は Fork ルート)
作り方:
- Web GUI: ブランチセレクタ → 名前入力 → 「Create branch」
- CLI:
git checkout -b feature/new-uigit push -u origin feature/new-ui消し方:
# ローカルgit branch -d feature/new-ui # merged 済みのみgit branch -D feature/new-ui # 強制
# リモートgit push origin --delete feature/new-uiWeb GUI: Branches ページ → ゴミ箱アイコン。
見分け方: ブランチセレクタ、または git branch -a。
セキュリティ観点:
main/release/*は Branch protection rules で保護すべき- 直接 push 禁止、PR + review 必須、status check 必須の3点セットが最低ライン
Worktree
目的: 同一リポの複数ブランチを、別々のディレクトリで同時にチェックアウトする。
使用シーン:
- main での hotfix と feature 開発を並行
- ブランチ切り替え時のビルド破棄を避けたい
作り方:
git worktree add ../repo-hotfix hotfix-branch削除:
git worktree remove ../repo-hotfix見分け方: git worktree list で確認。
Package(npm / pip / cargo など)
目的: コードを公式パッケージとして配布し、依存管理システム経由で組み込ませる。
使用シーン: 汎用ライブラリ、CLI ツール、フレームワーク。
メリット:
- semver によるバージョン管理
- 依存解決が自動
- インストールが簡単
デメリット:
- 公開・メンテナンスの手間
- レジストリへの登録が必要
GitHub Packages を使う場合:
- private package もリポとセットで管理可能
.npmrcに registry と${GITHUB_TOKEN}を設定
セキュリティ観点:
- Typosquatting 攻撃(似た名前の悪意パッケージ)に注意
- Dependabot / Renovate で依存更新を自動化
npm audit/pip-auditを CI に組込む
見分け方: リポの Packages タブ、または package.json の "name" フィールド。
Monorepo(workspaces)
目的: 密結合した複数パッケージを単一リポで管理。
ツール例: pnpm workspaces, Nx, Turborepo, Lerna
メリット: 一括 CI、統一 lint、原子的変更。
デメリット: リポ肥大化、CI 分離設計が必要。
CI 最適化:
paths-filteraction で変更検知 → 影響パッケージのみビルドTurborepoの remote cache でビルド共有
見分け方: pnpm-workspace.yaml, nx.json, ルート package.json の workspaces フィールド。
Release / Tag
目的: 特定コミットにバージョンラベルを付け、配布物として固定。
作り方:
git tag -a v1.0.0 -m "Release 1.0.0"git push origin v1.0.0Web GUI: Releases タブ →「Draft a new release」
消し方:
git tag -d v1.0.0git push origin --delete v1.0.0見分け方: Releases タブ、git tag -l。
セキュリティ観点:
- Release アセットへの署名(
cosign, GPG)で改ざん検知 gh attestationで SLSA provenance 生成
Gist
目的: 単一〜数ファイルのスニペット共有。ミニリポとして機能。
使用シーン: 設定サンプル、コードスニペット、一時的共有。
Fork 可能: Gist にも Fork 機能がある。
見分け方: URL が gist.github.com/...。
セキュリティ観点: Public Gist は検索エンジンにインデックスされる。うっかり API キーを貼ると秒で bot に拾われる。
見分け方まとめ(GitHub 画面で判別)
| 見た目 | 正体 |
|---|---|
| リポ名下「forked from ○○」 | Fork |
| リポ名下「generated from ○○」 | Template から生成 |
| フォルダに斜め矢印、別リポへ遷移 | Submodule |
| ファイル名に斜め矢印、同リポ内へ遷移 | Symlink |
通常のフォルダだが .gitmodules あり | Submodule 親リポ |
| Releases タブに項目あり | Release/Tag |
| Packages タブに項目あり | Package 公開 |
URL が gist.github.com | Gist |
CI/CD 統合チートシート
actions/checkout@v4 の主要オプション:
- uses: actions/checkout@v4 with: fetch-depth: 0 # 全履歴取得(tag/blame解析用) submodules: recursive # submodule 再帰取得 token: ${{ secrets.PAT }} # private submodule 用 lfs: true # Git LFS 有効化 persist-credentials: false # 後続 step で認証情報を残さない判断早見表:
| やりたいこと | 設定 |
|---|---|
| 通常のビルド | デフォルトで OK |
| tag からバージョン算出 | fetch-depth: 0 |
| submodule 使用 | submodules: recursive |
| private submodule | 上記 + token: PAT |
| 大容量ファイル | lfs: true |
| Fork PR で secret を守る | pull_request_target を避ける |
セキュリティ観点まとめ
| 機能 | 主なリスク | 対策 |
|---|---|---|
| Fork | PR での secret 漏洩 | pull_request_target 回避、label トリガー |
| Template | 履歴の秘密情報引継 | trufflehog で事前スキャン |
| Duplicate | 全履歴の秘密複製 | BFG Repo-Cleaner で除去後複製 |
| Submodule | URL 改ざん攻撃 | .gitmodules を CODEOWNERS 保護 |
| Package | Typosquatting | Dependabot、npm audit |
| Gist | 検索インデックス | Secret Gist 使用、公開前スキャン |
| Branch | 直接 push | Branch protection rules |
| Release | アセット改ざん | cosign / SLSA provenance |
Git Bash とクロスプラットフォーム
Windows の Git Bash は MSYS2 ベースで、以下が Linux/macOS と共通:
git全コマンドlscpmvrmgrepfindcatsshcurl- パイプ・リダイレクト・
&&||
差異:
- パスは
/c/Users/...形式 sudo不在- Symlink 作成に権限設定が必要
- 改行コード(
core.autocrlf)に注意
本記事のコマンドは全て Git Bash / macOS Terminal / Linux shell で共通動作する。
関連
- 2026-09-22-agent-config-symlink — AGENTS.md / CLAUDE.md の symlink 運用(TBD)
- 2026-09-22-methodology-integration — methodology サブモジュール運用(TBD)
- TBD: git-security-hardening — Git/GitHub セキュリティ強化(TBD)
更新履歴
初版。Submodule / Subtree / Symlink / Branch を中心に、GitHub の複製系機能15種を網羅。Pugh Matrix による組み込み手段比較、Mermaid フローチャート、CI/CD 統合チートシート、セキュリティ観点まとめ、各機能の「よくある失敗」を追加。
更新内容サマリー
前回レビューで挙げた改善点への対応:
| 指摘事項 | 対応 |
|---|---|
| ファイル名未出力 | 冒頭で明示 |
| CI/CD への言及不足 | 各機能に「CI/CD の落とし穴」節、末尾に統合チートシート追加 |
| セキュリティ観点欠落 | 各機能に「セキュリティ観点」節、末尾に一覧表追加 |
related 未記載 | related: [] を明示 |
| Pugh Matrix 未使用 | 組み込み手段比較で導入 |
updates 初期値 | updates: [] を明示 |
| コマンドの落とし穴 | 各機能に「よくある失敗」節追加 |
| フローチャートが粗い | Mermaid 版とテキスト版の二段構え |
| 「他者との関係」欠落 | 主要機能に補記 |
| tags 拡充 | ci-cd, security を追加 |