How to update owners.yaml

This guide explains how to add, update, and maintain entries in owners.yaml. For the policies behind this file, see owners.yaml principles.

File structure

The file has two top-level sections:

users:
  - &jsmith                    # (1)
    email: jsmith@redhat.com
    gluser: jsmith
    name: John Smith

subsystems:
  - subsystem: Netfilter       # (2)
    maintainers:
      - *jsmith
    paths:
      includes:
        - net/netfilter/

User definitions use YAML anchors (&name) so they can be referenced by multiple subsystems.
Each subsystem entry maps kernel files to their responsible team.

Adding a new user

Add the user to the users: list with an anchor. The anchor is how you reference this person in subsystem entries.

users:
  - &jsmith
    email: jsmith@redhat.com
    gluser: jsmith             # GitLab username
    name: John Smith

Adding a new subsystem

Add an entry under subsystems:. At minimum you need subsystem, maintainers, and paths.

subsystems:
  - subsystem: My Subsystem
    status: Maintained
    requiredApproval: true
    maintainers:
      - *jsmith
    reviewers:
      - *jdoe
    devel-sst:
      - rhel-sst-my-team
    qe-sst:
      - rhel-sst-my-team-qe
    jiraComponent: kernel / My Component
    paths:
      includes:
        - drivers/my_driver/
        - include/linux/my_driver.h

Updating an existing subsystem

Find the subsystem entry and edit the relevant fields. Common changes:

Adding or removing a maintainer: Update the maintainers: list.
Changing the SST: Update devel-sst:.
Adding file coverage: Add paths to paths.includes:.

Fields reference

Field Description

Field	Description
`subsystem`	Human-readable name of the kernel technology.
`status`	Maintenance status (e.g. `Maintained`).
`requiredApproval`	`true` if MRs touching these files require maintainer approval.
`fallback`	`true` marks this as a catch-all subsystem (e.g. `kernel-general`). A fallback subsystem only claims a file when no other non-fallback subsystem matches it. This is how generic owners are assigned to files that would otherwise be completely unmapped. Most subsystems should not set this field.
`maintainers`	List of user references (`*anchor`) responsible for this subsystem.
`reviewers`	List of user references who review but do not own the subsystem.
`devel-sst`	The SST(s) tracking this subsystem.
`devel-assigned-team`	The specific scrum team within the SST.
`qe-sst`	The QE SST responsible for testing.
`jiraComponent`	The JIRA component for filed tickets (e.g. `kernel / Networking / Netfilter`).
`paths.includes`	File patterns that belong to this subsystem. See path matching rules below.
`paths.excludes`	File patterns to exclude from this subsystem even if they match an include.
`paths.includeRegexes`	Regular expressions for matching file paths (use sparingly).
`scm`	Upstream source repository URL.
`mailingList`	Upstream mailing list URL.
`testVariants`	Kernel build variants that should be tested for this subsystem.

subsystem

Human-readable name of the kernel technology.

status

Maintenance status (e.g. Maintained).

requiredApproval

true if MRs touching these files require maintainer approval.

fallback

true marks this as a catch-all subsystem (e.g. kernel-general). A fallback subsystem only claims a file when no other non-fallback subsystem matches it. This is how generic owners are assigned to files that would otherwise be completely unmapped. Most subsystems should not set this field.

maintainers

List of user references (*anchor) responsible for this subsystem.

reviewers

List of user references who review but do not own the subsystem.

devel-sst

The SST(s) tracking this subsystem.

devel-assigned-team

The specific scrum team within the SST.

qe-sst

The QE SST responsible for testing.

jiraComponent

The JIRA component for filed tickets (e.g. kernel / Networking / Netfilter).

paths.includes

File patterns that belong to this subsystem. See path matching rules below.

paths.excludes

File patterns to exclude from this subsystem even if they match an include.

paths.includeRegexes

Regular expressions for matching file paths (use sparingly).

scm

Upstream source repository URL.

mailingList

Upstream mailing list URL.

testVariants

Kernel build variants that should be tested for this subsystem.

Path matching rules

The matching engine splits both the pattern and the file path by / and compares them component by component using shell-style glob matching.

Matching files inside a directory

A pattern ending with / matches everything under that directory, at any depth.

paths:
  includes:
    - net/netfilter/        # matches net/netfilter/nf_tables.c
                            # matches net/netfilter/ipvs/ip_vs_core.c
                            # matches any file under net/netfilter/

Matching files by name pattern

A pattern without a trailing / matches files at that exact depth only.

paths:
  includes:
    - include/linux/netfilter*    # matches include/linux/netfilter.h
                                  # matches include/linux/netfilter_arp.h
                                  # does NOT match include/linux/netfilter/x_tables.h

The \* wildcard only matches within a single path component. It does not cross / boundaries.

Common mistake: missing directory coverage

If your subsystem has files named netfilter*.h at one level AND files inside a netfilter/ directory, you need both patterns:

paths:
  includes:
    - include/linux/netfilter*    # files like netfilter.h, netfilter_arp.h
    - include/linux/netfilter/    # files inside the netfilter/ directory

Without the second pattern, files like include/linux/netfilter/x_tables.h will be reported as unmapped by the tooling, even though they clearly belong to your subsystem.

Quick reference

Pattern Example file Matches?

Pattern	Example file	Matches?
`net/netfilter/`	`net/netfilter/ipvs/ip_vs.c`	Yes
`include/linux/netfilter*`	`include/linux/netfilter_arp.h`	Yes
`drivers/gpu/drm/`	`drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c`	Yes
`include/linux/netfilter*`	`include/linux/netfilter/x_tables.h`	No
`drivers/gpu/drm/*.c`	`drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c`	No

net/netfilter/

net/netfilter/ipvs/ip_vs.c

Yes

include/linux/netfilter*

include/linux/netfilter_arp.h

Yes

drivers/gpu/drm/

drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c

Yes

include/linux/netfilter*

include/linux/netfilter/x_tables.h

drivers/gpu/drm/*.c

drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c

Using excludes

If a directory mostly belongs to your subsystem but a subdirectory belongs to someone else, use excludes:

paths:
  includes:
    - drivers/net/ethernet/
  excludes:
    - drivers/net/ethernet/intel/    # owned by the Intel NIC subsystem

What happens when you submit a merge request

When you submit an MR that changes owners.yaml, the kernel-webhooks dochook automatically analyzes the diff and creates approval rules based on what changed. You do not need to manually request reviews — the webhook handles it.

Approval rules by change type

What you changed Who must approve Required?

What you changed	Who must approve	Required?
Subsystem paths, name, labels, status, mailing list, SCM	Existing maintainers of that subsystem (unless you are one)	Yes
Adding a maintainer or reviewer	The added person (unless they are the MR author) AND existing maintainers (unless you are one)	Yes
Removing a maintainer or reviewer	The removed person (if they are still a Red Hat employee and group member). Existing maintainers are encouraged but not required.	Person: Yes. Maintainers: Optional.
Changing `devel-sst`, `devel-assigned-team`, `jiraComponent`, `requiredApproval`	Existing maintainers (unless you are one)	Yes
Adding a new subsystem	Every maintainer and reviewer listed in the new entry (unless they are the MR author)	Yes
Deleting a subsystem	Every maintainer and reviewer from the deleted entry (if they are still employees and group members)	Yes
Removing ALL maintainers from a subsystem	Blocked — this produces an error. Every subsystem must have at least one maintainer.	N/A

Subsystem paths, name, labels, status, mailing list, SCM

Existing maintainers of that subsystem (unless you are one)

Yes

Adding a maintainer or reviewer

The added person (unless they are the MR author) AND existing maintainers (unless you are one)

Yes

Removing a maintainer or reviewer

The removed person (if they are still a Red Hat employee and group member). Existing maintainers are encouraged but not required.

Person: Yes. Maintainers: Optional.

Changing devel-sst, devel-assigned-team, jiraComponent, requiredApproval

Existing maintainers (unless you are one)

Yes

Adding a new subsystem

Every maintainer and reviewer listed in the new entry (unless they are the MR author)

Yes

Deleting a subsystem

Every maintainer and reviewer from the deleted entry (if they are still employees and group members)

Yes

Removing ALL maintainers from a subsystem

Blocked — this produces an error. Every subsystem must have at least one maintainer.

N/A

Adding yourself vs. someone else adding you

If you add yourself as a maintainer or reviewer, no self-approval is needed. Existing subsystem maintainers still need to approve.
If someone else adds you, the webhook creates a required approval rule for you. You must approve the MR to confirm you accept the role.
If you remove yourself, no self-approval is needed.
If someone else removes you and you are still a Red Hat employee and a member of the kernel GitLab group, you must approve. Former employees do not need to approve their own removal.

User validation checks

Every user added to owners.yaml is validated automatically:

Required fields: gluser, name, and email must all be present. Please refer to the required fields in templates/owners-schema.yaml.
GitLab account: The gluser must exist as a GitLab user. Refer to the Gitlab Account Creation section in the documentation for more information.
Kernel group membership: The user must be a member of the redhat/centos-stream/src/kernel GitLab group. If they are not, the MR is blocked with an error. In this case, please contact your Donald Zickus <dzickus@redhat.com> to correct your gitlab permissions.
kernel-ark membership: The user should be a member of the cki-project/kernel-ark project. If they are not, a warning is added and project administrators are notified, but the MR is not blocked. The project administrators will handle adding users to the kernel-ark project
LDAP verification: The email address must resolve in Red Hat LDAP.

If a user fails the kernel group membership check, they need to be added to the group before their owners.yaml entry can be merged.