Skip to main content

О владельцах кода

Файл CODEOWNERS можно использовать для определения отдельных лиц или команд, ответственных за код в репозитории.

Кто может использовать эту функцию?

People with write permissions for the repository can create or edit the CODEOWNERS file and be listed as code owners. People with admin or owner permissions can require that pull requests have to be approved by code owners before they can be merged.

Вы можете определить владелец кода в общедоступных репозиториях с помощью GitHub Free и GitHub Free для организаций, а также в общедоступных и частных репозиториях с GitHub Pro, GitHub Team, GitHub Enterprise Cloud, а также GitHub Enterprise Server. Дополнительные сведения см. в разделе "Планы GitHub".

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

О владельцах кода

Владельцы кода автоматически получают запрос для проверки, когда кто-то открывает запрос на вытягивание, который изменяет код, принадлежащий владельцам. Владельцы кода не получают запросов для проверки черновиков запросов на вытягивание автоматически. Дополнительные сведения о черновике запросов на вытягивание см. в разделе "Сведения о запросах на вытягивание". Когда вы помечаете черновик запроса на вытягивание как готовый к проверке, владельцы кода автоматически получают уведомления. Если вы преобразуете запрос на вытягивание в черновик, для пользователей, которые уже подписаны на уведомления, подписка отменена не будет. Дополнительные сведения см. в разделе Изменение этапа запроса на вытягивание.

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

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

Снимок экрана: заголовок файла. Курсор наведите указатель мыши на значок щита, в котором отображается подсказка "Принадлежит пользователю или команде (из строки CODEOWNERS number).

Расположение файла CODEOWNERS

Чтобы использовать файл CODEOWNERS, создайте новый файл, вызываемый CODEOWNERS в .github/корневом каталоге или docs/ корневом каталоге репозитория, в ветви, в которой вы хотите добавить владелец кода. Если CODEOWNERS файлы существуют в нескольких из этих расположений, GitHub будет искать их в этом порядке и использовать первый, который он находит.

Каждый файл CODEOWNERS назначает владельцам кода одну ветвь в репозитории. Таким образом, можно назначить разных владельцев кода для различных ветвей, например, @octo-org/codeowners-team для базы кода в ветви по умолчанию и @octocat для сайта GitHub Pages в ветви gh-pages.

Чтобы владельцы кода получали запросы на проверку, файл CODEOWNERS должен находиться в базовой ветви запроса на вытягивание. Например, если вы назначаете @octocat в качестве владельца кода для файлов .js в ветви gh-pages репозитория, то при открытии запроса на вытягивание, содержащего изменения в файлах .js между головной ветвью и gh-pages, @octocat будет получать запросы на проверку.

CODEOWNERS и вилки

Чтобы активировать запросы на проверку, запросы на вытягивание используют версию CODEOWNERS из базовая ветвь запроса на вытягивание. Базовая ветвь — это ветвь, которая будет изменять запрос на вытягивание, если запрос на вытягивание будет объединен.

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

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

Размер файла CODEOWNERS

Размер файла CODEOWNERS не должен превышать 3 МБ. Если размер файла CODEOWNERS превышает это ограничение, то файл не будет загружен, и, следовательно, сведения о владельце кода не будут отображаться, а соответствующие владельцы кода не будут получать запросы для просмотра изменений в запросе на вытягивание.

Чтобы уменьшить размер файла CODEOWNERS, используйте шаблоны с подстановочными знаками для консолидации нескольких записей в одну запись.

Синтаксис файла CODEOWNERS

Предупреждение. Существуют некоторые правила синтаксиса для файлов gitignore, которые не работают в файлах CODEOWNERS:

  • Экранирование шаблона, начиная с # использования \ , поэтому оно рассматривается как шаблон, а не комментарий не работает
  • Использование ! для отмены шаблона не работает
  • Использование [ ] для определения диапазона символов не работает

В файле CODEOWNERS используется шаблон, который следует большинству правил, используемых в файлах gitignore . За шаблоном следует одно или несколько имен пользователей или имен команд GitHub в стандартном формате @username или @org/team-name. Пользователям и командам необходимо явно предоставить доступ write в репозитории, даже если у членов команды уже есть доступ.

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

В большинстве случаев вы также можете ссылаться на пользователя по адресу электронной почты, который был добавлен в свою учетную запись, например user@example.com. Нельзя использовать адрес электронной почты для ссылки на управляемая учетная запись пользователя. Дополнительные сведения о управляемые учетные записи пользователейсм. в разделе "Сведения о Enterprise Managed Users" в документации GitHub Enterprise Cloud. % else %}".

Пути CODEOWNERS чувствительны к регистру, так как GitHub использует файловую систему с учетом регистра. Так как файлы CODEOWNERS обрабатываются GitHub, то даже в системах, которые не учитывают регистр (например, macOS), в файлах CODEOWNERS должны указываться пути и имена файлов с правильным регистром.

Если любая строка в файле CODEOWNERS содержит недопустимый синтаксис, эта строка будет пропущена. При переходе к файлу CODEOWNERS в репозитории вы увидите все ошибки, выделенные. Список ошибок в файле CODEOWNERS репозитория также доступен через API. Дополнительные сведения см. в разделе Конечные точки REST API для репозиториев.

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

Пример файла CODEOWNERS

# This is a comment.
# Each line is a file pattern followed by one or more owners.

# These owners will be the default owners for everything in
# the repo. Unless a later match takes precedence,
# @global-owner1 and @global-owner2 will be requested for
# review when someone opens a pull request.
*       @global-owner1 @global-owner2

# Order is important; the last matching pattern takes the most
# precedence. When someone opens a pull request that only
# modifies JS files, only @js-owner and not the global
# owner(s) will be requested for a review.
*.js    @js-owner #This is an inline comment.

# You can also use email addresses if you prefer. They'll be
# used to look up users just like we do for commit author
# emails.
*.go docs@example.com

# Teams can be specified as code owners as well. Teams should
# be identified in the format @org/team-name. Teams must have
# explicit write access to the repository. In this example,
# the octocats team in the octo-org organization owns all .txt files.
*.txt @octo-org/octocats

# In this example, @doctocat owns any files in the build/logs
# directory at the root of the repository and any of its
# subdirectories.
/build/logs/ @doctocat

# The `docs/*` pattern will match files like
# `docs/getting-started.md` but not further nested files like
# `docs/build-app/troubleshooting.md`.
docs/*  docs@example.com

# In this example, @octocat owns any file in an apps directory
# anywhere in your repository.
apps/ @octocat

# In this example, @doctocat owns any file in the `/docs`
# directory in the root of your repository and any of its
# subdirectories.
/docs/ @doctocat

# In this example, any change inside the `/scripts` directory
# will require approval from @doctocat or @octocat.
/scripts/ @doctocat @octocat

# In this example, @octocat owns any file in a `/logs` directory such as
# `/build/logs`, `/scripts/logs`, and `/deeply/nested/logs`. Any changes
# in a `/logs` directory will require approval from @octocat.
**/logs @octocat

# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as its owners are left empty. Without an owner, changes
# to `apps/github` can be made with the approval of any user who has
# write access to the repository.
/apps/ @octocat
/apps/github

# In this example, @octocat owns any file in the `/apps`
# directory in the root of your repository except for the `/apps/github`
# subdirectory, as this subdirectory has its own owner @doctocat
/apps/ @octocat
/apps/github @doctocat

Файлы CODEOWNERS и защита ветвей

Владельцы репозитория могут обновлять правила защиты ветви, чтобы убедиться, что измененный код проверяется владельцами измененных файлов. Измените правило защиты ветви и включите параметр "Требовать проверку от владельцев кода". Дополнительные сведения см. в разделе Сведения о защищенных ветвях.

Примечание. Если требуются проверки из владелец кода, утверждение от любого из владельцев достаточно для удовлетворения этого требования. Например, предположим, что файл CODEOWNERS содержит следующую строку:

*.js     @global-owner1 @global-owner2

Это означает, что изменения в файлах JavaScript могут быть утверждены @global-owner1 либо либо@global-owner2, но утверждения от обоих не требуются.

Чтобы защитить репозиторий полностью от несанкционированных изменений, необходимо также определить владельца самого файла CODEOWNERS. Наиболее безопасным методом является определение файла CODEOWNERS в .github каталоге репозитория и определение владельца репозитория как владельца файла CODEOWNERS (/.github/CODEOWNERS @owner_username) или всего каталога (/.github/ @owner_username).

В качестве альтернативы правилам защиты ветви, можно создавать наборы правил. Наборы правил имеют несколько преимуществ по сравнению с правилами защиты branch защиты, такими как состояния и улучшенная возможность обнаружения, не требуя доступа администратора. Вы также можете применять несколько наборов правил одновременно. Дополнительные сведения см. в разделе Сведения о наборе правил.

Дополнительные материалы