Skip to content

Allow Prohibited Files When Pushed to LFS

Release notes

Add option to allow files matching push rule filename restrictions when they are stored in Git LFS, providing flexibility for teams using LFS to manage large binary files that may have restricted extensions.

Problem to solve

Currently, GitLab's push rules for prohibited filenames (file_name_regex) apply universally to all files, regardless of how they are stored. This creates friction for teams using Git LFS to manage large binary files (like .png, .dmg, .zip, etc.) that may have extensions matching prohibited filename patterns.

For example, a team may want to:

  • Block .png files from being committed directly to Git (to prevent repository bloat)
  • But allow .png files when stored in LFS (acceptable since they're tracked separately and don't bloat the repository)

This is particularly relevant for GitLab Dedicated customers who cannot implement server-side hooks for custom repository policies and rely entirely on GitLab's built-in push rules functionality.

This is similar to how the max_file_size push rule already works - large files are naturally exempt when stored as LFS pointers because the pointers themselves are small text files.

Intended users

  • Development teams using Git LFS for binary asset management
  • DevOps engineers configuring repository policies
  • GitLab Dedicated customers who need flexible push rules without server-side hooks
  • Security teams who want to restrict direct commits of certain file types while allowing LFS storage
  • Game development teams managing large binary assets
  • Design teams working with large media files

User experience goal

Users should be able to configure push rules that distinguish between files committed directly to Git versus files stored in LFS, providing more granular control over repository policies without blocking legitimate LFS usage.

Proposal

Add a new boolean setting allow_prohibited_files_in_lfs to push rules that, when enabled, exempts files stored in Git LFS from filename prohibition rules.

Implementation approach:

  • Add new boolean field to push rule models (project, group, and organization levels)
  • Modify the filename validation logic in EE::Gitlab::Checks::DiffCheck#file_name_validation to check if a file is an LFS pointer using blob&.lfs_pointer? when the setting is enabled
  • Only perform LFS detection for files that already match the prohibited filename regex (minimal performance impact)
  • Default the setting to false (disabled) to maintain backward compatibility
  • Mark as experimental in the UI with appropriate warnings (similar to diff file limit settings)

User workflow:

  1. Administrator enables "Allow prohibited files in LFS" in push rules settings
  2. Developer attempts to push a .png file directly → blocked by filename rule
  3. Developer configures Git LFS to track *.png files and pushes → allowed (file is stored as LFS pointer)

Further details

Technical implementation:

  • The feature leverages existing LFS pointer detection (Gitlab::Git::Blob#lfs_pointer?)
  • LFS pointers are small text files (120-200 bytes) containing metadata, not the actual binary content
  • Validation only occurs for files matching the prohibited regex, ensuring minimal performance impact
  • No changes needed to Gitaly or other core Git operations

Performance considerations:

  • Zero performance impact when the feature is disabled
  • When enabled, only files matching the prohibited filename pattern trigger LFS detection
  • LFS pointer detection is already optimized (size check first, then content pattern matching)

Experimental release approach:

  • Release as experimental feature with clear UI warnings (similar to diff file limit settings)
  • Feature flags are not suitable for this feature as GitLab Dedicated customers cannot access feature flag controls and this functionality is particularly valuable for them
  • Gather user feedback before marking as stable

Permissions and Security

  • Requires push rule configuration permissions (same as existing push rule settings)
  • Maintains security by still blocking direct commits of prohibited file types
  • LFS files are stored separately and can be managed with different access controls
  • No additional security risks introduced

Documentation

  • Update push rules documentation to describe the new experimental setting
  • Add examples showing the difference between direct commits vs LFS storage (using .png files)
  • Include configuration instructions for both UI and API
  • Update API documentation for push rules endpoints
  • Document the experimental nature and encourage feedback

Availability & Testing

  • Release as experimental feature without feature flag (following the pattern of diff file limit settings)
  • Include clear experimental warnings in the UI
  • Comprehensive test coverage for:
    • Files matching prohibited patterns committed directly (should be blocked)
    • Files matching prohibited patterns stored in LFS (should be allowed when setting enabled)
    • Performance impact testing
    • Edge cases (corrupted LFS pointers, etc.)

Available Tier

Premium and Ultimate (same as existing push rules feature)

Feature Usage Metrics

Track usage through:

  • Number of projects/groups with the setting enabled
  • Number of pushes where LFS exemption was applied
  • Adoption rate over time
  • User feedback on experimental feature

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

Success metrics:

  • Reduced friction for teams using LFS (fewer support requests about blocked LFS files)
  • Increased adoption of Git LFS for binary file management
  • Positive user feedback on the flexibility of push rule configuration
  • Particular adoption by GitLab Dedicated customers

Measurement:

  • Monitor support ticket volume related to push rule conflicts with LFS
  • Track feature adoption rates, especially among Dedicated customers
  • Collect user feedback through surveys or issue comments
  • Monitor experimental feature feedback

What is the type of buyer?

Organizations using GitLab Premium/Ultimate who:

  • Have security or compliance requirements for repository content
  • Use Git LFS for binary asset management
  • Need granular control over repository policies
  • GitLab Dedicated customers who cannot implement server-side hooks

Is this a cross-stage feature?

This is primarily a Source Code Management feature within the Create stage, specifically related to push rules functionality.

What is the competitive advantage or differentiation for this feature?

This feature provides more sophisticated and user-friendly repository policy management compared to competitors, allowing organizations to:

  • Implement security policies without hindering developer productivity
  • Better support modern Git workflows that include LFS
  • Provide more granular control than simple "allow/block" rules
  • Offer GitLab Dedicated customers functionality typically requiring server-side hooks

Binary asset management competitive advantage: This feature significantly enhances GitLab's binary asset management capabilities, making Git workflows more efficient and practical for teams handling large binary files. This improvement helps make Perforce-to-Git migrations more attractive by addressing one of the key pain points in Git's binary file handling. In industries where Perforce dominates (game development, media production, CAD/engineering), this granular control over binary file policies can be a decisive factor in choosing GitLab over competitors, as it provides the policy flexibility that teams migrating from Perforce expect while maintaining Git's distributed workflow advantages.

Links / references