Repository navigation
Description
Is your feature request related to a problem? Please describe.
Suggestion from @p1-dta
GitLab (only for Premium and Ultimate) provide default branch file and directory locks, allowing specific files or directories to be locked on the default branch.
This can be useful for sensitive or critical repository files such as:
.gitlab-ci.yml
.plumber.yaml
CODEOWNERS
pyproject.toml
uv.lock
or entire directories containing sensitive configuration.
However, there is currently no Plumber control to verify that files or directories expected to be locked are actually locked in the GitLab project.
A lock can be removed accidentally or simply forgotten when a project is created, leaving critical repository files modifiable while the project configuration still assumes they are protected.
Describe the solution you'd like
Add a new GitLab control that allows users to define a list of files and/or directories that are expected to be locked.
Suggested control name:
repositoryFilesMustBeLocked
Plumber would retrieve the current GitLab file/directory locks and verify that every configured path is covered by a lock.
For example:
controls:
repositoryFilesMustBeLocked:
enabled: true
paths:
- .gitlab-ci.yml
- .plumber.yaml
- CODEOWNERS
- config/Plumber should emit a finding for each configured path that is not locked.
Example:
.gitlab-ci.yml is locked ✓
.plumber.yaml is locked ✓
CODEOWNERS is not locked ✗
config/ is not locked ✗
A directory lock should also satisfy files located inside that directory.
For example, if the following directory is locked:
config/
then:
config/security.yml
config/deployment.yml
should be considered protected by the control.
Configuration in .plumber.yaml
controls:
repositoryFilesMustBeLocked:
enabled: true
paths:
- .gitlab-ci.yml
- .plumber.yaml
- CODEOWNERS
- config/Each configured path should be checked independently.
Each missing lock should generate a separate finding so users can identify exactly which expected protection is missing.
Implementation Hints
GitLab provides default branch file and directory locks for Premium and Ultimate projects.
These locks apply only to the project's default branch.
When a file or directory is locked:
- only the user who created the lock can modify it directly on the default branch;
- for other users, the locked path is read-only on the default branch;
- direct changes to the locked path on the default branch are blocked;
- merge requests modifying the locked path can only be merged if the merge request author is the lock owner.
The merge check is based on the merge request author, not on individual commit authors. Other users can still push changes to the merge request branch.
GitLab also supports directory locks, so the control should take parent directory locks into account.
For example:
config/
being locked should satisfy:
config/security.yml
The implementation could:
- Read the configured
pathsfrom.plumber.yaml. - Retrieve the project's current default-branch file and directory locks.
- Normalize configured paths and locked paths.
- For each configured path:
- check for an exact lock;
- check whether one of its parent directories is locked.
- Emit one finding for each configured path that is not covered by a lock.
The GitLab documentation exposes these locks through the UI under:
Code > Locked files
The exact GitLab API or GraphQL endpoint exposing default branch file and directory locks should be confirmed against the GitLab versions supported by Plumber before implementation.
This control should specifically target GitLab default branch file and directory locks, not Git LFS exclusive locks, as these are two different locking mechanisms.
The feature is currently available for GitLab Premium and Ultimate, so the control should handle unsupported GitLab tiers gracefully.
For example, if the GitLab instance does not support default branch locks, Plumber should report that the control cannot be evaluated rather than treating every configured file as unlocked.
Edge cases
Parent directory locked
Configuration:
paths:
- config/security.ymlGitLab lock:
config/
Expected result:
PASS
File explicitly locked
Configuration:
paths:
- .gitlab-ci.ymlGitLab lock:
.gitlab-ci.yml
Expected result:
PASS
File not locked
Configuration:
paths:
- CODEOWNERSNo corresponding file or parent directory lock exists.
Expected result:
FINDING: CODEOWNERS is expected to be locked but is not locked.
Multiple missing paths
Configuration:
paths:
- .gitlab-ci.yml
- .plumber.yaml
- CODEOWNERSIf only .gitlab-ci.yml is locked, two separate findings should be generated:
.plumber.yaml is expected to be locked but is not locked.
CODEOWNERS is expected to be locked but is not locked.
Unsupported GitLab tier
If the project is hosted on a GitLab tier where default branch file and directory locks are unavailable, the control should not produce misleading "unlocked file" findings.
Instead, it should clearly indicate that the control cannot be evaluated because the GitLab feature is unavailable.
Why It's Valuable
Some repository files have a much larger security or operational impact than normal source files.
For example, modifying:
.gitlab-ci.yml
.plumber.yaml
CODEOWNERS
can affect CI/CD execution, security controls, or repository governance.
GitLab already provides a mechanism to lock these files or directories, but there is currently no automated way in Plumber to ensure that the expected locks remain configured.
This control would allow organizations to:
- define which repository files or directories must remain locked;
- continuously verify that those protections are still present;
- detect accidental removal of locks;
- enforce consistent repository governance across projects;
- include repository-level protections in Plumber's compliance checks.
GitLab documentation:
https://docs.gitlab.com/user/project/file_lock/#lock-a-file-or-directory
Activity
p1-dta commentedon Sep 28, 2026
Thanks, I have nothing to add.