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

​

Requisitos previos

• GitHub Actions habilitado en tus repositorios de código y documentación
• Aplicación de GitHub de Mintlify instalada en ambos repositorios, de código y de 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

1. Abre el panel del agente en tu panel de control de Mintlify.
   
2. Haz clic en el botón Settings.
   
3. Haz clic en Add to New Organization. Irás a la página de instalación de la aplicación en GitHub.
4. Selecciona en la lista los repositorios a los que quieres conceder acceso.
5. 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 almacénala de forma segura.

​

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:
   Reportar código incorrecto

   Copiar

   Preguntar a la IA

   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)

​

Prueba la automatización

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

   Copiar

   Preguntar a la IA

   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 branch 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.