Las personas que elijas como propietarios del código deben tener permisos de escritura para el repositorio. Cuando el propietario del código es un equipo, ese equipo debe ser visible y tener permisos de escritura, incluso si todos los miembros individuales del equipo ya tienen permisos de escritura, a través de la membresía de la organización o a través de la membresía de otro equipo.
Acerca de los propietarios de código
Cuando alguien abre una solicitud de extracción que modifica el código que pertenece a alguien, automáticamente se les solicita una revisión a los propietarios del mismo. Lo que no se solicita automáticamente a estos propietarios es la revisión de los borradores de solicitudes de extracción. Para más información sobre solicitudes de incorporación de cambios de borrador, consulta "Acerca de las solicitudes de incorporación de cambios". Se notificará automáticamente a los dueños del código cuando marques un borrador de solicitud de extracción como listo para revisión. Si conviertes una solicitud de extracción en borrador, las personas que ya estén suscritas a las notificaciones no se darán de baja automáticamente. Para obtener más información, vea «Cambiar la etapa de una solicitud de extracción».
Cuando alguien con permisos administrativos o de propietario ha activado las revisiones requeridas, opcionalmente, también pueden solicitar aprobación de un propietario del código antes de que el autor pueda fusionar una solicitud de extracción en el repositorio. Para obtener más información, vea «Acerca de las ramas protegidas».
Si un archivo tiene un propietario del código, puedes ver quién es éste antes de que abras una solicitud de extracción. En el repositorio, puedes ir al archivo y mantener el puntero sobre para ver una sugerencia de herramientas con los detalles de propiedad del código.
Ubicación del archivo CODEOWNERS
Para usar un archivo CODEOWNERS, cree un nuevo archivo denominado CODEOWNERS en el directorio raíz, .github/, o docs/ del repositorio, en la rama donde desea agregar los propietarios del código. Si los archivos CODEOWNERS existen en más de una de esas ubicaciones, GitHub los buscará en ese orden y usará el primero que encuentre.
Cada archivo CODEOWNERS asigna los propietarios del código para una única rama en el repositorio. Por lo tanto, puede asignar diferentes propietarios de código para diferentes ramas, como @octo-org/codeowners-team para una base de código en la rama predeterminada y @octocat para un sitio de GitHub Pages en la rama gh-pages.
Para que los propietarios del código reciban las solicitudes de revisión, el archivo CODEOWNERS debe estar en la rama base de la solicitud de extracción. Por ejemplo, si asigna @octocat como propietario del código para los archivos .js en la rama gh-pages del repositorio, @octocat recibirá solicitudes de revisión cuando se abra una solicitud de incorporación de cambios con cambios en los archivos .js archivos entre la rama principal y gh-pages.
CODEOWNERS y bifurcaciones
Para desencadenar solicitudes de revisión, las solicitudes de incorporación de cambios usan la versión de CODEOWNERS de la rama base de la solicitud de incorporación de cambios. La rama base es la rama que modificará una solicitud de incorporación de cambios si se combina la solicitud de incorporación de cambios.
Si creas una solicitud de incorporación de cambios desde una bifurcación y la rama base está en el repositorio ascendente, la solicitud de incorporación de cambios usará el archivo CODEOWNERS de esa rama en el repositorio ascendente. Si la rama base es una rama dentro de la bifurcación, la solicitud de incorporación de cambios usará el archivo CODEOWNERS de esa rama en la bifurcación, pero esto solo desencadenará solicitudes de revisión si los propietarios de código se agregan a la bifurcación específicamente con acceso de write.
Cuando veas quién es responsable de un archivo al mantener el puntero sobre , verás información del archivo CODEOWNERS para la rama en el repositorio que estés viendo.
Tamaño de archivo de CODEOWNERS
Los archivos de CODEOWNERS deben ser de menos de 3 MB. Un archivo de CODEOWNERS que sobrepase este límite no se cargará, lo cual significa que la información de los propietarios de código no se mostrará y que no se solicitará que los propietarios de código adecuados revisen los cambios en una solicitud de cambios.
Para reducir el tamaño de tu archivo de CODEOWNERS, considera utilizar patrones de comodín para consolidar varias entradas en una.
Sintáxis de CODEOWNERS
Advertencia: Hay algunas reglas de sintaxis para los archivos de gitignore que no funcionan con los archivos de CODEOWNERS:
- Agregar un carácter de escape a un patrón que comience por
#utilizando\para que se le trate como un patrón y no como un comentario no funciona - Usar
!para negar un patrón no funciona - Usar
[ ]para definir un intervalo de caracteres no funciona
Un archivo CODEOWNERS usa un patrón que sigue casi todas las mismas reglas que se usan en los archivos gitignore. El patrón va seguido de uno o varios nombres de usuario o de equipo de GitHub con el formato estándar @username o @org/team-name. Los usuarios y los equipos deben tener acceso explícito de write al repositorio aunque los miembros del equipo ya tengan acceso.
Si quieres hacer coincidir dos o más propietarios de código con el mismo patrón, todos los propietarios de código deben estar en la misma línea. Si los propietarios de código no están en la misma línea, el patrón coincide solo con el propietario del código mencionado por última vez.
En la mayoría de los casos, tú también puedes hacer referencia a un usuario por la dirección de correo electrónico que se ha agregado a su cuenta, por ejemplo user@example.com. No puedes usar una dirección de correo electrónico para hacer referencia a una cuenta de usuario administrada. Para más información sobre cuentas de usuario administradas, consulta "Acerca de Enterprise Managed Users".
Las rutas de CODEOWNERS distinguen entre mayúsculas y minúsculas, ya que GitHub utiliza un sistema de archivos que también lo hace. Ya que GitHub evalúa a los CODEOWNERS, incluso los sistemas que distinguen entre mayúsculas y minúsculas (por ejemplo, macOS) deben utilizar rutas y archivos que utilicen mayúsculas y minúsculas correctamente en el archivo de CODEOWNERS.
Si cualquier línea del archivo CODEOWNERS contiene una sintaxis inválida, la línea se omitirá. Al navegar al archivo CODEOWNERS en el repositorio puede ver los errores resaltados. También se puede acceder a una lista de los errores del archivo CODEOWNERS de cualquier repositorio a través de la API. Para obtener más información, vea «Puntos de conexión de la API de REST para repositorios».
Si especificas un usuario o equipo que no existe o no tiene acceso suficiente, no se asignará un propietario de código.
Ejemplo de un archivo 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
Protección de rama y de CODEOWNERS
Los propietarios de los repositorios pueden actualizar reglas de protección de rama para asegurarse de que los propietarios de los archivos que se modificaron revisen el código que cambió. Edita la regla de protección de rama y habilita la opción "Exigir revisión de los propietarios del código". Para obtener más información, vea «Acerca de las ramas protegidas».
Nota: Cuando se requieren revisiones de propietarios de código, una aprobación de cualquiera de los propietarios es suficiente para cumplir este requisito. Por ejemplo, supongamos que el archivo CODEOWNERS contiene la siguiente línea:
*.js @global-owner1 @global-owner2
Esto significa que los cambios en los archivos de JavaScript se pueden aprobar mediante @global-owner1 o @global-owner2, pero no se requieren aprobaciones de ambos .
Para proteger completamente un repositorio contra cambios no autorizados, también debes definir un propietario para el propio archivo CODEOWNERS. El método más seguro es definir un archivo CODEOWNERS en el directorio .github del repositorio y definir el propietario del repositorio como propietario del archivo CODEOWNERS (/.github/CODEOWNERS @owner_username) o todo el directorio (/.github/ @owner_username).
Como alternativa a las reglas de protección de ramas, puede crear conjuntos de reglas. Los conjuntos de reglas tienen algunas ventajas sobre las reglas de protección de ramas, como estados, y una mejor detectabilidad sin necesidad de acceso de administrador. Puedes aplicar igualmente varios conjuntos de reglas al mismo tiempo. Para obtener más información, vea «Acerca de los conjuntos de reglas».