---
name: github-cli
description: >
Integración de la CLI de GitHub (gh) para gestionar incidencias, pull requests, ramas,
commits y revisiones de código directamente desde la terminal. Úsalo cuando Claude necesite
crear, listar, ver o actualizar incidencias de GitHub; crear ramas y pull requests
en borrador; hacer commits y enviar cambios; revisar diffs y cambios de pull requests;
aprobar o fusionar PRs; gestionar flujos de trabajo de GitHub Actions; o trabajar con
repositorios de GitHub sin cambiar al navegador. Requiere la CLI gh instalada
y autenticada.
---
Habilidad de la CLI de GitHub (gh)
Usa la CLI gh para interactuar con repositorios de GitHub, incidencias, pull requests y flujos de trabajo de GitHub Actions desde la terminal.
Prerrequisitos
Verifica que gh esté instalado y autenticado:
gh --version
gh auth status
Si no está autenticado, ejecuta gh auth login y sigue las instrucciones.
Flujos de Trabajo Principales
Gestión de Incidencias
# Listar incidencias
gh issue list # Incidencias abiertas en el repo actual
gh issue list --state all # Todas las incidencias, incluidas cerradas
gh issue list --assignee @me # Incidencias asignadas a ti
gh issue list --label "bug" # Filtrar por etiqueta
# Crear incidencia
gh issue create -t "Título" -b "Descripción"
gh issue create -t "Título" --label "bug,priority:high" --milestone "hito-1"
gh issue create # Modo interactivo
# Ver/actualizar incidencia
gh issue view 123 # Ver detalles de la incidencia
gh issue view 123 --web # Abrir en el navegador
gh issue edit 123 --add-label "en-progreso"
gh issue close 123
gh issue reopen 123
# Añadir comentarios
gh issue comment 123 -b "Estoy trabajando en esto ahora"
Flujo de Trabajo de Ramas y Commits
# Crear rama de funcionalidad/corrección
git checkout -b feature/mi-funcionalidad
git checkout -b fix/issue-123
git checkout -b draft/wip-experimento
# Preparar y hacer commit de cambios
git add .
git commit -m "feat: añadir nueva funcionalidad"
git commit -m "fix: resolver incidencia #123"
# Enviar rama al remoto
git push -u origin feature/mi-funcionalidad
Gestión de Pull Requests
# Crear PR (varios métodos)
gh pr create # Modo interactivo
gh pr create --fill # Auto-rellenar desde commits
gh pr create --draft # Crear como borrador
gh pr create --draft --fill # Borrador con auto-rellenado
gh pr create -t "Título" -b "Descripción" -B main
gh pr create --label "revisión-necesaria" --assignee @me
# Listar PRs
gh pr list # PRs abiertos
gh pr list --assignee @me # Tus PRs
gh pr list --search "review-requested:@me" # PRs que solicitan tu revisión
gh pr list --draft # Solo PRs en borrador
# Ver detalles del PR
gh pr view 45 # Ver PR en terminal
gh pr view 45 --web # Abrir en el navegador
Flujo de Trabajo de Revisión de Código
# Obtener el PR localmente para pruebas
gh pr checkout 45 # Obtener rama del PR localmente
# Revisar cambios
gh pr diff 45 # Ver diff del PR
gh pr diff # Diff del PR de la rama actual
# Añadir comentarios de revisión
gh pr comment 45 -b "LGTM, sugerencia menor en la línea 42"
gh pr comment -b "Por favor añade pruebas" # Comentar en el PR de la rama actual
# Enviar una revisión formal
gh pr review 45 --approve
gh pr review 45 --request-changes -b "Por favor corrige el manejo de errores"
gh pr review 45 --comment -b "Se ve bien en general, algunas sugerencias"
# Fusionar
gh pr merge 45 # Fusión interactiva
gh pr merge 45 --squash # Fusión squash
gh pr merge 45 --rebase # Fusión rebase
gh pr merge 45 --merge # Fusión estándar con commit
gh pr merge 45 --auto # Fusión automática cuando pasen las comprobaciones
Actualizar un PR Existente
gh pr edit 45 --title "Nuevo título"
gh pr edit 45 --body "Descripción actualizada"
gh pr edit 45 --base develop
gh pr edit 45 --add-label "listo-para-revisar"
gh pr ready 45 # Marcar como listo (quitar borrador)
Gestión de Flujos de Trabajo de GitHub Actions
# Listar ejecuciones de flujo de trabajo
gh run list # Ejecuciones recientes
gh run list --workflow=ci.yml # Flujo de trabajo específico
gh run list --status=failure # Solo ejecuciones fallidas
# Ver detalles de una ejecución
gh run view # Selector interactivo de ejecución
gh run view 12345 # Ejecución específica
gh run view 12345 --web # Abrir en el navegador
# Desencadenar flujo de trabajo
gh workflow run ci.yml # Ejecutar en la rama por defecto
gh workflow run ci.yml --ref feature/x # Ejecutar en una rama específica
gh workflow run ci.yml -f clave=valor # Con parámetros de entrada
# Re-ejecutar trabajos fallidos
gh run rerun 12345 # Re-ejecutar todos los trabajos
gh run rerun 12345 --failed # Re-ejecutar solo los trabajos fallidos
# Ver registros de trabajos
gh run view 12345 --log # Salida de registro completa
gh run view 12345 --log-failed # Solo registros de trabajos fallidos
# Ver una ejecución en progreso
gh run watch # Ver ejecución actual
gh run watch 12345 # Ver ejecución específica
Referencia de Banderas Comunes
| Banderas | Descripción |
|---|---|
-R, --repo OWNER/REPO | Apuntar a un repositorio diferente |
-B, --base | Rama base para el PR |
-H, --head | Rama head para el PR |
-t, --title | Título para incidencia/PR |
-b, --body | Cuerpo/descripción para incidencia/PR |
-l, --label | Etiquetas (separadas por comas) |
-a, --assignee | Nombre de usuario asignado |
-m, --milestone | Nombre del hito |
--draft | Crear como PR en borrador |
--fill | Auto-rellenar desde mensajes de commit |
--web | Abrir en el navegador |
-y, --yes | Saltar confirmaciones |
Variables de Entorno
export GH_TOKEN="ghp_xxxx" # Token de acceso personal
export GH_HOST="github.example.com" # Instancia de GitHub Enterprise
export GH_REPO="owner/repo" # Repositorio predeterminado
Consejos y Puntos Clave
Descripciones Multilínea con Markdown
Al crear incidencias o PRs con descripciones largas que contengan markdown (bloques de código, acentos graves), evita los heredocs ya que pueden fallar debido a la interpretación del shell. En su lugar:
# Paso 1: Escribir la descripción en un archivo temporal (fuera de bash)
# Paso 2: Crear desde el archivo temporal
gh issue create -t "Título" -b "$(cat temp_description.txt)"
# Paso 3: Limpiar
rm temp_description.txt
Esto evita problemas con:
- Acentos graves en bloques de código que entran en conflicto con la sustitución de comandos
- Caracteres especiales interpretados por el shell
- Conflictos con delimitadores de heredoc
Obtener Descripciones de Archivos Existentes
Para crear una incidencia o PR desde un archivo de plan markdown:
# Usar la bandera body-file para descripciones limpias basadas en archivos
gh issue create -t "Título" --body-file docs/plans/mi-plan.md
gh pr create -t "Título" --body-file docs/plans/mi-plan.md
Referencia Detallada
Para opciones de comandos completas y ejemplos, consulta references/commands.md.