Skip to content

[FEAT] Check required locked files and directories #499

Description

@Karine-Bauch

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:

  1. Read the configured paths from .plumber.yaml.
  2. Retrieve the project's current default-branch file and directory locks.
  3. Normalize configured paths and locked paths.
  4. For each configured path:
    • check for an exact lock;
    • check whether one of its parent directories is locked.
  5. 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.yml

GitLab lock:

config/

Expected result:

PASS

File explicitly locked

Configuration:

paths:
  - .gitlab-ci.yml

GitLab lock:

.gitlab-ci.yml

Expected result:

PASS

File not locked

Configuration:

paths:
  - CODEOWNERS

No 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
  - CODEOWNERS

If 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

  1. p1-dta commented on Sep 28, 2026

    @p1-dta
    Contributor

    Thanks, I have nothing to add.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions