FXCode
ENTRAR →
Doc. 08 — Funciones

Ramas y PR

Cómo cerrar bien las tareas que un agente trabaja en una rama de git, a mano o con el webhook de GitHub.

«Working» significa que alguien la está tocando ahora. Si el trabajo ya está hecho pero vive en otra rama que aún no se ha mergeado, la tarea no está «Working»: está «En revisión».

Antes, un agente terminaba en su rama y la tarea se quedaba con el barrido animado aunque nadie la tocara. Con las ramas y PR, cada tarea guarda su rama y su pull request, y al terminarla FXCode decide si va a revisión o se completa según dónde estés.

Los tres modos

Cada proyecto elige uno en Proyecto → Avanzado → Ramas y PR (solo el propietario o un administrador).

Modo Qué hace al terminar una tarea Cuándo elegirlo
Revisión (recomendado, por defecto) En una rama distinta de la principal, la pasa al estado de revisión y guarda la rama. En la principal, o sin rama, la completa. Casi siempre. Trabajas con ramas y cierras las tareas al mergear.
GitHub Igual que Revisión, y además los webhooks de pull requests de GitHub mueven las tareas solos: PR abierto → revisión, PR mergeado en la principal → completada. El repo está en GitHub y quieres que el merge cierre la tarea sin tocar nada.
Manual Terminar siempre completa la tarea. La rama y el PR son solo informativos. Trabajas directamente sobre la rama principal o no usas ramas.

En los mismos ajustes eliges:

  • Rama principal (main por defecto): terminar en ella completa la tarea.
  • Estado de revisión: a dónde van las tareas terminadas fuera de la principal. Si lo dejas en Automático, se usa el estado llamado «En revisión» (sin importar mayúsculas ni tildes); si no existe, la tarea no se mueve y solo se guarda la rama. Créalo en Ajustes → Estados de tarea si aún no lo tienes.
  • Horas para «sin actividad» (24 por defecto). Ver más abajo.

El flujo típico con un agente

¿Varios agentes a la vez? Dale a cada uno su worktree y su rama con fxc tasks start <id> --worktree: mira Trabajo en paralelo (worktrees).

# 1. Una rama con el id de la tarea en el nombre
git switch -c feat/fxc-cm4k2x9ab0001-login-github

# 2. La tarea pasa a Working mientras trabajas
fxc tasks update cm4k2x9ab0001 -s Working

# … el agente trabaja, hace commits y sube la rama …

# 3. Al terminar, desde la rama
fxc tasks finish cm4k2x9ab0001
# ✓ Task moved to review (branch feat/fxc-cm4k2x9ab0001-login-github): En Revisión

# 4. Opcional: guarda el PR en la tarea
fxc tasks update cm4k2x9ab0001 --pr https://github.com/acme/tienda/pull/42

fxc tasks finish toma la rama actual con git rev-parse --abbrev-ref HEAD si estás dentro de un repo; también puedes pasarla con --branch. Fuera de un repo, o en la rama principal, la tarea se completa.

  1. Al mergear en main, la tarea se cierra:
    • en modo Revisión, la pasas tú al estado terminado (fxc tasks update <id> -s Terminada, o fxc tasks finish <id> --branch main);
    • en modo GitHub, la cierra el webhook en cuanto GitHub avisa del merge.

En la lista de tareas y en su detalle ves la rama y el PR con su estado (abierto, mergeado o cerrado). En el detalle de la tarea puedes editarlos a mano.

Conectar el webhook de GitHub

  1. En Proyecto → Avanzado → Ramas y PR, elige el modo GitHub, escribe el repositorio como owner/repo y guarda.
  2. Pulsa Generar secreto. Cópialo en ese momento: solo se muestra una vez. Si lo pierdes, rota uno nuevo (el anterior deja de valer).
  3. En GitHub, abre el repositorio → Settings → Webhooks → Add webhook y rellena:
Payload URL     https://api.fxcode.dev/integrations/github/webhook
Content type    application/json
Secret          <el secreto que generaste en FXCode>
SSL verification  Enable SSL verification
Which events?   ( ) Just the push event
                ( ) Send me everything
                (•) Let me select individual events
                    [x] Pull requests      ← solo este
Active          [x]
  1. Guarda. GitHub envía un ping; en Recent Deliveries debería salir con un check verde.

La URL exacta de tu instalación aparece en los ajustes, junto a un botón para copiarla (en self-hosted es <tu API>/integrations/github/webhook).

Qué hace cada evento:

Evento pull_request Efecto en la tarea
opened, reopened, ready_for_review Pasa a revisión y guarda la URL y el número del PR, el estado abierto y la rama
closed con merge en la rama principal Pasa al estado terminado; PR mergeado
closed con merge en otra rama PR mergeado, sin cambiar el estado
closed sin merge PR cerrado, sin cambiar el estado

Cada entrega se verifica con la firma X-Hub-Signature-256 contra el secreto del proyecto: una firma inválida se rechaza y nada cambia. El webhook solo actúa si el proyecto está en modo GitHub, y solo sobre las tareas de ese proyecto. El secreto se guarda cifrado; nunca sale en las respuestas del API.

Cómo se asocia un PR a una tarea

El webhook busca la tarea por su id en el nombre de la rama, el título o el cuerpo del PR, con cualquiera de estos dos formatos:

Formato Dónde Ejemplo
fxc-<taskId> Nombre de la rama (o título/cuerpo) feat/fxc-cm4k2x9ab0001-login-github
[fxc:<taskId>] Título o cuerpo del PR Login con GitHub [fxc:cm4k2x9ab0001]

También reconoce el PR si la tarea ya lo tenía guardado (mismo prUrl) o si su rama coincide con la del PR (head.ref). Un PR puede citar varias tareas: se mueven todas.

Rama:    fix/fxc-cm4k2x9ab0001-carrito-vacio
Título:  Arregla el carrito vacío [fxc:cm4k2x9ab0001]
Cuerpo:  También cierra fxc-cm4k3abcd0002.

El id de una tarea lo ves en su URL, con fxc tasks list --json o con list_tasks por MCP.

Sin actividad

Una tarea en un estado con animación de progreso («Working») que no cambia en más de las horas configuradas deja de mostrar el barrido y enseña una etiqueta discreta: sin actividad · hace 3 días. Al pasar el ratón explica qué significa.

  • No cambia el estado: solo se ve distinto. Al tocar la tarea (cambiarla, terminarla) vuelve a la normalidad.
  • Se ajusta por proyecto en Ramas y PR → Horas para «sin actividad»; 0 lo apaga.
  • El API lo devuelve como stale: true en cada tarea, para que scripts y agentes lo usen.

La regla de oro: nunca dejes una tarea en Working si ya no la estás tocando. Termínala con fxc tasks finish o devuélvela a su estado anterior.

Desde un agente por MCP

Las mismas acciones existen como herramientas en el servidor MCP, local y remoto:

Herramienta Qué hace
finish_task taskId y branch?. Aplica el modo del proyecto: en una rama de trabajo, a revisión; en la principal, completada. En el MCP local, sin branch usa la rama de git actual
update_task Además de lo de siempre, branch, prUrl y prNumber (la cadena vacía los borra; el número sale de la URL)

Las tareas que devuelven las herramientas incluyen branch, prUrl, prState y stale.

Desde el API

# Terminar según el modo del proyecto
curl -X POST https://api.fxcode.dev/tasks/<id>/finish \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"branch":"feat/fxc-<id>-login"}'
# → la tarea, con "outcome": "review" | "completed" | "unchanged"

# Guardar rama y PR
curl -X PATCH https://api.fxcode.dev/tasks/<id> \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"branch":"feat/fxc-<id>-login","prUrl":"https://github.com/acme/tienda/pull/42"}'

Los ajustes del proyecto están en GET/PATCH /projects/<id>/branch-settings y el secreto en POST/DELETE /projects/<id>/branch-settings/webhook-secret, solo para el propietario o un administrador.