Cap 6: Integración con GitHub

Orca y GitHub

Orca se integra con GitHub para que el flujo de trabajo multi-agente se conecte directamente con PRs, Issues y CI/CD. No necesitas salir de Orca para gestionar tu workflow en GitHub.

Autenticación

Orca usa la autenticación de GitHub CLI (gh). Si ya tienes gh configurado, Orca lo detecta automáticamente:

# Verificar que gh está autenticado
gh auth status

Si no tienes gh instalado, Orca te guía en la configuración desde Settings > GitHub.

Pull Requests

Crear PR desde un worktree

Cuando un agente termina su trabajo en un worktree, puedes crear un PR directamente:

# Desde Orca CLI
orca pr create --worktree feat-auth

# Orca hace push del branch y crea el PR
# Título y descripción se generan automáticamente basándose en los commits

Desde la UI, click derecho en el worktree > Create Pull Request. Orca pre-llena:

• Título: basado en el nombre del branch
• Descripción: resumen de los commits del agente
• Labels: detectados por el tipo de cambio (feat, fix, refactor)
• Reviewers: configurables por defecto en Settings

Flujo completo

sequenceDiagram
    participant A as Agente
    participant O as Orca
    participant GH as GitHub

    A->>O: Tarea completada
    O->>O: Revisar diffs
    O->>GH: git push origin feat/auth
    O->>GH: gh pr create
    GH-->>O: PR #42 creada
    GH->>GH: CI/CD ejecuta checks
    GH-->>O: Checks passed
    O->>GH: gh pr merge

Revisar PRs existentes

Orca permite revisar PRs de otros colaboradores directamente en la UI:

# Abrir PR en Orca para revisión
orca pr checkout 42

Esto crea un worktree temporal con el branch del PR, donde puedes revisar, ejecutar tests y dejar comentarios.

Issues

Crear tareas desde Issues

Orca puede tomar un Issue de GitHub y convertirlo en una tarea para un agente:

# Asignar un Issue a un agente
orca issue assign 15 --agent claude --branch fix/issue-15

Orca:

1. Lee el Issue #15 de GitHub
2. Crea un worktree con el branch fix/issue-15
3. Lanza Claude Code con el contexto del Issue como prompt
4. El agente trabaja en resolverlo

Desde la UI

El panel de Issues (Ctrl/Cmd + I) muestra los Issues abiertos del repositorio. Arrastra un Issue al panel de agentes para asignarlo.

Cerrar Issues automáticamente

Si el commit del agente incluye fixes #15 o closes #15, GitHub cierra el Issue automáticamente al hacer merge del PR.

# Orca puede agregar la referencia automáticamente
orca commit --worktree fix-issue-15 -m "fix: resolve timeout en API (closes #15)"

GitHub Actions

Monitorear CI/CD

Orca muestra el estado de GitHub Actions en tiempo real. Cuando un agente hace push y se dispara un workflow:

• El panel de estado muestra el progreso del CI
• Notificaciones si el CI falla
• Click en el workflow para ver los logs

# Ver estado del CI desde CLI
orca ci status feat-auth

Salida:

PR #42 (feat/auth)
  ✓ lint          (12s)
  ✓ test:unit     (45s)
  ✗ test:e2e      (2m 10s) — FAILED
  ○ deploy        (skipped)

Corregir fallos de CI

Si el CI falla, puedes pedirle al agente que corrija:

# Re-lanzar agente en el mismo worktree con contexto del error
orca run --agent claude --worktree feat-auth \
  "El CI falló en test:e2e. Log del error: $(orca ci logs feat-auth test:e2e)"

El agente recibe el log del CI como contexto y trabaja en corregirlo.

GitHub Discussions y Notifications

Orca integra también:

• Notifications: badge en la barra de estado con el conteo de notificaciones
• Discussions: lectura de discussions del repo desde el panel de Issues

Configuración de GitHub

En Settings > GitHub puedes configurar:

{
  "github": {
    "defaultReviewers": ["@team/frontend"],
    "defaultLabels": ["ai-generated"],
    "autoCreatePR": false,
    "prTemplate": ".github/pull_request_template.md",
    "ciWatchEnabled": true
  }
}

Opción	Descripción
defaultReviewers	Reviewers asignados automáticamente a PRs
defaultLabels	Labels aplicados a PRs creados desde Orca
autoCreatePR	Crear PR automáticamente al terminar una tarea
prTemplate	Template para la descripción del PR
ciWatchEnabled	Monitorear CI/CD en tiempo real

Buenas prácticas

1. Label ai-generated: marca los PRs generados por agentes para que el equipo sepa revisarlos con más cuidado
2. Template de PR: incluye una sección “Generado por IA” con el agente usado y el prompt original
3. CI obligatorio: configura branch protection para que todos los PRs pasen CI antes de merge
4. Issues como fuente de verdad: usa Issues para definir tareas y asignarlas a agentes