GitHub CLI — Gestión de Issues y Labels

gh es la herramienta oficial de GitHub para gestionar issues, PRs, labels y más desde la terminal. Permite trabajar con GitHub sin salir del editor, ideal para flujos ágiles y automatización.

Instalación

Windows

winget install --id GitHub.cli

Una vez instalado, cerrar y reabrir PowerShell para que el PATH se refresque.

Linux / macOS

# macOS
brew install gh

# Linux (Debian/Ubuntu)
sudo apt install gh

Autenticación

gh auth login

Elegir las siguientes opciones:

GitHub.com
HTTPS
Login with a web browser — se abre el navegador para autorizar

Verificar que funciona:

gh auth status

Comandos esenciales

Issues

# Listar issues abiertos
gh issue list --repo ikcdv23/Syncro

# Filtrar por label
gh issue list --repo ikcdv23/Syncro --label "area:core"

# Ver un issue concreto
gh issue view 99 --repo ikcdv23/Syncro

# Crear un issue con labels
gh issue create --repo ikcdv23/Syncro \
  --title "Título del issue" \
  --body "Descripción detallada" \
  --label "area:core,priority:high,status:todo"

# Cerrar un issue
gh issue close 99 --repo ikcdv23/Syncro

# Reabrir un issue
gh issue reopen 99 --repo ikcdv23/Syncro

# Asignar issue a un usuario
gh issue edit 99 --add-assignee "ikcdv23"

Labels

# Listar todas las labels
gh label list --repo ikcdv23/Syncro

# Crear una label nueva
gh label create area:core --repo ikcdv23/Syncro \
  --color "0E8A16" \
  --description "Núcleo de gestión: Kanban, backlog, boards, labels"

# Editar una label existente
gh label edit area:core --repo ikcdv23/Syncro --color "FF0000"

# Borrar una label
gh label delete sprint:0 --repo ikcdv23/Syncro --yes

# Clonar labels de un repo a otro
gh label clone ikcdv23/repo-origen --repo ikcdv23/repo-destino

PRs

# Crear un PR desde la rama actual
gh pr create --base dev --title "Título del PR" --body "Descripción"

# Crear PR y asignar reviewers
gh pr create --base dev --title "Título" --body "Descripción" --reviewer "ikcdv23"

# Listar PRs abiertos
gh pr list

# Ver checks de CI de un PR
gh pr checks

# Mergear un PR
gh pr merge --squash

Labels del proyecto Syncro

Transición: de sprints a temas

El proyecto migró de un modelo basado en sprints cerrados (S0-S4) a un modelo de temas abiertos. Esto requirió actualizar las labels de GitHub.

Labels eliminadas (sprints obsoletos)

Label	Motivo
`sprint:0`	Modelo antiguo de sprints
`sprint:1`	Modelo antiguo de sprints
`sprint:2`	Modelo antiguo de sprints
`sprint:3`	Modelo antiguo de sprints

Labels nuevas (temas del backlog)

Label	Color	Descripción
`area:core`	`#0E8A16`	Núcleo de gestión: Kanban, backlog, boards, labels
`area:collaboration`	`#1D76DB`	Chat en tiempo real y notificaciones
`area:team`	`#5319E7`	Roles, invitaciones, perfiles
`area:planning`	`#FBCA04`	Calendario, reportes, estadísticas
`area:tech`	`#BFDADC`	CI/CD, tests, seguridad, deuda técnica
`area:ux`	`#D93F0B`	Onboarding, accesibilidad, i18n, dark mode
`focus:current`	`#B60205`	Tareas del foco trimestral activo

Labels que se mantienen

Categoría	Labels
Área técnica	`area:backend`, `area:frontend`, `area:fullstack`, `area:docs`, `area:infra`
Prioridad	`priority:high`, `priority:medium`, `priority:low`
Estado	`status:todo`, `status:in-progress`, `status:review`, `status:done`

Resumen visual de labels

Al combinar área técnica + tema + prioridad + estado, un issue queda perfectamente clasificado:

Ejemplo: area:core  area:fullstack  priority:high  status:todo  focus:current

Esto permite filtrar issues por cualquier dimensión desde la UI de GitHub o con gh issue list --label "...".

Issues de la Fase 1 — Cimientos + Boards

Los siguientes issues se crearon como parte del arranque de la Fase 1 del roadmap.

#	Issue	Labels	Rama sugerida
#99	T-01: Boards — CRUD completo (listar, renombrar, eliminar)	`area:core` `priority:high` `focus:current`	`feat/boards-crud`
#98	T-02: Configurar GitHub Issues (templates + milestones)	`area:tech` `priority:high`	`feat/github-issues-setup`
#102	T-03: Unit tests para capa service	`area:tech` `priority:high`	`feat/unit-tests`
#100	T-04: CI — Workflow de lint + typecheck bloqueante	`area:tech` `priority:high`	`feat/ci-workflow`
#101	Limpiar ramas muertas y docs desactualizadas	`area:tech` `priority:medium`	`chore/cleanup-branches`

Flujo de trabajo con `gh`

Ciclo completo de un issue

# 1. Crear rama desde dev
git checkout dev
git pull origin dev
git checkout -b feat/mi-feature

# 2. Trabajar en el código...

# 3. Commit y push
git add .
git commit -m "feat: descripción del cambio"
git push origin feat/mi-feature

# 4. Crear PR vinculado al issue
gh pr create --base dev --title "T-01: Descripción" --body "Closes #99"

# 5. Cuando el PR se mergea, el issue se cierra automáticamente

Ver el estado del proyecto

# Issues del foco actual
gh issue list --repo ikcdv23/Syncro --label "focus:current"

# Issues listos para empezar
gh issue list --repo ikcdv23/Syncro --label "status:todo"

# Issues en progreso
gh issue list --repo ikcdv23/Syncro --label "status:in-progress"

Solución de problemas

`gh: command not found`

Cerrar y reabrir la terminal. Si sigue sin funcionar, usar la ruta completa:

& "C:\Program Files\GitHub CLI\gh.exe" auth status

`You are not logged into any GitHub hosts`

gh auth login

`--confirm has been deprecated`

Usar --yes en lugar de --confirm (versiones recientes de gh).