> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Repositorios
> Conecta repositorios; configura revisión, PM, reglas de branch, webhooks de VCS y bootstrap de arquitectura.
Los repositorios son el centro operativo de Acrity. Definen cómo se analizan los pull requests o merge requests, qué proveedores se usan y qué excepciones aplican a cada proyecto.
Usa `Consola > Repositorios` para listar, conectar, configurar, pausar, validar y eliminar repositorios.
Da seguimiento al estado de las revisiones, las decisiones y los hallazgos en el panel de Ops. Usa `Consola > Audit Trail` solo para detalles técnicos de eventos, diagnóstico y auditoría administrativa.
## Quién puede acceder
Los repositorios requieren un admin de workspace. Los admins de plataforma también tienen acceso. Los roles son conjuntos fijos de capacidades definidos por Acrity, no configurables por tu organización.
## Conectar repositorios
Accede a `Consola > Repositorios > Conectar repositorio`.
Selecciona aplicación conectada, credencial manual o conector local.
Elige los repositorios disponibles o informa los nombres según el origen elegido.
Opcionalmente asocia un proveedor de gestión de tareas y campos de extracción.
Configura branches, comportamiento para drafts, checks e idioma cuando sea necesario.
Guarda y da seguimiento al estado de readiness en la lista o en el detalle del repositorio.
## Métodos de conexión
| Método | Cuándo usar |
| -------------------- | -------------------------------------------------------------------------- |
| Aplicación conectada | Proveedor SaaS con una instalación autorizada en el workspace. |
| Credencial manual | Token o credencial específica controlada por el workspace. |
| Conector local | VCS privado, self-hosted o accesible solo desde la red de la organización. |
## Estados de readiness
Un repositorio debe alcanzar el estado **Ready** antes de que Acrity analice sus pull requests o merge requests. Da seguimiento al estado actual en la lista de repositorios y en la página de detalle del repositorio.
El bootstrap de `ARCHITECTURE.md` es obligatorio, no opcional. Hasta que se haga merge, el repositorio permanece en **Awaiting architecture merge** y no recibe revisiones.
| Estado | Significado | Cómo avanzar |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Ready | La conexión está autorizada, el webhook entrante es válido y se ha hecho merge de `ARCHITECTURE.md`. Acrity revisa los nuevos PRs/MRs. | No se requiere acción. Mantén la conexión y el webhook en buen estado. |
| Awaiting architecture merge | La conexión y el webhook son válidos, pero el repositorio aún necesita su línea base de arquitectura. El bootstrap de `ARCHITECTURE.md` es obligatorio y condiciona el readiness. | Abre la pestaña Bootstrap, genera la documentación de arquitectura y haz merge de `ARCHITECTURE.md` en la branch destino. |
| Setup incomplete | Falta configuración obligatoria, como el webhook entrante, la credencial o la selección de conector. | Completa los pasos de Conectar repositorio: confirma el origen, pega la URL del webhook entrante y la clave en el proveedor, y revalida. |
| Blocked | Acrity no puede acceder al repositorio. La credencial, la aplicación conectada o el conector falló la validación, o se revocaron los permisos. | Corrige o rota la credencial, reautoriza la aplicación conectada o revalida el conector, y luego confirma los permisos. |
```mermaid theme={null}
stateDiagram-v2
state "Setup incomplete" as Setup
state "Blocked" as Blocked
state "Awaiting architecture merge" as Awaiting
state "Ready" as Ready
[*] --> Setup: Repository connected
Setup --> Blocked: Validation fails
Setup --> Awaiting: Connection and webhook valid
Blocked --> Awaiting: Credential or connector fixed
Awaiting --> Ready: ARCHITECTURE.md merged
Ready --> Blocked: Access revoked
Ready --> [*]: Repository removed
```
## Pantalla de lista
La lista de repositorios ayuda a identificar:
* repositorios conectados;
* estado de readiness;
* proveedor VCS;
* método de autenticación;
* última validación;
* alertas de webhook, credencial o conector;
* repositorios que requieren acción antes de recibir revisiones.
Usa filtros y búsqueda para ubicar proyectos rápidamente. La lista de repositorios puede mostrar indicios operativos, pero el panel de Ops es el lugar principal para dar seguimiento al progreso y a los resultados de las revisiones.
## Detalle del repositorio
La página de detalle concentra las configuraciones del proyecto.
| Pestaña o sección | Para qué sirve |
| ----------------- | -------------------------------------------------------------------------------------------- |
| Configuraciones | Datos generales, proveedor, autenticación, idioma, pausa de revisiones y estado operacional. |
| PM | Campos y fuentes usados para asociar PRs/MRs a tareas, criterios y contexto de producto. |
| Revisión | Tiers e instrucciones adicionales específicas del repositorio. |
| Bootstrap | Flujo asistido para preparar o revisar la documentación de arquitectura del repositorio. |
## Idioma del repositorio
El idioma del repositorio sobrescribe el predeterminado del workspace para ese proyecto.
Úsalo cuando:
* un equipo trabaja en un idioma diferente al resto del workspace;
* repositorios de clientes requieren respuestas localizadas;
* los comentarios de revisión necesitan seguir un estándar de comunicación específico.
Si no hay idioma configurado en el repositorio, Acrity usa el predeterminado del workspace.
## Reglas de branch
Las reglas de branch ayudan a evitar revisiones en escenarios que no necesitan análisis o que generan ruido.
Configuraciones comunes:
* branches raíz o principales, como `main`, `master`, `develop` o equivalentes;
* ignorar merges entre branches raíz;
* reglas para ignorar combinaciones específicas de origen y destino;
* coincidencia por texto exacto, prefijo, sufijo, fragmento o patrón configurado;
* revisión de PR/MR en draft;
* comportamiento cuando los checks del proveedor indican éxito.
Empieza con reglas conservadoras. Después ajusta con base en el volumen real de revisiones y en los casos que generaron ruido.
## Integración con PM
La integración con PM permite que Acrity relacione PRs/MRs con tareas, criterios de aceptación y contexto de producto.
Campos comunes:
* identificador de la tarea;
* criterios de aceptación;
* story points;
* sprint;
* épica;
* prioridad;
* componente;
* labels;
* campo de fallback cuando la información principal no está disponible.
Fuentes comunes para extracción:
* nombre de la branch;
* título del PR/MR;
* descripción del PR/MR;
* comentarios cuando estén habilitados por la configuración.
## Configuración de revisión por repositorio
La configuración del repositorio debe usarse para excepciones al predeterminado del workspace.
Úsala cuando:
* un proyecto requiere instrucciones diferentes;
* un repositorio necesita solo un tier de revisión;
* el equipo tiene convenciones específicas;
* la salida de revisión debe usar un idioma o enfoque diferente.
Evita duplicar en el repositorio lo que ya está bien definido en `Consola > Policy Engine`.
## Pausar y retomar revisiones
Pausar revisiones impide nuevos análisis automáticos para el repositorio mientras la pausa esté activa.
Usa la pausa cuando:
* el repositorio está en migración;
* el proveedor está inestable;
* las credenciales se están rotando;
* el equipo quiere interrumpir las revisiones durante una ventana planificada;
* las reglas necesitan revisarse antes de continuar.
Retoma tan pronto como se resuelva la causa.
## Webhook de VCS
El webhook de VCS permite que los eventos del proveedor activen Acrity.
Desde la Consola, puedes:
* configurar el webhook cuando el proveedor y el método de conexión lo permitan;
* revalidar el webhook;
* revisar el estado de configuración;
* identificar pendientes de permiso o secreto.
Si se accede al proveedor mediante un conector local, sigue también la documentación de `Consola > Conectores`.
## Cómo se disparan las revisiones
Acrity inicia una revisión cuando tu proveedor envía un evento de pull request o merge request al webhook entrante de VCS de Acrity.
En las conexiones por aplicación conectada, Acrity registra el webhook por ti. En las conexiones por credencial manual y conector local, tú mismo pegas el webhook en el proveedor:
Abre la página de detalle del repositorio y ve a la sección Webhook de VCS. Copia la URL del webhook entrante y la clave de firma.
En la configuración de tu proveedor de VCS, crea un webhook. Pega la URL en el campo de payload o URL destino y la clave en el campo de secreto.
Suscríbete a los eventos de pull request o merge request para que el proveedor notifique a Acrity cuando se abre o actualiza un PR/MR.
Vuelve a la sección Webhook de VCS y revalida. Acrity confirma que puede recibir eventos antes de que el repositorio pase a Ready.
```mermaid theme={null}
sequenceDiagram
participant Dev as Developer
participant VCS as VCS provider
participant Acrity as Acrity inbound webhook
participant Review as Review run
Dev->>VCS: Open or update PR/MR
VCS->>Acrity: Send PR/MR event to inbound webhook
Acrity->>Acrity: Verify signing key and branch rules
Acrity->>Review: Start review run
Review-->>Dev: Post review comments on the PR/MR
```
## Bootstrap de arquitectura
La pestaña Bootstrap ayuda a preparar la documentación de arquitectura del repositorio cuando el flujo esté disponible.
Úsala para:
* verificar si el repositorio ya tiene documentación de arquitectura;
* iniciar la generación asistida;
* revisar el material propuesto;
* elegir la branch destino cuando corresponda;
* concluir el flujo con o sin commit, según las opciones mostradas;
* repetir o reiniciar cuando la pantalla indique que está permitido.
Revisa el contenido generado antes de publicarlo en el repositorio. La organización es responsable de aceptar y versionar la documentación.
## Security scans
Cuando está habilitado, el repositorio puede mostrar información de scans de seguridad y dependencias. Usa la pantalla para dar seguimiento al último scan, la próxima ejecución y las acciones disponibles.
Los detalles de datos y seguridad están en `Seguridad > Tratamiento de datos`.
## Problemas comunes
| Síntoma | Qué verificar |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| El repositorio no queda listo | Revisa la credencial, la aplicación conectada, el conector, los permisos y el webhook. |
| Las revisiones no se disparan | Verifica si el repositorio está pausado, si el webhook es válido y si las reglas de branch ignoran el evento. Da seguimiento al estado de las revisiones en el panel de Ops; usa Audit Trail solo para detalles técnicos de eventos y diagnóstico. |
| Los comentarios aparecen en el idioma incorrecto | Revisa el idioma del repositorio y el idioma del workspace. |
| La tarea de PM no se encuentra | Revisa las fuentes de extracción y los campos configurados en la pestaña PM. |
| Se revisan demasiados PRs irrelevantes | Ajusta las reglas de branch, la revisión de drafts y la política de autores del workspace. |