Repositorios por proyecto

Estado: guia operativa inicial

Fecha: 2026-05-24

Para que sirve

Un repositorio por proyecto permite que Comandesk ejecute o prepare trabajo sin depender del disco local del usuario. El repo se convierte en la frontera operativa: branch, diff, commit, pull request o worktree remoto.

Esto no obliga a usar GitHub. El modelo acepta GitHub, GitLab, Gitea, Forgejo, Bitbucket o un remoto Git generico.

Cuando usar repo/remoto

Usa repo/remoto si:

• el proyecto ya vive en Git;
• quieres revisar diffs antes de publicar;
• el equipo trabaja con branches o pull requests;
• no quieres instalar un runner local en la maquina del usuario;
• necesitas reproducibilidad y rollback.

Usa runner local si:

• los archivos solo existen en el ordenador del usuario;
• hay herramientas o modelos locales no disponibles en remoto;
• el trabajo no puede subirse a un repo.

Campos del repositorio

• provider: github, gitlab, gitea, forgejo, bitbucket o generic.
• remote_url: URL remota HTTPS, SSH o formato Git.
• default_branch: branch principal, normalmente main.
• work_strategy: branch, pull_request, worktree o manual.
• web_url: enlace web opcional para inspeccion humana.
• trust_level: untrusted o trusted.
• push_policy: none, branch, pull_request o direct.
• auto_push: true solo si quieres que el runner pueda empujar automaticamente cuando la politica lo permita.
• allowed_push_branches: ramas autorizadas para push automatico.

Por defecto un repositorio es untrusted, push_policy=none y auto_push=false.

Eso significa que el agente puede preparar cambios y commits locales, pero debe devolver push_required en la evidencia en vez de ejecutar git push.

Para permitir push automatico deben cumplirse todas estas condiciones:

• el proyecto esta marcado como trust_level=trusted;
• auto_push=true;
• push_policy es branch, pull_request o direct;
• la rama actual esta dentro de allowed_push_branches;
• la tarea deja evidencia de commit, push y branch.

Abogado del diablo: direct a la rama principal es comodo para proyectos internos, pero no debe ser el valor por defecto para clientes. En producto vendible, usa pull_request como opcion segura y reserva direct para workspaces internos o repositorios expresamente confiables.

Flujo de alta

1. Abrir el cockpit del proyecto.
2. Ir a Infraestructura.
3. Pulsar Configurar repo.
4. Elegir proveedor.
5. Guardar remote URL y branch principal.
6. Elegir estrategia de trabajo.
7. Definir politica de push: sin push, branch, pull request o direct.
8. Marcar como confiable solo si el remoto, la rama y la credencial son correctos.
9. Configurar credencial deployment/server si el worker remoto la necesita.
10. Crear preflight en modo Repo remoto.
11. Ejecutar una tarea pequena.
12. Revisar evidencia: diff, commit, PR o resumen de cambios.

Estrategias

Branch

El agente trabaja en una rama por tarea o por fase.

Bueno para:

• cambios pequenos;
• revision rapida;
• proyectos sin flujo formal de PR.

Pull request

El agente debe entregar un PR o MR revisable.

Bueno para:

• equipos;
• auditoria;
• clientes que no quieren cambios directos en rama principal.

Worktree

El agente usa un worktree aislado por ejecucion.

Bueno para:

• tareas concurrentes;
• pruebas antes de commit;
• runners remotos persistentes.

Manual

Comandesk registra el repo y el preflight, pero la ejecucion la hace una persona o una herramienta externa.

Bueno para:

• pilotos;
• clientes con restricciones;
• casos sin automatizacion fiable todavia.

Readiness esperado

Para modo repo/remoto, el cockpit debe poder mostrar al menos:

• repositorio configurado o target remoto vinculado;
• branch principal;
• estrategia de trabajo;
• credencial aplicable si el worker necesita clonar, hacer push o crear PR;
• preflight de primera ejecucion.

Primer preflight

La primera tarea no debe publicar. Debe validar:

• que el remoto es accesible;
• que el branch existe;
• que la estrategia elegida es viable;
• que la credencial no tiene mas permisos de los necesarios;
• que la evidencia esperada queda clara.

Limites actuales

• El repo queda modelado en el proyecto; la creacion automatica en proveedores se implementara por proveedor.
• La primera version no asume GitHub como unico proveedor.
• Crear PR/MR automatico requiere credenciales y adaptador del proveedor.
• Para URL Git generica, Comandesk puede coordinar branch/diff/commit, pero no todas las funciones web existen.

Criterio para venderlo

Se puede vender como:

> Ejecucion remota o revisable a traves del repositorio del proyecto, sin depender del disco local.

No se debe vender como:

> Creamos y publicamos en cualquier proveedor sin configuracion ni permisos.