跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://mintlify-mintlify-cli-update-client-1777421729.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
你将构建的内容

一个自动化流程：当你将代码推送到主 branch 时自动更新文档。你可以在多个平台上搭建此工作流，包括 GitHub Actions 和 n8n。它会监控你的代码存储库，然后调用代理 API，在单独的文档存储库中更新文档。 此工作流连接两个独立的存储库：
  • 代码存储库：用于存放应用程序代码。你将在此存储库上设置自动化触发器。示例包括后端 API、前端应用、SDK，或命令行界面 (CLI) 工具。
  • 文档存储库：用于存放文档并连接到你的 Mintlify 项目。代理会在此存储库中创建包含文档更新的拉取请求 (PR；亦称“合并请求”/Merge Request) 。
本教程假设你的文档与应用程序代码位于不同的存储库中。如果你使用 monorepo，请修改工作流以定位存放文档的目录。

​
工作流概览

  1. 有人将代码推送到你的主分支。
  2. 工作流被触发。
  3. 工作流调用代理的 API 来更新你的文档。
  4. 代理在你的文档存储库中创建一个包含文档更新的拉取请求 (PR) 。

​
选择你的平台

如果您的代码已在 GitHub 上,GitHub Actions 是最简单的选择。无需额外服务。

​
GitHub Actions 前提条件

​
在代码存储库中安装 Mintlify 应用

在你的代码存储库中安装 Mintlify 应用，以便 agent 能够从代码库获取上下文信息。要将应用添加到新存储库:
  1. 在控制台中进入 Agent 页面。
  2. 点击 Add to New Organization。这会打开 GitHub 上的应用安装页面。
  3. 从列表中选择你要授予访问权限的仓库。
  4. 保存更改。

​
获取管理员 API 密钥

  1. 在控制台中进入 API keys 页面。
  2. 点击 Create Admin API Key。
  3. 将该密钥复制并安全保存。

​
构建 GitHub Actions 工作流

​
创建工作流文件

  1. 在代码仓库中创建一个新文件：.github/workflows/update-docs.yml
  2. 添加以下工作流： 
    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}`);
            }

​
添加密钥

  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 页面找到)
更多信息请参阅 GitHub 文档中的在 GitHub Actions 中使用密钥。

​
测试 GitHub Actions 自动化

  1. 在你的代码仓库中做一个小改动，并推送到 main 分支： 
    git add .
git commit -m "Test: trigger docs automation"
git push origin main
  2. 在代码仓库中打开 Actions 标签页，查看工作流的运行情况。
  3. 工作流运行完成后，查看你的文档仓库中是否已创建包含文档更新的新分支和拉取请求 (pull request) 。

​
GitHub Actions 故障排除

​
工作流未运行

  • 请确认你已在代码仓库中启用 GitHub Actions。
  • 在 Actions 标签页中查看错误信息。
  • 确保工作流文件位于 .github/workflows/ 目录下，且文件扩展名为 .yml。

​
代理 API 返回 401 错误

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

​
文档更新未显示

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