教程：代码变更时自动更新文档

​

前提条件

• 已在代码和文档仓库中启用 GitHub Actions
• 已在代码和文档仓库中安装 Mintlify GitHub 应用
• Mintlify 管理 API 密钥
• Mintlify 项目 ID
• Mintlify Pro 或 Custom 方案
• 对存放您代码和文档的 GitHub 仓库拥有管理员权限

​

在代码仓库中安装 Mintlify 应用

1. 在 Mintlify 控制台中打开 agent 面板。
   
2. 点击 Settings 按钮。
   
3. 点击 Add to New Organization。这会打开 GitHub 上的应用安装页面。
4. 从列表中选择要授予访问权限的仓库。
5. 保存更改。

​

获取管理员 API 密钥

1. 在仪表盘中前往 API keys 页面。
2. 选择 Create Admin API Key。
3. 将该密钥复制并妥善保存。

​

构建工作流

​

创建工作流文件

1. 在代码仓库中创建一个新文件：.github/workflows/update-docs.yml
2. 添加以下工作流：
   name: 更新文档
   
   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('缺少 MINTLIFY_PROJECT_ID 或 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: '你是一个根据代码变更自动更新文档的操作执行器。你不应该提出任何问题。如果无法访问代码仓库,请报告错误并退出。'
                   },
                   {
                   role: 'user',
                   content: `更新我们最近推送到 main 分支的文档:\n\n代码仓库: ${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 请求失败,状态码为 ${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(`已为 ${owner}/${repo} 触发文档更新任务`);
               } catch (error) {
                   core.setFailed(`创建文档更新任务失败: ${error.message}`);
               }
   

​

添加密钥

1. 在代码仓库中，依次点击 Settings → Secrets and variables → Actions。
2. 点击 New repository secret。
3. 添加以下机密：
   • 名称：MINTLIFY_API_KEY，Secret：您的 Mintlify 管理员 API 密钥
   • 名称：MINTLIFY_PROJECT_ID，Secret：您的 Mintlify 项目 ID（可在仪表盘的 API keys 页面找到）

​

测试自动化

1. 在你的代码仓库中做一个小改动，并推送到 main 分支：
   git add .
   git commit -m "测试：触发文档自动化"
   git push origin main
   
2. 在代码仓库中打开 Actions 选项卡，查看工作流的运行情况。
3. 工作流运行完成后，查看你的文档仓库中是否已创建包含文档更新的新分支和拉取请求（pull request）。

​

故障排除

​

工作流未运行

• 请确认已在代码仓库中启用 GitHub Actions。
• 在 Actions 选项卡中查看错误信息。
• 确保工作流文件位于 .github/workflows/ 目录下，并使用 .yml 扩展名。

​

代理 API 返回 401 错误

• 请确认你的 API 密钥是否以 mint_ 开头。
• 检查 Authorization 请求头的格式是否为 Bearer mint_yourkey。
• 确认该 API 密钥对应的是正确的 Mintlify 组织。

​

文档更新未显示

• 确认文档仓库已连接到你的 Mintlify 项目。
• 确认代理对文档仓库有写入权限。
• 查看工作流日志中代理返回的错误信息。