Buenas Prácticas de Integración con GitHub

Patrones probados para usar Claude Code de forma segura y eficaz en pull requests y pipelines de CI, desde la apertura manual de un PR hasta la ejecución de un bot de revisión totalmente automatizado.

Cómo Usar Esta Lista

• Trata las reglas "A" como valores predeterminados innegociables para cualquier integración de Claude Code y GitHub; trata los grupos posteriores como ajustes una vez que los conceptos básicos estén en su lugar.
• Aplica las reglas específicas de CI (C y D) solo una vez que hayas pasado de la sesión interactiva al uso en un trabajo automatizado de GitHub Actions.
• Revisa esta lista cada vez que agregues un nuevo flujo de trabajo que ejecute Claude Code, ya que los errores de secretos y el alcance de permisos son fáciles de repetir en diferentes archivos.
• Combina esto con Configuración de un Trabajo de GitHub Actions que Ejecuta Claude Code para la lista de verificación de compilación paso a paso.

A - Trabajar con la CLI de gh

• Autentica gh una vez por entorno y verifícala antes de confiar en ella. Ejecuta gh auth status después de gh auth login, y vuelve a verificarlo cada vez que los comandos de GitHub de una sesión fallen inesperadamente.
• Deja que Claude Code ejecute los mismos comandos gh y git que escribirías tú mismo. No hay una "función de GitHub de Claude Code" separada que aprender; comprender los comandos subyacentes gh pr create, gh pr view y gh pr comment facilita la verificación de lo que realmente hizo una sesión.
• Confirma la rama actual antes de confirmar o abrir un PR. Un rápido git status o git branch --show-current evita confirmar cambios en la rama incorrecta, especialmente después de extraer un PR para trabajo de seguimiento.
• Escribe los cuerpos de los PR con un Resumen y un Plan de Pruebas claros. Un cuerpo estructurado (como se muestra en el artículo de creación de PR de esta sección) es más fácil de hojear para un revisor humano que un párrafo no estructurado.

B - Apertura de PRs y Respuesta a Comentarios

• Referencia el problema que cierra un PR. Incluye Fixes #<número> o Refs #<número> en el cuerpo del PR para que GitHub vincule y cierre automáticamente el problema al fusionar.
• Obtén los comentarios de revisión a nivel de línea con gh api, no solo con gh pr view --comments. El punto final de la API devuelve el archivo y la línea a los que se refiere cada comentario, lo que la salida de vista de nivel superior no siempre muestra claramente.
• Vuelve a ejecutar las pruebas antes de enviar un commit de seguimiento, no solo después. Una corrección que satisface un comentario de revisión aún puede romper algo más; confirma que el conjunto de pruebas pasa antes de confirmar el seguimiento.
• Escribe mensajes de commit de seguimiento que describan lo que cambió, no solo "abordar comentarios". Un mensaje específico como "Validar los límites de la ventana de límite de tasa según el comentario de revisión" es mucho más útil al hojear el historial más adelante.
• Confirma que el push realmente se aplicó antes de solicitar otra revisión. Verifica gh pr view --json commits en lugar de asumir que un push tuvo éxito antes de volver a notificar a los revisores.

C - Ejecución de Claude Code sin Interfaz Gráfica (Headless)

• Prueba una invocación headless localmente antes de integrarla en CI. Ejecuta el mismo comando claude -p "..." desde una terminal primero para validar el prompt y el formato de salida antes de colocarlo en un flujo de trabajo de GitHub Actions.
• Configura los permisos y el acceso a las herramientas antes de que comience la ejecución, nunca a mitad de la ejecución. El modo headless no tiene a nadie presente para aprobar una llamada a herramienta de forma interactiva, por lo que una lista blanca no configurada hará que la ejecución falle o se detenga.
• Elige un formato de salida que coincida con el consumidor. Texto plano para un comentario de PR legible por humanos, JSON estructurado cuando un paso posterior de CI necesite analizar campos específicos programáticamente.
• Escribe prompts headless con suficiente contexto para evitar ambigüedades. No hay preguntas de seguimiento disponibles a mitad de la ejecución, por lo que el prompt debe contener las restricciones y el contexto que una persona normalmente proporcionaría de forma interactiva.

D - Seguridad del Trabajo de CI

• Almacena la clave API de Anthropic como un secreto de GitHub Actions, nunca como una variable de flujo de trabajo simple. Cualquier cosa que no se almacene en secretos del repositorio u organización es visible en los registros y para cualquiera con acceso de lectura al archivo de flujo de trabajo.
• Escala explícitamente el bloque permissions del flujo de trabajo. Otorga solo lo que el trabajo necesita: típicamente contents: read y pull-requests: write para un trabajo de revisión, en lugar de depender de permisos de token predeterminados más amplios.
• Usa pull_request, no pull_request_target, a menos que lo necesites específicamente y comprendas la compensación. pull_request_target puede exponer secretos del repositorio al código de un PR bifurcado si no se maneja con cuidado.
• Establece un tiempo de espera para cualquier trabajo que ejecute Claude Code sin interfaz gráfica. Una configuración de timeout-minutes a nivel de trabajo evita que una invocación colgada ocupe minutos del runner indefinidamente.

E - Mantener Útil la Revisión Automatizada

• Da prioridades explícitas al trabajo de revisión en lugar de un prompt genérico de "revisar este PR". Nombrar señales específicas: pruebas faltantes, deriva de estilo, patrones de defectos comunes, produce hallazgos más precisos y accionables que una instrucción genérica.
• Instruye a la revisión para que permanezca en silencio en diffs limpios. Sin esa instrucción explícita, una revisión automatizada tiende a encontrar algo que decir en cada PR, lo que entrena a los revisores para ignorar sus comentarios.
• Trata los hallazgos de la revisión automatizada como una señal, no como una puerta de entrada. La revisión automatizada se ejecuta junto con los revisores humanos y las reglas de protección de ramas existentes; no reemplaza a ninguno de forma predeterminada.
• Revisa la guía de revisión cuando consistentemente falle en detectar o marque en exceso algo. La guía del prompt no es fija; si una categoría de problema sigue pasando desapercibida (o se marca en exceso), eso es una señal para refinar el prompt, no una limitación permanente.
• Vuelve a activar la revisión en cada push a un PR, no solo en su apertura inicial. Incluye synchronize en los tipos de eventos pull_request del flujo de trabajo para que los commits posteriores también se revisen, no solo el estado inicial del PR.

Preguntas Frecuentes

Relacionados

• Cómo Claude Code Encaja en tu Flujo de Trabajo de GitHub Pull Request - la imagen general en la que se enmarcan estas prácticas.
• Configuración de un Trabajo de GitHub Actions que Ejecuta Claude Code - la lista de verificación de compilación paso a paso que estas prácticas fortalecen.
• Ejecución de Claude Code como un Bot de Revisión de Código Automatizado en CI - un flujo de trabajo completo que implementa las prácticas enfocadas en CI aquí.
• Cómo Claude Code Decide Qué Marcar en una Revisión Automatizada - el razonamiento detrás de las prácticas de guía de revisión en el grupo E.

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.