Skip to content

Enhance push rule error messages to show filenames instead of blob IDs

Release notes

Enhanced push rule error messages now display specific filenames and file sizes when files are rejected, making it easier for developers to identify and resolve issues with oversized files and understand Git LFS requirements.

Problem to solve

As a Developer or Platform Engineer, when my push is rejected due to file size limits or other push rules, I want to see exactly which files were rejected and why, so I can quickly resolve the issue without having to decode blob IDs or guess which files caused the problem.

Currently, push rule error messages show cryptic blob IDs like 6a88374be83e5797c92caba0c788d93833dc96ec (4.97 MiB) which requires developers to run additional git commands to identify the actual files, slowing down their workflow and creating frustration.

Intended users

User experience goal

The user should be able to immediately understand which specific files were rejected by push rules and receive actionable guidance on how to resolve the issue, without needing to run additional git commands or decode blob references.

Proposal

Enhance push rule error messages to include:

  1. Clear file identification: Show actual file paths instead of blob IDs
  2. File size information: Display individual file sizes alongside the limit
  3. Actionable guidance: Provide specific commands or next steps
  4. Better formatting: Organize information in a scannable format

Current behavior

remote: GitLab: You are attempting to check in one or more files which exceed the 4MiB limit. 
remote: 
remote: - 6a88374be83e5797c92caba0c788d93833dc96ec (4.97 MiB) r
remote: 
remote: To resolve this error, you must either reduce the size of the above blobs, or utilize Git LFS. remote: You may use "git ls-tree -r HEAD | grep $BLOB_ID" to see the file path.

Proposed enhanced behavior

remote: GitLab: You are attempting to check in one or more files which exceed the 4MiB limit.
remote: 
remote: The following files were rejected:
remote:   - src/assets/large-video.mp4 (4.97 MiB) - exceeds 4MiB limit
remote:   - docs/presentation.pptx (8.2 MiB) - exceeds 4MiB limit
remote:   - data/dataset.csv (12.5 MiB) - exceeds 4MiB limit
remote: 
remote: To resolve this error, you can:
remote:   1. Remove these files from your commit
remote:   2. Use Git LFS to track these files: git lfs track "*.mp4" "*.pptx" "*.csv"
remote:   3. Reduce file sizes before committing
remote: 
remote: For Git LFS setup instructions, visit: https://docs.gitlab.com/ee/topics/git/lfs/

Further details

Use cases:

  • Large media files (videos, images, presentations) accidentally committed
  • Data files (CSVs, databases) exceeding size limits
  • Binary artifacts that should use Git LFS
  • Developers working in teams where file size policies are enforced

Benefits:

  • Reduced developer friction and faster problem resolution
  • Better developer experience when working with Git LFS
  • Clear guidance on compliance with organizational policies
  • Reduced support tickets and confusion

Current pain points:

  • Developers must manually decode blob IDs using git commands
  • Unclear which specific files are problematic
  • Limited actionable guidance on resolution steps
  • Poor user experience when encountering file size limits

Permissions and Security

This enhancement affects the error message display only and does not change any permission models. Push rule enforcement permissions remain unchanged:

  • No impact to members with no access (0)
  • No impact to Guest (10) members
  • No impact to Reporter (20) members
  • Developer (30) members see enhanced error messages when push fails
  • Maintainer (40) members see enhanced error messages when push fails
  • Owner (50) members see enhanced error messages when push fails

The enhancement only affects error message content and does not expose additional repository information beyond what's already available in the rejected push.

Documentation

  • Update push rules documentation to reflect new error message format
  • Add examples of enhanced error messages to troubleshooting guides
  • Update Git LFS documentation to reference improved error messaging
  • Consider adding to developer workflow documentation

Availability & Testing

Test coverage needed:

  • Unit tests: Verify error message formatting for various file types and sizes
  • Integration tests: Test push rule rejection scenarios with new message format
  • End-to-end tests: Validate complete developer workflow with enhanced messages

Risk assessment:

  • Low risk change affecting only error message display
  • No impact on core Git operations or repository functionality
  • Improved user experience with minimal technical complexity

Available Tier

  • Premium
  • Ultimate

(Push rules are only available in Premium and Ultimate tiers)

Feature Usage Metrics

Track usage through:

  • Push rule violation frequency (existing metric)
  • Developer workflow completion after receiving enhanced errors
  • Reduction in support tickets related to push rule confusion
  • Time to resolution for file size issues

What does success look like, and how can we measure that?

Success metrics:

  • Decreased average time from push rejection to successful resolution
  • Reduced support tickets related to push rule error confusion
  • Improved developer satisfaction scores for Git workflow experience
  • Increased adoption of Git LFS for appropriate file types

Acceptance criteria:

  • Error messages display actual filenames instead of blob IDs
  • File sizes are shown clearly alongside limits
  • Actionable guidance is provided for common resolution steps
  • Messages remain performant even with multiple rejected files
  • Formatting is consistent and readable across different terminal environments

What is the type of buyer?

Enterprise/Premium buyer - Organizations that enforce development standards and compliance policies through push rules. This feature supports enterprise governance and developer productivity requirements.

Is this a cross-stage feature?

This feature primarily affects the Source Code stage but may have minor touchpoints with:

  • Documentation for updated guides
  • Growth for improved developer experience metrics

What is the competitive advantage or differentiation for this feature?

Enhanced developer experience in enterprise Git workflows, positioning GitLab as developer-friendly while maintaining enterprise governance capabilities. Reduces friction in compliance-heavy environments where push rules are essential.

Links / references

Edited by 🤖 GitLab Bot 🤖