GitLabCI/CDDevOps自己ホスト型アーティファクトパイプライン設定ガイドインフラ

自己ホスト型GitLabのアーティファクトサイズ上限を無制限に近づける設定ガイド

👤 いわぶち 📅 2025-12-26 ⭐ 4.5点 ⏱️ 12m

ポッドキャスト

🎙️ 音声: ずんだもん / 春日部つむぎ（VOICEVOX）

📌 1分で分かる記事要約

自己ホスト型GitLabはプラン制限がなく、アーティファクトサイズを自由に増やせます（SaaS版GitLab.comとは異なり）
Admin Area > Settings > CI/CDで「Maximum artifact size (MB)」を変更するだけで、インスタンス全体に適用されます
デフォルトでは単一ファイル100MB、アーカイブ全体は設定値に従いますが、Railsコンソールで個別制御も可能
サーバーのディスク容量やメモリを超えないよう、リソース管理に注意が必要です
不要なファイルを除外する.gitlab-ci.ymlのartifacts: exclude設定も併用すると効率的です

📝 結論

自己ホスト型GitLabでアーティファクトサイズの上限を引き上げるには、Admin Areaの設定変更が最も簡単です。プラン制限の制約がないため、サーバーリソースの許す限り自由に上限を設定できますが、ディスク容量やメモリの監視が重要になります。

🔧 自己ホスト型GitLabの強み：プラン制限がない

GitLab.com（SaaS版）とセルフマネージド版（自己ホスト型）では、アーティファクトサイズ上限の扱いが大きく異なります。

**GitLab.com（SaaS版）**では、サブスクリプションプランごとに上限が決められています。例えば、Freeプランでは256MB、Premiumプランでは2GBなど、プランに応じた制限が存在します。

一方、自己ホスト型GitLabではこのようなプラン制限が存在しません。つまり、サーバーのリソース（ディスク容量やメモリ）が許す限り、アーティファクトサイズの上限を自由に設定できるということです。これは大規模なビルド成果物を扱う組織にとって大きなメリットになります。

📋 Admin Areaでの設定手順

アーティファクトサイズの上限を変更する最も標準的な方法は、GitLabの管理画面から行います。

ステップ1：Admin Areaにアクセス

GitLabインスタンスの管理者権限を持つアカウントでログインし、管理者エリア（Admin Area）を開きます。通常、画面左上のメニューから「Admin」を選択するか、URLで /admin にアクセスします。

ステップ2：CI/CD設定ページへ移動

Admin Areaの左側メニューから Settings > CI/CD を選択します。このページには、CIパイプライン全体に関わる設定が集約されています。

ステップ3：Maximum artifact sizeを変更

ページ内で 「Maximum artifact size (MB)」 という項目を探します。デフォルト値が表示されていますので、これを希望のサイズに変更してください。

例えば、現在の上限が100MBで、5GBまで対応したい場合は、5120（5GB = 5120MB）と入力します。

ステップ4：変更を保存

画面下部の 「Save changes」 ボタンをクリックして、設定を保存します。この変更はGitLabインスタンス全体に即座に適用されます。

ステップ5：パイプラインを再実行

既に実行中のパイプラインがある場合、新しい上限を適用するためにパイプラインを再実行してください。新規ジョブから新しい上限が有効になります。

📊 アーティファクトサイズの階層構造を理解する

GitLabのアーティファクト制限は、複数のレベルで設定されています。正確に理解することが、トラブルシューティングに役立ちます。

レベル1：Maximum artifact size (MB) - アーカイブ全体

Admin Areaで設定する値です。パイプラインで生成されるアーティファクトアーカイブ全体の上限を指定します。これが最も広範な制限になります。

レベル2：単一ファイルの制限

デフォルトでは、圧縮後の単一ファイルあたり100MBという制限があります。これはアーカイブ全体の上限とは別の制約です。

レベル3：アーティファクトタイプ別の制限

さらに細かい制御が必要な場合、Railsコンソールを使用して、特定のアーティファクトタイプ（junit、sast、archiveなど）ごとに上限を設定できます。

🛠️ Railsコンソールでの個別制御

より高度な設定が必要な場合、GitLabのRailsコンソールを使用して、アーティファクトタイプごとの上限を個別に設定できます。

Railsコンソールへのアクセス

自己ホスト型GitLabのサーバーにSSH接続し、以下のコマンドを実行します：

sudo gitlab-rails console

アーティファクトタイプ別の上限設定

例えば、archiveタイプのアーティファクト上限を1GB（1024MB）に設定する場合：

Plan.default.actual_limits.update!(ci_max_artifact_size_archive: 1024)

他のタイプの例：

# JUnit形式のレポート上限を512MBに
Plan.default.actual_limits.update!(ci_max_artifact_size_junit: 512)

# SAST形式のレポート上限を2GBに
Plan.default.actual_limits.update!(ci_max_artifact_size_sast: 2048)

**デフォルト値は0**で、これはプロジェクト全体の上限（Admin Areaで設定した値）が適用されることを意味します。

設定の確認

設定が正しく適用されたか確認するには：

Plan.default.actual_limits

このコマンドで、全アーティファクトタイプの制限値が表示されます。

⚠️ 注意点とリスク管理

アーティファクトサイズの上限を引き上げる際に、注意すべき点があります。

サーバーリソースの監視

ディスク容量がサイズ上限を超えないよう注意してください。アーティファクトは通常、GitLabサーバーの/var/opt/gitlab/gitlab-rails/shared/artifactsディレクトリに保存されます。ディスク使用率を定期的に監視し、必要に応じてストレージを拡張してください。

また、メモリ使用量も考慮が必要です。大容量のアーティファクトを圧縮・解凍する際にメモリが消費されるため、サーバーのRAM容量が不足していないか確認しましょう。

エラーメッセージの対応

サイズ超過時には以下のエラーが発生します：

ERROR: Job failed: artifact size limit exceeded

このエラーが頻繁に発生する場合、単に上限を引き上げるのではなく、後述の除外設定で不要なファイルを削減することも検討してください。

🎯 .gitlab-ci.ymlで不要ファイルを除外する

上限を引き上げるだけでなく、アーティファクトに含めるファイルを厳選することも重要です。

artifacts: excludeの活用

.gitlab-ci.ymlで、アーティファクトから特定のファイルやディレクトリを除外できます：

build_job:
  script:
    - npm run build
  artifacts:
    paths:
      - dist/
      - build/
    exclude:
      - dist/**/*.map        # ソースマップを除外
      - build/temp/**/*      # 一時ファイルを除外
      - "**/*.log"           # ログファイルを除外

この方法で、実際に必要なファイルだけをアーティファクトに含めることで、ストレージ効率を大幅に改善できます。

ファイル圧縮の活用

大容量のテキストファイルが多い場合、gzip圧縮を活用してサイズを削減できます：

build_job:
  script:
    - npm run build
    - tar -czf reports.tar.gz reports/
  artifacts:
    paths:
      - reports.tar.gz

📈 ベストプラクティス

段階的な上限引き上げ

いきなり大幅に上限を引き上げるのではなく、段階的に増やしながら動作を確認することをお勧めします。例えば、100MB → 500MB → 1GB というように、様子を見ながら進めてください。

定期的なストレージ監視

上限を引き上げた後も、ディスク使用率を定期的に確認してください。GitLabには、古いアーティファクトを自動削除する設定もあります（artifacts_expire_in）。これを活用して、不要なアーティファクトを自動的に削除するようにしましょう。

ドキュメント化

チーム内で、なぜこの上限に設定したのか、どのような運用ルールを決めたのかをドキュメント化しておくことが、将来的なトラブルシューティングに役立ちます。

🔍 トラブルシューティング

設定が反映されない場合

設定を変更した後、既に実行中のジョブには新しい上限が適用されません。新しいパイプラインを実行して、変更が反映されたか確認してください。

依然としてサイズ超過エラーが発生

以下の点を確認してください：

Admin Areaでの設定値が、実際に必要なサイズに設定されているか
Railsコンソールで個別タイプの上限が、より厳しい制限になっていないか
サーバーのディスク容量が、実際に不足していないか

パフォーマンスの低下

上限を大幅に引き上げた後、GitLabのパフォーマンスが低下した場合、アーティファクト保存用のストレージをSSDからより高速なストレージに変更する、またはネットワークストレージを使用することを検討してください。

まとめ

自己ホスト型GitLabでアーティファクトサイズの上限を引き上げることは、SaaS版のような制限がないため、比較的簡単に実現できます。ただし、サーバーリソースの監視と、不要ファイルの除外設定を組み合わせることで、安定した運用が可能になります。

段階的に上限を調整しながら、チームの実際のニーズに合わせた最適な設定を見つけていくことが、長期的な成功の鍵となるでしょう。