CODEOWNERS y buenas prácticas de protección de ramas
Última actualización
CODEOWNERS indica quién debe revisar qué archivos. La protección de ramas (o los rulesets) define qué debe cumplirse antes de que el código llegue a main. Juntos son los controles de calidad y seguridad más económicos que tiene, siempre que estén configurados de forma que nadie pueda saltárselos. Esta guía cubre la sintaxis y los ajustes que más importan.
Cómo funciona CODEOWNERS
Un archivo CODEOWNERS asigna patrones de ruta a usuarios o equipos. GitHub lo busca en .github/, en la raíz del repositorio o en docs/, en ese orden, y usa el primero que encuentra. Cuando un PR modifica archivos que coinciden, GitHub solicita automáticamente la revisión a los propietarios indicados. Si la protección de ramas exige la revisión de los propietarios de código, el PR no puede fusionarse sin la aprobación de uno de ellos.
# Default owners for everything
* @acme/platform
# Frontend
/web/ @acme/frontend
*.css @acme/frontend @acme/design
# Backend and database
/services/api/ @acme/backend
/db/migrations/ @acme/backend @acme/dba
# CI and security-sensitive files
/.github/ @acme/platform @acme/security
/infra/ @acme/platform
Dockerfile @acme/platform
Las reglas, según la documentación de GitHub:
- Gana el último patrón que coincida. Ordene de lo general a lo específico. Un archivo que coincida con dos líneas toma solo los propietarios de la línea posterior, no de ambas.
- Los patrones siguen las reglas de
.gitignore, con excepciones: no puede usar la negación!, y los rangos de caracteres[ ]no son compatibles. - Los propietarios son
@username,@org/team-nameo una dirección de correo electrónico vinculada a una cuenta. - Los propietarios deben tener acceso de escritura al repositorio, y un equipo debe ser visible y tener acceso de escritura. De lo contrario, la línea se ignora.
- Un archivo de más de 3 MB no se lee.
- Las líneas no válidas se marcan en la lista de errores de la vista del archivo; compruébela después de editar.
Genere un archivo inicial con el generador de CODEOWNERS y, a continuación, revíselo como lo haría un revisor.
Use equipos, no personas
Las personas se van, se ausentan de vacaciones y se convierten en cuellos de botella. Asigne equipos y deje que la asignación de revisiones por equipo de GitHub elija uno o más miembros (por turnos o equilibrando la carga) en la configuración del equipo. En equipos muy grandes, active la «Asignación automática» para que las notificaciones no lleguen a todos.
Mantenga la propiedad lo bastante amplia como para que siempre haya alguien disponible en un PR, y lo bastante acotada como para que tenga sentido. Un archivo en el que cada PR necesite cinco aprobaciones enseña a la gente a aprobar sin revisar.
Proteja las rutas que los atacantes quieren
Asigne a un equipo de confianza la propiedad de:
/.github/y, sobre todo,/.github/workflows/. Un cambio en un workflow puede acceder a secretos y desplegar; consulte cómo proteger GitHub Actions.- El propio
CODEOWNERS, para que las reglas no puedan modificarlas quienes no son propietarios de nada. - Los manifiestos de dependencias y los archivos de bloqueo, si la revisión de la cadena de suministro le importa.
- El código de infraestructura, la lógica de autenticación y facturación, y las migraciones.
¿Protección de ramas o rulesets?
Los rulesets son el mecanismo más reciente. Pueden superponerse, aplicarse a muchas ramas mediante patrones, funcionar en toda una organización y tener listas de omisión auditadas. Las reglas de protección de ramas son más antiguas, pero siguen siendo compatibles. En cualquier caso, configure estas opciones en main y en las ramas de publicación:
| Ajuste | Recomendación | Motivo |
|---|---|---|
| Exigir un pull request antes de fusionar | Activado | Sin envíos directos |
| Aprobaciones requeridas | 1, o 2 en repositorios sensibles | Revisión para cada cambio |
| Descartar aprobaciones obsoletas con nuevos commits | Activado | Una aprobación debe cubrir el código que se fusiona |
| Exigir revisión de los propietarios de código | Activado | Hace que CODEOWNERS sea vinculante |
| Exigir aprobación del envío más reciente | Activado | El autor no puede añadir commits después de la aprobación ni fusionar por su cuenta |
| Exigir comprobaciones de estado | Activado, con comprobaciones requeridas indicadas por nombre | El CI debe pasar |
| Exigir que las ramas estén actualizadas | Activado, o use una merge queue | Evita conflictos semánticos |
| Exigir resolución de conversaciones | Activado | Los comentarios reciben respuesta |
| Exigir commits firmados | Opcional | Necesario en algunos marcos de cumplimiento normativo |
| Exigir historial lineal | Opcional | Coincide con la fusión por squash o rebase |
| Bloquear force pushes y eliminaciones | Activado | Proteger el historial |
| No permitir omitir la regla | Activado para todos, incluidos los administradores | "Los administradores pueden anular" suele usarse en el peor momento |
Las comprobaciones obligatorias deben ser pocas y estables: pruebas, linter, compilación y un análisis de seguridad. Asígneles nombre mediante un único job de resumen, de modo que renombrar las celdas de una matrix no rompa la regla; consulte compilaciones con matrix bien hechas. Una comprobación obligatoria que se omite por un filtro paths queda pendiente indefinidamente, así que gestiónela en el workflow.
Evite los errores habituales
- Revisión de propietarios de código en un repositorio con un solo mantenedor. El autor no puede aprobar su propia PR, así que un único propietario queda bloqueado. Añada un segundo propietario o use un equipo de al menos dos personas.
- Propietario que no está en la lista de escritura del repositorio. La línea se ignora sin avisar.
- **
catch-all with a huge team.* Everyone is requested on every PR, so nobody feels responsible. - Bots. Las PR de Dependabot y Renovate también necesitan propietarios para no quedar bloqueadas. Asígnelas a un equipo rotatorio de responsables de dependencias y use auto-merge para las actualizaciones de bajo riesgo. Consulte configuración de Dependabot.
- Comprobaciones obligatorias inestables. La gente empieza a usar la omisión por administrador. Corrija las inestabilidades; consulte cómo tratar las pruebas inestables.
- Listas de omisión que crecen. Revíselas cada trimestre.
Buenas prácticas de revisión que lo acompañan
- Mantenga las PR pequeñas. Los revisores aprueban diffs grandes sin leerlos.
- Añada una plantilla de PR con una lista de verificación para las rutas de riesgo.
- Controle el tiempo de revisión; las revisiones lentas alargan el lead time, una de las métricas DORA.
- Use revisiones obligatorias de los propietarios para las rutas de riesgo y un proceso más ligero para la documentación. CODEOWNERS permite expresarlo: asigne la documentación a un equipo amplio.
Pruébelo
Tras cambiar las reglas, abra una PR de prueba que toque cada área protegida y confirme que se solicita a las personas correctas y que el botón de fusión queda bloqueado. En la vista del archivo CODEOWNERS, GitHub muestra los errores de sintaxis; corríjalos primero.
Preguntas frecuentes
¿Dónde debe estar el archivo CODEOWNERS?
.github/CODEOWNERS es la opción habitual. GitHub también lee la raíz del repositorio y docs/.
¿Puede un archivo tener varios propietarios?
Sí. Indique varios propietarios en una misma línea. Cualquiera de ellos puede cumplir el requisito de propietario de código (no todos a la vez), salvo que cree requisitos independientes con rulesets.
¿Se aplican los propietarios de código al autor de la PR?
Un propietario que crea la PR no puede aprobarla por sí mismo, así que tiene que aprobarla otro propietario.
¿La rama main es la única que necesita esto?
Proteja cualquier rama que despliegue, como release/* o production. Un ruleset con un patrón de ramas lo hace en un solo lugar.
Relacionado
Combine esto con la guía de Dependabot para que las PR de actualización tengan un propietario. Unas comprobaciones obligatorias más rápidas también ayudan a que la gente siga el proceso: el modo de comparación de compiler.dev muestra cuánto antes terminan sus comprobaciones obligatorias en runners más rápidos.
Relacionado
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.
- Mejores proveedores de runners para GitHub Actions 2026Los mejores proveedores de runners para GitHub Actions, por caso de uso: precio, macOS, builds con Docker, ARM, AWS y tarifa plana. Precios públicos al 22/10/2026.