Enable the REGISTRY_FF_ENFORCE_LOCKFILES feature flag by default
Summary
Enable the REGISTRY_FF_ENFORCE_LOCKFILES feature flag by default as part of the planned rollout timeline for lockfile enforcement in the container registry. This change is scheduled for the 18.9 milestone and follows the lockfile data repair work completed in 18.8.
Background
Lockfiles are a feature in the container registry that prevent simultaneous use of filesystem and database metadata storage modes. The REGISTRY_FF_ENFORCE_LOCKFILES feature flag controls whether these lockfiles are enforced during registry operations.
Current State:
- The feature flag was previously enabled by default in !2538 (merged) but was reverted due to lockfile state inconsistencies (#1776)
- Lockfile enforcement is already deployed and active on GitLab.com
- The feature flag was incorrectly implemented in multiple code paths, causing it to control lockfile management rather than just enforcement
Recent Fixes:
- 18.8 milestone includes lockfile data repair functionality (#1783, !2673 (merged)) to automatically correct inconsistent lockfile states on startup
- Fixes have been implemented for importer lockfile handling (!2648 (merged)) and application startup lockfile handling (!2649 (merged))
Rollout Timeline
This change is part of a phased approach to lockfile enforcement and metadata database adoption:
| Milestone | Action | Description |
|---|---|---|
| 18.8 | Lockfile data repair | Automatic repair of inconsistent lockfile states on startup (#1783) |
| 18.9 | Enable enforcement FF by default |
This issue - Make REGISTRY_FF_ENFORCE_LOCKFILES=true the default |
| 18.10 | Remove enforcement FF | Remove the feature flag entirely from the codebase |
| 19.0 | Prefer mode | Implement database.enabled: prefer configuration that intelligently selects between database and legacy metadata based on installation context. Fresh installs default to metadata database, existing installations continue with their current method (gitlab-org#19638) |
Proposal
Change the default value of REGISTRY_FF_ENFORCE_LOCKFILES from false to true in the 18.9 release.
Why now:
- The 18.8 lockfile repair functionality (#1783) will have been deployed, allowing instances with inconsistent states to self-heal
- The root cause bugs in lockfile management have been fixed (!2648 (merged), !2649 (merged))
- This provides one full milestone for instances to repair their lockfile states before enforcement becomes the default
- Enforcement is already proven stable on GitLab.com
- This is a prerequisite for the 19.0 prefer mode implementation, which relies on lockfiles to detect and enforce metadata storage modes
Implementation
- Update the feature flag default value to
true - Update documentation to reflect the new default behavior
Risks and Mitigation
Risk: Instances that haven't upgraded to 18.8 may still have inconsistent lockfile states
Mitigation:
- The 18.8 repair functionality will run automatically on upgrade
- Instances can disable the feature flag if issues arise:
REGISTRY_FF_ENFORCE_LOCKFILES=false - Clear documentation and workaround instructions are available in #1776
Success Criteria
- Feature flag default changed to
true - No increase in support requests related to lockfile issues
- Documentation updated to reflect new default
- Lockfile enforcement stable across self-managed instances in preparation for 19.0 prefer mode
Related Issues and MRs
Issues:
- #1776 - Fix: gracefully handle inconsistent lockfile states from REGISTRY_FF_ENFORCE_LOCKFILES misuse
- #1783 - Feat: Repair lockfile state inconsistencies on startup when enforcement is disabled
Merge Requests:
- !2538 (merged) - feat(registry): enable REGISTRY_FF_ENFORCE_LOCKFILES by default (reverted)
- !2647 (merged) - fix(registry): disable REGISTRY_FF_ENFORCE_LOCKFILES by default