Saltearse al contenido
Nappai Documentation

GitHubIssue

Componente GitHubIssue en Nappai

Bienvenido al componente GitHubIssue de Nappai. Esta herramienta te permite interactuar de manera directa y automatizada con tu repositorio de GitHub, específicamente para gestionar Issues (incidencias, tareas o solicitudes).

Imagina que este componente es como un asistente personal que vive dentro de tu sistema Nappai y sabe cómo hablar con GitHub. A través de este componente, puedes crear nuevas tareas, buscar las que ya existen, responder comentarios, actualizar el estado de un problema o incluso eliminar entradas antiguas, todo desde tu dashboard gráfico.

¿Cómo funciona?

Internamente, este componente actúa como un puente seguro entre Nappai y la API de GitHub. Cuando configuras el componente, le estás dando las llaves (el “Token de Acceso Personal”) necesarias para que Nappai pueda entrar a tu repositorio y hacer los cambios que necesitas.

El proceso sigue estos pasos:

  1. Identificación: El componente sabe a qué repositorio pertenece la tarea (quién es el dueño y cómo se llama el proyecto).
  2. Acción: Tú le indicas qué quieres hacer (por ejemplo, “Crear un nuevo issue” o “Listar los issues abiertos”).
  3. Ejecución: El componente envía una solicitud segura a GitHub.
  4. Resultado: GitHub responde confirmando si la tarea se hizo correctamente, y el componente devuelve esa información para que puedas usarla en el siguiente paso de tu automatización.

Conexión y Credenciales

Para que este componente pueda “hablar” con GitHub, necesitas configurar una credencial de seguridad. Esto asegura que solo tú (o tu sistema autorizado) puedas realizar cambios en tus repositorios.

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo GitHub API.
  3. Guarda tu Personal Access Token en este campo. Nota: Debes generar este token en la configuración de desarrollador de GitHub y otorgarle permisos de lectura/escritura (repo).
  4. Una vez guardada la credencial, vuelve a tu flujo de trabajo y selecciona esa credencial en el campo Credential de este componente.

Operaciones

Este componente es muy versátil y ofrece varias acciones. Importante: Solo puedes elegir una operación a la vez para cada uso del componente.

Selecciona la acción que necesitas desde el menú desplegable:

  • Get: Recupera los detalles de una incidencia específica utilizando su número. Es útil cuando quieres verificar qué dice una tarea antes de responderla o modificarla.
  • List: Obtiene una lista de incidencias basadas en filtros (como estado “abierto” o etiquetas específicas). Ideal para ver un resumen de todas las tareas pendientes en tu repositorio.
  • Create: Crea una nueva incidencia desde cero. Usas este comando cuando necesitas reportar un error o proponer una nueva funcionalidad.
  • Edit: Modifica una incidencia que ya existe. Puedes cambiar su título, descripción, etiquetas o asignársela a otra persona.
  • Create Comment: Añade un comentario a una incidencia ya existente. Perfecto para responder a las dudas de un reportero o actualizar el estado del trabajo.
  • Lock: Bloquea una incidencia. Esto impide que más personas añadan comentarios, ideal cuando un problema ya ha sido resuelto o se considera spam.
  • Unlock: Permite nuevamente la interacción en una incidencia que estaba bloqueada.
  • Delete: Elimina una incidencia permanentemente del repositorio.

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. La visibilidad de cada campo depende de la operación que hayas seleccionado arriba:

  • Operation: Selecciona la tarea específica que deseas realizar (ej. Crear, Buscar, Editar).

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Credential: Aquí seleccionas la credencial de GitHub que configuraste previamente.

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Repository: Elige el repositorio de GitHub donde quieres trabajar.

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Repository Input Type: Define cómo vas a especificar el repositorio (por nombre directo o por ID).

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Repository ID: Si no usas el menú desplegable, puedes escribir el repositorio en formato ‘propietario/repositorio’ (ej. ‘miempresa/app-v2’).

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Issue Number: El número único de la incidencia que quieres manipular (ej. Issue #42).

    • Visible en: Get, Edit, Create Comment, Lock, Unlock, Delete

  • Issue Title: El título de la incidencia.

    • Visible en: Create, Edit

  • Issue Body: El contenido principal de la incidencia (la descripción completa).

    • Visible en: Create, Edit

  • State: Filtra las incidencias por su estado (abierto, cerrado, etc.).

    • Visible en: List, Edit

  • Labels: Lista de etiquetas para categorizar la incidencia (separadas por comas).

    • Visible en: List, Create, Edit

  • Comment Body: El texto específico del comentario que quieres dejar.

    • Visible en: Create Comment

  • Limit: Número máximo de elementos a devolver (útil en la operación List).

    • Visible en: List

  • Mapping Data: Entrada adicional habilitada solo cuando activas el “Mapping Mode”.

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Tool Name: Nombre del agente de IA que usará este componente.

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Tool Description: Descripción detallada para que la IA entienda cuándo usar esta herramienta.

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

  • Tools arguments metadata: Define los metadatos de los argumentos para las herramientas.

    • Visible en: Get, List, Create, Edit, Create Comment, Lock, Unlock, Delete

Salidas

Al completar una operación, este componente te devuelve datos que puedes usar en los siguientes pasos de tu automatización en Nappai.

Ejemplo de Respuesta JSON

Si realizas una operación exitosa (como Get o Create), recibirás una respuesta similar a esta estructura: json { “data”: { “id”: 123456789, “number”: 42, “title”: “Error en el login”, “state”: “open”, “body”: “El usuario no puede iniciar sesión con credenciales válidas.”, “created_at”: “2023-10-27T10:00:00Z”, “assignees”: [ { “login”: “dev_juan” } ], “labels”: [ { “name”: “bug” }, { “name”: “high-priority” } ] } }

Puedes mapear campos como number o state para tomar decisiones posteriores (por ejemplo, si el estado es “closed”, enviar un correo de agradecimiento).

Conectividad

Este componente está diseñado para trabajar dentro de flujos de gestión de proyectos o soporte técnico.

  • Entrada Típica: Suelen conectarle datos de origen (como un correo electrónico de un reporte de error o un formulario web) hacia los campos Issue Title o Issue Body mediante la función de Mapeo (Mapping Mode).
  • Salida Típica: Sus salidas (Data) suelen conectarse a componentes de visualización (para mostrar el estado del issue en un panel) o a componentes de notificación (para avisar al equipo sobre la creación de una nueva tarea).

Ejemplo de Uso

Escenario: Tu equipo de soporte recibe un reporte de error y quieres crear una tarea automática en GitHub para que el equipo de desarrollo lo resuelva.

  1. Configura el componente GitHubIssue.
  2. Selecciona la operación Create.
  3. En Repository, elige tu proyecto de desarrollo.
  4. En Issue Title, mapea el asunto del correo electrónico recibido.
  5. En Issue Body, mapea el cuerpo del mensaje de error.
  6. En Labels, escribe fijo: bug, urgent.
  7. Al ejecutar el flujo, Nappai creará la tarea en GitHub y devolverá el número de la incidencia en la salida Data.
  8. Puedes usar ese número en un paso posterior para notificar al usuario que su reporte ha sido registrado.

Notas Importantes

🔒 Security GitHub API Token Needed Debes proporcionar un Personal Access Token de GitHub válido con los permisos adecuados (scopes) para que el componente pueda acceder a tu repositorio. Sin un token válido, las operaciones fallarán.

🔒 Security Keep Tokens Secret Nunca compartes tu token públicamente. Almacénalo de forma segura dentro de las credenciales de Nappai.

🟡 Medium Limitation Development Version Este componente se encuentra en fase de desarrollo. Algunas características podrían no ser estables o cambiar en el futuro. Se recomienda verificar las actualizaciones de la documentación oficial.

🟡 Medium Configuration Input Parameters Must Match Base Definition Asegúrate de que los datos que ingreses (como el nombre del repositorio) coincidan exactamente con la configuración base, ya que el componente hereda estructuras estrictas.

ℹ️ Low Behavior List Includes All Issue States La operación List devuelve todas las incidencias (abiertas, cerradas y pull requests) a menos que filtres explícitamente por estado o etiquetas.

Consejos y Mejores Prácticas

  • Usa el Mapping Mode para conectar datos dinámicos (como nombres de usuarios o errores de logs) en lugar de escribir textos fijos, haciendo tu automatización más flexible.
  • Cuando solo necesites leer datos (por ejemplo, para verificar el estado de un issue), utiliza un Token de Acceso Personal con permisos solo de lectura (public_repo o repo de solo lectura) para mayor seguridad.
  • Documenta bien el Issue Body usando formato Markdown para que la información sea legible en GitHub.

Consideraciones de Seguridad

Es fundamental utilizar un Personal Access Token con los permisos mínimos necesarios. Si solo vas a leer issues, configura un token de solo lectura. Evita usar tokens con permisos de administrador (admin:repo_hook, etc.) si no son estrictamente necesarios. Guarda siempre el token en la sección de Credenciales de Nappai y nunca lo expongas en el código visible del flujo.