Saltearse al contenido
Nappai Documentation

File

Bienvenido al componente File en Nappai. Este es tu asistente para interactuar con archivos en repositorios de GitHub.

Piensa en este componente como un “cajero automático” o un “gestor digital” para tus archivos. Puedes usarlo para:

  • Leer el contenido de un archivo existente (como un archivo de configuración o un documento).
  • Crear nuevos archivos desde cero.
  • Editar el contenido de archivos que ya existen.
  • Eliminar archivos que ya no necesitas.

Todo esto ocurre dentro de tu repositorio de GitHub, ayudándote a automatizar tareas repetitivas de gestión de datos sin tener que entrar manualmente a la web de GitHub.

¿Cómo funciona?

Internamente, el componente se conecta a la API de GitHub. Cuando ejecutas una operación, el componente:

  1. Se identifica usando tus credenciales de seguridad.
  2. Busca la rama específica del repositorio (por ejemplo, main) y la ruta del archivo indicada.
  3. Realiza la acción solicitada (leer, crear, editar o borrar).
  4. Registra la acción como un “commit” (una versión guardada de los cambios) en Git, dejando un historial claro de lo que sucedió.

Si la operación es exitosa, el componente te devolverá información sobre el estado de la tarea, el código único del archivo (SHA) y el enlace directo al archivo en GitHub.

Conexión y Credenciales

Este componente requiere configurar 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 y guarda los campos requeridos (específicamente el GitHub Personal Access Token con permisos de repo).
  3. 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: Lee y devuelve el contenido textual de un archivo específico. Útil cuando necesitas leer datos para usarlos en pasos siguientes.
  • List Files: Muestra una lista de los archivos y carpetas que existen dentro de una ruta específica en el repositorio. Ideal para explorar qué archivos hay disponibles.
  • Create: Crea un nuevo archivo en el repositorio con el contenido que tú proporciones.
  • Edit: Modifica el contenido de un archivo que ya existe en el repositorio.
  • Delete: Elimina un archivo específico del repositorio en la rama indicada.

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 (por ejemplo, escribiendo una ruta fija como docs/readme.md).
  • Mapped (Mapeado): Conectas la salida de otro componente anterior para usar su resultado como valor (por ejemplo, usando el nombre de un archivo generado por otro paso).
  • Javascript: Escribes código pequeño en Javascript para calcular o transformar el valor dinámicamente antes de usarlo.

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:

  • Repository: Permite seleccionar el repositorio de GitHub donde se realizarán las acciones. La lista de repositorios solo aparece después de seleccionar una credencial válida.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Repository Input Type: Define cómo quieres especificar el repositorio (ya sea seleccionándolo de una lista o pasando su nombre dinámicamente).

    • Visible en: Get, List Files, Create, Edit, Delete

  • Repository ID: Te permite pasar el nombre del repositorio dinámicamente (en formato propietario/repositorio). Esto sobrescribe la selección de la lista desplegable si está activo el modo dinámico.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Branch: Especifica la rama del repositorio sobre la que trabajarás (por defecto suele ser main o master). Asegúrate de trabajar en la rama correcta.

    • Visible en: Get, List Files, Create, Edit, Delete

  • File Path: La ruta relativa del archivo dentro del repositorio (ejemplo: src/config.json). Nota: No comiences la ruta con una barra diagonal /.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Directory Path: Indica hacia qué directorio apuntas. Déjalo vacío si te refieres a la raíz del repositorio. Principalmente usado para listar archivos.

    • Visible en: List Files

  • Limit: Establece el número máximo de elementos a devolver (útil en operaciones de lista). El límite máximo permitido por la API es de 1000.

    • Visible en: List Files

  • Operation: El menú desplegable clave donde eliges qué acción realizar (Get, Create, Edit, etc.).

    • Visible en: Get, List Files, Create, Edit, Delete

  • File Content: El texto o datos que se guardarán en el archivo. Este campo es necesario únicamente si estás creando o editando un archivo.

    • Visible en: Create, Edit

  • Commit Message: Un mensaje corto que describe los cambios realizados. Este mensaje se guardará en el historial de Git para que sepas qué se hizo.

    • Visible en: Create, Edit

  • Credential: Selección de la credencial configurada previamente para autorizar el acceso a GitHub.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Tool Name: El nombre que aparecerá para el agente de IA cuando use este componente como una herramienta.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Tool Description: Una descripción detallada que ayuda al agente de IA a entender cuándo y cómo debe usar esta herramienta.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Tools arguments metadata: Define los metadatos de los argumentos para la herramienta.

    • Visible en: Get, List Files, Create, Edit, Delete

  • Mapping Mode: Interruptor para activar el modo de mapeo avanzado.

    • Visible en: Get, List Files, Create, Edit, Delete

Salidas

Este componente produce los siguientes resultados según la operación realizada:

  • Data: Contiene el resultado principal de la operación.
    • En Get, devuelve el texto del archivo.
    • En List Files, devuelve la lista de archivos.
    • En Create/Edit/Delete, devuelve una confirmación de estado.
  • Tool: Convierte este componente en una herramienta utilizable por los agentes de IA de Nappai para tareas automáticas.

Ejemplo de Respuesta JSON

Este es un ejemplo de lo que recibirías en la salida Data al realizar una operación Get exitosa: json { “content”: “Hola, este es el contenido de mi archivo README.md\n\nEjemplo de automatización con Nappai.”, “sha”: “a1b2c3d4e5f6…”, “status”: “success”, “file_url”: “https://github.com/miusuario/mirepo/blob/main/README.md”, “commit_id”: “commit-xyz-123” }

Nota: En operaciones como Create o Edit, la salida incluirá el nuevo sha y el commit_id generados por el cambio.

Conectividad

Este componente es versátil y puede conectarse a varios tipos de nodos posteriores:

  1. Hacia procesadores de texto o datos: Si usas Get, puedes conectar la salida a componentes que lean, analicen o transformen ese texto.
  2. Hacia sistemas de envío de mensajes: Si usas Create o Edit, puedes conectar la salida para notificar (por correo, Slack, etc.) que un archivo ha sido creado o actualizado.
  3. Hacia otros componentes de archivos: Puedes encadenar operaciones, por ejemplo, Get un archivo para leerlo y luego usar esa información para Edit otro archivo.

Ejemplo de Uso

Escenario: Actualizar automáticamente la versión de tu software en un archivo

  1. Usa el componente GitHubFile con la operación Get para leer el archivo version.txt y obtener su contenido actual.
  2. Conecta la salida a un componente de “Expresión” o “Python” para aumentar el número de versión en 1.
  3. Usa el componente GitHubFile nuevamente con la operación Edit.
  4. En File Path, escribe version.txt.
  5. En File Content, mapea el resultado del paso 2 (la nueva versión).
  6. En Commit Message, escribe “Bump version to 1.0.1”.
  7. Al ejecutar, el componente leerá la versión actual, la actualizará en el servidor de GitHub y guardará el cambio con el mensaje especificado.

Notas Importantes

🔒 GitHub Personal Access Token Needed 🟢 Debes suministrar un Token de Acceso Personal (PAT) de GitHub con el alcance “repo” para autenticar el componente. Sin un token válido, el componente no puede acceder ni modificar archivos en el repositorio.

🔒 Repository Access Must Be Granted 🟢 El PAT debe tener permisos de lectura/escritura para el repositorio objetivo. Verifica que el propietario del token sea un colaborador o tenga los derechos apropiados para crear, editar o eliminar archivos.

🔒 Keep Your Token Secret 🟡 Nunca codifiques el PAT en archivos fuente ni lo compartas en los registros (logs). Guárdalo en una variable de entorno segura o en un gestor de secretos para evitar accesos no autorizados a tu repositorio.

⚠️ Development Version – Unstable Behavior 🟡 El componente está marcado como “en desarrollo” (is_development = True), lo que significa que la API podría cambiar o contener errores. Espera fallos ocasionales o cambios inesperados en el comportamiento.

⚠️ GitHub API Rate Limits Apply 🟡 Las operaciones frecuentes de archivos pueden alcanzar los límites de velocidad de la API de GitHub, causando fallos temporales. Si planeas muchas acciones, añade lógica de reintento o separa las solicitudes en el tiempo.

⚠️ Large File Size Restrictions 🟡 La API de GitHub limita generalmente las cargas de archivos en bruto a unos 100 MB. Para archivos más grandes, considera usar Git LFS o dividir el contenido en partes más pequeñas.

💡 Use Descriptive Commit Messages 🟢 Cada operación de archivo crea un commit. Incluye mensajes claros y concisos para ayudarte a seguir el rastro de los cambios y colaborar con otros.

💡 Specify Correct Branch and Path 🟢 Proporciona el nombre exacto de la rama y la ruta del archivo para evitar sobrescrituras o eliminaciones accidentales en la rama equivocada. Verifica la ortografía de la ruta y la sensibilidad a mayúsculas/minúsculas.

ℹ️ Delete Operation is Permanent 🟡 Eliminar un archivo lo quita del historial de la rama especificada. Si necesitas recuperar el archivo, usa el historial de Git o una copia de seguridad antes de ejecutar la eliminación.

⚙️ Avoid Leading Slashes in File Path 🟡 El componente espera rutas de archivo sin una barra diagonal inicial (ej. "docs/readme.md", no "/docs/readme.md"). Las barras iniciales pueden causar que el archivo no se encuentre o se escriba incorrectamente.

Consejos y Mejores Prácticas

  • Siempre usa la operación Get primero para asegurarte de que el archivo existe antes de intentar editarlo.
  • Si trabajas en un entorno colaborativo, evita editar archivos simultáneamente en la misma rama para prevenir conflictos.
  • Usa Commit Message para documentar tus cambios; esto facilita la auditoría y el trabajo en equipo.
  • Revisa los permisos de tu token de GitHub (PAT) regularmente para asegurar que solo tenga los accesos necesarios.

Consideraciones de Seguridad

Dado que este componente interactúa directamente con repositorios de código, la seguridad es crítica.

  1. Seguridad de Credenciales: Nunca almacenes tokens en texto plano en tu flujo de trabajo. Usa la sección de Credenciales de Nappai.
  2. Limitación de Permisos: Asegúrate de que el Token de Acceso Personal tenga solo los permisos necesarios (scope repo es estándar para este tipo de gestión, pero verifica si necesitas scopes más restrictivos si tu empresa lo permite).
  3. Prevención de Pérdida de Datos: Ten en cuenta que la operación Delete es permanente en la rama seleccionada. Haz respaldos o usa ramas de prueba (dev o feature) antes de borrar archivos importantes en la rama principal (main).