Your GitLab CI jobs are failing because the artifacts they’re trying to save exceed GitLab’s configured size limits.
The most common culprit is simply generating too much data that gets bundled into artifacts. This could be compiled code, test reports, logs, or any other output from your build process that you’ve explicitly told GitLab to save.
Here’s a breakdown of common causes and how to fix them:
1. Unnecessary Files in Artifacts
Diagnosis: You’re archiving more than you need. Look at your .gitlab-ci.yml file. The artifacts: paths: directive is likely pointing to broad directories or many individual files.
Cause: A common mistake is to include entire build directories (build/ or dist/) without cleaning them up first, or archiving all logs (*.log).
Fix: Be specific. Instead of artifacts: paths: [build/], try artifacts: paths: [build/my-app.js, build/my-app.css, build/assets/*]. For logs, explicitly list important ones or use a pattern that captures only what’s essential, like artifacts: paths: [logs/latest.log].
Why it works: This precisely targets only the files that are absolutely necessary for subsequent jobs or for user download, dramatically reducing the artifact size.
2. Large Compiled Binaries or Dependencies
Diagnosis: Your build process produces massive executable files or a huge number of dependencies. Check the size of individual files within your artifact paths.
Cause: Compiling large applications, especially with many libraries or without stripping debug symbols, can lead to very large binaries. Similarly, front-end projects that pull in many large npm packages can balloon.
Fix:
- For compiled languages: Use build flags to strip debug symbols. For example, with GCC, use
-sor-Wl,-s. For Go,go build -ldflags="-s -w"can significantly reduce binary size. - For Node.js projects: Use tools like
npm prune --productionin your artifact path before archiving to remove development dependencies, or configure your build to only include necessary files.
Why it works: Stripping debug symbols removes extraneous information from executables, and pruning dependencies removes development-only packages that aren’t needed in production or for downstream CI stages.
3. Excessive Test Reports or Coverage Data
Diagnosis: Test reports (e.g., JUnit XML) or code coverage reports are often generated as artifacts. Check the size of these specific files.
Cause: Some testing frameworks can generate very verbose reports, especially when dealing with large test suites or complex coverage metrics.
Fix: Configure your test runner to generate more concise reports. For example, in many Java test runners, you can disable verbose logging or specific report types. For coverage, consider if you need detailed line-by-line coverage for every file in every job, or if aggregated reports suffice. You can often filter what gets included in coverage generation.
Why it works: By reducing the verbosity or scope of generated reports, you directly cut down on the data size being archived.
4. Large Docker Images (if building/pushing within CI)
Diagnosis: If your CI job builds or pushes Docker images, and you’re trying to artifact the image itself (which is rare but possible, or you’re artifacting build artifacts from a large image), the image size is the problem.
Cause: Docker images can become very large due to unoptimized Dockerfiles, caching layers, or including unnecessary build tools.
Fix: Optimize your Dockerfile:
- Use multi-stage builds to separate build dependencies from runtime dependencies.
- Clean up package manager caches (
apt-get clean,rm -rf /var/lib/apt/lists/*). - Use
.dockerignoreto prevent unnecessary files from being copied into the build context.
Why it works: Multi-stage builds ensure only the final, lean application and its runtime dependencies are in the final image. Cleaning caches and using .dockerignore reduce the overall size of the layers.
5. GitLab Runner Configuration (Less Common but Possible)
Diagnosis: While less frequent, the GitLab Runner itself might have configuration that impacts artifact handling. Check the runner’s config.toml file.
Cause: The concurrent setting in the config.toml can affect how many jobs run simultaneously. If you have many jobs trying to upload artifacts at once, it could, in rare cases, lead to timeouts or resource exhaustion that manifests as artifact errors. More directly, the artifacts_max_size setting on the runner itself is a hard limit.
Fix:
- Increase
artifacts_max_size: In/etc/gitlab-runner/config.toml(or wherever your runner config is), find the[[runners]]section and add/modifyartifacts_max_size = 0(for unlimited, use with caution) or a sufficiently large value (e.g.,artifacts_max_size = 2048for 2GB). Restart the runner service. - Adjust
concurrent: If you have very high concurrency, consider reducing it toconcurrent = 4orconcurrent = 8if your runner machine has limited CPU/RAM.
Why it works: artifacts_max_size directly increases the limit for artifact uploads. Adjusting concurrency can prevent resource contention if multiple large artifact uploads are happening simultaneously.
6. GitLab Server Configuration (If Self-Hosted)
Diagnosis: If you’re running a self-hosted GitLab instance, the artifact size limit is controlled at the server level.
Cause: The GitLab server has a default artifact size limit, typically set in gitlab.rb.
Fix: Edit your GitLab configuration file (/etc/gitlab/gitlab.rb on a Linux server) and add or modify the following line:
gitlab_rails['artifacts_size_limit'] = 2147483648 # Example: 2GB in bytes
Then, reconfigure GitLab:
sudo gitlab-ctl reconfigure
Why it works: This directive directly increases the maximum allowed size for any artifact uploaded to your GitLab instance.
After implementing these fixes, your next likely error will be Your repository is too large to clone.