Tutorial: Actualiza automáticamente la documentación cuando cambie el código

Usa la API del agente para actualizar automáticamente tu documentación.

​

Qué vas a construir

Una automatización que actualiza tu documentación cuando se hace push de código a tu branch principal. El flujo de trabajo se puede crear en varias plataformas, incluidas GitHub Actions y n8n. Supervisa tu repositorio de código y luego llama a la API del agente para actualizar tu documentación en un repositorio de documentación independiente.

Este flujo de trabajo conecta dos repositorios separados:

• Repositorio de código: Donde almacenas el código de la aplicación. Configurarás el disparador de la automatización en este repositorio. Algunos ejemplos incluyen una API de backend, una aplicación de frontend, un SDK o una herramienta de CLI.
• Repositorio de documentación: Donde almacenas tu documentación y lo conectas a tu proyecto de Mintlify. El agente crea solicitudes de extracción con actualizaciones de documentación en este repositorio.

Este tutorial asume que tu documentación está en un repositorio separado del código de tu aplicación. Si tienes un monorepo, modifica el flujo de trabajo para apuntar al directorio donde almacenas tu documentación.

​

Descripción general del flujo de trabajo

1. Alguien sube código a tu branch principal.
2. Se activa el flujo de trabajo.
3. El flujo de trabajo llama a la API del agente para actualizar tu documentación.
4. El agente crea una solicitud de extracción con actualizaciones de la documentación en tu repositorio de documentación.

​

Elige tu plataforma

GitHub Actions

GitHub Actions es la opción más simple si tu código ya está en GitHub. No se requieren servicios adicionales.

​

Requisitos previos

• GitHub Actions activado en tus repositorios de código y documentación
• Aplicación de GitHub de Mintlify instalada en tus repositorios de código y documentación
• Clave de API de administración de Mintlify
• ID del proyecto de Mintlify
• Plan Pro o personalizado de Mintlify
• Acceso de administrador a los repositorios de GitHub que contienen tu código y tu documentación

​

Instala la aplicación de Mintlify en tu repositorio de código

La aplicación de Mintlify debe estar instalada en tu repositorio de código para que el agente pueda obtener el contexto de tu código base. Para agregar la aplicación a repositorios nuevos:

1. Ve a la página de Agent en tu panel de control de Mintlify.
2. Haz clic en Add to new organization. Irás a la página de instalación de la aplicación en GitHub.
3. Selecciona en la lista los repositorios a los que quieres conceder acceso.
4. Guarda los cambios.

​

Obtén tu clave de API de administrador

1. Ve a la página de claves de API en tu panel de control.
2. Selecciona la opción Create Admin API Key.
3. Copia la clave y guárdala en un lugar seguro.

​

Construye el flujo de trabajo

​

Crear el archivo de flujo de trabajo

1. En tu repositorio de código, crea un nuevo archivo: .github/workflows/update-docs.yml

2. Añade este flujo de trabajo:

   name: Actualizar Documentación
   
   on:
   push:
       branches:
       - main
   
   jobs:
   update-docs:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/github-script@v8
           env:
           MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
           PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
           with:
           script: |
               const { owner, repo } = context.repo;
               const projectId = process.env.PROJECT_ID;
               const apiKey = process.env.MINTLIFY_API_KEY;
   
               if (!projectId || !apiKey) {
               core.setFailed('Faltan los secretos MINTLIFY_PROJECT_ID o MINTLIFY_API_KEY');
               return;
               }
   
               const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
               const payload = {
               branch: `mintlify/docs-update-${Date.now()}`,
               messages: [
                   {
                   role: 'system',
                   content: 'Eres un ejecutor de acciones que actualiza la documentación según los cambios en el código. Nunca debes hacer preguntas. Si no puedes acceder al repositorio, reporta el error y finaliza.'
                   },
                   {
                   role: 'user',
                   content: `Actualiza la documentación para nuestros pushes recientes a main:\n\nRepositorio: ${owner}/${repo}`
                   }
               ]
               };
   
               try {
                   const response = await fetch(url, {
                   method: 'POST',
                   headers: {
                       'Authorization': `Bearer ${apiKey}`,
                       'Content-Type': 'application/json'
                   },
                   body: JSON.stringify(payload)
                   });
   
                   if (!response.ok) {
                   throw new Error(`La solicitud a la API falló con estado ${response.status}: ${await response.text()}`);
                   }
   
                   const reader = response.body.getReader();
                   const decoder = new TextDecoder();
                   let buffer = '';
   
                   while (true) {
                   const { done, value } = await reader.read();
                   if (done) break;
                   buffer += decoder.decode(value, { stream: true });
                   const lines = buffer.split('\n');
                   buffer = lines.pop() || '';
                   for (const line of lines) {
                       if (line.trim()) {
                       console.log(line);
                       }
                   }
                   }
                   if (buffer.trim()) {
                   console.log(buffer);
                   }
   
                   core.notice(`Trabajo de actualización de documentación activado para ${owner}/${repo}`);
               } catch (error) {
                   core.setFailed(`Error al crear el trabajo de actualización de documentación: ${error.message}`);
               }
   

​

Agregar secretos

1. En tu repositorio de código, ve a Settings → Secrets and variables → Actions.
2. Haz clic en New repository secret.
3. Añade los siguientes secretos:
   • Nombre: MINTLIFY_API_KEY, Secreto: Tu clave de API de administrador de Mintlify
   • Nombre: MINTLIFY_PROJECT_ID, Secreto: Tu ID de proyecto de Mintlify (se encuentra en la página de API keys de tu panel de control)

Para obtener más información, consulta Uso de secretos en GitHub Actions en la documentación de GitHub.

​

Prueba la automatización

1. Realiza un pequeño cambio en tu repositorio de código y súbelo a la rama main:

   git add .
   git commit -m "Prueba: activar automatización de docs"
   git push origin main
   

2. Comprueba la pestaña Actions de tu repositorio de código para ver el flujo de trabajo en ejecución.

3. Cuando haya finalizado el flujo de trabajo, revisa tu repositorio de documentación para comprobar si se ha creado una nueva rama y una solicitud de extracción con actualizaciones de la documentación.

​

Solución de problemas

​

El flujo de trabajo no se está ejecutando

• Comprueba que GitHub Actions esté habilitado en tu repositorio de código.
• Revisa la pestaña Actions para ver los mensajes de error.
• Asegúrate de que el archivo de flujo de trabajo se encuentre en .github/workflows/ y tenga la extensión .yml.

​

Error 401 de la API del agente

• Verifica que tu clave de API empiece por mint_.
• Comprueba que el encabezado Authorization tenga el formato Bearer mint_yourkey.
• Confirma que la clave de API corresponde a la organización correcta de Mintlify.

​

Las actualizaciones de documentación no aparecen

• Comprueba que el repositorio de documentación esté conectado a tu proyecto de Mintlify.
• Verifica que el agente tenga permisos de escritura en el repositorio de documentación.
• Consulta los registros del flujo de trabajo para ver si hay mensajes de error del agente.