Git Health - higiene del repositorio

Git Health observa cómo se usa un repositorio, no el código que contiene: ramas muertas, merges sin revisión, force-push a ramas protegidas, commits desmesurados y señales de higiene similares.

Cómo funciona

• Se ejecuta en el servidor, contra el proveedor Git, con la credencial conectada del proyecto - sin collector, sin paso de CI. Todo proyecto con credencial queda cubierto. Los cuatro proveedores Git están cubiertos - GitLab, GitHub, Bitbucket Cloud y Azure DevOps Repos; una regla que un proveedor no puede responder (por ejemplo, el borrado por defecto de la rama origen en Bitbucket) se omite, no falla.
• Los análisis se encolan y procesan en segundo plano; se lanzan desde el proyecto o con los análisis programados.
• Cada regla produce un hallazgo con uno de cuatro estados; la puntuación del proyecto es una suma ponderada - un force-push pesa más que un detalle de nomenclatura.

Condiciones de merge y reglas de push

Más allá de la protección de rama en sí, Git Health lee lo que un merge exige realmente y lo que la protección todavía deja pasar:

• Aprobaciones - una merge request necesita al menos una aprobación, al menos dos, y su autor no puede aprobarla.
• Condiciones de merge - el merge requiere un pipeline correcto y las discusiones resueltas.
• Pushes a la rama por defecto - sin force push y sin push directo que evite una merge request. Una rama protegida puede seguir permitiendo el push directo a los maintainers o a personas nombradas en la rama: eso cuenta la mitad; si los desarrolladores pueden hacer push, no cuenta nada. Una rama sin proteger se informa una sola vez, con la regla de protección de rama; las dos reglas de push esperan a que la rama esté protegida.
• Tags - al menos un tag está protegido, para que una versión publicada no pueda moverse ni borrarse. Si un proyecto sigue sus versiones por tag, la regla de protección de versiones revisa esos tags y esta se retira.

Esto se lee en GitLab y GitHub; Bitbucket Cloud y Azure DevOps lo guardan en políticas de rama que todavía no se leen, así que allí las reglas no se aplican. La protección de tags solo se lee en GitLab.

Precaución

Las aprobaciones requieren un GitLab con licencia. Las aprobaciones de merge request son una función de GitLab Premium / Ultimate. En una instancia GitLab Free, las tres reglas de aprobación se omiten (no fallan) con el motivo la configuración de aprobaciones requiere un GitLab con licencia; las demás reglas se siguen evaluando. GitHub no necesita licencia para esto.

Las reglas de pipeline también buscan, además del escaneo de secretos y dependencias, un paso de análisis estático de seguridad (SAST), el escaneo de imágenes de contenedor y una lista de materiales de software generada (CycloneDX o SPDX). También se leen los archivos incluidos, plantillas de GitLab incluidas: las plantillas de GitLab de escaneo de dependencias y de contenedores generan ellas mismas una SBOM CycloneDX. Las plantillas de merge request y de issue se comprueban como archivos del repositorio.

Nota

Git Health y Cumplimiento se reparten el trabajo: Git Health lee la configuración del proveedor y el pipeline (protección de rama, condiciones de merge, pasos de CI, archivos secretos subidos), Cumplimiento lee los documentos propios del repositorio (README, .gitignore, SECURITY.md, .editorconfig). Una carencia la informa uno de los dos, no ambos.

Leer los resultados

• Puntuación y nota del proyecto, con los hallazgos detrás; cada uno explica qué se observó y por qué importa.
• Vista del espacio de trabajo - qué proyectos están cubiertos y cuáles nunca se analizaron (nunca analizado se informa como desconocido, no como sano).
• El área de Administración muestra la misma imagen a escala de la instalación.

Nota

Las reglas se ajustan por espacio de trabajo; una regla que no encaja con tu flujo se apaga en vez de discutirse.

Claves de incidencia, Sonar y versiones

• La regla de ramas exige una clave de incidencia (GIT_BRANCH_RULE_REQUIRES_ISSUE_KEY, GitLab) - se lee la regla de push del proyecto (branch name regex). Se cumple cuando la regla rechaza una rama sin clave (feature/add-login) y acepta una con ella (feature/PROJ-123-add-login, o en minúsculas feature/proj-123-...). Se juzga por lo que hace con nombres de ejemplo, no por cómo está escrita.
• Resultados de Sonar en la merge request (CI_SONAR_MR_REPORT) - el pipeline escribe el resultado de SonarQube en la merge request: un job que lo publica en la descripción, o el análisis de merge requests de Sonar (sonar.pullrequest.key). Un pipeline sin SonarQube se omite aquí; esa carencia la informa la regla de SonarQube.
• Las claves en minúsculas cuentan: bugfix/proj-123 nombra la incidencia tan claramente como bugfix/PROJ-123 en la regla de nombres de rama.
• Promociones de versión - una merge request que lleva una rama release/ a la rama por defecto contiene todas las incidencias de la versión, así que no cuenta en la regla de títulos de merge request, igual que los commits de merge no cuentan en la regla de commits.
• Protección con comodín - una rama protegida por un patrón (release/*) cuenta como protegida, en la regla de ramas de versión y en todas partes.
• Los archivos de bloqueo se buscan hasta tres carpetas de profundidad (src/<layer>/<Project>/packages.lock.json), primero las carpetas de código; una búsqueda que el escaneo no pudo terminar queda omitida, nunca ausente.

Reglas retiradas

Estas reglas ya no se ejecutan. Los hallazgos de escaneos anteriores quedan en el historial; junto a cada una figura la regla que responde ahora a la misma pregunta.

Regla	Sustituida por	Motivo
REPO_README_PRESENT	Cumplimiento DOC_README_EXISTS	Los documentos del repositorio los comprueba Cumplimiento; el mismo archivo ausente se informaba en los dos módulos.
REPO_GITIGNORE_PRESENT	Cumplimiento REPO_GITIGNORE_EXISTS	El mismo motivo.
REPO_SECURITY_MD_PRESENT	Cumplimiento SEC_POLICY_EXISTS	El mismo motivo.