gh

gh CLI — Flujos Autenticados con GitHub

Guía de buenas prácticas para CULTIVA IA: reemplaza curl sin autenticar por comandos gh en todos los flujos de repositorios privados, PRs, issues y la API REST de GitHub.

Web · Desarrollo · CLI · GitHub

Regla de oro

⚡

Nunca uses curl, wget ni peticiones HTTP directas a raw.githubusercontent.com o a la API de GitHub cuando hay un comando gh equivalente. El CLI gestiona la autenticación automáticamente, evita los límites de rate de la API pública (60 req/h) y funciona con repos privados de cultivaia/* sin configuración extra.

❌  Antes — curl sin autenticar
✅  Ahora — gh autenticado
EVITAR · Listar Pull Requests
curl -s https://api.github.com/repos/cultivaia/plataforma-agencia/pulls
# ⚠ 60 req/h · falla en repos privados · sin formato
USAR · Listar Pull Requests
gh pr list --repo cultivaia/plataforma-agencia
# ✓ autenticado · 5000 req/h · repos privados OK
EVITAR · Ver detalle de PR
curl -s https://api.github.com/repos/cultivaia/plataforma-agencia/pulls/42
# Devuelve JSON crudo, sin diff ni comentarios
USAR · Ver detalle de PR
gh pr view 42 --repo cultivaia/plataforma-agencia
# Título, body, reviewers, checks — formateado
EVITAR · Leer archivo de repo privado
curl -s https://raw.githubusercontent.com/cultivaia/skills-arsenal/main/README.md
# 404 en repos privados sin token en header
USAR · Leer archivo de repo privado
gh api repos/cultivaia/skills-arsenal/contents/README.md --jq '.content' | base64 -d
# O clona y lee local: gh repo clone cultivaia/skills-arsenal
EVITAR · Crear issue desde terminal
curl -X POST -H "Authorization: token $TOKEN" \
  https://api.github.com/repos/cultivaia/plataforma-agencia/issues \
  -d '{"title":"Bug login"}'
# Token expuesto, gestión manual de credencial
USAR · Crear issue desde terminal
gh issue create --repo cultivaia/plataforma-agencia \
  --title "Bug login" --body "Falla con SSO" --label "bug"
# Sin tokens en shell history · seguro
EVITAR · Llamada genérica a la API
curl -H "Authorization: Bearer $GH_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/cultivaia/plataforma-agencia/releases
# Headers manuales, sin paginación automática
USAR · Llamada genérica a la API
gh api repos/cultivaia/plataforma-agencia/releases --paginate
# Headers automáticos · paginación integrada

Flujos reales — CULTIVA IA

Daily dev check plataforma-agencia

Revisar el estado del repo y los PRs abiertos cada mañana antes de ponerse a trabajar.

gh repo view cultivaia/plataforma-agencia
# Info general: descripción, topics, star, forks

gh pr list --repo cultivaia/plataforma-agencia \
  --state open --assignee @me
# PRs asignados a ti, abiertos

gh pr checks --repo cultivaia/plataforma-agencia

Sync de skills skills-arsenal

Descargar la última versión del arsenal de skills desde el repo privado, sin exponer credenciales.

# Clonar / actualizar arsenal local
gh repo clone cultivaia/skills-arsenal \
  ~/projects/skills-arsenal

# O si ya existe, pull via gh
gh api repos/cultivaia/skills-arsenal/git/refs/heads/main \
  --jq '.object.sha'
# Muestra el SHA del último commit en main

Releases automatizaciones automatizaciones-n8n

Publicar una nueva versión de un workflow n8n desde CI/CD o desde terminal.

# Crear release con tag
gh release create v2.4.0 \
  --repo cultivaia/automatizaciones-n8n \
  --title "v2.4.0 - Flujo facturación" \
  --notes "Nuevo nodo Stripe + Lemon Squeezy" \
  ./workflows/facturacion-v2.json
# Sube el JSON como asset del release

Gestión de issues de clientes plataforma-agencia

Crear, asignar y cerrar issues de cliente sin salir del terminal ni abrir el navegador.

# Crear issue etiquetado
gh issue create \
  --repo cultivaia/plataforma-agencia \
  --title "[Cliente] Error en skill SEO audit" \
  --label "cliente,bug" --assignee alvarog

# Ver issues abiertos filtrados
gh issue list --label cliente --state open

Rate limits — Por qué importa

60
curl sin autenticar peticiones / hora por IP. Un script que lea 10 repos ya consume el 17%. En CI falla en segundos.
5.000
gh autenticado (OAuth App) peticiones / hora por token. 83× más capacidad. GitHub Apps llegan a 15.000/h instalación.

Cuándo aplicar esta skill

✅ Usar gh CLI

  • Repositorios, PRs, issues, releases o la API de GitHub
  • Repos privados de cultivaia/*
  • Necesitas rate limits altos (CI/CD, scripts, agentes)
  • Estás a punto de escribir curl ... api.github.com
  • Quieres autenticarse sin exponer tokens en el historial del shell
  • Flujos de GitHub Actions que llaman a la API

— NO aplicar

  • El destino no es GitHub (GitLab, Bitbucket, etc.)
  • Operaciones git locales puras (git pull, git commit)
  • APIs de terceros no relacionadas con GitHub
  • Lectura de archivos ya clonados localmente

Setup en 30 segundos

1 — Instalar
brew install gh
# macOS (Homebrew)

winget install gh
# Windows
2 — Autenticar
gh auth login
# → GitHub.com
# → HTTPS
# → Authenticate with browser
3 — Verificar
gh auth status
# ✓ Logged in to github.com
# ✓ Token: ghp_***
# ✓ Token scopes: repo, ...