Administra las aprobaciones de solicitud de extracción con CODEOWNERS

Vista previa

Este producto o función está sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta guía, se describen la estructura, la sintaxis y la implementación de la función CODEOWNERS, que te permite controlar de manera flexible los requisitos de aprobación de las solicitudes de extracción (PR).

Introducción

La función CODEOWNERS de Secure Source Manager usa archivos en tu base de código para establecer aprobadores a nivel de archivo. Esto ofrece un control más preciso que otras reglas de ramas, ya que puedes asignar propietarios específicos a archivos específicos y definir conjuntos independientes de aprobadores.

La función CODEOWNERS ofrece las siguientes capacidades:

• Define los usuarios que pueden aprobar solicitudes de extracción para archivos, directorios y ramas.
• Configura diferentes conjuntos de propietarios del código para proteger diferentes ramas.
• Asegúrate de que los propietarios designados revisen los cambios en los archivos.

Cómo habilitar la revisión del propietario del código

Para activar y aplicar las reglas de CODEOWNERS, los administradores de protección de ramas deben actualizar las reglas de ramas en la configuración del repositorio a Require Code Owner Review on Pull Requests. Selecciona esta opción en la configuración de la regla de bifurcación. Si este parámetro de configuración está desactivado, el sistema ignora los archivos CODEOWNERS para las combinaciones en la rama de destino. Si seleccionas esta opción, el sistema bloqueará los envíos y las combinaciones a la rama hasta que los propietarios del código revisen y aprueben las solicitudes de extracción.

Nota: Otros parámetros de configuración, como N Revisores requeridos o N Aprobadores requeridos, son independientes y requisitos adicionales. Si eres propietario del código y tienes el permiso repositories.approvePullRequests, puedes cumplir con ambos requisitos con una sola revisión.

Ubicación y precedencia del archivo CODEOWNERS

Secure Source Manager admite dos opciones para definir archivos CODEOWNERS:

1. Archivos anidados: Archivos CODEOWNERS en cualquier directorio excepto en el directorio .securesourcemanager Los archivos CODEOWNERS anidados solo afectan a su propio directorio (incluidos los subdirectorios), y las rutas de acceso a los archivos dentro de ellos deben especificarse en relación con el directorio en el que se encuentra el archivo CODEOWNERS. Este es el enfoque recomendado para la mayoría de los casos de uso.

2. Archivo dedicado único: Si necesitas distinguir el archivo CODEOWNERS de Secure Source Manager de otros archivos CODEOWNERS que usan otras herramientas (por ejemplo, .gitlab/CODEOWNERS), puedes usar un solo archivo ubicado en .securesourcemanager/CODEOWNERS en la raíz de tu repositorio. Si este archivo existe, Secure Source Manager ignora todos los demás archivos CODEOWNERS de la misma rama, incluidos los anidados. El directorio .securesourcemanager solo se reconoce en la raíz del repositorio.

Interacción con solicitudes de extracción y aprobaciones

Cuando se crea una solicitud de extracción o cuando se actualiza su rama de origen con nuevas confirmaciones, el sistema solo usa los archivos CODEOWNERS de la rama base (la rama en la que se realiza la combinación) para determinar los requisitos de aprobación. El sistema ignora los cambios en los archivos CODEOWNERS dentro del código de envío para esa verificación.

Sintaxis y estructura de CODEOWNERS

Un archivo CODEOWNERS consta de comentarios, líneas de reglas y marcadores de sección. Los comentarios comienzan con # y el sistema los ignora.

Formato de la línea de regla

El formato estándar para una línea de regla es el siguiente:

[BRANCH_GLOB] PATH_GLOB [OWNERS...]

Aquí:

• BRANCH_GLOB: Es un patrón glob opcional que especifica a qué ramas se aplica la regla. Si no especificas un comodín de rama, la regla se aplica a cualquier rama en la que se registre el archivo CODEOWNERS (si la rama tiene habilitado CODEOWNERS en sus reglas de rama). Por ejemplo:

  • main solo coincide con la rama main.
  • dev-* coincide con las ramas que comienzan con dev-.
  • *-glob coincide con las ramas que terminan en -glob.
  • my-*-glob coincide con ramas como my-feat-glob.
  Nota: Si bien un archivo CODEOWNERS protege solo su propia rama, mantener diferentes contenidos de CODEOWNERS en las ramas puede generar conflictos de combinación. Si usas el campo de rama, puedes usar el mismo contenido de CODEOWNERS en cada rama y, al mismo tiempo, establecer propietarios de código específicos de la rama.

• PATH_GLOB: Es un patrón glob obligatorio que especifica a qué rutas de acceso de archivos se aplica la regla. La sintaxis de Secure Source Manager se basa en patrones de gitignore.

  • Si un patrón no contiene / o solo lo contiene como carácter final, es un glob que coincide en cualquier directorio./
    • *.js coincide con los archivos de JavaScript en cualquier lugar.
    • build/ coincide con los directorios llamados build en cualquier lugar.
  • Si un patrón contiene / en cualquier lugar que no sea el final, se trata como una ruta de acceso relativa a la ubicación del archivo CODEOWNERS.
    • docs/* coincide con los archivos en docs/ en relación con el archivo CODEOWNERS.
    • /*.js coincide con los archivos de JavaScript en el mismo directorio que el archivo CODEOWNERS, pero no con los archivos de JavaScript anidados.
  • Un patrón que termina en / solo coincide con los directorios y su contenido de forma recursiva. Por ejemplo, build-*/ coincide con directorios como build-app/ y build-tool/ en cualquier lugar.
  • Si se usa .securesourcemanager/CODEOWNERS, las rutas son relativas a la raíz del repositorio.

• OWNERS: Es una lista opcional de direcciones de correo electrónico del propietario, separadas por espacios. Si se omite, esta regla actúa como una exclusión de ruta de acceso.

  Nota: Debes especificar las direcciones de correo electrónico de los usuarios individuales en los archivos CODEOWNERS. No se admiten los Grupos de Google para definir propietarios.

Propiedad específica de la rama

El campo BRANCH_GLOB opcional que se encuentra al principio de una línea de regla te permite implementar controles de propietario del código específicos de la rama.

• Si no especificas un BRANCH_GLOB al comienzo de la regla, esta se aplica a todas las ramas.
• El sistema ignora cualquier línea con un comodín de rama que no coincida con la rama actual.

Conceptos básicos de la sintaxis

• Interpretación del campo: Los campos están separados por espacios.
  • Los campos que contienen @ se identifican como direcciones de correo electrónico del propietario.
  • Si un campo sin @ precede a las direcciones de correo electrónico del propietario, se trata como PATH_GLOB. Por ejemplo, en *.js [e-mail], *.js es el PATH_GLOB.
  • Si dos campos sin @ preceden a las direcciones de correo electrónico del propietario, el primero es BRANCH_GLOB y el segundo es PATH_GLOB. Por ejemplo, en main *.js [e-mail], main es BRANCH_GLOB y *.js es PATH_GLOB.
  • Se aplica la misma lógica si no se especifican propietarios: un campo es PATH_GLOB y dos campos son BRANCH_GLOB PATH_GLOB.
• Sintaxis de estilo glob: Secure Source Manager usa la sintaxis estándar de estilo glob (estilo .gitignore) para las expresiones de ruta.
• Detalles de los caracteres comodín:
  • ** coincide con cualquier secuencia de caracteres, incluido /.
  • * coincide con cualquier secuencia de caracteres, excepto /.
  • ? coincide con cualquier carácter, excepto /.
• Distinción entre mayúsculas y minúsculas: Los archivos CODEOWNERS distinguen entre mayúsculas y minúsculas.
• Identificación del propietario: El sistema identifica a los propietarios por dirección de correo electrónico. El carácter @ distingue los campos del propietario.
• En las direcciones de correo electrónico del propietario, solo se deben escapar space y backslash.
• Caracteres reservados: El sistema reserva los siguientes caracteres. Debes agregar una barra inversa (\) antes de los caracteres especiales en las expresiones de ramas y rutas: [, ], , @, *, ?, \, {, } y !.
• Si ** se mezcla con caracteres que no son barras, el sistema lo trata como un comodín normal. Por ejemplo, /**/*.py coincide con cualquier archivo de Python de cualquier profundidad, y /**.py se trata como /*.py y solo coincide con los archivos del directorio raíz.

Secciones para varios conjuntos de aprobaciones

Las líneas [Section] agrupan las reglas en aprobaciones independientes requeridas. Esto es útil para solicitar revisiones de distintos equipos, por ejemplo, de Seguridad o de QA.

• Definición de sección: Usa una línea con el formato [Section Name] (usa cualquier nombre en lenguaje natural).
• Recuento de aprobaciones: Una sección puede incluir un sufijo opcional [<approverCount>] para especificar un recuento de aprobaciones distinto de 1. Un recuento de 0 significa propietarios opcionales. Por ejemplo, puedes usar esta función para mostrar expertos en archivos específicos con fines informativos sin necesidad de que los revisen.
• Finalización de la sección: Una sección se aplica a todas las reglas que la siguen hasta que comienza la siguiente sección.
• Reglas sin secciones: El sistema trata las reglas que aparecen antes de cualquier definición de [Section] como una sola sección unificada, lo que requiere una aprobación de forma predeterminada.
• Consolidación: El sistema trata las secciones con el mismo nombre sin distinción de mayúsculas y minúsculas, incluso en varios archivos CODEOWNERS anidados, como una sola sección unificada, según las reglas de precedencia estándar.

Exclusión de ruta

Para excluir rutas de acceso específicas de una cláusula más amplia anterior, establece en cero la cantidad de propietarios de la ruta de acceso. Si defines una regla sin propietarios, el sistema quitará los propietarios de esa ruta de acceso establecidos por reglas anteriores, y la ruta de acceso no requerirá aprobaciones de propietarios.

Las coincidencias de directorios solo funcionan si terminan en / o si no contienen comodines en la parte final.

Por ejemplo, *.py no coincidirá con un directorio oculto .py/, pero *.py/ sí lo hará.

Resolución de conflictos y precedencia

Si existe un archivo .securesourcemanager/CODEOWNERS, se ignoran todos los demás archivos CODEOWNERS. Si una ruta coincide con dos líneas diferentes en la misma sección, solo se aplicará la última línea. Si las líneas se encuentran en diferentes secciones, se aplicarán ambas.

El sistema usa una regla de precedencia basada en la ubicación para los archivos anidados:

• Las reglas de un archivo CODEOWNERS anidado más profundamente (más local) anulan las reglas coincidentes de un archivo menos profundo.
• El archivo CODEOWNERS del directorio raíz siempre tiene la prioridad más baja.

Ejemplo de archivo CODEOWNERS

El siguiente es un archivo CODEOWNERS de ejemplo que muestra la sintaxis de CODEOWNERS:

# Un-sectioned rules; 1 approve required from any of owners of last matching line.
# Format: [BRANCH_GLOB] PATH_GLOB [OWNERS...]

# Make repo-admin the owner of all files of the current branch.
*   [e-mail]      # No slash prefix; matches in sub-dirs too.
/**/* [e-mail]      # Slash-prefix equivalent of prior line.

# Match all py files (including sub-dirs). Note repo-admin must be re-added.
*.py  [e-mail] [e-mail]

# With repo-admin not included here, repo-admin no longer owns README.
/README.md [e-mail]

/scratchpad.txt             # Can also override a path to have zero owners (path exclusion).

# Branch-specific syntax.
# Note that since un-sectioned rules are independent of sectioned rules,
# the above [Section] rules will still apply to this branch if they
# aren't modified to add e.g. `main ` as a prefix.
dev-* *             # Remove all owners reqs on dev branches.
dev-* /experimental/ [e-mail]   # dev-specific owners.

# Make repo admin own all CODEOWNERS files, regardless of any prior rules.
CODEOWNERS [e-mail]

# Section; 1 approval required *in addition* to owners outside this section.
[Security Team]
/secure-directory/ [e-mail] [e-mail]
/**/*secure\ me* [e-mail] [e-mail]

# Section w/ req approval count of 2 instead of 1.
[Doc Team][2]
/docs [e-mail] [e-mail]
*.md [e-mail] [e-mail]

Compatibilidad con otros administradores de código fuente

Secure Source Manager proporciona una sintaxis familiar y portátil con otros administradores de código fuente. La sintaxis de CODEOWNERS de Secure Source Manager es compatible con la sintaxis de CODEOWNERS de GitHub y parcialmente compatible con la sintaxis de CODEOWNERS de GitLab, incluidos los recuentos de aprobación seccionales, como [Section Name][2].

La implementación de CODEOWNERS de Secure Source Manager no admite la sintaxis de !path de GitLab para la negación de rutas. Para obtener información sobre la negación de rutas en Secure Source Manager, consulta Exclusión de rutas. Secure Source Manager tampoco admite propietarios predeterminados en los encabezados de sección, por ejemplo, [Section Name] @owner1 @owner2.

Validación y manejo de errores

Cuando se visualiza un archivo CODEOWNERS, la IU muestra su estado y advertencias o información a nivel de la línea (por ejemplo, líneas que no coinciden con esta rama). Puedes colocar el cursor sobre los números o las líneas destacados para ver detalles adicionales.

Aplicación

Una protección previa al envío aplica la verificación de errores de sintaxis en cualquier rama en la que habilites la regla de rama de propietarios del código. Esto evita que se registren por accidente archivos CODEOWNERS dañados.

Manejo de errores de sintaxis

Las verificaciones previas al envío solo se ejecutan en las ramas en las que está habilitada la opción Require Code Owner Review on Pull Requests. Si se confirma un archivo CODEOWNERS sintácticamente no válido en una rama y, luego, se habilita la revisión del propietario del código para esa rama, el sistema controla los errores de forma correcta:

• El sistema ignora las líneas que no se pueden analizar en una definición de sección, una línea de regla o un formato de comentario.
• Si el recuento de aprobaciones es negativo, el sistema lo considera como 0.
• El sistema sigue analizando y aplicando las líneas válidas como de costumbre.

¿Qué sigue?

• Descripción general de la protección de ramas
• Configura la protección de ramas
• Trabaja con problemas y solicitudes de extracción
• Conéctate a Cloud Build