Release

El componente Release es una herramienta esencial dentro de Nappai para gestionar las versiones de tu proyecto en GitHub. Imagina que este componente actúa como un asistente personal que se encarga de etiquetar, describir y publicar las nuevas actualizaciones de tu software en tu repositorio.

Ya sea que necesites crear una nueva versión (como v1.0.0), buscar información sobre una versión existente o limpiar versiones antiguas, este componente te permite hacerlo mediante una interfaz visual sencilla, sin necesidad de escribir código complejo ni acceder manualmente a la página web de GitHub.

¿Cómo funciona?

Este componente funciona como un “puente” inteligente entre Nappai y GitHub. Cuando lo configuras, le dices a Nappai qué repositorio quieres tocar y qué quieres hacer con él (crear, buscar, borrar, etc.).

Internamente, el componente se comunica con la API de GitHub utilizando tu credencial de seguridad. Al seleccionar una operación, el componente envía las instrucciones correctas a GitHub (por ejemplo, “Crea una nueva etiqueta llamada v1.0”). Una vez que GitHub procesa la solicitud, el componente te devuelve la confirmación y los detalles de lo que ocurrió, permitiéndote conectar este resultado con otros pasos en tu flujo de automatización.

Conexión y Credenciales

Este componente requiere que tengas configurada una credencial de GitHub en Nappai para poder interactuar con tu repositorio.

Sigue estos pasos para configurar la conexión:

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo GitHub API.
- Asegúrate de generar un GitHub Personal Access Token desde tu configuración de desarrollador en GitHub y otorgarle permisos de acceso al repositorio (scope repo).
En este componente, selecciona la credencial que acabas de guardar en el campo Credential.

Nota: Sin esta credencial válida, el componente no podrá realizar ninguna acción.

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 Release: Busca y recupera los detalles específicos de una versión única utilizando su etiqueta.
Create Release: Crea una nueva versión en tu repositorio, definiendo su nombre, descripción y notas del lanzamiento.
Update Release: Modifica la información de una versión existente (por ejemplo, cambiar la descripción o el nombre).
Delete Release: Elimina permanentemente una versión específica del repositorio.
List All: Obtiene una lista de todas las versiones disponibles en tu repositorio.

Para usar el componente, primero selecciona la operación que necesitas en el campo Operation.

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: Selección principal para decidir qué acción realizará el componente.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Repository: Permite seleccionar el repositorio de GitHub con el que trabajar desde una lista desplegable.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Repository ID: Te permite escribir manualmente el nombre del repositorio (ej. “usuario/repo”) si prefieres no usar la lista desplegable. Sobrescribe la selección anterior.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Repository Input Type: Define qué tipo de entrada usarás para identificar el repositorio (si usas la lista desplegable o el campo de texto manual).
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Release Tag: La etiqueta identificativa de la versión (por ejemplo, v1.0.0). Es necesaria para identificar qué versión específica quieres consultar, modificar o borrar.
- Visible en: Get Release, Create Release, Update Release, Delete Release
Release Name: El título visible de la versión que se mostrará en GitHub.
- Visible en: Create Release, Update Release
Release Description: La descripción detallada o “changelog” que explica los cambios de esta versión.
- Visible en: Create Release, Update Release
Limit: Número máximo de elementos a devolver (útil para listas largas). Máximo 1000.
- Visible en: List All

Campos avanzados de integración:

Credential: Campo interno para conectar la credencial de seguridad de GitHub.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Mapping Mode: Activador para habilitar la lógica de mapeo dinámico.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Mapping Data: Entrada adicional para procesar múltiples registros cuando el modo de mapeo está activo.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Tool Name: Nombre de la herramienta visible para el agente de IA.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Tool Description: Descripción detallada para ayudar al agente a entender el uso de la herramienta.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All
Tools arguments metadata: Metadatos de argumentos para la herramienta.
- Visible en: Get Release, Create Release, Update Release, Delete Release, List All

Salidas

Este componente devuelve datos que puedes usar para continuar tu flujo de automatización. Las principales salidas son:

Data: Contiene la información completa obtenida o procesada (por ejemplo, los detalles de un release o una lista de releases). Puedes mapear esta salida a otros componentes que necesiten leer esta información.

Ejemplo de Respuesta JSON

Si utilizas la operación Get Release o Create Release con éxito, podrías recibir una estructura de datos similar a esta en la salida Data: json { “html_url”: “https://github.com/nappai/example-repo/releases/tag/v1.0.0”, “tag_name”: “v1.0.0”, “name”: “Versión 1.0.0 Inicial”, “body”: “Esta es la primera versión oficial del proyecto. Incluye correcciones de errores básicos y mejoras de rendimiento.”, “published_at”: “2023-10-27T10:00:00Z”, “author”: { “login”: “usuario-nappai” }, “assets”: [], “prerelease”: false, “draft”: false }

Nota: Si usas List All, la salida Data será una lista (array) de objetos con esta misma estructura.

Conectividad

Este componente está diseñado para integrarse en flujos de CI/CD (Integración Continua / Despliegue Continuo) y gestión de proyectos.

Entradas: Generalmente se conecta a componentes que definen el contexto del proyecto (como un componente de “Repo Config” que provee el nombre del repositorio) o a componentes de trigger (como “Webhook” o “Schedule”) que inician el proceso de lanzamiento.
Salidas: La salida Data suele conectarse a:
- Componentes de notificación (como Email o Slack) para informar al equipo de la nueva versión.
- Componentes de base de datos para registrar el historial de versiones.
- Otros componentes de GitHub si necesitas realizar acciones adicionales basadas en la información del release recién creado.

Ejemplo de Uso

Imagina que estás desarrollando una aplicación y acabas de terminar una nueva versión estable. Quieres automatizar el proceso de publicar esta versión en GitHub.

Configuras el componente Release y seleccionas la operación Create Release.
En Repository, seleccionas tu proyecto desde la lista desplegable.
En Release Tag, escribes v1.2.0.
En Release Name, escribes “Actualización Estable 1.2”.
En Release Description, escribes “Se han corregido los errores de login y mejorado la velocidad de carga”.
Al conectar este componente a un botón de “Deploy” o a un horario fijo, Nappai se encargará automáticamente de crear el lanzamiento en GitHub, ahorrándote la tarea manual de entrar a la web y hacerlo clic por clic.

Notas Importantes

🔒 Protect Your GitHub Token El componente requiere un token de acceso personal. Mantén este token confidencial y otórgale solo los permisos mínimos necesarios (por ejemplo, acceso al repositorio).

⚠️ Component in Development Este componente está marcado como “en desarrollo”. Puede contener errores o tener características incompletas. Evítalo para flujos de trabajo de producción críticos hasta que se considere estable.

📋 Valid GitHub Personal Access Token Es obligatorio tener un token de acceso personal (PAT) válido de GitHub con permisos de repositorio. Sin él, ninguna operación funcionará.

ℹ️ Delete Operation Is Irreversible Borrar una versión es una acción permanente. No hay forma de recuperar una release eliminada a través de este componente. Verifica bien qué release estás borrando antes de confirmar.

⚠️ GitHub API Rate Limits GitHub limita el número de consultas que puedes hacer a su API en un periodo corto. Si realizas muchas operaciones de golpe, podrías recibir un error temporal.

⚙️ Correct Repository Format Asegúrate de especificar el repositorio en el formato correcto (ej. “dueño/repo”). Un formato incorrecto impedirá que el componente encuentre tu proyecto.

ℹ️ Handle Pagination for Release Lists Si tienes muchas versiones en tu repositorio, la operación List All podría devolver solo una parte de la lista por defecto. Considera filtrar o paginar si necesitas ver todas las versiones antiguas.

💡 Test in a Staging Repository Antes de usar este componente en tu repositorio principal de producción, pruébalo primero en un repositorio de prueba (staging) para asegurarte de que el comportamiento es el esperado.

Consejos y Mejores Prácticas

Usa la operación List All al principio de tu flujo si necesitas obtener el ID de la última versión para compararla con la que estás creando.
Al crear releases, incluye notas detalladas en Release Description para que tu equipo entienda los cambios sin tener que revisar el código.
Si tu flujo de automatización es muy rápido, ten en cuenta los límites de velocidad de la API de GitHub para evitar bloqueos temporales.
Guarda las credenciales en la sección de Credenciales de Nappai, nunca pongas los tokens directamente en el código o en textos planos.

Consideraciones de Seguridad

Privacidad del Token: El componente utiliza un Token de Acceso Personal (PAT) para autenticarse. Nunca compartas este token públicamente ni lo commits en tu código fuente.
Permisos Mínimos: Al crear el token en GitHub, asegúrate de darle solo los permisos necesarios (scope repo o repo:status según sea necesario) en lugar de dar acceso completo a tu cuenta.
Reversibilidad: Ten mucho cuidado con la operación Delete Release, ya que la eliminación es irreversible y afecta la visibilidad pública de tu software.