Пользователи, которых вы выбираете в качестве владельцев кода, должны иметь разрешения на запись в репозитории. Если владелец кода является командой, то эта команда должна быть видимой и должна иметь разрешения на запись, даже если все отдельные участники команды уже имеют разрешения на запись напрямую, через членство в организации или через другое членство в команде.
О владельцах кода
Владельцы кода автоматически получают запрос для проверки, когда кто-то открывает запрос на вытягивание, который изменяет код, принадлежащий владельцам. Владельцы кода не получают запросов для проверки черновиков запросов на вытягивание автоматически. Дополнительные сведения о черновике запросов на вытягивание см. в разделе "Сведения о запросах на вытягивание". Когда вы помечаете черновик запроса на вытягивание как готовый к проверке, владельцы кода автоматически получают уведомления. Если вы преобразуете запрос на вытягивание в черновик, для пользователей, которые уже подписаны на уведомления, подписка отменена не будет. Дополнительные сведения см. в разделе «Изменение этапа запроса на вытягивание».
Если пользователь с разрешениями администратора или владельца включил необходимые проверки, он также может потребовать утверждения от владельца кода, прежде чем автор сможет объединить запрос на вытягивание в репозитории. Дополнительные сведения см. в разделе «Сведения о защищенных ветвях».
Если у файла есть владелец кода, вы можете просмотреть, кто является владельцем кода, перед открытием запроса на вытягивание. В репозитории можно перейти к файлу и навести указатель мыши на , чтобы просмотреть подсказку средства с сведениями о кодоверстве.
Расположение файла 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
Warning
Существуют некоторые правила синтаксиса для файлов Gitignore, которые не работают в файлах CODEOWNERS:
- Экранирование шаблона, начиная с
#
использования\
, поэтому оно рассматривается как шаблон, а не комментарий не работает - Использование
!
для отмены шаблона не работает - Использование
[ ]
для определения диапазона символов не работает
В файле CODEOWNERS используется шаблон, который следует большинству правил, используемых в файлах gitignore . За шаблоном следует одно или несколько имен пользователей или имен команд GitHub в стандартном формате @username
или @org/team-name
. Пользователям и командам необходимо явно предоставить доступ write
в репозитории, даже если у членов команды уже есть доступ.
Если вы хотите сопоставить два или более владелец кода с одинаковым шаблоном, все владелец кода должны находиться в одной строке. Если владелец кода не находятся в той же строке, шаблон соответствует только последним упомянутым владелец кода.
Вы также можете ссылаться на пользователя по адресу электронной почты, который был добавлен в свою учетную запись, например user@example.com
.
Пути 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 и защита ветвей
Владельцы репозитория могут обновлять правила защиты ветви, чтобы убедиться, что измененный код проверяется владельцами измененных файлов. Измените правило защиты ветви и включите параметр "Требовать проверку от владельцев кода". Дополнительные сведения см. в разделе «Сведения о защищенных ветвях».
Note
Если требуются проверки из владелец кода, утверждение от любого из владельцев достаточно для удовлетворения этого требования. Например, предположим, что файл CODEOWNERS содержит следующую строку:
*.js @global-owner1 @global-owner2
Это означает, что изменения в файлах JavaScript могут быть утверждены @global-owner1
либо либо@global-owner2
, но утверждения от обоих не требуются.
Чтобы защитить репозиторий полностью от несанкционированных изменений, необходимо также определить владельца самого файла CODEOWNERS. Наиболее безопасным методом является определение файла CODEOWNERS в .github
каталоге репозитория и определение владельца репозитория как владельца файла CODEOWNERS (/.github/CODEOWNERS @owner_username
) или всего каталога (/.github/ @owner_username
).
В качестве альтернативы правилам защиты ветви или правилам защиты тегов, можно создавать наборы правил. Наборы правил имеют несколько преимуществ по сравнению с правилами защиты branch и тегами защиты, такими как состояния и улучшенная возможность обнаружения, не требуя доступа администратора. Вы также можете применять несколько наборов правил одновременно. Дополнительные сведения см. в разделе «Сведения о наборе правил».