GitLab File Size Limits: Repository Caps, LFS, and Agent Workspaces

GitLab file size limits restrict web UI attachments to 100 MB by default and individual git pushes to 5 GiB through Cloudflare, with Git LFS supporting files up to 5 GB on SaaS. GitLab limits web UI attachments and web repository uploads to 100 MB by default, as detailed in the official GitLab account and limit settings. This 100 MB default upload limit in GitLab applies to comment attachments, issue descriptions, merge request replies, and files added directly to repositories using the web interface or Web IDE. When teams exceed these thresholds, uploads fail with HTTP 413 Request Entity Too Large errors, while git pushes bounce back with remote rejection notices.

Understanding GitLab limits requires separating file upload paths from storage boundaries. Developers frequently confuse the web attachment slider with git push network thresholds or total repository storage quotas. In practice, GitLab enforces constraints across multiple distinct layers:

1. Web interface upload limit: GitLab limits web UI attachments and web repository uploads to 100 MB by default. This threshold controls attachments in issues, merge requests, release descriptions, and files committed directly through the browser Web IDE.
2. Git push request limit: GitLab SaaS restricts git push requests to 5 GiB through Cloudflare with a 10 GB repository storage limit, as outlined in GitLab.com settings. On self-managed instances, the default push size is governed by instance configuration and web server buffers.
3. Git Large File Storage single file limit: Files tracked through Git LFS bypass git packfiles and support single files up to 5 GB on GitLab SaaS, subject to overall project storage quotas.
4. Repository storage limit: GitLab SaaS restricts git push requests to 5 GiB through Cloudflare with a 10 GB repository storage limit on the Free tier, combining git repository data, commit history, and Git LFS objects.
5. CI/CD job artifacts: GitLab SaaS enforces default artifact ceilings for compressed job outputs, while self-managed instances allow custom administrative quotas.
6. Wiki page content: GitLab limits individual wiki page content to 5 MB by default.

The following table summarizes default file size limits and repository storage caps across GitLab deployments:

These limits protect GitLab servers and edge networks from resource exhaustion. Git was engineered as a distributed version control system for source code, not as an object store for multi-gigabyte binary datasets, machine learning models, or database snapshots. Pushing large binary files directly into a repository creates permanent history bloat that degrades cloning speed for every team member.

• CSV File Size Limits: AI Assistant Upload Caps, Parsing Ceilings, and FixesCSV file size limits vary from strict row boundaries in spreadsheets to memory and token constraints in AI chat...
• Excel File Size Limits: Documented Caps and Large Workbook WorkaroundsMicrosoft Excel enforces a 1,048,576 row cap per worksheet, Excel Online restricts browser editing to 100MB workbooks,...
• JSON File Size Limits: RFC Standards, Engine Memory, and AI Context CapsThe official JSON standard (RFC 8259) defines no maximum file size limit. In practice, the V8 JavaScript engine throws...
• OpenAI Assistant File Limits: Upload Caps, Size Limits, and SolutionsOpenAI assistant file limits balance responsiveness against overhead, restricting direct attachments while capping...
• ChatGPT Plus Upload Limit: File Size, Count, and Rolling CapsThe ChatGPT Plus upload limit caps subscribers at `80` file uploads every 3 hours, a `512 MB` file ceiling, and a...
• GitHub File Size Limits Explained for Teams and CopilotGitHub hard-blocks any single file larger than 100 MiB in normal Git history, warns above 50 MiB, and caps browser...

More on this subject: Agent File and Document Workflows (269 guides)

The official Git Large File Storage documentation explains that Git LFS replaces large binary files with lightweight text pointers inside the Git repository tree, while transferring the actual binary content to an external object store. Git stores every revision of a tracked file as a full compressed object in its internal packfile. When a developer modifies a large binary asset, Git cannot compute a line-by-line plaintext diff. Git compresses and stores a complete replacement copy in the repository history, multiplying disk space consumption with every revision.

Git LFS addresses packfile bloat by altering how Git handles designated file types. When a file matches a pattern in the repository .gitattributes file, Git LFS intercepts the commit. Instead of committing the binary blob into the Git tree, Git writes a tiny text pointer file containing metadata:

version https://git-lfs.github.com/spec/v1
oid sha256:4d7a2872bc6f75f319364a61524d47104f71f9e4b921649f30bf2e3796c51cdb
size 2147483648

The pointer file contains three values:

• version: The Git LFS specification standard.
• oid: The cryptographic SHA-256 hash identifying the binary object.
• size: The exact file size in bytes.

During a git push, the Git LFS client negotiates with the GitLab LFS API and uploads the binary payload directly to GitLab object storage over HTTPS, bypassing the Git packfile transfer. When other team members run git clone or git pull, Git downloads the small pointer files first, and the LFS client retrieves the matching binary objects.

A common misconception among engineering teams is that Git LFS provides unlimited file storage that bypasses GitLab repository size caps. In reality, GitLab SaaS restricts git push requests to 5 GiB through Cloudflare with a 10 GB repository storage limit that includes all stored LFS assets. If a project contains standard Git history and several large Git LFS objects, the project crosses the storage threshold once their cumulative total reaches the ceiling.

Once a project crosses its cumulative storage threshold, GitLab switches the project into a read-only state. Team members cannot push commits, upload new LFS assets, or merge pull requests until storage drops below the quota or the organization purchases additional storage packs. Git LFS prevents local git clone commands from downloading unused asset versions, but it does not exempt your team from GitLab repository storage pricing.

Administrators managing self-hosted GitLab Omnibus or cloud-native installations can adjust default upload and push limits through the GitLab Admin Area. However, adjusting the application setting alone is rarely sufficient, as underlying web proxies and client buffers enforce independent ceilings.

To increase the maximum file attachment size in the GitLab web interface:

1. Log in to your self-managed GitLab instance with administrator credentials.
2. In the top navigation bar, select Admin.
3. In the left navigation menu, go to Settings and select General.
4. Expand the Account and limit section.
5. Locate Maximum attachment size (MiB) and enter your desired threshold. The default value is 100 MiB.
6. Locate Maximum push size (MiB). Setting this value to 0 allows pushes up to the web server buffer limit.
7. Select Save changes.

Even after updating the Admin Area, administrators often find that large uploads continue failing with HTTP 413 Request Entity Too Large errors. This failure occurs because Omnibus GitLab routes web traffic through an embedded NGINX reverse proxy that enforces its own body size restriction.

To align NGINX with your application settings, edit the Omnibus configuration file:

nginx['client_max_body_size'] = "500m"

After modifying the configuration file, apply the changes by running the reconfiguration command:

sudo gitlab-ctl reconfigure

A third bottleneck exists in GitLab Workhorse, the reverse proxy daemon that handles Git HTTP traffic, file uploads, and LFS streaming. Workhorse buffers incoming uploads before handing metadata to Puma and Rails. If an external load balancer, such as an AWS Application Load Balancer or Cloudflare proxy, sits in front of GitLab, its request timeout and body size limits must also match or exceed your configured threshold.

On the developer side, pushing large commits over HTTP can fail due to local Git buffer constraints. When Git attempts to push a large packfile over an HTTPS connection, the local curl transport can run out of memory or timeout. Developers can resolve this client-side bottleneck by increasing the local post buffer:

git config --global http.postBuffer 524288000

Increasing http.postBuffer allocates additional memory buffer space for Git HTTP transactions. On GitLab SaaS, administrators cannot modify NGINX or Workhorse settings. As documented in official limits, GitLab SaaS restricts git push requests to 5 GiB through Cloudflare with a 10 GB repository storage limit, keeping edge transfer boundaries fixed.

Store and Index AI Datasets Beyond GitLab Repository Caps

Decouple heavy models, training corpora, and build artifacts into shared workspaces with persistent file versioning, semantic search, and consolidated MCP tooling for AI agents. Monthly plans start with a 30-day free trial.

Start 30-Day Trial

The rapid rise of autonomous coding agents, including Claude Code, Cursor, Codex, OpenClaw, and Cline, has turned repository storage management into a daily operational challenge. Human software engineers commit source code incrementally, rarely adding more than a few megabytes of text files per sprint. Autonomous agents operate in continuous loops, generating test fixtures, benchmark traces, synthetic datasets, and intermediate build artifacts across dozens of automated coding sessions.

When an AI coding agent is tasked with running full integration suites or training local models, it frequently writes heavy binary assets into the project workspace:

• SQLite databases created during local automated testing.
• Synthetic mock media, audio samples, or video clips used for pipeline validation.
• Intermediate ONNX models or PyTorch checkpoint weights produced during model evaluation.
• High-volume execution logs and profiler memory dumps.

If the repository .gitignore file does not anticipate every agent artifact path, the agent commits these binary files directly into Git. Once committed, the damage to Git history is permanent. Even if a subsequent cleanup commit removes the files using git rm, Git retains the full object blobs in the hidden .git directory to preserve historical checkout capability.

This repository bloat mirrors the context window bottlenecks developers experience with Anthropic's Claude. In Claude, a chat accepts attachments while Claude Projects accepts files with no fixed file count cap. However, Claude Projects remains practically bounded by the model context window. When a corpus expands beyond what fits comfortably inside context memory, adding more project files degrades response quality and triggers context exhaustion.

The same architectural mistake occurs in version control. Storing heavy data files inside a code repository clutters version control and risks quota lockouts. In cloud environments where GitLab SaaS restricts git push requests to 5 GiB through Cloudflare with a 10 GB repository storage limit, pushing repetitive binary fixtures pushes project storage beyond the ceiling. GitLab locks the repository against further writes, pushes are rejected, merge requests cannot be completed, and CI/CD pipelines fail until an engineer intervenes.

To prevent repository bloat and avoid hitting GitLab storage limits, software teams decouple application source code from binary assets, training corpora, and agent context. Source code belongs in GitLab, where pull requests, code reviews, and CI/CD workflows thrive. Large datasets, media files, and agent outputs belong in dedicated persistent workspaces.

Engineering teams evaluate several storage patterns when implementing this separation:

1. Raw Cloud Object Storage (Amazon S3 or Google Cloud Storage): S3 buckets provide scalable object storage at low cost. However, raw object storage lacks interactive file inspection interfaces, document viewers, and built-in semantic search. Engineering teams must build custom presigned URL generation services, manage IAM roles, and build internal dashboards for non-technical team members who need to review files.
2. Consumer Cloud Drives (Google Drive, Dropbox, Box): Consumer cloud drives offer familiar file browsing interfaces. However, programmatic agent integration remains brittle. Frequent OAuth refresh token expirations, rigid API rate limits, and desktop sync latency make cloud drives difficult to coordinate with autonomous AI agents that require deterministic, immediate file reads and writes. Cloud Sync is available for Dropbox, Box, and OneDrive on a schedule or on demand, while Google Drive operates via import with sync planned for the future.
3. Persistent Intelligent Workspaces: Modern development architectures use shared persistent workspaces designed for human-agent collaboration. Platforms like Fast.io provide organization-owned workspaces where files are stored with per-file version history, granular access controls, advisory file locks, and branded shares that do not expire. Teams seeking dedicated storage for agents can connect their automations to an intelligent workspace where files stay versioned and accessible.

When Intelligence Mode is enabled on a workspace, incoming documents, code exports, and datasets are automatically indexed for full-text and semantic search. Rather than uploading bloated files directly into GitLab or cramming full datasets into LLM context windows, an AI agent interacts with the workspace using a Model Context Protocol server. The agent queries indexed files through semantic search, retrieves precise citations, and writes lightweight reference links into repository documentation.

The following Python example shows how an automation worker or CI pipeline offloads a build artifact to an external workspace using the Fast.io API with the standard httpx library, committing only the durable URL reference to GitLab:

import httpx

FASTIO_WORKSPACE_ID = "ws_project_artifacts_123"
FASTIO_API_KEY = "fastio_api_token_sample"
UPLOAD_URL = f"https://api.fast.io/current/workspace/{FASTIO_WORKSPACE_ID}/storage/root/addfile/"

def store_agent_artifact(local_file_path: str, artifact_name: str) -> dict:
    with open(local_file_path, "rb") as file_handle:
        file_bytes = file_handle.read()
    headers = {"Authorization": f"Bearer {FASTIO_API_KEY}"}
    files = {"file": (artifact_name, file_bytes, "application/octet-stream")}
    response = httpx.post(UPLOAD_URL, headers=headers, files=files, timeout=60.0)
    response.raise_for_status()
    payload = response.json()
    share_url = payload.get("data", {}).get("share_url", "")
    return {
        "artifact_name": artifact_name,
        "byte_size": len(file_bytes),
        "durable_url": share_url,
        "status": "stored_externally",
    }

By offloading multi-megabyte binaries to dedicated workspace storage, the GitLab repository remains lean, clones complete in seconds, and AI coding agents can persist outputs without exhausting Git storage quotas. Teams evaluating long-term workspace architecture can start a 14-day free trial to test external document indexing and durable links. Monthly plans start with a 30-day free trial that requires a credit card, providing scalable storage tiers for growing teams.

When a GitLab repository approaches its storage threshold, engineering teams must audit disk usage and remove unneeded assets before the repository enters a read-only lock state. Reclaiming space requires inspecting project storage components and scrubbing historical Git history.

To audit storage allocation on GitLab:

1. Open your project in GitLab.
2. In the left navigation menu, go to Settings and select Usage quotas.
3. Select the Storage tab. GitLab displays a detailed breakdown across Repository, Git LFS, Job Artifacts, and Package Registry.

In many development pipelines, CI/CD job artifacts consume more disk space than the actual Git repository. Build logs, coverage reports, and compiled binaries accumulate across hundreds of pipeline runs. Teams can reclaim significant space by enforcing artifact expiration in the project .gitlab-ci.yml configuration file:

test_job:
  stage: test
  script:
    - npm test
  artifacts:
    expire_in: 7 days
    paths:
      - coverage/

Setting expire_in to 7 days prompts GitLab background cleanup jobs to purge older artifacts automatically.

If large files were accidentally committed directly to Git history, simply deleting them with git rm will not reduce repository size. The historical commits remain inside the packfile. To purge large files from Git history permanently, use the modern git-filter-repo utility:

git clone --mirror git@gitlab.com:example-org/project-repo.git
cd project-repo.git
git filter-repo --strip-blobs-bigger-than 50M
git push origin --force --all
git push origin --force --tags

Running git-filter-repo rewrites commit hashes across your repository. Team members must re-clone the repository after history rewriting to avoid re-introducing pruned blobs during subsequent pushes.

On self-managed instances, administrators can clean up unreferenced Git LFS objects and orphaned files by running the GitLab Rake maintenance routine:

sudo gitlab-rake gitlab:cleanup:orphan_lfs_file_references

Finally, establish proactive repository guardrails to prevent accidental binary commits. In Project Settings, navigate to Repository and expand Push rules. Configure the Maximum file size rule to reject commits containing large binaries, and add regex rejection patterns for archive formats. Enforcing push rules requires human developers and autonomous AI agents to route heavy files to external workspaces rather than bloating Git version control.