Documentación de Oteador

Oteador reúne en un solo lugar el análisis de todos los repositorios de tu organización: los agrupa, les aplica reglas y controles de calidad de forma automática, y te muestra el estado de todo el portafolio. La idea es que puedas dirigir la calidad del código de un equipo grande sin tener que revisar cada repositorio a mano.

Esta guía explica cómo usar el producto paso a paso, qué hace cada una de las herramientas de análisis que integra y cómo se manejan sus licencias. Puedes leerla de corrido o usar el buscador de arriba y el menú lateral para ir directo a lo que necesites.

Conceptos clave

• Proyecto. Un grupo de repositorios que quieres ver y analizar como una sola unidad. Normalmente son los de un mismo producto o un mismo equipo.
• Perfil de análisis. La lista de qué análisis se corren en ese proyecto y con qué reglas. Cada repositorio del proyecto puede ajustar ese perfil si necesita algo distinto de los demás.
• Corrida. Cada vez que Oteador analiza un repositorio aplicándole el perfil. De cada corrida salen los hallazgos y un veredicto.
• Quality gate. Ese veredicto, resumido en tres estados —OK, revisar o bloqueado— según qué tan graves sean los hallazgos encontrados.
• Portafolio. La vista de conjunto de toda la organización: cuántos repositorios están cubiertos, cómo se reparten los veredictos y cuáles son los de mayor riesgo.

Primeros pasos

1. Conecta una credencial. En Credentials pegas un token de acceso de tu proveedor de Git (GitHub, GitLab, Azure o Bitbucket). Oteador lo guarda cifrado y lo usa para descargar tus repositorios y para enterarse cuando cambian.
2. Sigue repositorios. En Repositories agregas los repositorios que quieres vigilar. Oteador se pone al día con cada uno y trae su historial: los commits, las ramas y los pull requests.
3. Crea un proyecto. En Proyectos agrupas esos repositorios y eliges qué análisis quieres correr sobre ellos.
4. Corre el análisis. Lanzas la primera corrida y, cuando termina, revisas los resultados de cada repositorio y la foto general en el Portafolio.

Proyectos y perfiles de análisis

Cada proyecto tiene un perfil de análisis que decide qué análisis se corren en sus repositorios y con qué reglas. Lo ves y lo ajustas desde el proyecto, con interruptores; por debajo se guarda con esta forma:

{
  "analyzers": {
    "gitleaks":  { "enabled": true },
    "trivy":     { "enabled": true, "severities": ["CRITICAL","HIGH"] },
    "semgrep":   { "enabled": true, "ruleset": "auto" },
    "archunit":  { "enabled": true, "no_cycles": true,
                   "rules": [
                     { "from": "app/domain/**", "to": "app/infrastructure/**",
                       "severity": "critical",
                       "message": "el dominio no debe depender de infraestructura" }
                   ] }
  }
}

Si un repositorio del proyecto necesita algo distinto de los demás, puede llevar su propio ajuste con esta misma forma, que se aplica encima del perfil general solo para ese repositorio.

Correr el análisis

Desde el detalle del proyecto, el botón Correr análisis lanza el análisis de todos sus repositorios a la vez. Cada uno se procesa por separado, así que si el análisis de un repositorio falla, los demás siguen su curso sin verse afectados.

Dentro de cada repositorio, los distintos tipos de análisis también corren por separado. Todos sus hallazgos se ordenan en un mismo formato —severidad, regla, ubicación y mensaje— y se guardan junto al veredicto, de modo que más adelante siempre puedes ver de dónde salió cada resultado.

Quality gates

Cada corrida termina con un veredicto, y ese veredicto depende de qué tan graves son los hallazgos que encontró:

• Bloqueado. Apareció al menos un hallazgo crítico —por ejemplo, un secreto expuesto en el código o el incumplimiento de una regla de arquitectura que marcaste como crítica—. Es la señal de que algo debería resolverse antes de seguir adelante.
• Revisar. No hay nada crítico, pero sí hallazgos importantes o advertencias que vale la pena mirar con calma.
• OK. El repositorio salió limpio: solo información, o nada que reportar.

Portafolio

La vista de portafolio junta la última corrida de cada repositorio en una sola pantalla para toda la organización: cuántos proyectos y repositorios tienes, qué parte ya está analizada (la cobertura), cómo se reparten los veredictos, cuántos hallazgos hay en cada nivel de gravedad y cuáles son los repositorios de mayor riesgo. Es la foto que usas para decidir por dónde empezar.

Análisis programado

Si activas Análisis diario en un proyecto, Oteador analiza todos sus repositorios una vez al día de forma automática, sin que tengas que lanzarlo a mano. Es la manera de asegurarte de que nada se queda sin revisar, incluso cuando hablamos de cientos o miles de repositorios.

Herramientas de análisis (open source)

Oteador no reimplementa los analizadores. En lugar de eso, aprovecha proyectos open source que ya llevan años probándose en la industria y los ejecuta como programas independientes: a cada uno le entrega una copia del repositorio que quieres analizar, espera a que termine y recoge lo que reporta. El código de esas herramientas nunca queda dentro del de Oteador, sino que corre por fuera, como cuando abres un programa aparte en tu computadora.

Reglas de arquitectura

Este tipo de análisis te deja declarar reglas de arquitectura en el perfil del proyecto y las hace cumplir automáticamente: por ejemplo, "una capa no puede depender de otra" o "no se permiten dependencias circulares".

Cuando marcas una de esas reglas como crítica, incumplirla bloquea el quality gate. Así una decisión de arquitectura deja de ser solo un acuerdo escrito en un documento y pasa a aplicarse por sí sola en toda la organización, sin que nadie tenga que ir a revisarla repositorio por repositorio.

Atribuciones y licencias de terceros

Cada herramienta open source que usa Oteador viene con su propia licencia, y no todas piden lo mismo. Algunas, las llamadas copyleft (como GPL, AGPL o LGPL), obligan a que quien modifique la herramienta o la incorpore dentro de su propio programa publique también su código fuente. Otras, las permisivas (MIT, Apache-2.0, BSD), solo piden que se mantengan los créditos del autor.

Oteador está construido para respetar ambas sin quedar atrapado por la primera. La clave está en cómo usa las herramientas: no las mete dentro de su código, sino que las ejecuta como programas aparte y se comunica con ellas por fuera. En términos de licenciamiento, a esto se le llama mantenerlas «a distancia de brazo». Mientras esa separación se conserve, la obligación de publicar el código recae sobre cada herramienta por su cuenta, no sobre Oteador, y por eso es posible combinar en un mismo producto herramientas con licencias que de otro modo serían incompatibles entre sí.

En la tabla puedes ver la licencia exacta de cada herramienta y, marcadas con copyleft, las que por eso corren siempre como programa aparte. El enlace de cada fila lleva al código fuente del proyecto, que es donde vive el texto legal completo de su licencia y sus condiciones de uso.