Review

Este componente, llamado Review, actúa como un enlace directo entre tu sistema de automatización Nappai y tu repositorio en GitHub. Su propósito principal es permitirte gestionar interacciones con el código, específicamente en los Pull Requests (PRs).

Puedes usar este componente para automatizar flujos de trabajo de revisión de código: desde obtener información sobre un PR específico hasta solicitar revisiones a tu equipo o agregar comentarios automáticamente. Piensa en él como un asistente virtual que se encarga de gestionar la conversación y el estado de aprobación de tu código sin que tengas que entrar manualmente a GitHub.

¿Cómo funciona?

Internamente, este componente se conecta a la API de GitHub utilizando credenciales seguras (Tokens de Acceso Personal) que tú configuras previamente. Al ejecutar una operación, el componente traduce tu acción (como “aprobar” o “comentar”) en una solicitud técnica a GitHub.

El componente opera de forma flexible: puedes seleccionarlo para realizar una sola acción específica en un Pull Request (como obtener sus detalles) o para listar varios PRs según ciertos filtros (como su estado). Además, cuenta con un modo avanzado que te permite conectar sus entradas con datos provenientes de otros componentes en tu flujo de trabajo, haciéndolo ideal para automatizaciones complejas que procesen múltiples repositorios o cambios de código.

Conexión y Credenciales

Este componente requiere que configures previamente una credencial en el panel de Nappai para poder interactuar con el servicio de GitHub.

1. Dirígete a la sección de Credenciales en tu panel de Nappai.
2. Crea una nueva credencial del tipo GitHub API.
3. Completa los campos requeridos (como el Token de Acceso Personal) con las claves correspondientes a tu cuenta de GitHub.
4. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Get PR: Recupera los detalles específicos de un Pull Request dado.
• List PRs: Obtiene una lista de Pull Requests, permitiendo filtrar por su estado (por ejemplo, solo los abiertos).
• Create PR Comment: Añade un comentario de texto simple a la conversación de un Pull Request.
• Get Review: Recupera los detalles de una revisión formal específica realizada en un PR.
• List Reviews: Obtiene una lista de revisiones realizadas en un Pull Request.
• Create Review: Crea una revisión formal (puede ser una aprobación, solicitud de cambios o un comentario formal) en un PR.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Operation: Selecciona la operación del pull request a realizar.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• Comment Body: The text content for the PR comment. Use this for simple comments without review status.

  • Visible en: Create PR Comment

• Limit: Maximum number of items to return (max 1000).

  • Visible en: List PRs, List Reviews

• Mapping Mode: Enable mapping mode to process multiple data records in batch

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• PR State: Filter pull requests by their state.

  • Visible en: List PRs

• Pull Request Number: The number of the pull request to interact with.

  • Visible en: Get PR, Create PR Comment, Get Review, List Reviews, Create Review

• Repository: Select a repository. The list populates after selecting a credential.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• Repository Input Type: Select the input type for the repository.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• Repository ID: Pass the repository name in format ‘owner/repo’ (e.g., ‘octocat/Hello-World’). Overrides the dropdown selection.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• Review Body: The text content for the formal review. Required for COMMENT and REQUEST_CHANGES events.

  • Visible en: Create Review

• Review Event: Review action: COMMENT (with body), APPROVE (body optional), REQUEST_CHANGES (body required). Note: Cannot APPROVE or REQUEST_CHANGES on your own PR.

  • Visible en: Create Review

• Review ID: The ID of the specific review to retrieve.

  • Visible en: Get Review

• Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

• Tools arguments metadata: Defines the arguments metadata for the tools.

  • Visible en: Get PR, List PRs, Create PR Comment, Get Review, List Reviews, Create Review

Salidas

El componente devuelve información sobre el estado de la operación y datos relacionados con GitHub para que puedas usarlos en pasos siguientes de tu automatización.

• Data: Información principal resultante de la operación (método: perform_operation).
• Tool: Representación de la herramienta para el agente (método: to_toolkit).

Ejemplo de Respuesta JSON

json { “operation”: “Get PR”, “status”: “SUCCESS”, “repository”: “owner/repo-name”, “pull_request_number”: 42, “pr_state”: “open”, “pr_title”: “Add new feature”, “review_status”: “SUCCESS”, “message”: “Pull request details retrieved successfully”, “errors”: [] }

Conectividad

Este componente suele conectarse en flujos de integración continua (CI/CD) o automatización de revisiones de código.

• Conexión Entrante: Generalmente recibe el número de PR o el nombre del repositorio desde un disparador de eventos de GitHub (cuando se crea un nuevo PR) o desde un componente de lógica condicional que decide qué repositorios revisar.
• Conexión Saliente: Las salidas como Data se suelen conectar a:
  • Componentes de Notificación: Para enviar un email o mensaje de Slack a los revisores cuando un PR está listo.
  • Componentes de Lógica: Para tomar decisiones basadas en el estado del PR (por ejemplo, si el estado es “open”, proceder a solicitar revisiones).
  • Componentes de Base de Datos: Para guardar un registro de las revisiones realizadas.

Ejemplo de Uso

Escenario: Automatización de Comentario en PRs Recién Creados

Imagina que quieres notificar automáticamente a tu equipo cuando se crea un nuevo PR en el repositorio mi-proyecto/web.

1. Configura el Componente: Selecciona la operación Create PR Comment.
2. Completa los Campos:
   • En Repository, selecciona mi-proyecto/web.
   • En Pull Request Number, mapea el número del PR recibido desde el disparador de eventos.
   • En Comment Body, escribe: “Este PR está listo para revisión por favor revisad los cambios.”
3. Ejecuta: Al ejecutarse, el componente se conectará a GitHub y dejará el comentario automáticamente en el PR correspondiente.

Notas Importantes

🔒 Handle Tokens Securely 🟡 Keep your GitHub token confidential. Avoid hard‑coding it in public repositories or exposing it in logs. Use secure credential storage whenever possible.

⚠️ Component is in Development 🟢 GitHubReview is flagged as a development component, meaning its features and stability may change. Users may encounter unexpected behavior or missing functionalities.

📋 GitHub Authentication Needed 🔴 To use this component, you must provide a valid GitHub access token with appropriate permissions for pull request operations.

💡 Test in a Safe Environment First 🟢 Because the component is still in development, try it in a non‑production or sandbox setup to confirm expected behavior before deploying to live projects.

ℹ️ Inherits Base Inputs/Outputs 🟢 GitHubReview uses the same inputs and outputs as its base class, so the available actions and data fields are defined there. Check the base documentation for exact details.

⚙️ Component Flag Indicates Unstable State 🟢 The is_development = True flag signals that the component may not be fully stable. Avoid relying on it for critical production workflows until a stable release is available.

Consejos y Mejores Prácticas

• Verifica Permisos: Asegúrate de que tu Token de Acceso Personal tenga los permisos adecuados (scope repo) para interactuar con los repositorios privados o públicos.
• Usa el Modo Mapeo: Si necesitas aplicar la misma operación a múltiples PRs, activa el “Mapping Mode” para conectar la entrada de datos masivos.
• Revisa las Operaciones: Ten cuidado de seleccionar la operación correcta. “Create Review” es distinto de “Create PR Comment”; el primero es una aprobación formal que afecta al estado del PR, mientras que el segundo es solo un texto en la conversación.
• Formato del Repositorio: Si usas “Repository ID” manualmente, asegúrate de usar el formato usuario/repo (ej: facebook/react).

Consideraciones de Seguridad

• Tokens Privados: Nunca compartas tu Token de Acceso Personal. Guárdalo siempre en las credenciales seguras de Nappai.
• Entorno de Desarrollo: Dado que el componente está en fase de desarrollo (is_development = True), se recomienda probarlo en un entorno de pruebas antes de usarlo en flujos críticos de producción.
• Validación de Entradas: El componente valida que el formato del repositorio y el número de PR sean correctos, lo que ayuda a prevenir errores de conexión con la API.