Code Owners development guidelines contribute
This document was created to help contributors understand the code design of Code Owners. You should read this document before making changes to the code for this feature.
This document is intentionally limited to an overview of how the code is designed, as code can change often. To understand how a specific part of the feature works, view the code and the specs. The details here explain how the major components of the Code Owners feature work.
This document should be updated when parts of the codebase referenced in this document are updated, removed, or new parts are added.
Business logic
All of the business logic for code owners is located in the Gitlab::CodeOwners
namespace. Code Owners is an EE-only feature, so the files only exist in the ./ee
directory.
Gitlab::CodeOwners
: the main module used to interact with the code owner rules.- Defined in
./ee/lib/gitlab/code_owners.rb
.
- Defined in
Gitlab::CodeOwners::File
: wraps aCODEOWNERS
file and exposes the data through the class’ public methods.- Defined in
./ee/lib/gitlab/code_owners/file.rb
.
- Defined in
Gitlab::CodeOwners::Section
: wraps a section heading from aCODEOWNERS
file and parses the different parts.- Defined in
./ee/lib/gitlab/code_owners/section.rb
.
- Defined in
Gitlab::CodeOwners::Entry
: wraps an entry (a pattern and owners line) in aCODEOWNERS
file and exposes the data through the class’ public methods.- Defined in
./ee/lib/gitlab/code_owners/entry.rb
.
- Defined in
Gitlab::CodeOwners::Loader
: finds the correctCODEOWNER
file and loads the content into aGitlab::CodeOwners::File
instance.- Defined in
./ee/lib/gitlab/code_owners/loader.rb
.
- Defined in
Gitlab::CodeOwners::ReferenceExtractor
: extractsCODEOWNER
user, group, and email references from texts.- Defined in
./ee/lib/gitlab/code_owners/reference_extractor.rb
.
- Defined in
Gitlab::CodeOwners::UsersLoader
: the correctCODEOWNER
file and loads the content into aGitlab::CodeOwners::File
instance.- Defined in
./ee/lib/gitlab/code_owners/users_loader.rb
.
- Defined in
Gitlab::CodeOwners::GroupsLoader
: finds the correctCODEOWNER
file and loads the content into aGitlab::CodeOwners::File
instance.- Defined in
./ee/lib/gitlab/code_owners/groups_loader.rb
.
- Defined in
Gitlab::CodeOwners::Validator
: validates no files in theCODEOWNERS
entries have been changed when a user pushes to a protected branch withrequire_code_owner_approval
enabled.- Defined in
./ee/lib/gitlab/code_owners/validator.rb
.
- Defined in
Where Code Owners sits in the Git access check execution order
Gitlab::Checks::DiffCheck#file_paths_validations
returns either an empty array, or an array with a single member of the results of #lfs_file_locks_validation
if LFS is enabled and file locks are present. The return result of #validate_code_owners
in the EE version of this file is inserted at the end of this list in the EE::Gitlab::Checks::DiffCheck#file_paths_validations
. LFS checks are performed before Code Owners checks.
These checks are executed after those listed in #validations_for_path
, which exists only in the EE version, and include #path_locks_validation
and #file_name_validation
. This means that checks for Path Locks precede checks for Code Owners in the flow.
The check order is as follows in EE
(only LFS exists as a non-EE feature):
- Path Locks
- Filenames
- Blocks files containing secrets for example
id_rsa
- Blocks files matching the
PushRule#file_name_regex
- Blocks files containing secrets for example
- LFS File Locks
- Code Owners
Related models
ProtectedBranch
The ProtectedBranch
model is defined in app/models/protected_branch.rb
and
extended in ee/app/models/concerns/ee/protected_branch.rb
. The EE version includes a column
named require_code_owner_approval
which prevents changes from being pushed directly
to the branch being protected if the file is listed in CODEOWNERS
.
ApprovalMergeRequestRule
The ApprovalMergeRequestRule
model is defined in ee/app/models/approval_merge_request_rule.rb
.
The model stores approval rules for a merge request. We use multiple rule types,
including a code_owner
type rule.
Controllers and Services
The following controllers and services below are being used for the approval rules feature to work:
Api::Internal::Base
This /internal/allowed
endpoint is called when pushing to GitLab to ensure the
user is allowed to push. The /internal/allowed
endpoint performs a Gitlab::Checks::DiffCheck
.
In EE, this includes code owner checks.
Defined in lib/api/internal/base.rb
.
Repositories::GitHttpController
When changes are pushed to GitLab over HTTP, the controller performs an access check
to ensure the user is allowed to push. The checks perform a Gitlab::Checks::DiffCheck
.
In EE, this includes Code Owner checks.
Defined in app/controllers/repositories/git_http_controller.rb
.
EE::Gitlab::Checks::DiffCheck
This module extends the CE Gitlab::Checks::DiffChecks
class and adds code owner
validation. It uses the Gitlab::CodeOwner::Validator
class to verify users are
not pushing files listed in CODEOWNER
directly to a protected branch while the
branch requires code owner approval.
MergeRequests::SyncCodeOwnerApprovalRules
This service is defined in services/merge_requests/sync_code_owner_approval_rules.rb
and used for:
- Deleting outdated code owner approval rules when new changes are pushed to a merge request.
- Creating code owner approval rules for each changed file in a merge request that is also listed in the
CODEOWNER
file.
Flow
These flowcharts should help explain the flow from the controllers down to the models for different features.
A lot of the Code Owners implementations exist in the EE
variants of the classes.
Push changes to a protected branch with require_code_owner_approval
enabled, over SSH
Push changes to a protected branch with require_code_owner_approval
enabled, over HTTPS
Sync code owner rules to merge request approval rules
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support