Доступно с версии 1.8.6 (SE, EE)

Функция CODEOWNERS позволяет определить ответственных за отдельные части репозитория. Ответственными могут быть пользователи и группы. Изменения, затрагивающие файлы, указанные в CODEOWNERS, должны получить апрув от владельцев кода.

Использование CODEOWNERS помогает:

  • требовать апрувы от доменных экспертов для важных директорий;
  • упростить процесс поиска «ответственных» за конкретный участок кода.

CODEOWNERS дополняет механизм правил апрува, но не заменяет их. В отличие от правил апрува, которые задаются вручную в UI, CODEOWNERS работает через файл CODEOWNERS в репозитории.

Как работает CODEOWNERS

CODEOWNERS — текстовый файл в репозитории. Deckhouse Code использует его для определения владельцев файлов, участвующих в запросе на слияние.

Сопоставляются те файлы, которые показывает вкладка «Изменения» запроса на слияние: итоговая разница между базой и вершиной запроса на слияние, а не файлы отдельных коммитов. Переименованный файл учитывается и по старому, и по новому пути, поэтому применяется запись, которая владеет любым из них.

Ищется в трёх местах (по приоритету):

  1. ./CODEOWNERS.
  2. ./docs/CODEOWNERS.
  3. ./.gitlab/CODEOWNERS.

Используется только первый найденный файл.

Если в проекте существует несколько файлов и вы сейчас просматриваете неприоритетный, то увидите соответствующее сообщение.

Неприоритетный файл

Валидация файла CODEOWNERS

Валидация помогает увидеть ошибки в файле на этапе редактирования.

Если файл валиден, отображается соответствующее сообщение:

Валидный файл

Если файл невалиден, будут отображены проблемные строки и тип ошибки:

Невалидный файл

Валидация сообщает о следующих типах ошибок:

  • У владельцев нет доступа в этот проект или их уровень доступа недостаточен — как минимум один из владельцев не имеет достаточных прав в проекте.
  • Пробелы в пути — если путь содержит пробелы, нужно их экранировать символом \.
  • Нет владельцев — не указано ни одного владельца.
  • Незакрытый раздел — не хватает символа закрытия раздела ].

Где применяется CODEOWNERS

Если MR, изменяющий файл, попадает под правила CODEOWNERS, то необходимо получить апрувы от владельцев.

Формат CODEOWNERS

Строка правила:

<путь или паттерн> <список владельцев>

Владельцы:

  • @user;
  • @group;
  • @group/subgroup;
  • роли: @@developer, @@maintainer, @@owner.

Примеры

# Владелец всех файлов
* @default-team

# README.md только в корне
/README.md @docs-team

# Все Ruby-файлы
*.rb @backend-team

# Вся директория config
/config/ @devops

# README.md в любом месте
README.md @docs

Паттерны путей

Deckhouse Code использует подстановочные символы:

  • * — любые символы кроме /.
  • ** — матч нескольких уровней директорий.
  • /dir/ — только указанная директория.
  • *.md — все Markdown-файлы.
  • /config/**/*.rb — все Ruby-файлы внутри config/* на всех уровнях.

Примеры паттернов

/docs/*       @docs-one      # один уровень
/docs/**      @docs-two      # рекурсивно
/app/**/*.rb  @ruby-team

Секции CODEOWNERS

В файле CODEOWNERS секции — это именованные области, которые анализируются отдельно и всегда применяются. Пока вы не определите ни одной секции, Deckhouse Code рассматривает весь файл CODEOWNERS как одну единственную секцию.

Особенности использования CODEOWNERS:

  • Deckhouse Code рассматривает записи без секций, включая правила, определённые до первой секции, как отдельную, безымянную секцию.
  • Каждая секция обрабатывает свои правила отдельно.
  • Если путь к файлу соответствует нескольким записям внутри одной секции, используется только последняя подходящая запись в этой секции.
  • Если путь к файлу соответствует записям в нескольких секциях, используется последняя подходящая запись в каждой секции.

Например, в файле CODEOWNERS со следующими секциями, определяющими владельцев для README:

* @root

[README Owners]
README.md @user1 @user2
internal/README.md @user4

[README other owners]
README.md @user3

Владельцы для README.md в корневой директории:

  • @root — из безымянной секции.
  • @user1 и @user2 — из секции [README Owners].
  • @user3 — из секции [README other owners].

Владельцы для internal/README.md:

  • @root — из безымянной секции.
  • @user4 — из секции [README Owners]. (И README.md, и internal/README.md подходят под правила секции, но используется только последняя подходящая запись в этой секции).
  • @user3 — из секции [README other owners].

В виджете запроса на слияние каждый владелец кода отображается под своим ярлыком.

Пример codeowners

Детальный пример: сложная комбинация секций

Ниже — пример реального промышленного файла, показывающий:

  • секции с разным количеством апрувов;
  • переопределение владельцев;
  • опциональные секции;
  • исключения;
  • наследование секций с одинаковыми именами.
# Глобальные настройки
* @fallback-team
!*.lock                    # lock-файлы не требуют апрувов
!**/generated/**           # автоматическая генерация

[Backend][2] @backend-core
# Требуются 2 апрува от backend-core для любого Ruby-кода
app/**/*.rb

# Но для критических моделей определяем другой порядок
app/models/**/*.rb @backend-core @security-team

# Эта модель — исключение, владелец другой
app/models/legacy/**/*.rb @migration-team

[Backend]
# Дополнение секции: теперь Backend включает также SQL
db/**/*.sql @db-team

[Ruby Optional]
# Дополнительная подсветка владельцев, апрувы НЕ обязательны
^[Ruby Optional]
*.rb @ruby-advisors

[Frontend][3]
# Для UI требуется 3 апрува
*.vue @frontend-team
*.js  @frontend-team

# переопределение: конкретный файл → конкретный человек
frontend/critical_entry.vue @frontend-lead

[Docs]
*.md @technical-writers

[Docs]
# переопределение: README всегда принадлежит docs-lead
README.md @docs-lead

Особенности примера:

  • секция [Backend] объявлена дважды → Deckhouse Code объединит её;
  • [Backend][2] @backend-core задаёт обязательные 2 апрува;
  • [Frontend][3] требует 3 апрува от фронтенда;
  • [Ruby Optional] отмечена как опциональная — владельцы видны, но их апрув не обязателен;
  • исключения !*.lock и !**/generated/** означают, что эти файлы вообще не требуют апрувов.

Исключения (!)

Используются для исключения файлов внутри секции:

* @default
!package-lock.json
!**/generated/**

После исключения файл не может быть снова включён в ту же секцию.

Порядок обработки правил

Правила обрабатываются в соответствии со следующим порядком:

  • Deckhouse Code читает файл сверху вниз.
  • В пределах одной секции правила с одинаковым путём переопределяют предыдущие.
  • Если файл подходит под несколько секций — владельцы из всех этих секций добавляются.
  • Секции не переопределяют друг друга — они независимы.

Кто может быть владельцем (eligible owners)

В файле CODEOWNERS владельцем кода указывается пользователь, группа или роль. Владельцами кода считаются только участники проекта с ролью Developer или выше.

Пользователи (через @username)

Пользователь считается валидным владельцем, если:

  • Имеет прямое членство в проекте (Developer, Maintainer или Owner).
  • Имеет членство в группе проекта (включая наследуемое: группа проекта, родительские группы, предки родительских групп).
  • Является прямым или унаследованным участником группы, которая напрямую приглашена в проект.
  • Является прямым но не унаследованным участником группы которая приглашена в группу проекта.
  • Является прямым но не унаследованным участником группы которая приглашена в предка группы проекта.

Если подытожить, то подходят все пользователи которые отображаются на странице участников проекта с ролью developer или выше.

Не считается владельцем, если:

  • заблокирован,
  • доступ отозван,
  • роль ниже Developer.

Группы (через @group или @group/subgroup)

Группа может быть владельцем только если:

  • Она напрямую приглашена в проект с ролью Developer+ (через «Пригласить группу»).
  • Владельцами считаются только прямые участники этой группы.

Наследуемые участники родительских групп владельцами не считаются.

Роли (через @@role)

Формат:

@@developer
@@maintainer
@@owner

Особенности:

  • учитываются только прямые участники проекта;
  • члены групп в расчёт не входят;
  • роли не наследуют друг друга (@@developer НЕ включает maintainer’ов).

Можно указывать несколько ролей в одной строке:

file.md @@developer @@maintainer

Взаимодействие с правилами апрува

CODEOWNERS и правила апрувов работают независимо, но их требования суммируются.

Пример:

  • правило Security требует 1 апрув;
  • секция [Backend][2] требует 2 апрува;
  • MR меняет backend-файл.

Итог: необходимо 3 апрува.

Отключение проверок CODEOWNERS

Проверки CODEOWNERS включены в Deckhouse Code по умолчанию. Если в проекте есть файл CODEOWNERS, но для некоторых веток апрувы от владельцев кода не нужны, отключите проверки в правиле, которое защищает эти ветки.

Чтобы отключить проверки для веток правила, перейдите в раздел «Проект» → «Настройки» → «Репозиторий» → «Правила веток», нажмите «Просмотреть детали» у нужного правила и выключите переключатель «Требовать апрув от владельцев кода». В списке правил у такого правила появляется отметка «Апрув владельцев кода отключён».

Выключенный переключатель «Требовать апрув от владельцев кода»

Отметка «Апрув владельцев кода отключён» в списке правил

Проверки отключаются для целевой ветки запроса на слияние, когда выполнены все условия:

  • ветке соответствует хотя бы одно правило проекта;
  • у всех правил проекта, соответствующих ветке, переключатель выключен;
  • ветке не соответствует ни одно правило, унаследованное от группы.

Чтобы отключить проверки во всём проекте, в списке правил выберите «Добавить правило ветки» → «Имя или шаблон ветки», введите * и выключите переключатель на странице нового правила. Если у ветки есть собственное правило, например у ветки по умолчанию, выключите переключатель и у него.

Правило * делает защищёнными все ветки проекта. По умолчанию в новом правиле для параметров «Разрешено выполнять push и слияние» и «Разрешено слияние» выбраны «Мейнтейнеры». Поэтому пользователи с ролью Developer не смогут создавать ветки, выполнять push и сливать запросы на слияние в проекте.

Если в правиле * выбрать «Разработчики и мейнтейнеры», пользователи с ролью Developer смогут выполнять push и слияние во все ветки проекта, включая ветки с собственными правилами, например ветку по умолчанию. Права всех правил, соответствующих ветке, суммируются.

Если в дополнительных настройках апрувов группы включена настройка «Запретить редактирование правил апрува в наследуемых сущностях», переключатель изменить нельзя.

Когда проверки отключены для целевой ветки:

  • запросы на слияние в эту ветку не блокируются из-за отсутствующих апрувов от владельцев кода;
  • владельцы кода не назначаются проверяющими;
  • на страницах файлов ветки не показывается блок «Владельцы кода»;
  • если в секции «При добавлении коммита» выбрано «Снимать апрувы владельцев кода, если их файлы были изменены», новые коммиты не снимают апрувы;
  • изменение настройки сразу применяется к уже открытым запросам на слияние.

Push в ветку переключатель не блокирует и не разрешает. Проверка синтаксиса файла CODEOWNERS продолжает работать.

Автоматическое назначение владельцев кода проверяющими

Владельцев кода, соответствующих изменённым файлам, можно автоматически назначать проверяющими запроса на слияние.

Для этого перейдите в раздел «Проект» → «Настройки» → «Запросы на слияние» → «Автоматическое назначение проверяющих» и выберите настройку «Автоматически назначать владельцев кода проверяющими».

Настройка «Автоматически назначать владельцев кода проверяющими»

По умолчанию настройка выключена. При её включении владельцы кода назначаются проверяющими:

  • при создании запроса на слияние сразу в готовом статусе (не в статусе черновика);
  • при снятии статуса черновика с запроса на слияние.

При автоматическом назначении действуют следующие ограничения:

  • для черновиков назначение не выполняется;
  • если у запроса на слияние уже есть проверяющие, автоматическое назначение не выполняется — назначенные вручную проверяющие сохраняются;
  • автор запроса на слияние не может быть назначен проверяющим;
  • назначаются только пользователи, у которых есть доступ на чтение запроса на слияние;
  • если в проекте запрещено назначать нескольких проверяющих, назначается только первый владелец кода.

Рекомендации по оформлению

При оформлении файла CODEOWNERS следуйте рекомендациям:

  • Сначала задавайте широкие правила (* @team). Далее уточняющие (app/**/*.rb @backend-team).
  • Используйте секции для лучшей структуры и наглядности.
  • Избегайте дубликатов — последнее правило в секции имеет приоритет.
  • Опциональные секции полезны для подсветки экспертов без обязательных апрувов.

Пример финального файла

# Глобальные владельцы
* @default-team

# Исключения
!yarn.lock
!**/generated/**

[Backend][2]
app/**/*.rb @backend-core

[Frontend][3]
*.vue @frontend-team
*.js @frontend-team

^[Docs]
*.md @docs-team

[Critical Overrides]
/config/production.yml @ops-lead