mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
f9ad675bf2
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
414 lines
17 KiB
Plaintext
414 lines
17 KiB
Plaintext
---
|
|
title: "Automatiza la documentación cuando el código cambia"
|
|
sidebarTitle: "Automatiza las actualizaciones de la documentación"
|
|
description: "Usa la API del agente para actualizar automáticamente tu documentación."
|
|
keywords: ["automatización con agente", "n8n", "GitHub Actions", "actualizaciones automáticas de la documentación"]
|
|
---
|
|
|
|
<div id="what-you-will-build">
|
|
## Qué vas a construir
|
|
</div>
|
|
|
|
Una automatización que actualiza tu documentación cuando haces push de código a tu branch principal. Puedes crear este flujo de trabajo 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.
|
|
|
|
<div id="workflow-overview">
|
|
### Descripción general del flujo de trabajo
|
|
</div>
|
|
|
|
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.
|
|
|
|
<div id="choose-your-platform">
|
|
## Elige tu plataforma
|
|
</div>
|
|
|
|
<Tabs>
|
|
<Tab title="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 habilitadas en tus repositorios de código y documentación
|
|
* [Aplicación de GitHub de Mintlify](/es/deploy/github) instalada tanto en tu repositorio de código como en el de documentación
|
|
* [Clave de API de administración de Mintlify](https://dashboard.mintlify.com/settings/organization/api-keys)
|
|
* [ID del proyecto de Mintlify](https://dashboard.mintlify.com/settings/organization/api-keys)
|
|
* [Plan Enterprise de Mintlify](https://mintlify.com/pricing)
|
|
* Acceso de administrador a los repositorios de GitHub de tu código y documentación
|
|
|
|
### Instala la aplicación de Mintlify en tu repositorio de código
|
|
|
|
Instala la aplicación de Mintlify 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](https://dashboard.mintlify.com/products/agent) en tu dashboard.
|
|
1. Haz clic en **Add to New Organization**. Esto te llevará a la página de instalación de la aplicación en GitHub.
|
|
1. Selecciona en la lista los repositorios a los que quieres otorgar acceso.
|
|
1. Guarda tus cambios.
|
|
|
|
### Obtén tu clave de API de administrador
|
|
|
|
1. Ve a la página de [claves de API](https://dashboard.mintlify.com/settings/organization/api-keys) 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:
|
|
|
|
```yaml
|
|
name: Update Docs
|
|
|
|
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('Missing MINTLIFY_PROJECT_ID or MINTLIFY_API_KEY secrets');
|
|
return;
|
|
}
|
|
|
|
const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
|
|
const payload = {
|
|
branch: `mintlify/docs-update-${Date.now()}`,
|
|
messages: [
|
|
{
|
|
role: 'system',
|
|
content: 'You are an action runner that updates documentation based on code changes. You should never ask questions. If you are not able to access the repository, report the error and exit.'
|
|
},
|
|
{
|
|
role: 'user',
|
|
content: `Update the documentation for our recent pushes to main:\n\nRepository: ${owner}/${repo}`
|
|
}
|
|
],
|
|
asDraft: false
|
|
};
|
|
|
|
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(`API request failed with status ${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(`Documentation update job triggered for ${owner}/${repo}`);
|
|
} catch (error) {
|
|
core.setFailed(`Failed to create documentation update job: ${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](https://dashboard.mintlify.com/settings/organization/api-keys) de tu panel de control)
|
|
|
|
Para obtener más información, consulta [Uso de secretos en GitHub Actions](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) en la documentación de GitHub.
|
|
|
|
## Prueba la automatización
|
|
|
|
1. Realiza un pequeño cambio en tu repositorio de código y haz push a la rama main:
|
|
```bash
|
|
git add .
|
|
git commit -m "Test: trigger docs automation"
|
|
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 termine 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 en la documentación.
|
|
|
|
## Solución de problemas
|
|
|
|
### El flujo de trabajo no se está ejecutando
|
|
|
|
* Comprueba que hayas habilitado GitHub Actions 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 use el formato `Bearer mint_yourkey`.
|
|
* Confirma que la clave de API corresponda a la organización correcta de Mintlify.
|
|
|
|
### Las actualizaciones de documentación no aparecen
|
|
|
|
* Comprueba que hayas conectado el repositorio de documentación 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.
|
|
</Tab>
|
|
|
|
<Tab title="n8n">
|
|
n8n ofrece un editor visual de flujos de trabajo y se puede integrar con múltiples servicios.
|
|
|
|
## Requisitos previos
|
|
|
|
* Espacio de trabajo de n8n
|
|
* [Plan Enterprise de Mintlify](https://mintlify.com/pricing)
|
|
* Aplicación de Mintlify instalada en tu repositorio de código
|
|
* Clave de API de administración de Mintlify
|
|
* Acceso de administrador a los repositorios de GitHub que contienen tu código y tu documentación
|
|
* Token de acceso personal de GitHub
|
|
|
|
### Instala la aplicación de Mintlify en tu repositorio de código
|
|
|
|
Instala la aplicación de Mintlify 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](https://dashboard.mintlify.com/products/agent) en tu dashboard.
|
|
1. Haz clic en **Add to New Organization**. Irás a la página de instalación de la aplicación en GitHub.
|
|
1. Selecciona en la lista los repositorios a los que deseas conceder acceso.
|
|
1. Guarda los cambios.
|
|
|
|
### Obtén tu clave de API de administrador
|
|
|
|
1. Ve a la página de [claves de API](https://dashboard.mintlify.com/settings/organization/api-keys) 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.
|
|
|
|
### Obtén tu token de acceso personal de GitHub
|
|
|
|
1. En GitHub, ve a **Configuración**.
|
|
2. Haz clic en **Developer settings**.
|
|
3. Haz clic en **Personal access tokens**.
|
|
4. Haz clic en **Tokens (classic)**.
|
|
5. Haz clic en **Generate new token (classic)**.
|
|
6. Selecciona estos permisos:
|
|
* `repo` (control total de los repositorios privados)
|
|
* `admin:repo_hook` (si quieres que n8n pueda crear webhooks)
|
|
7. Genera y guarda el token en un lugar seguro.
|
|
|
|
Para obtener más información, consulta [Crear un token de acceso personal (clásico)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens?versionId=free-pro-team%40latest\&productId=account-and-profile#creating-a-personal-access-token-classic) en la documentación de GitHub.
|
|
|
|
## Construye el flujo de trabajo
|
|
|
|
### Crear el activador de webhook
|
|
|
|
1. En n8n, crea un nuevo flujo de trabajo.
|
|
2. Añade un nodo de webhook.
|
|
3. Configura el webhook:
|
|
* Método HTTP: `POST`
|
|
* Ruta: `auto-update-documentation` (o cualquier otra ruta única)
|
|
* Autenticación: Ninguna
|
|
* Responder: Inmediatamente
|
|
4. Guarda el flujo de trabajo.
|
|
5. Copia la URL del webhook de producción. Se ve algo así: `https://your-n8n-instance.app.n8n.cloud/webhook/auto-update-documentation`
|
|
|
|
<Frame>
|
|
<img
|
|
src="/images/guides/n8n/webhook-node.png"
|
|
alt="Captura de pantalla de la configuración del nodo de webhook."
|
|
style={{
|
|
width: 'auto',
|
|
height: '700px',
|
|
}}
|
|
/>
|
|
</Frame>
|
|
|
|
### Configurar el webhook de GitHub
|
|
|
|
1. Accede a tu repositorio de código en GitHub.
|
|
2. Haz clic en **Settings**.
|
|
3. Haz clic en **Webhooks**.
|
|
4. Haz clic en **Add webhook**.
|
|
5. Configura el webhook:
|
|
* URL de carga útil: pega la URL de tu webhook de n8n
|
|
* Tipo de contenido: `application/json`
|
|
* ¿Qué eventos quieres usar para activar este webhook?
|
|
* Selecciona **Let me select individual events.**
|
|
* Selecciona solo **Push events**.
|
|
* Selecciona **Active**
|
|
6. Haz clic en **Add webhook**.
|
|
|
|
### Filtrar pushes a la rama principal
|
|
|
|
Agrega un nodo de código después del webhook para filtrar los pushes a main y extraer la información relevante.
|
|
|
|
1. Añade un nodo de código.
|
|
2. Llámalo "Filtrar pushes a main."
|
|
3. Configura el modo en **Run Once for All Items**.
|
|
4. Añade este código JavaScript:
|
|
|
|
```javascript
|
|
const webhookData = $input.first().json.body;
|
|
|
|
// Solo continuar si es un push a main
|
|
if (webhookData.ref !== "refs/heads/main") {
|
|
return [];
|
|
}
|
|
|
|
// Extraer información
|
|
const repository = webhookData.repository;
|
|
const pusher = webhookData.pusher;
|
|
|
|
// Construir mensaje para el agente
|
|
const agentMessage = `Actualiza la documentación para los cambios enviados a main en ${repository.name}. Siempre edita los archivos y crea una solicitud de extracción.`;
|
|
|
|
return {
|
|
json: {
|
|
codeRepoName: repository.full_name,
|
|
codeRepoShortName: repository.name,
|
|
agentMessage: agentMessage
|
|
}
|
|
};
|
|
```
|
|
|
|
<Frame>
|
|
<img src="/images/guides/n8n/filter-merged-PRs-node.png" alt="Captura de pantalla de la configuración del nodo «Filtrar pushes a main»." />
|
|
</Frame>
|
|
|
|
Este código detiene el flujo de trabajo si el push no se realizó a main, extrae toda la información relevante del webhook de GitHub y crea un mensaje para la API del agente.
|
|
|
|
### Llamar a la API del agente
|
|
|
|
Añade un nodo de solicitud HTTP para crear un trabajo de documentación.
|
|
|
|
1. Añade un nodo de solicitud HTTP.
|
|
2. Llámalo "Crear trabajo de agente."
|
|
3. Configura la solicitud:
|
|
|
|
* Método: `POST`
|
|
* URL: `https://api.mintlify.com/v1/agent/YOUR_PROJECT_ID/job` (reemplaza `YOUR_PROJECT_ID` con el ID de tu proyecto en la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys))
|
|
* Autenticación: Generic Credential Type → Header Auth
|
|
* Crea una nueva credencial:
|
|
* Nombre: `Authorization`
|
|
* Valor: `Bearer mint_YOUR_API_KEY` (reemplázalo con tu API key)
|
|
* Enviar cuerpo: Activado
|
|
* Tipo de contenido del cuerpo: JSON
|
|
* Especificar cuerpo: Usar JSON
|
|
* Agrega este JSON:
|
|
|
|
```json
|
|
{
|
|
"branch": "docs-update-from-{{ $json.codeRepoShortName }}-{{ $now.toISOString() }}",
|
|
"messages": [
|
|
{
|
|
"role": "system",
|
|
"content": "{{ $json.agentMessage }}"
|
|
}
|
|
],
|
|
"asDraft": false
|
|
}
|
|
```
|
|
|
|
<Frame>
|
|
<img
|
|
src="/images/guides/n8n/create-agent-job-node.png"
|
|
alt="Captura de pantalla de la configuración del nodo de creación de tareas de agente."
|
|
style={{
|
|
width: 'auto',
|
|
height: '700px',
|
|
}}
|
|
/>
|
|
</Frame>
|
|
|
|
El agente crea una solicitud de extracción en tu repositorio de documentación usando un nombre de branch descriptivo que incluye el nombre del repositorio de origen y la marca temporal.
|
|
|
|
### Activar el flujo de trabajo
|
|
|
|
1. Guarda tu flujo de trabajo.
|
|
2. Actívalo.
|
|
|
|
Tu flujo de trabajo ahora está monitoreando tu repositorio de código en busca de pushes a main.
|
|
|
|
<Frame>
|
|
<img src="/images/guides/n8n/workflow.png" alt="Captura de pantalla del flujo de trabajo de automatización en el editor de n8n." />
|
|
</Frame>
|
|
|
|
## Prueba la automatización
|
|
|
|
1. Crea una branch de prueba en tu repositorio de código:
|
|
```bash
|
|
git checkout -b test-docs-automation
|
|
```
|
|
|
|
2. Realiza un pequeño cambio y haz una confirmación:
|
|
```bash
|
|
git add .
|
|
git commit -m "Test: trigger docs automation"
|
|
git push origin test-docs-automation
|
|
```
|
|
|
|
3. Abre una solicitud de extracción en GitHub.
|
|
|
|
4. Fusiona la solicitud de extracción.
|
|
|
|
### Verificar la automatización
|
|
|
|
Deberías ver una nueva ejecución de n8n con todos los nodos completados exitosamente, y una nueva branch y solicitud de extracción en tu repositorio de documentación.
|
|
|
|
## Solución de problemas
|
|
|
|
### El webhook no se está activando
|
|
|
|
* Comprueba que el flujo de trabajo esté activo en n8n.
|
|
* En la configuración del repositorio de GitHub, ve a Settings → Webhooks → Recent Deliveries para ver el código de respuesta.
|
|
* Confirma que la URL del webhook coincida exactamente con la URL de tu webhook de n8n.
|
|
|
|
### Error 401 de la API del agente
|
|
|
|
* Verifica que tu clave de API empiece con `mint_`.
|
|
* Comprueba que el encabezado Authorization use el formato `Bearer mint_yourkey`.
|
|
* Confirma que la clave de API corresponda a la organización correcta de Mintlify.
|
|
|
|
### Error 401 de GitHub
|
|
|
|
* Asegúrate de que tu token tenga el permiso `repo`.
|
|
* Comprueba que el token no haya caducado.
|
|
* Confirma que has incluido el encabezado `User-Agent` en la solicitud a GitHub.
|
|
</Tab>
|
|
</Tabs> |