GitHub CLI
La CLI gh administra pull requests, issues, ejecuciones de Actions y releases desde la terminal, de forma similar a como los equipos de Python ya automatizan uv y pytest en CI.
Receta
gh auth login
gh pr create --fill --base main
gh pr checks --watch
gh pr merge --squash --delete-branchCuándo usar esto:
- Abrir PRs sin salir de la terminal
- Observar el flujo de trabajo de
ruff/pytesttras un push - Etiquetado masivo de issues o carga de assets de release
- Automatizar la higiene del repositorio en runbooks del equipo de plataforma
Ejemplo de Trabajo
# Después del trabajo de una característica
git push -u origin feat/bill-42-tax
gh pr create \
--title "feat(billing): add tax line item [BILL-42]" \
--body "Adds VAT calculation; updates uv.lock for pydantic bump." \
--reviewer @acme/billing-team
# Observar CI (mismos pasos que en .github/workflows/pr.yml)
gh pr checks 42 --watch
# Cambios solicitados abordados - fusionar cuando esté en verde
gh pr merge 42 --squash --delete-branchLo que esto demuestra:
--fillusa mensajes de commit para el cuerpo del borrador cuando es apropiado--watchse bloquea hasta que las comprobaciones requeridas se completan- Política de fusión squash alineada con la documentación de branching
- La eliminación automática de ramas mantiene el repositorio remoto ordenado
Análisis Profundo
Cómo Funciona
gh auth- Almacena el token o usa SSH para operaciones git.gh pr- Envuelve las Pull Requests de GitHub REST/GraphQL.gh run- Lista y visualiza las ejecuciones de flujos de trabajo de Actions.gh api- API sin procesar autenticada para scripts personalizados.
Comandos de Alto Valor
| Tarea | Comando |
|---|---|
| Extraer PR localmente | gh pr checkout 42 |
| Ver diff de PR | gh pr diff 42 |
| Volver a ejecutar trabajo fallido | gh run rerun <run-id> --failed |
| Crear release | gh release create v1.2.0 dist/* |
| Listar issues | gh issue list --label bug |
Notas de Python
# Comentar fragmento de fallo de pytest en PR
gh pr comment 42 --body "$(uv run pytest -q 2>&1 | tail -20)"Errores Comunes
- Alcance del token de autenticación - Se necesitan
repoyworkflowpara Actions privadas. Solución:gh auth refresh -s repo,workflow. - Repositorio predeterminado incorrecto -
ghapunta al remoto del directorio actual. Solución:gh repo set-default acme/billing-api. - Fusionar antes de que CI esté en verde - Ignora la política si es administrador. Solución: esperar a
gh pr checks. - Plantilla de PR omitida - Cuerpos vacíos ralentizan la revisión. Solución:
.github/pull_request_template.md+gh pr create --template. - Fuga de secretos en comentarios - Los logs pegados pueden incluir tokens. Solución: redactar antes de
gh pr comment. - Discrepancia entre squash y merge - La política de la organización puede prohibir squash. Solución:
gh pr merge --mergesegún ADR.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Interfaz web de GitHub | Revisión visual de imágenes/UI | Creación repetitiva de PRs |
hub (legado) | Scripts antiguos | Nueva automatización - usar gh |
GitLab glab | Alojamiento en GitLab | Organización de GitHub |
| API + curl | Endpoints exóticos | gh api ya envuelve la autenticación |
Preguntas Frecuentes
¿SSH o HTTPS para gh auth?
SSH si git ya usa claves SSH; HTTPS con token para control de PAT granular.
¿gh en CI?
Usar el secreto GH_TOKEN con el mínimo alcance, no un PAT personal en runners compartidos.
¿Draft PR desde la CLI?
gh pr create --draft para feedback temprano antes de la cola de revisión.
¿Aprobar PR como revisor?
gh pr review 42 --approve cuando la política permita revisiones desde la CLI.
¿Desencadenar workflow_dispatch?
gh workflow run pr.yml --ref feat/branch
¿Descargar artefactos de Actions?
gh run download <run-id> -n coverage-report
¿Múltiples remotos?
gh pr create --repo acme/other-service apunta a un repositorio explícito.
¿Crear issue desde CI fallida?
gh issue create --title "CI flaky test_tax" --body "run id ..."
¿Alias para flujos comunes?
gh alias set prc 'pr create --fill --web' - el equipo comparte la documentación de alias.
¿Enterprise Server?
gh auth login --hostname github.acme.com para GHES.
Relacionado
- Comandos Esenciales de Git -
git pushantes de PR - Pipelines de CI/CD - paridad de flujos de trabajo
- Branching y Merging - políticas de fusión
- Mejores Prácticas de Git - normas de git del equipo
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.