GitHubストレージ完全ガイド｜容量制限・Git LFS・大容量ファイル管理を徹底解説

「GitHubにpushしたら容量制限エラーが出た…」「100MBを超えるファイルがアップロードできない」「リポジトリが重くなってクローンに時間がかかる」

こんな悩みを抱えていませんか？

GitHubには様々なストレージ制限があり、知らずに使っていると突然エラーに遭遇します。でも大丈夫！Git LFSや適切な管理方法を使えば、大容量ファイルも効率的に扱えるんです。

この記事では、GitHubのストレージ制限から、Git LFSの使い方、リポジトリサイズの最適化まで、実例たっぷりで解説します。もうストレージ問題で悩むことはありません！

GitHubのストレージ制限を完全理解
ファイルサイズを確認する方法
1. リポジトリ全体のサイズ確認
2. 大きなファイルを探す
Git LFS（Large File Storage）の使い方
容量を節約するテクニック
GitHub Actionsのアーティファクトストレージ
GitHub Packagesのストレージ
1. パッケージレジストリの制限
2. Docker イメージの管理
リポジトリサイズの最適化戦略
1. モノレポ vs マルチレポ
2. 部分クローンの活用
トラブルシューティング
1. プッシュが拒否される場合
2. LFSの容量超過
ベストプラクティス
1. 開発時の注意点
2. CI/CDでの最適化
よくある質問（FAQ）
まとめ：GitHubストレージを賢く使う

GitHubのストレージ制限を完全理解

無料プランの制限（2025年時点）

基本的な制限：

項目	制限値	詳細
リポジトリサイズ推奨	5GB未満	推奨される最大サイズ
リポジトリサイズ上限	10GB	これを超えるとGitHub Supportから連絡
単一ファイルサイズ	100MB	Webインターフェースは25MB
Git LFS容量	1GB	無料枠
Git LFS帯域	1GB/月	無料枠

プッシュ時の警告とエラー

# 50MB以上のファイル：警告が表示される
warning: Large files detected. Consider using Git LFS

# 100MB以上のファイル：エラーで拒否される
remote: error: GH001: Large files detected.
remote: error: File large_file.zip is 101.00 MB; this exceeds GitHub's file size limit of 100.00 MB

# リポジトリが5GBを超える：警告メール
# リポジトリが10GBを超える：GitHub Supportから連絡

GitHub Pagesのストレージ制限

- サイト全体：1GB まで
- 単一ファイル：100MB まで
- 帯域制限：100GB/月
- ビルド時間：10分まで

ファイルサイズを確認する方法

リポジトリ全体のサイズ確認

GitHub Web上で確認：

リポジトリページ → Settings
一番下の「Danger Zone」上部にサイズ表示

APIで確認：

# GitHub APIを使用
curl -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/ユーザー名/リポジトリ名 \
  | jq '.size'

# 結果はKB単位で表示される

ローカルで確認：

# .gitフォルダを含むサイズ
du -sh .

# .gitフォルダのサイズ
du -sh .git

# より詳細な内訳
du -sh .git/objects

大きなファイルを探す

# リポジトリ内の大きなファイルTOP10
find . -type f -exec du -h {} + | sort -rh | head -10

# Gitで管理されているファイルのサイズ
git ls-files | xargs du -h | sort -rh | head -10

# Git履歴も含めて大きなファイルを探す
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  sed -n 's/^blob //p' | \
  sort --numeric-sort --key=2 | \
  tail -10 | \
  cut -c 1-12,41- | \
  $(command -v gnumfmt || echo numfmt) --field=2 --to=iec-i --suffix=B --padding=7 --round=nearest

Git LFS（Large File Storage）の使い方

Git LFSとは？

Git LFSは、大容量ファイルを効率的に扱うための拡張機能です。

仕組み：

大きなファイルの実体は別サーバーに保存
Gitリポジトリにはポインタファイルのみ保存
必要な時だけ実ファイルをダウンロード

Git LFSのインストール

# Ubuntu/Debian
sudo apt install git-lfs

# macOS (Homebrew)
brew install git-lfs

# Windows
# Git for Windowsに含まれている場合が多い
# または https://git-lfs.github.com/ からダウンロード

# インストール後の初期設定
git lfs install

Git LFSの基本的な使い方

Step 1: トラッキングするファイルを指定

# 特定の拡張子をLFSで管理
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"

# 特定のファイル
git lfs track "large_file.bin"

# パターンで指定
git lfs track "assets/videos/*"

# .gitattributesが自動生成される
cat .gitattributes
# *.psd filter=lfs diff=lfs merge=lfs -text

Step 2: ファイルを追加してコミット

# .gitattributesを先にコミット
git add .gitattributes
git commit -m "Add Git LFS tracking"

# 大容量ファイルを追加
git add large_file.psd
git commit -m "Add large PSD file"

# プッシュ
git push origin main

既存ファイルをLFSに移行

# 既存の大きなファイルをLFSに移行
git lfs migrate import --include="*.psd,*.zip" --everything

# 特定のブランチのみ
git lfs migrate import --include="*.psd" --include-ref=main

# 確認のみ（実際には変更しない）
git lfs migrate info --everything

LFSファイルの確認

# LFSで管理されているファイル一覧
git lfs ls-files

# LFSの使用状況
git lfs status

# トラッキングパターンの確認
git lfs track

# LFS関連のログ
GIT_TRACE=1 git lfs fetch

容量を節約するテクニック

不要なファイルを.gitignoreに追加

# .gitignore の例
# ビルド成果物
build/
dist/
*.exe
*.dll
*.so
*.dylib

# 依存関係
node_modules/
vendor/
packages/

# IDEの設定
.idea/
.vscode/
*.swp
*.swo

# OSのファイル
.DS_Store
Thumbs.db

# ログファイル
*.log
logs/

# 一時ファイル
*.tmp
temp/
cache/

Git履歴から大きなファイルを削除

BFG Repo-Cleanerを使う方法（推奨）：

# BFGをダウンロード
wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar

# 100M以上のファイルを履歴から削除
java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 100M

# 特定のファイルを削除
java -jar bfg-1.14.0.jar --delete-files large_file.zip

# ガベージコレクション
git reflog expire --expire=now --all && git gc --prune=now --aggressive

# 強制プッシュ
git push --force

git filter-branchを使う方法：

# 特定ファイルを履歴から完全削除
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch path/to/large_file" \
  --prune-empty --tag-name-filter cat -- --all

# ガベージコレクション
git gc --aggressive --prune=now

# 強制プッシュ
git push origin --force --all

リポジトリのスリム化

# 不要なオブジェクトを削除
git gc --aggressive --prune=now

# 到達不可能なオブジェクトを削除
git prune --expire now

# packファイルを最適化
git repack -a -d -f --depth=250 --window=250

# reflogをクリア
git reflog expire --expire=now --all

GitHub Actionsのアーティファクトストレージ

アーティファクトの制限

# 無料プラン
- ストレージ：500MB
- 保持期間：90日（パブリック）、90日（プライベート）

# 有料プラン
- GitHub Pro：1GB
- GitHub Team：2GB
- GitHub Enterprise：50GB

アーティファクトのアップロード

name: Build and Store Artifacts

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Build project
        run: |
          mkdir output
          echo "Build output" > output/result.txt
      
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: build-output
          path: output/
          retention-days: 30  # 保持期間を指定

アーティファクトの管理

# 自動削除の設定
- name: Delete old artifacts
  uses: actions/github-script@v6
  with:
    script: |
      const artifacts = await github.rest.actions.listArtifactsForRepo({
        owner: context.repo.owner,
        repo: context.repo.repo,
      });
      
      const oldArtifacts = artifacts.data.artifacts.filter(artifact => {
        const age = Date.now() - Date.parse(artifact.created_at);
        return age > 7 * 24 * 60 * 60 * 1000; // 7日以上前
      });
      
      for (const artifact of oldArtifacts) {
        await github.rest.actions.deleteArtifact({
          owner: context.repo.owner,
          repo: context.repo.repo,
          artifact_id: artifact.id,
        });
      }

GitHub Packagesのストレージ

パッケージレジストリの制限

無料プラン：
- ストレージ：500MB
- 転送量：1GB/月

GitHub Pro：
- ストレージ：2GB
- 転送量：10GB/月

パブリックパッケージ：
- 無制限（無料）

Docker イメージの管理

# GitHub Container Registryにログイン
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# イメージをプッシュ
docker build -t ghcr.io/username/image:latest .
docker push ghcr.io/username/image:latest

# 古いイメージを削除
# GitHub UIから、またはAPIで削除

リポジトリサイズの最適化戦略

モノレポ vs マルチレポ

モノレポの場合：

# メリット
- 依存関係の管理が簡単
- 一括での変更が容易

# デメリット
- リポジトリサイズが巨大化
- クローンに時間がかかる

# 対策：sparse-checkoutを使用
git clone --filter=blob:none --sparse <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set <directory>

マルチレポの場合：

# サブモジュールで管理
git submodule add https://github.com/user/lib.git libs/lib
git submodule update --init --recursive

部分クローンの活用

# blobless clone（コミット履歴のみ）
git clone --filter=blob:none <url>

# treeless clone（より軽量）
git clone --filter=tree:0 <url>

# 浅いクローン（最新の履歴のみ）
git clone --depth=1 <url>

# 特定のブランチのみ
git clone --single-branch --branch main <url>

トラブルシューティング

プッシュが拒否される場合

# エラー：large files detected
# 解決：Git LFSを使用
git lfs track "*.large"
git add .gitattributes
git add large_file
git commit -m "Add large file with LFS"
git push

# エラー：pack exceeds maximum allowed size
# 解決：分割してプッシュ
git push origin main~10:main
git push origin main~5:main
git push origin main

LFSの容量超過

# 使用状況を確認
git lfs ls-files --size

# 不要なLFSファイルを削除
git lfs prune

# LFSのキャッシュをクリア
rm -rf .git/lfs/objects

ベストプラクティス

開発時の注意点

# 1. コミット前にファイルサイズを確認
find . -size +50M -type f

# 2. pre-commitフックで大きなファイルを防ぐ
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
# 50MB以上のファイルをブロック
files=$(git diff --cached --name-only --diff-filter=ACM)
for file in $files; do
  size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)
  if [ "$size" -gt 52428800 ]; then
    echo "Error: $file is larger than 50MB"
    exit 1
  fi
done
EOF
chmod +x .git/hooks/pre-commit

CI/CDでの最適化

# GitHub Actions: 浅いクローンを使用
- uses: actions/checkout@v3
  with:
    fetch-depth: 1
    lfs: true  # LFSファイルも取得

# キャッシュの活用
- uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

よくある質問（FAQ）

Q1：無料でどれくらい使える？

A：用途によって十分です

通常のコード：リポジトリ5GBまで推奨
Git LFS：1GB + 1GB/月の転送量
小〜中規模プロジェクトなら問題なし

Q2：容量を増やすには？

A：有料プランまたはLFSデータパック

Git LFS データパック：$5/月
- 50GB ストレージ
- 50GB 帯域幅

Q3：プライベートリポジトリも同じ制限？

A：はい、同じです パブリック/プライベートで容量制限は同じ。ただし、GitHub Packagesはパブリックなら無制限。

Q4：他のGitホスティングと比較すると？

A：GitHubは中間的

GitLab：10GBリポジトリ制限
Bitbucket：1GB〜2GBリポジトリ制限
自社サーバー：制限なし（要管理）

まとめ：GitHubストレージを賢く使う

GitHubのストレージ管理について重要なポイントをまとめます：

基本の制限を覚える：

📦 リポジトリ：5GB推奨、10GB上限
📄 単一ファイル：100MB
🗄️ Git LFS：1GB + 1GB/月

大容量ファイルの対処法：

Git LFSを使う（推奨）
.gitignoreで除外
別サービスに保存してリンク

最適化のコツ：

# LFSの設定
git lfs track "*.zip"

# 履歴のクリーンアップ
java -jar bfg.jar --strip-blobs-bigger-than 100M

# 部分クローン
git clone --filter=blob:none <url>

ベストプラクティス：

バイナリファイルは極力避ける
ビルド成果物は含めない
定期的にリポジトリサイズを確認
CI/CDでは浅いクローンを使用

GitHubのストレージ制限は適切に管理すれば問題になりません。この記事のテクニックを活用して、効率的なリポジトリ運用を実現しましょう！